Managing Outbound SSL Certificates in Nexus Repository 2

Available in Nexus Repository Pro only

When the SSL certificate of a remote proxy repository is not trusted, the repository may be automatically blocked or outbound requests fail with a message similar to PKIX path building failed.

Nexus Repository Manager Pro includes a specific SSL configuration tab for each repository in the repository configuration documented in Managing Repositories to solve this problem. It is displayed when the remote URL of a proxy repository resolves to an https:// location.

The SSL tab shows the details of the remote certificate, as in the example Figure 23.1, “SSL Tab for a Proxy Repository with Remote Server Using HTTPS”. Use the 'SSL’ tab when the remote certificate is not issued by a well-known public certificate authority included in the default Java trust store. This specifically also included usage of self-signed certificates used in your organization.

To confirm trust of the remote certificate, click the Add to trust store button on the top-right of the SSL tab. This feature is analogous to going to the Figure 23.2, “SSL Certificates Administration” user interface and using the Add button found there. If the certificate is already added, the button can undo this operation and will read Remove from trust store .

The checkbox labelled Use Nexus SSL trust store is used to confirm that the repository manager should consult the private, internal truststore when confirming trust of the remote repository certificate. Without adding the certificate to the private truststore and enabling the checkbox, the repository will not trust the remote.

The default JVM truststore of the JVM installation used to run the repository manager and the private truststores are merged. The result of this merge is used to decide about the trust of the remote server. The default Java truststore already contains public certificate authority trust certificates. If the remote certificate is signed by one of these authorities, then explicitly trusting the remote certificate will not be needed.

Figure 23.1. SSL Tab for a Proxy Repository with Remote Server Using HTTPS

Available in Nexus Repository Pro only

Nexus Repository Manager Pro allows you to manage trust of all remote SSL certificates in a centralized user interface. Use this interface when you wish to examine all the currently trusted certificates for remote repositories, or manage certificates from secure remotes that are not repositories.

Access Figure 23.2, “SSL Certificates Administration” by selecting SSL Certificates in the left-hand Administration menu. The list shows any certificates that are already trusted.

Figure 23.2. SSL Certificates Administration

Buttons are provided to Refresh the list from the server, Add a new certificate or Delete the selected certificate.

The Add button presents two options - Paste PEM and Load from server.

There are two types of secure addresses supported by the Load from server option.

The common approach is to choose Load from server and enter the full https:// url of the remote site, e.g, https://repo1.maven.org . The repository manager will connect using HTTPS and use the HTTP proxy server settings if applicable. Any other protocol than https:// is ignored, and a direct socket connection is attempted in that case.

When the remote is not accessible using https://, only enter the host name or IP address, optionally followed by colon and the port number. For example: example.com:8443. In this case repository manager will attempt a direct SSL socket connection to the remote host at the specified port.

Alternatively you can choose the Paste PEM option to configure trust of a remote certificate. Copy and paste the Base64 encoded X.509 DER certificate to trust. This text must be enclosed between lines containing -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

An example method to get the encoded X.509 certificate into a file on the command line using keytool is:

keytool -printcert -rfc -sslserver repo1.maven.org > repo1.pem

The resulting repo1.pem file will contain the encoded certificate text that you can cut and paste into the dialog. An example of inserting such a certificate is shown in Figure 23.3, “Providing a Certificate in PEM Format”.

Figure 23.3. Providing a Certificate in PEM Format

If the repository manager can successfully retrieve the remote certificate or decode the pasted certificate, the details will be shown in a dialog allowing you to confirm details as shown in Figure 23.4, “Certificate Details Displayed after Successful Retrieval”. Please review the displayed information carefully before clicking Add Certificate to establish the trust store addition.

Figure 23.4. Certificate Details Displayed after Successful Retrieval

In some organizations, all of the remote sites are accessed through a globally configured proxy server which rewrites every SSL certificate. This single proxy server is acting as a private certificate authority. In this case, you can follow special instructions for trusting the proxy server root certificate , which can greatly simplify your certificate management duties.

Available in Nexus Repository OSS and Nexus Repository Pro

Managing trusted SSL certificates from the command line using keytool and system properties is an alternative and more complex option than using the SSL certificate management features of Nexus Repository Manager Pro.

Before you begin the process of trusting a certificate from the command line you will need:

If you are connecting to servers which have certificates that are not signed by a public CA, you will need to complete these steps:

wrapper.java.additional.10=-Djavax.net.ssl.trustStore=<truststore>
wrapper.java.additional.11=-Djavax.net.ssl.trustStorePassword=<truststore_password>