Repository Management with Nexus

24.2. SSL Client Certificates

24.2.1. SSL Certificate Management

Nexus allows you to manage all SSL certificates directly in the user interface. The administration interface for SSL certificates as visible in Figure 24.1, “SSL Certificates Administration” and can be accessed by selecting SSL Certificates in the left-hand Administration menu. The list of certificates displayed shows the certificate for the SSL-secured Central Repository preconfigured in Nexus Professional and a self-signed certificate registered in Nexus.

[Note]

The SSL Certificate Management is a Nexus Professional feature.

figs/web/ssl-certificates-list.png

Figure 24.1. SSL Certificates Administration


The actual list of SSL certificates can be reloaded by clicking the Refresh button above the list. In addition, certificates can be added and deleted with the Add and Delete buttons.

Pressing the add button provides a choice to load a certificate from a server with the Load from server option or to insert a certificate in PEM format with the Paste PEM.

The dialog to load a certificate from a server allows you to provide a host name, a hostname:port string or a full URL. When providing a host name a connection via http:// using the default SSL port 443 will be attempted. Using a full URL on the other hand gives the most control.

As an example, you could retrieve the certificate for the secured Central Repository using the URL

https://repo1.maven.org

Besides retrieving certificates for servers running HTTPS, you can retrieve and register the certificate for email and directory servers. An LDAP directory server certificate can be loaded with a URL using the LDAPS protocol and the desired host name and port similar to ldaps://localhost:10636. A SMTP server can be queried with a similar pattern using smtps://localhost:465. After successful retrieval, the details of the certificate as displayed in a dialog. Figure 24.2, “Certificate Details Displayed after Successful Retrieval” shows the result from querying a certificate from smtps://smtp.gmail.com:465. Pressing the Add Certificate button will save the certificate within Nexus and allow you to connect to the associated services.

figs/web/ssl-add-server.png

Figure 24.2. Certificate Details Displayed after Successful Retrieval


The dialog displays details about the certificate owner in the Subject section, the certificate issuer in the Issuer section and the certificate itself in the Certificate section. The same data is displayed below the list of certificates,f when you select a specific certificate in the list.

The alternate method of registering a certificate with Nexus uses the PEM format of the X.509 certificate as used by SSL. An example of inserting such a certificate in the dialog is shown in Figure 24.3, “Providing a Certificate in PEM Format”.

figs/web/ssl-pem.png

Figure 24.3. Providing a Certificate in PEM Format


Once a certificate for an LDAP server or SMTP server has been registered in Nexus, you can configure connections to these servers in the LDAP and Server/SMTP Settings administration user interfaces.

24.2.2. Proxying SSL Secured Repositories

When setting up a proxy repository with a remote storage location secured with HTTPS the repository administration will display an SSL configuration tab under the list of repositories if the proxy repository is selected. For a repository using a self-signed certificate, the repository status will initially be set to be in service, but the remote will be automatically blocked and set to be unavailable, since the certificate of the remote server is not trusted. Remote repositories that use a certificate authority(CA)-signed certificate will be automatically trusted.

The SSL tab displays as visible in Figure 24.4, “SSL Tab for a Proxy Repository with Remote Server Using HTTPS” the details of the certificate and allows you to add the certificate to the trust store or to remove it from it with the button on the top right-hand corner named Add to trust store and Remove from trust store respectively.

In addition, the checkbox on the top left corner allows you to store the certificate in the Nexus internal SSL trust store. Otherwise the certificate is installed into the trust store of the Java Virtual Machine (JVM) running Nexus. Using the Nexus internal trust store is recommended. It will work fine, even when migrating Nexus from one machine to another or when switching the Java runtime and JVM between restarts for example during upgrades. At runtime the JVM and Nexus trust stores are merged and both used so you can use a combination, if your organization e.g., maintains a default trust store for all JVM installations.

figs/web/ssl-secure-central.png

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


When removing a certificate from the trust store, a Nexus restart is required.

24.2.3. Manually Configuring Trust Stores

The Nexus user interface should be sufficient to work with the trust stores and certificates. In older versions of Nexus as well as some use cases, you need to manually configure the trust store.

Sonatype provides an import-ssl tool that can be downloaded from http://download.sonatype.com/nexus/import-ssl.jar. It allows you to import a client certificate in two steps:

  • importing the server’s SSL chain and
  • importing the client SSL key/certificate pair.

The Java Virtual Machine running Nexus uses the Java Secure Socket Extension (JSSE) to enable secure Internet communication. It uses two certificate stores - truststore and keystore.

A truststore contains certificates from servers run by other parties with who you expect to communicate, or from Certificate Authorities that you trust to identify other parties. This truststore ships with a number of CA’s out-of-the-box, trusted root certificates.

A keystore contains private keys and the certificates with their corresponding public keys. Typically, they are stored in separate files stored in the default location of ${JRE_HOME}/lib/security/cacerts.

Some notes about the location of the keystore and default keystore passwords:

  • If you are using the default JSSE keystore locations on either a Linux or OS X platform, you must run the commands below as the root user. You can do this either by changing to the root user (su -) or by using the sudo command: sudo [command].
  • The default password used by Java for the built-in keystores is changeit. If your key-store uses a different password, you’ll need to specify that password as the last parameter on the command lines above.
  • If you want to specify your own keystore/truststore file, provide that in place of <keystore_dir> in the examples below.
  • If you’re using a password other than changeit for your keystore, you should supply it immediately following the keystore path in the commands below.
  • If you specify a keystore location that doesn’t exist, the import-ssl utility will create it on-demand.

Before you begin the process of importing a Server SSL Chain and a client certificate you will need the following:

  • Network access to the SSL server you are connecting to,
  • An SSL client certificate,
  • and a certificate password.

For server certificates you should either import directly into ${JRE_HOME}/lib/security/cacerts, or make a copy of the file and import into that.

[Warning]

If you replace the existing truststore rather than adding to it or if you override the truststore location, you will lose all of the trusted CA root certificates of the JRE and no SSL sites will be accessible.

Import the Server SSL Chain

The first command imports the entire self-signed SSL certificate chain for central.sonatype.com into your JSSE keystore:

$ java -jar import-ssl.jar server repo1.maven.org <keystore>

Substitute the server name used in the previous listing with the server name to which you are attempting to connect. This particular command will connect to https://repo1.maven.org, retrieve, and import the server’s SSL certificate chain.

Import the Client SSL Key/Certificate Pair

The second command imports your client-side SSL certificate into the JSSE keystore, so Nexus can send it along to the server for authentication:

$ java -jar import-ssl.jar client <your-certificate.p12> \
<your-certificate-password> keystore

When the client command completes, you should see a line containing the keystore path. Please note this, as you will use it in your next configuration step.

...
Writing keystore: /System/Library/Frameworks/JavaVM.framework/\
Versions/1.6.0/Home/lib/security/jssecacerts

If you want to make a new keystore into which to import your keys, use the keytool that ships with your Java installation to create an empty keystore:

keytool -genkey -alias foo -keystore keystore
keytool -delete -alias foo -keystore keystore
[Tip]

Make sure to use the keytool commands for your Java version used to run Nexus. The documentation for keytool is available online for Java 6 as well as Java 7.

Configuring Nexus Startup

Once both sets of SSL certificates are imported to your keystore and/or truststore, you can modify the wrapper.conf file located in $NEXUS_HOME/bin/jsw/conf/ to inject the JSSE system properties necessary to use these certificates, as seen below adapting the iterator number (10, 11.. ) to start at the last used value, which depends on the rest of your configuration.

warpper.java.additional.10=-Djavax.net.ssl.keyStore=<keystore>
warpper.java.additional.11=-Djavax.net.ssl.keyStorePassword=<keystore_password>
warpper.java.additional.12=-Djavax.net.ssl.trustStore=<truststore>
warpper.java.additional.13=-Djavax.net.ssl.trustStorePassword=<truststore_password>

Once you have configured the Nexus startup option shown above, restart Nexus and attempt to proxy a remote repository which requires an SSL client certificate. Nexus will use the keystore location and keystore password to configure the SSL interaction to accept the server’s SSL certificate and send the appropriate client SSL certificate using the manual configuration you have completed with the import-ssl tool.