X.509 Trusted Certificates

This Credential type is used to store trusted TLS certificates, such as the public certificates of Certificate Authorities (CAs). This is in addition to the generally accepted list of trusted Root CAs contained within the Java KeyStore. Trusted Certificates are used to verify the identity of a remote server or service whilst establishing a secure HTTPS connection from RunMyJobs.

The default HTTPS connection method is to verify the server's certificate. RunMyJobs checks it against the default Java JVM trust store, which will contain the OS or JVM default CAs. If this doesn't work, RunMyJobs checks to see if the server's certificate or root CA is stored as a X509_TrustedCertificate Credential. The Common Name set in the Credentials for these certificates is only a (unique) alias. To make sure it is unique, Redwood suggests setting this to the actual CommonName field as found in the certificate. For example, if the URL is https://client.example.com/path, the CommonName can be set to client.example.com.

A PEM-encoded public certificate will consist of a -----BEGIN CERTIFICATE----- header and a -----END CERTIFICATE----- footer, encoding base-64 encoded text that represents the actual certificate. Text such as Bag Attributes`, such as generated by tools such as openssl during conversion to PEM format, does not need to be manually removed before input.

Only a single certificate should be input into each X.509 Trusted Certificate Credential. The password field will be ignored, and should be left blank for X.509 Trusted Certificate Credentials. The Common Name (endpoint) set in a X.509 Trusted Certificate Credential is a unique alias; to ensure uniqueness, it is suggested that the Endpoint field is set to the actual CommonName found in the certificate.

HTTPS connections verify the hostname by checking whether the hostname or IP address is allowed by the server certificate. If not, either a warning is given in an Operator Message or the connection fails.

The above checks can be configured via the configuration system. The following options have been added:

Http.VerifyHostname
Verify / Warn / DontVerify

The DontVerify option is designed for troubleshooting purposes and should NOT be used.

A description of the current contents of the X.509 Trusted Certificate Credential store can be seen by using System_DynamicTrace with Trace string api.http=debug;http=debug;net=debug

How Trusted Certificates are Used

The default HTTPS connection method verifies the identity of the remote server or service to which RunMyJobs is connecting. This is achieved by the remote server presenting their public certificate combined with the chain of digital signing certificates leading up to a Root Certificate Authority (Root CA). Trust of a remote server certificate is established when RunMyJobs trusts the Root CA, or specifically trusts a self-signed certificate.

The remote server certificate will be checked against the default Java JVM trust store, which will contain the OS or JVM default CAs. On-premises customers can ask their Java system administrator to add extra trusted certificates to this KeyStore.

It is also possible to add extra trusted certificates via X509_TrustedCertificate Credentials.

The Redwood Server will first try to match the root CA certificate of the remote server against the default Java JVM trust store contents. If this match fails, it will look for a match in the X509_TrustedCertificate Credentials. To establish a secure connections to a remote server that presents a certificate issued by one or more private Root and intermediate CAs, you only need to create a X509_TrustedCertificate Credential for the Root CA. But if your connection is to a remote server that presents a self-signed certificate, you will need to create an X509_TrustedCertificate Credential for the self-signed certificate.

HTTPS connections verify the remote server hostname by checking whether the hostname or IP address is allowed by the server certificate. If not, either a warning is given in an Operator Message or the connection fails.

Creating X509 Trusted Certificates using the API

Field	Value
Protocol	X509_TrustedCertificate
Protocol Type	Certificate
Certificate	Where you upload the certificate file.
Password	The Root Certificate in PEM or base64-encoded format.
Common Name	CommonName for the Root CA (recommended), or hostname of the server that is contacted.