How to import untrusted certificates Into IBM Security SOAR

Steps

IBM SOAR might interact with services that do not use trusted SSL certificates (for example, self-signed certificates, certificates issued by an internal certificate authority). Some of these services might include:

• Proxies
• SMTP servers
• Custom threat services
• Active Directory domain controllers

IBM SOAR does not connect to a server with an untrusted certificate. You might find the following error message in the client.log:

java.security.cert.CertificateException: None of the TrustManagers trust this certificate chain

This can occur when IBM SOAR connects to Threat Sources where a proxy is in between IBM SOAR and the Threat Sources server, websvc.resilientsystems.com. If the proxy intercepts the connection and terminates it the SSL certificate returned might not match websvc.resilientsystems.com or *.resilientsystems.com, which means the connection is not trusted.

15:02:03.759 [Co3Scheduler_Worker-2] ERROR com.co3.threat.Co3ThreatFeed - Encountered error when looking up artifact
java.lang.RuntimeException: Unexpected response from https://websvc.resilientsystems.com/rest/artifacts
Caused by: javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: None of the TrustManagers trust this certificate chain

It can also occur after configuring SMTP while not importing the untrusted SSL certificates in to the custcerts keystore. You might see an error when testing the SMTP connection from the IBM SOAR server.

sudo resutil smtptest -email test.user@dexample.com

An error occurred while running the command line utility: Sending the email to the following server failed : smtp.example.com:25
Sending the email to the following server failed : smtp.example.com:25
  Could not convert socket to TLS
    java.security.cert.CertificateException: None of the TrustManagers trust this certificate chain
      None of the TrustManagers trust this certificate chain

If obtaining a trusted certificate is not possible, you may follow these steps to tell IBM SOAR to trust the certificate.

Step 1: Obtain the certificate from the service

echo | openssl s_client -connect <HOST>:<PORT> | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > untrusted_cert.pem

Replace <HOST> with the host name or IP address.

Replace <PORT> with the port where the service is listening on. In most cases, the port is 443.

The subject (CN=) in the certificate must match the URL for which IBM SOAR is using to connect to the service, otherwise you see a hostname mismatch error. You can use Subject Alternate Names (SAN) instead.

The command assumes that there is no chain to import, only a single certificate. In most cases, if you do not import the full chain then IBM SOAR cannot trust the application. To check whether there is a chain, run the following command and check the output.

Chained certificates

openssl s_client -connect <HOST>:<PORT> -showcerts

If there is more than one certificate printed, then you need to copy all the certificates, paste them into a single file in the order of server (leaf) -> intermediate -> root, including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

Alternatively, use this command to return all the certificates in a chain.

keytool -printcert -rfc -sslserver {server}:<port> > cacerts.pem

Keytool is a Java tool widely used by various applications and operating systems which, is installed on the IBM SOAR appliance.

STARTTLS

The previously mentioned commands work well for retrieving certificates from web applications and LDAP but for SMTP servers (including others) that use STARTTLS you might need to do something different.

openssl s_client -starttls smtp -connect <HOST>:<PORT> -crlf -showcerts

This command tells openssl to use the STARTTLS command before starting TLS. Remember, if it is a chain you need to copy the certificates manually.

Step 2: Create a password to protect the custcerts keystore

If /crypt/certs/custcerts doesn't exist, then you need to create a password to protect it.

sudo resutil keyvaultset -name custcerts -value "$(openssl rand -hex 32)"

The command can take about 10 seconds to complete. If it takes longer, then it doesn't have sufficient random data to create the password. You need to log in to the appliance from another terminal and generate random data by typing randomly into the new terminal.

If you are using v32 or higher, use the following command.

sudo resutil keyvaultset -name custcerts -stdin

Enter the password and use Ctrl + D or Command + D to come out as the "enter" or "return" buttons are not accepted. You can use this in combination with $ openssl rand -hex 32 to create a random secure password.

Step 3: Import untrusted certificate into IBM SOAR

This step creates the keystore and imports the certificate.

echo yes | sudo keytool -importcert -trustcacerts -keystore /crypt/certs/custcerts -storepass "$(sudo resutil keyvaultget -name "custcerts")" -file untrusted_cert.pem -alias "<ALIAS>"

Replace <ALIAS> with a name to help you identify the certificate in the keystore (for example, "proxy", "smtp", or "custom threat service").

Additional information

In IBM SOAR system, /crypt/certs/ contains the following files:

• Keystore - the keystore that contains the web application’s certificate and private key.
• Cacerts - the IBM SOAR keystore that contains certificates specific to IBM SOAR. This keystore maybe replaced with each IBM SOAR release.
• Custcerts (optional) - the keystore that contains customer-specific certificates for communication with external systems (for example, SMTP servers, custom threat feeds, etc). IBM SOAR explicitly trusts all certificates within this keystore. This file is not altered during upgrades.

Step 3 adds the untrusted certificate to the custcerts keystore, telling IBM SOAR to trust the certificate.

To list the contents of the custcerts.

sudo keytool -list -v -keystore /crypt/certs/custcerts -storepass "$(sudo resutil keyvaultget -name "custcerts")"

To delete a certificate from custcerts.

sudo keytool -delete -alias <CERT TO REMOVE> -keystore /crypt/certs/custcerts -storepass "$(sudo resutil keyvaultget -name "custcerts")"

To check the certificate in X.509 Base64 encoded format.

openssl x509 -in <third party cert> -text -noout

To check the third-party certificate content.

keytool -printcert -v -file <third party cert>