Applies to:
- Liquibase Pro
- Liquibase Open Source (Community)
Summary:
When troubleshooting SSL/TLS connection issues in Liquibase, it’s often difficult to identify the root cause due to the secure nature of the protocol. Java provides a useful debugging option, -Djavax.net.debug=ssl:handshake:verbose
, which enables detailed logging of the SSL/TLS handshake process. This can help pinpoint issues related to certificates, key stores, trust stores, or protocol mismatches.
The -Djavax.net.debug
option instructs the Java Virtual Machine (JVM) to print debug information related to SSL/TLS. By specifying ssl:handshake:verbose
, you can gather detailed insights about the handshake process, which is critical in establishing secure connections.
Environment Conditions:
- Any version of Liquibase Pro or Open Source
- Using SSL/TLS connection
How to troubleshoot an SSL/TLS connection
Step 1: Enable SSL Handshake Debugging
To enable the SSL/TLS debugging in your Java application, add the following JVM option when running Liquibase:
JAVA_OPTS="-Djavax.net.debug=ssl:handshake:verbose" liquibase update
- ssl: Enables SSL/TLS debugging.
- handshake: Focuses on the SSL/TLS handshake process, which is where most connection issues arise.
- verbose: Provides additional detailed output for each step of the handshake process.
More information for JAVA_OPTS can be found on our JAVA_OPTS Environment Variable documentation page.
Step 2: Review Output
Once the debugging flag is enabled, Java will start printing detailed logs related to the SSL handshake. These logs will include:
- Protocol version negotiation (e.g., TLS 1.2, TLS 1.3).
- Client and server hello messages.
- Certificate exchanges.
- Cipher suite negotiation.
- Certificate validation, including issues related to trust anchors.
- Session resumption or session renegotiation steps.
Step 3: Identify Common Issues
The debugging output provides clues to common SSL/TLS issues:
- Protocol Mismatch: If the client and server are using different TLS versions, the log will show a failure during protocol negotiation.
- Certificate Issues: If there’s a problem with the server or client certificate (e.g., expired, untrusted), the log will show validation failures during the certificate exchange.
- Cipher Suite Mismatch: If no mutually supported cipher suite is found, the handshake will fail after the ClientHello and ServerHello steps.
Step 4: Troubleshooting Actions
Depending on what the logs reveal, you may need to take different actions:
- Update SSL/TLS Protocol Versions: Ensure both client and server support the same version of TLS (e.g., TLS 1.2 or TLS 1.3).
- Fix Certificate Issues: Make sure the certificates in your keystore and truststore are valid, trusted, and configured correctly.
- Configure Supported Cipher Suites: Ensure that the client and server have at least one cipher suite in common.
Step 5: Disable Debugging
Once the issue is resolved, remove the -Djavax.net.debug=ssl:handshake:verbose
option from the JAVA_OPTS being passed to Liquibase to stop logging the detailed SSL handshake information, as leaving it enabled in a production environment could generate large logs and expose sensitive information.
Comments
0 comments
Article is closed for comments.