The CA API Gateway ("Gateway") can present a multitude of unique certificate-related errors in the audits or logs. The common ones are compiled in this article for convenience, with common root causes and resolutions.

Release:
Component: APIGTW ( all versions )

Certificate Not Verified

Error presents itself as follows:

• Unable to obtain HTTP response from https://<hostname>.<yourdomain>.com/path/to/remote/service: Certificate not verified.

This indicates that the Gateway was unable to establish trust with a remote system. This could be because the Gateway does not trust the issued certificate implicitly or it does not trust the issuer of a certificate. To resolve this issue:

1. Verify the certificate of the remote service or the issuer of said certificate is added to the Manage Certificates task. Add the certificate to the Gateway if it does not already exist.
2. Verify the certificate of the remote service or the issuer of said certificate has not been revoked on the API Gateway.

Bad Certificate

Error presents itself as follows:

1. Unable to obtain HTTP response from https://<hostname>.<yourdomain>.com/path/to/remote/service: Fatal Alert received: Bad Certificate
2. This error may also include an error code of {48}

This indicates that the API Gateway's certificate was rejected by the remote system. This could be because the remote system does not trust the certificate presented by the API Gateway or the issuer of the API Gateway's certificate. To resolve this issue:

1. Verify the certificate of the API Gateway or the issuer of said certificate is trusted by the remote system. The process for this will vary by the end point being contacted.
2. Verify the certificate of the API Gateway or the issuer of said certificate has not been revoked by the remote system. The process for this will vary by the end point being contacted.

Host Name Does Not Match Certificate

Error presents itself as follows:

• Unable to obtain HTTP response from https://<hostname>.<yourdomain>.com/path/to/remote/service: Host name does not match certificate '<hostname>.<yourdomain>.com'.

This indicates that the API Gateway was unable to match the CN value of the certificate presented by the remote system to the host name of the remote system being contacted. If the CN value of the certificate being presented does not match the hostname of the system being contacted, this error will occur. To resolve this:

1. Set the io.httpsHostVerify cluster-wide property to the boolean false.

This issue can also occur because a certificate issued by an authority is a wildcard certificate. This means that this valid for multiple individual hosts and is not specific to a single host. By default, the API Gateway takes the least trustful behaviour. Trusting a wildcard value for the hostname is not a default behaviour and must be enabled by an administrator To resolve this:

1. Set the io.httpsHostAllowWildcard cluster-wide property to the boolean true.

Documentation: Managing cluster-wide properties in the CA API Gateway

Certificate Path Validation And/Or Revocation Checking Failed

Error presents itself as follows:

• Unable to obtain HTTP response from https://<hostname>.<yourdomain>.com/path/to/remote/service: Certificate not verified. Caused by: Certificate path validation and/or revocation checking failed

This indicates that the Gateway rejected the certificate presented by the remote system because it was explicitly not trusted. This is due to a failure in the certificate validation process-either in validating the trust chain of the issuer or because a certificate or authority is explicitly revoked. Typically, this is caused by the Gateway not being able to fully follow the trust chain of a certificate presented by the remote system that is not self-signed. To resolve this issue:

1. Verify the certificate of the intermediary and/or root certificate authority is saved in the Manage Certificates dialog.
2. Ensure the certificate is trusted for signing client certificates and the certificate for a root CA is configured to act as a trust anchor.
3. Certificates that have an extended key usage policy set to critical. If a policy is marked critical and the application can’t interpret the policy, it should reject it . Work with your PKI vendor to disable the critical setting. You can verify this by opening the certificate as a .crt extension and viewing the Details tab and showing Critical Extensions Only.

More information on importing certificates as trusted issuers can be found here: Sign a certificate

CA Cert(s) Found but Not Trusted for Signing SSL Server Certs

Error presents itself as follows:

• Unable to obtain HTTP response from https://<hostname>.<yourdomain>.com/path/to/remote/service: Certificate not verified. Caused by: CA Cert(s) with DN 'cn=ca.<yourdomain>.com' found but not trusted for signing SSL Server Certs.

This indicates that the API Gateway sees a CA certificate in the trust chain of a certificate returned by an endpoint but that the CA certificate is not explicitly or implicitly trusted to issue client certificates.  To resolve this issue:

1. Import one or all of the intermediate and root CA certificates into the Manage Certificates task.
2. Ensure Outbound SSL Connection is set as an enabled option.

For more information on adding certificates to the API Gateway's certificate trust store, please review Chapter 3 of the Layer 7 Policy Manager User Manual -- Managing Certificates: Adding a New Certificate.

Server Cert Found but Not Trusted For SSL

Error presents itself as follows:

• Unable to obtain HTTP response from https://<hostname>.<yourdomain>.com/path/to/remote/service: Certificate not verified. Caused by: Server cert 'cn=system.<yourdomain>.com' found but not trusted for SSL.

This indicates that the API Gateway is rejecting a certificate presented by the remote system because it or a portion of its trust chain is not trusted specifically for SSL communication. To resolve this issue:

1. Import one or all of the intermediate and root CA certificates into the Manage Certificates task.
2. Ensure Signing Certificates for Outbound SSL Connections is set as an enabled option.
3. Ensure Signing Client Certificates is set as an enabled option.

Additionally, this error could occur due to an inconsistency between a certificate stored in the Manage Certificates trust store and the certificate provided by server. If the distinguished name of a certificate stored in the trust store matches the distinguished name of a certificate used by the server but the certificate itself does not match then this error will occur. To resolve this problem:

1. Export the certificate stored in the Manage Certificates trust store.
2. Export the certificate from the appropriate server.
3. Compare them for differences.

Specifically, the values for the modulus and thumbprint of each certificate will likely show differences. If these values are different then the certificates are different. This is the core of the issue: The certificates are different but the distinguished names are the same. This results in a certificate being found (as indicated by the log entry) but not matching the existing certificate.

Additionally, the error can be seen if the remote system certificates are not in the trusted certificates list of the routing assertion. To check the trusted certificates list on the Route Via HTTP(S) assertion, edit the Route Via HTTP(S) Assertion > Connection tab > Trusted Server Certificates. It must have the "Trust all Trusted Certificates" selected or otherwise will need to add the remote server certificates in the "Trust only the specified Trusted Certificates" list.

For more information on adding certificates to the API Gateway's certificate trust store, please review Chapter 3 of the Layer 7 Policy Manager User Manual--Managing Certificates: Adding a New Certificate.

Received Record Has Incorrect Protocol Major Version

Error presents itself as follows:

• Unable to obtain http response from https://<hostname>.<yourdomain>.com/path/to/remote/service?wsdl: Received record has incorrect protocol major Version.

This indicates that the API Gateway is trying to make an outbound SSL connection to a remote system and the API Gateway was unable to find an agreed upon an SSL/TLS version to use for the connection. Most typically, this occurs when the API Gateway is trying to connect to a remote system that is requiring SSLv3. SSLv3 support has been disabled on the API Gateway and special steps must be taken to utilize SSLv3. You can re-enable SSLv3 in the Route via HTTP(S) assertion under the "Security Tab." If you require instructions for enabling SSLv3 globally, please contact Support for more information.

Unknown CA

Error presents itself as follows:

• Unable to obtain HTTP response from https://<hostname>.<yourdomain>.com/path/to/remote/service?wsdl: Received fatal alert: unknown_ca

This error occurs when negotiating client mutual authentication via SSL and the remote system does not trust the CA or issuer of the certificate the API Gateway is presenting. When mutual authentication is being initialized, each side requests the trusted CA allowed for the transaction. If the issuer of the certificate presented by the API Gateway is not trusted by the remote system, the connection will fail. To resolve this issue:

1. Save the certificate of the issuing authority in PEM-encoded format to your workstation
2. Edit the "io.httpsAcceptedClientCa" property in Manage Cluster-Wide Properties
3. Add the PEM-encoded certificate of the CA into the cluster-wide property, including the BEGIN CERTIFICATE and END CERTIFICATE lines
4. Restart the API Gateway (SSG) service

For more information on adding or updating API Gateway cluster-wide properties, please review Chapter 2 of the Layer 7 Policy Manager User Manual -- Managing Cluster-Wide Properties.

Certificate Not Presented to API Gateway

Error presents itself as follows:

• No Client Certificate was present in the request

This error occurs when using SSL/TLS and requiring a client certificate, but none is presented. This is due to the client not receiving a list of acceptable CAs from the API Gateway on it's ACK during the SSL Handshake. This is expected behaviour for TLS 1.0 per standards. To resolve this issue:

1. You can toggle TLS 1.1 on the listen port being used. This will cause the API gateway to present the CA list during the handshake per TLS 1.1 standards. Enabling TLS 1.1 can have further reaching implications past simply enabling this list, so it is recommended that this be tested in a lower environment before moving forward.
2. You can edit the "io.httpsAcceptedClientCa" property in Manage Cluster-Wide Properties by adding a trusted CA. Having this list populated will cause the API Gateway to send a trusted CA list regardless of the protocol version of TLS enabled.
3. You are also able to set the listen port advanced property "acceptedIssuers" to "true" to resolve this issue. This will force the API Gateway to present this list regardless of the protocol version of TLS that is enabled.

For more information on configuring the TLS settings of an active Listen Port, please review Chapter 2 of the Layer 7 Policy Manager User Manual--Managing Listen Ports.

For more information on adding or updating API Gateway cluster-wide properties, please review Chapter 2 of the Layer 7 Policy Manager User Manual--Managing Cluster-Wide Properties.

Unknown Certificate

Error presents itself as follows:

• Unable to obtain HTTP response from https://<hostname>.<yourdomain>.com/path/to/remote/service?wsdl: Received fatal alert: Certificate Unknown

This error occurs when using SSL/TLS to communicate with a protected service and the protected service is requiring a client certificate from the API Gateway. This error will be presented when the protected service completely rejects the certificate provided by the API Gateway. In this case, the certificate provided by the API Gateway to the protected service is not trusted or the issuer of the API Gateway's certificate is untrusted. To resolve this error:

1. Configure the protected service or application to trust the API Gateway's certificate or
2. Configure the protected service or application to trust the issuer of the API Gateway's certificate or
3. Disable client certificate authentication in the protected service or application.

SSL Verification Failed

Error presents itself as follows:

• Problem routing to https://<hostname>.<yourdomain>.com/aresource. Error msg: Unable to obtain HTTP response from https://<hostname>.<yourdomain>.com/aresource: SSL verification failed! Request routing failed with status 601 (Error in Assertion Processing) 

This error can occur when the backend certificate has a wild card in the CN.  By default the gateway does not trust them, this behavior can be overwritten by setting io.httpsHostAllowWildcard cluster-wide property to the boolean value of true.

It can also occur when the backend hostname is completely different with the backend server certificate CN,  or it try to use intermediate or root CA as trusted anchor. 

If it try to use intemediate or root CA certificate as trusted anchor for certificate verification, set io.httpsHostVerify as false. 

Sample error message:

• Problem routing to https://backendurl: SSL verification failed!

Sample curl command and error message:

• curl -v https://backendurl
• curl: (60) SSL: no alternative certificate subject name matches target host name 'backend hostname'

Sample hostname and CN:

• hostname: example.com
• CN: CN=example.net

Solution: Re-generate correct server certificate

Workaround: set io.httpsHostVerify as false