>
    Decryption Log Errors, Error Indexes, and Bitmasks
    Focus
    Download PDF
    Focus
    1. Home
    2. PAN-OS
    3. Decryption
    4. Troubleshoot and Monitor Decryption
    5. Decryption Log
    6. Decryption Log Errors, Error Indexes, and Bitmasks
    Download PDF

    Decryption Log Errors, Error Indexes, and Bitmasks

    Table of Contents

    Decryption Log Errors, Error Indexes, and Bitmasks

    View and interpret certificate, cipher, protocol, version, and other TLS handshake errors to troubleshoot decryption issues.
    The Error Index and Error columns of the Decryption Log provide information about the decryption error category and details, respectively. You can also see error and error index information in the Handshake Details section of the Detailed Log View (click
    for any log entry). The decryption log Error Index indicates one of eight error categories:
    If no suitable error category exists for an error, the default message is General TLS protocol error.
    • Certificate—Errors such as invalid certificates, expired certificates, unsupported client certificates, Online Certificate Status Protocol (OCSP) or CRL check revocations and failures, and untrusted issuer CAs (sessions signed by an untrusted root, which includes incomplete certificate chains).
      When the firewall does not have an intermediate certificate because the site did not send the full certificate chain, you can find and install the missing certificate to repair incomplete certificate chains.
    • Cipher—Unsupported cipher errors where:
      • The client tries to negotiate a cipher that the firewall supports but that the Decryption profile applied to the traffic doesn’t support.
      • The client tries to negotiate a cipher that the firewall doesn’t support.
      • (Rare) Inbound Inspection is enabled and the server’s capabilities don’t match the Decryption profile settings.
      • The error message includes the supported client cipher bitmask value and the supported Decryption profile cipher bitmask value. You can use these values to identify the cipher the client tried to use and to list the cipher values that the Decryption profile supports as described later in this topic.
    • Feature—Errors such as oversized TLS handshakes or unknown handshakes, oversized certificate chains (more than five certificates), and other unsupported features.
    • HSM—Hardware storage module (HSM) errors such as unknown requests, items not found in the configuration, request timeouts, and other HSM errors and failures.
    • Protocol—Errors such as TLS handshake failures, private and public key mismatches, Heartbleed errors, TLS key exchange failures, and other TLS protocol errors. Protocol errors show when the server doesn’t support the protocols that the client supports, the server uses certificate types that the firewall doesn’t support, and general TLS protocol errors.
    • Resource—Errors such as lack of sufficient memory.
    • Resume—Session resumption errors concerning resume session IDs and tickets, resume session entries in the firewall cache, and other session resumption errors.
    • Version—Errors related to TLS version mismatches between a client and a Decryption profile or a client and server. The error messages include bitmask values that identify the TLS versions supported by the client and Decryption profile. You can use these values to identify the cipher the client tried to use and to list the cipher values that the Decryption profile supports.
    The following tables list specific errors from each error category along with additional information and resources. For some errors, possible remediation steps are shared.
    Certificate Errors
    Decryption Error MessageAdditional Information and Resources
    Invalid (client or server) certificate
    Description: The certificate presented by either a client or server is not valid or cannot be verified.
    Related Documentation:
    Remediation:
    Expired (client or server) certificate
    Description: A certificate has expired or is not currently valid.
    RFC Information: This alert falls under the certificate_expired error defined in RFC 5246, which applies to TLSv1.1-TLSv1.3.
    Related Documentation: Troubleshoot Expired Certificates
    Remediation:
    Unsupported client certificate
    Description: The client certificate was of an unsupported type.
    RFC Information: This alert falls under the unsupported_certificate error defined in RFC 5246, which is applicable to TLSv1.1-TLSv1.3.
    OCSP / CRL check: certificate revoked
    Description: A certificate was revoked by its signer.
    RFC Information: This alert falls under the certificate_revoked error defined in RFC 5246, which applies to TLSv1.1-TLSv1.3.
    Related Documentation:
    Remediation:
    OCSP / CRL check failure
    Description: Sent by clients when an invalid or unacceptable OCSP response is provided by the server through the "status_request" extension.
    RFC Information: This alert falls under the bad_certificate_status_response error defined in RFC 8446, which applies to TLSv1.3.
    Untrusted issuer CA
    Description: A valid certificate chain was received, but the certificate authority (CA) certificate could not be matched with a known trust anchor.
    RFC Information: This alert falls under the unknown_ca error defined in RFC 5246, which applies TLSv1.1-TLSv1.3.
    Related Documentation: Identify Untrusted CA Certificates
    Remediation: This error may be due to a configuration issue. Make sure your firewall certificate uses a trusted external CA (rather than an untrusted or self-signed CA). See Obtain a Certificate from an External CA.
    Received fatal alert <error name> from (client or server)
    Description: The variable error has caused the connection to fail.
    Server and firewall's certificate mismatch
    Description: The sender was unable to negotiate an acceptable set of security parameters with the receiver. A few possible causes are incorrect certificates, a missing client certificate, an untrusted server certificate, or a missing server certificate.
    RFC Information: This alert falls under the handshake_failure error defined in RFC 5246, which applies to TLSv1.1-TLSv1.3.
    Remediation:
    SNI didn't match with subject name or SAN
    Related Documentation: SSL Decryption and Subject Alternative Names (SAN)
    General (client or server) certificate errorThis message indicates that an error does not meet the criteria for any of the aforementioned certificate errors.
    Cipher Errors
    Decryption Error MessageAdditional Information and Resources
    Unsupported cipher
    Description: The sender was unable to negotiate an acceptable set of security parameters with the receiver, likely due to incompatible cipher suites.
    RFC Information: This alert falls under the handshake_failure error defined in RFC 5246, which applies to TLSv1.1-TLSv1.3.
    Remediation:
    • Follow the steps to fix cipher errors.
    • Configure your Decryption profiles such that the cipher suites selected are compatible with your sender and receiver's supported cipher suites. If needed, create a new Decryption policy rule for a specific use case of your firewall causing this issue.
    Cipher log errors include bitmask values that you can convert to actual values using operational CLI commands:
    • Cipher error bitmask values identify encryption and other mismatches between the client and the Decryption profile applied to the traffic.
      admin@vm1>debug dataplane show ssl-decrypt bitmask-cipher <bitmask-value>
      The command returns the cipher that matches the bitmask.
      Filter the decryption log to find cipher errors, plug the bitmask values for sessions with errors into the appropriate CLI command, obtain the values of the cipher that caused the error, and use the information to update the decryption policy rule or Decryption profile if you want to allow access to the site in question.
    Feature Errors
    Decryption Error MessageAdditional Information and Resources
    Client certificate received
    Related Documentation:
    Oversized chain (>5 certificates) received
    Description: The certificate chain contains more than five certificates.
    Remediation:
    Oversized handshake received
    Unknown handshake message received
    Description: A field in the handshake was incorrect or inconsistent with other fields (albeit conforms to the formal protocol syntax), likely causing an unrecognizable handshake message.
    RFC Information: This alert falls under the illegal_parameter error defined in RFC 5246, which applies to TLSv1.1-TLSv1.3.
    Unsupported featureThis message indicates that an error does not meet the criteria for any of the aforementioned feature errors.
    HSM Errors
    Decryption Error MessageAdditional Information and Resources
    Unknown request
    Certificate not found in configuration
    Remediation:
    Private key not found on HSM
    Remediation:
    • Store Private Keys on an HSM.
      • Verify that you successfully imported the certificate and private key used in your decryption deployment. Check the Key column for either a lock or error icon. The error icon indicates the private key is not on the HSM or the HSM is not properly authenticated or connected.
    • Restart the HSM.
    • Reset the HSM configuration. Select DeviceSetupHSM, and then Reset HSM Configuration from the Hardware Security Operations section.
    Request to HSM timed out
    Troubleshooting:
    • Verify firewall connectivity and authentication with the HSM.
      • Select DeviceSetupHSM and look for a green dot next to Status. This indicates that the firewall is successfully connected and authenticated to the HSM.
    Remediation:
    • Restart the HSM.
    • Reset the HSM configuration. Select DeviceSetupHSM, and then Reset HSM Configuration from the Hardware Security Operations section.
    HSM is down
    Related Documentation:
    Could not send request to HSM
    Related Documentation:
    Remediation: Restart the HSM.
    HSM server not found in configuration
    Related Documentation:
    General HSM errorThis message indicates that an error does not meet the criteria for any of the aforementioned HSM errors.
    Protocol Errors
    Decryption Error MessageAdditional Information and Resources
    TLS Handshake Failure
    Description: The sender was unable to negotiate an acceptable set of security parameters with the receiver. A few possible causes are incompatible cipher suites, incompatible SSL/TLS versions, incorrect certificates, a missing client certificate, untrusted server certificate, or a missing server certificate.
    RFC Information: This alert falls under the handshake_failure error defined in RFC 5246, which applies to TLSv1.1-TLSv1.3.
    Remediation:
    Private key does not match public key
    Related Documentation:
    TLS Key Exchange Failure
    Description: The client and server are unable to exchange the keys needed to secure communication. A few possible causes are incompatible cipher suites, incompatible SSL/TLS versions, or an incomplete certificate chain.
    Remediation:
    OpenSSL Error
    Description: An OpenSSL error was detected.
    General TLS Protocol Error
    This message indicates that an error doesn't meet the criteria for any of the aforementioned protocol errors.
    If no suitable error category exists for any error, this is the default error message.
    Resource Errors
    Decryption Error MessageAdditional Information and Resources
    Out of the firewall resources: memory
    Description: An internal error unrelated to the peer or SSL/TLS protocol correctness (such as a memory allocation error) makes it impossible to continue.
    RFC Information: This alert falls under the internal_errors error defined in RFC 5246, which applies to TLSv1.1-TLSv1.3.
    Out of the firewall resources (general)This message indicates that an error doesn't meet the criteria for any of the aforementioned resource errors.
    Resume Errors
    Decryption Error MessageAdditional Information and Resources
    No resume entry in firewall cache
    Description: The firewall tried to resume a session for which a cache entry doesn't exist.
    General sessions resumption errorThis message indicates that an error doesn't meet the criteria for any of the aforementioned resume errors.
    Version Errors
    Decryption Error MessageAdditional Information and Resources
    Client and decrypt profile version mismatch
    Description: The sender was unable to negotiate an acceptable set of security parameters with the receiver given the available options. This is likely due to incompatibility between the SSL/TLS versions supported by the client and the Decryption profile.
    RFC Information: This alert falls under the handshake_failure error defined in RFC 5246, which applies to TLSv1.1-TLSv1.3.
    Related Documentation: Troubleshoot Unsupported Cipher Suites
    Remediation:
    Client and server version mismatch
    Description: The sender was unable to negotiate an acceptable set of security parameters with the receiver given the available options. This is likely due to incompatibility between the SSL/TLS versions supported by the client and server.
    RFC Information: This alert falls under the handshake_failure error defined in RFC 5246, which is applicable to TLSv1.1-TLSv1.3.
    Related Documentation: Troubleshoot Unsupported Cipher Suites
    The troubleshooting topic uses the "Client and decrypt profile version mismatch" search query. For this error, use the (error contains ‘Client and server version mismatch’) query.
    Remediation:
    Version log errors include bitmask values that you can convert to actual values using operational CLI commands:
    • Version error bitmask values identify mismatches between the TLS protocol versions that the client and server use and also identify TLS protocol mismatches between the client and the Decryption profile applied to the traffic. The CLI command to convert version error bitmasks is debug dataplane show ssl-decrypt bitmask-version <bitmask-value>.
      The command returns the TLS version that matches the bitmask.
      Filter the decryption log to find version errors, plug the bitmask values into the appropriate CLI command, obtain the values of the protocol version that caused the error, and use the information to update the decryption policy rule or Decryption profile if you want to allow access to the site in question.

    Version Errors

    To identify and fix version mismatch errors:
    1. Use the (err_index eq Version) query to filter by version errors. The bitmask values are highlighted.
      You can filter decryption logs in many ways. For example, to see only TLSv1.3 version errors, use the (err_index eq Version) and (tls_version eq TLS1.3) query.
    2. Log in to the CLI and look up the bitmask values using the debug dataplane show ssl-decrypt bitmask-version <bitmask-value> command.
      The version errors in the first screenshot (the same error for all three sessions) show a client and Decryption profile mismatch—the supported client version bitmask is 0x08 and the supported Decryption profile version bitmask is 0x70:
      admin@vm1> debug dataplane show ssl-decrypt bitmask-version 0x08
TLSv1.0
      This output shows that the client supports only TLSv1.0.
      admin@vm1> debug dataplane show ssl-decrypt bitmask-version 0x70
TLSv1.1
TSLv1.2
TLSv1.3
      This output shows that the Decryption profile supports TLSv1.1, TLSv1.2, and TLSv1.3, but not TLSv1.0. The issue is that the client supports a version of the TLS protocol that the Decryption profile attached to the decryption policy rule controlling the traffic blocks.
      The next step is to decide what action to take. You could update the client so that it accepts a more secure TLS version. However, if the client requires TLSv1.0 for some reason, you can:
      • Let the firewall continue to block the traffic.
      • Update the Decryption profile to allow all TLSv1.0 traffic (not recommended).
      • Create a decryption policy rule and profile that allows TLSv1.0 and apply it only to the client devices that must use TLSv1.0 and cannot support a more secure protocol—the most secure option for allowing the traffic.
      The version error in the second screenshot shows a different issue: a client and server version mismatch. The error indicates the supported client bitmask as 0x20:
      admin@vm1> debug dataplane show ssl-decrypt bitmask-version 0x20
TLSv1.2
      The output shows that the client supports only TLSv1.2, which means that the server doesn't support this version. The server might only support TLSv1.3 or it might support only TLSv1.1 or lower (less secure protocols). You can use Wireshark or another packet analysis tool to find out which TLS versions the server supports. How you fix this error depends on the TLS versions that the server supports and your business needs:
      • If the server only supports TLSv1.3, you could edit the Decryption profile to support TLSv1.3.
      • If the server only supports TLSv1.1 or lower, evaluate whether you need to access that server for business purposes. If not, consider blocking the traffic to increase security. If you need to access the server for business purposes, create or add the server to a decryption policy rule that applies only to the servers and sites you need to access for business; don’t allow access to all servers that use less secure TLS versions.
    3. To find the decryption policy rule that controls the session traffic, check the Policy Name column in the log (or click the magnifying glass icon
      next to the decryption log to see the information in the General section of the Detailed Log View). In the example above, the decryption policy rule name is Big Brother. To find the decryption policy rule and profile, go to PoliciesDecryption, select the policy named Big Brother, and then select the Options tab. Decryption Profile displays the name of the Decryption profile.
      Go to ObjectsDecryptionDecryption Profile, select the appropriate profile, and edit it to address the version issue.

    Cipher Errors

    Hunting down cipher errors is similar to hunting down version errors–you filter the Decryption Log for a specific error and obtain error bitmasks. Then, you use a CLI to convert the bitmasks to error values and take appropriate corrective measures. The following steps illustrate this process.
    1. Use the (err_index eq Cipher) query to filter by cipher errors. Let’s examine a session with the following error message: Unsupported cipher. Supported client cipher bitmask: 0x80000000. Supported decrypt profile cipher bitmask 0x60f79980.
    2. Log in to the CLI and look up the bitmask values:
      admin@vm1>debug dataplane show ssl-decrypt bitmask-cipher 0x80000000
CHACHA_PLY1305_SHA256
      This output shows that the client tried to negotiate a cipher that the firewall supports. When the firewall doesn't support a cipher, the bitmask is all zeros (0x0000000).
      admin@vm1> debug dataplane show ssl-decrypt bitmask-cipher 0x60f79980
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA256
TLS_RSA_WITH_AES_128_CBC_SHA256
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_DHE_RSA_WITH_AES_256_CBC_SHA
TLS13_WITH_AES_256_GCM_SHA384
TLS13_WITH_AES_128_GCM_SHA256
      This output shows that the Decryption profile that controls the traffic supports many ciphers, but does not support the cipher the client is trying to use. To fix this issue so that the firewall allows and decrypts the traffic, you need to add support for the missing cipher to the Decryption profile.
    3. Check the decryption log or the Policy Name in the Detailed Log View to get the name of the decryption policy rule that controls the traffic. Go to PoliciesDecryption and select the rule. On the Options tab, look up the name of the Decryption profile. Next, go to ObjectsDecryptionDecryption Profile, select the appropriate profile, and edit it to address the version issue.
      In this example, the Decryption profile does not support the TLS13_WITH_CHACHA_POLY1305_SHA256 cipher, so the client can’t connect.
      To fix the issue, select the CHACHA20-POLY1305 encryption algorithm option (the Max Version setting of Max means that the profile already supports TLSv1.3 and the Authentication Algorithm setting already includes SHA256, so only the encryption algorithm support was missing) and then Commit the configuration. After you commit the configuration, the Decryption profile supports the missing cipher and the decryption sessions for the traffic succeed.
      If the firewall does not support a cipher suite and you need to allow the traffic for business purposes, create a decryption policy rule and profile that applies only to that traffic. In the Decryption profile, disable the Block sessions with unsupported cipher suites option.

    Root Status “Uninspected”

    In some cases, the Root Status column displays the value uninspected. There are several reasons why the firewall could not inspect the root status, including:
    • Session resumption.
    • Traffic was not decrypted because a No Decryption policy rule controlled the traffic.
    • A decryption failure occurred before the firewall could inspect the server certificate.
    Filter the decryption log (root_status eq uninspected) and (tls_version eq TLS1.3) to see Decryption sessions for which the Root Status is uninspected:

    © 2024 Palo Alto Networks, Inc. All rights reserved.