Repository Management with Nexus

21.2. SSL Client Certificates

21.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 21.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 21.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 fand 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 hostname, a hostname:port string or a full URL. When providing a hostname a connection via http:// using the default SSL port 443 will be attempted. Using a full URL on the other hands gives the most control.

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

https://secure.central.sonatype.com

Besides retrieving certificates for servers running https you can retrieve and therefore 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 hostname 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 21.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 21.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 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 21.3, “Providing a Certificate in PEM Format”.

figs/web/ssl-pem.png

Figure 21.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.

21.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 CA signed certificate will be automatically trusted.

The SSL tab displays as visible in Figure 21.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 truststore 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 JVM running Nexus. Using the Nexus internal trust store 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, and is therefore recommended. At runtime the JVM and Nexus trust stores are merged and both used so you can use a combination, if you organization e.g. maintains a default trust store for all JVM installations.

figs/web/ssl-secure-central.png

Figure 21.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.

21.2.3. Manually Configuring Trust Stores

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

Sonatype provides an import-ssl tool, which can be downloaded from: http://central.sonatype.com/help/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 - the truststore and the keystore.

A truststore contains certificates from servers run by other parties that you expect to communicate with, 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

Some notes about the location of the key-store and default key-store passwords:

  • If you are using the default JSSE key-store 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 key-stores 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 key-store/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 three things:

  • 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 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 central.sonatype.com <keystore>

You would substitute the server name used in the previous listing with the server name you are attempting to connect to. This particular command will connect to https://central.sonatype.com, 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, like the one that follows. This path is important; you will use it in your Nexus configuration below, so make a note of it!

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

If you want to make a new keystore to import your keys into, you will have to 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 Start-up

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 start-up 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 complete with the import-ssl tool.