Decryption Log Errors, Error Indexes, and Bitmasks
Table of Contents
Expand All
|
Collapse All
Next-Generation Firewall Docs
-
-
- Cloud Management of NGFWs
- PAN-OS 10.0 (EoL)
- PAN-OS 10.1
- PAN-OS 10.2
- PAN-OS 11.0
- PAN-OS 11.1 & Later
- PAN-OS 9.1 (EoL)
-
- PAN-OS 10.1
- PAN-OS 10.2
- PAN-OS 11.0
- PAN-OS 11.1 & Later
-
-
-
- Cloud Management and AIOps for NGFW
- PAN-OS 10.0 (EoL)
- PAN-OS 10.1
- PAN-OS 10.2
- PAN-OS 11.0
- PAN-OS 11.1
- PAN-OS 11.2
- PAN-OS 8.1 (EoL)
- PAN-OS 9.0 (EoL)
- PAN-OS 9.1 (EoL)
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.
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 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 error | This message indicates that an error does not meet the criteria for any of the aforementioned certificate 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 applies to
TLSv1.1-TLSv1.3.
Remediation:
|
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.
Decryption Error Message | Additional 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 feature | This message indicates that an error does not meet the criteria for any of the aforementioned feature errors. |
Decryption Error Message | Additional Information and Resources |
---|---|
Unknown request | |
Certificate not found in configuration |
Remediation:
|
Private key not found on HSM |
Remediation:
|
Request to HSM timed out |
Troubleshooting:
Remediation:
|
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 does not meet the criteria for any of the aforementioned HSM 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, 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. |
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 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. |
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. |
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 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:
- 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.
- 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.
- To find the decryption policy rule that controls the session traffic, check the Policy Name column in the log (or click the magnifying glass iconGo 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.
- 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.
- 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. - 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: