Decryption Log Errors, Error Indexes, and Bitmasks
Focus
Focus

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 in 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
.
  • —Errors such as invalid certificates, expired certificates, unsupported client certificates, 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 doesn’t 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.
  • —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.
  • —Errors such as oversized TLS handshakes or unknown handshakes, oversized certificate chains (more than five certificates), and other unsupported features.
  • —Hardware storage module (HSM) errors such as unknown requests, items not found in the configuration, request timeouts, and other HSM errors and failures.
  • —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.
  • —Errors such as lack of sufficient memory.
  • —Session resumption errors concerning resume session IDs and tickets, resume session entries in the firewall cache, and other session resumption errors.
  • —Errors regarding client and Decryption profile version mismatches and client and server version mismatches. The error messages includes bitmask values that identify the supported client and Decryption profile versions. 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 Message
Additional 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 is applicable 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 is applicable to TLSv1.1-TLSv1.3.
Remediation:
OCSP / CRL check failure
Description:
Sent by clients when an invalid or unacceptable Online Certificate Status Protocol (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 is applicable 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 is applicable to 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 is applicable to TLSv1.1-TLSv1.3.
Remediation:
SNI didn't match with subject name or SAN
General (client or server) certificate error
This message indicates that an error doesn't meet the criteria for any of the aforementioned certificate errors.
Cipher Errors
Decryption Error Message
Additional 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 is applicable 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 includes 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 Message
Additional Information and Resources
Client certificate received
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 is applicable to TLSv1.1-TLSv1.3.
Unsupported feature
This message indicates that an error doesn't meet the criteria for any of the aforementioned feature errors.
HSM Errors
Decryption Error Message
Additional 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
    Device
    Setup
    HSM
    , 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
      Device
      Setup
      HSM
      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
    Device
    Setup
    HSM
    , 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 error
This message indicates that an error doesn't meet the criteria for any of the aforementioned HSM errors.
Protocol Errors
Decryption Error Message
Additional 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, 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 is applicable to TLSv1.1-TLSv1.3.
Remediation:
Private key does not match public key
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 Message
Additional 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 is applicable 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 Message
Additional 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 error
This message indicates that an error doesn't meet the criteria for any of the aforementioned resume errors.
Version Errors
Decryption Error Message
Additional 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 in the Decryption profile.
RFC Information:
This alert falls under the
handshake_failure
error defined in RFC 5246, which is applicable to TLSv1.1-TLSv1.3.
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.
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 includes 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:
    admin@vm1>
    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 for sessions with errors 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. Filter the Decryption Log to identify version errors using the filter
    (err_index eq Version)
    . The highlighted values are bitmask values:
    You can filter the Decryption log in many ways. For example, to see only TLSv1.3 version errors, use the filter
    (err_index eq Version) and (tls_version eq TLS1.3)
    :
  2. Log in to the CLI and look up the bitmask values. The version errors in the first screenshot (the same errors for all three sessions) show an issue with 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. Now you know the issue is that the client only supports a very old version of the TLS protocol and the Decryption profile attached to the decryption policy rule that controls the traffic does not allow TLSv1.0 traffic.
    The next thing to do is decide what action to take. You could update the client so that it accepts a more secure TLS version. 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 allow TLSv1.0 and apply it only to the client devices that must use TLSv1.0 and cannot support a more secure protocol (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. Since the server does not support TLSv1.2, it may only support TLSv1.3 or it may support only TLSv1.1 or lower (less secure protocols). You can use Wireshark or another packet analysis tool to find out which version of TLS the server supports. Depending on what the server supports, you can:
    • If the server only supports TLSv1.3, you could edit the Decryption profile so that it supports TLSv1.3.
    • If the server only supports TLSv1.1 or lower, evaluate whether you need to access that server for business reasons. 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
    Policies
    Decryption
    , select the policy named Big Brother, and then select the
    Options
    tab.
    Decryption profile
    displays the name of the Decryption profile.
    Go to
    Objects
    Decryption
    Decryption Profile
    , select the appropriate Decryption profile, and edit it to address the version issue.

Cipher Errors

Using the Decryption log to hunt down cipher errors is similar to hunting down version errors—you filter the log to find errors and obtain error bitmasks. Then you go to the CLI, convert the bitmask to the error value, and then take appropriate action to fix the issue. For example:
  1. Filter the Decryption Log to identify cipher errors using the filter
    (err_index eq Cipher)
    . For example, let’s examine a cipher error with the
    Error
    message
    Unsupported cipher. Supported client cipher bitmask: 0x80000000. Support 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 client tried to negotiate a cipher that the firewall supports (if the bitmask is all zeros (
    0x0000000
    , then the client tried to negotiate a cipher that the firewall doesn’t support):
    admin@vm1>
    debug dataplane show ssl-decrypt bitmask-cipher 0x80000000
    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 Detailed Log View
    Policy Name
    to get the name of the decryption policy rule that controls the traffic. Go to
    Policies
    Decryption
    and select the rule. On the
    Options
    tab, look up the name of the Decryption profile. Next, Go to
    Objects
    Decryption
    Decryption Profile
    , select the appropriate Decryption 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 a number of 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:

Recommended For You