Certificates

MailArchiva provides certificate management functions for generating, installing and managing X509 digital certificates and keys. These certificates and keys are used throughout the product to provide mutually authenticated STARTTLS/SSL security for HTTPS server console access. They are also used for securing incoming SMTP server listeners and outgoing client connections (e.g. SMTP/IMAP/POP). Protecting the server console is a strong requirement, as without which, the master admin password is vulnerable to password sniffers.

Get Free Certificate - Generate a free certificate from Let's Encrypt CA using the ACME protocol

Generate & Install Server And Trusted Certificates - How to generate the server certificate and install trusted CA certificates

Obtaining the Key Store Secret - Obtaining the keystore secret for insertion into Tomcat's server.xml file and general keytool usage.

Using KeyStore Explorer - An alternate GUI for performing certificate management operations on the keystore

Using the KeyTool Command - The use of the Java Keytool command (with respect to the MailArchiva keystore).

Import Existing Private Key - How to import an existing private key

Get free let's encrypt certificate

Obtain and install a free digital certificate from Let's Encrypt Certificate Authority for the purposes of securing the web console (among other uses). Let's Encrypt certificates are typically accepted by all modern browsers. Before Let's Encrypt can issue a certificate, it must verify ownership of the domain to which the certificate is issued. There are two methods available to do this:

1. HTTP challenge verification method - Let's Encrypt obtains and verifies a challenge from MailArchiva on port 80 from outside your network.
2. DNS challenge verification method - Let's Encrypt obtains and verifies a challenge from a TXT entry on your domain's DNS record.  

The advantage of the HTTP challenge verification method is that, provided Let's Encrypt can reach MailArchiva server on port 80, a new certificate can be requested automatically by MailArchiva and obtained from Let's Encrypt before the existing one expires. In contrast, when using the DNS challenge method, a TXT record must be added to your domain's DNS record. Adding the TXT record to the domain's DNS record, can either be done manually using the DNS provider's website, or by using a third-party utility (either open source or supplied by your DNS provider) to update the TXT record automatically. Since Let's Encrypt certificates expire every three months, it may be impractical to update the DNS record manually each time. The main advantage of using the DNS challenge method is that it is possible to generate a Wildcard certificate. A Wildcard certificate is normally only necessary when using MailArchiva Multitenant (MT).

HTTP challenge verification method

  For the automatic certificate retrieval process to work, the MailArchiva server must be accessible on HTTP/port 80 from outside the local area network. The complete set of steps required to obtain a free certificate are outlined below:

1. Switch the MailArchiva server to listen on port 80
   
   Edit /var/opt/mailarchiva/tomcat/conf/server.xml (Linux) or
         C:\ProgramData\MailArchiva\Tomcat\conf\server.xml (Windows)
   
   using a text editor, search and replace 8090 with 80, and restart MailArchiva.
2. Allocate an external IP address to MailArchiva on your firewall
3. Port forward port 80 and 443 from an external IP address on your company firewall to the MailArchiva server
4. Create an A record on your company domain to point to the IP address. (e.g. mailarchiva.company.com)
5. Verify that MailArchiva is accessible on port 80 from outside your network. For example, to verify that the server is accessible from outside, hit the url http://mailarchiva.company.com in a web browser.
6. In the Certificates tab of Configuration, click “Get free cert” button.
7. Select HTTP as a challenge method.

7. Choose and enter a storage alias name. It is customary, though not required, to use the alias "tomcat".
8. Enter the fully qualified domain name (FQDN) of the server specified in Step 4 above.
9. Click "Get free Cert" button.
10. Once the process is complete, refresh the browser page in Configuration->Certificates to see the installed certificates. 
11. If you enter a storage alias of tomcat above, the server certificate storage alias will be "letsencrypt.org-server-tomcat". This is the alias name that must be entered in the Tomcat HTTP/S connector.

MailArchiva will fetch a new server certificate and all CA certificates in the trusted chain from Let's Encrypt and install them. Once the certificates are installed, MailArchiva can be configured for HTTP/S authentication. The server certificate is only valid for 3 months. A new one will need to be manually generated when the old one is near to expiry. 

DNS challenge verification method

1. In the Certificates tab of Configuration, click “Get free cert” button.
2. In the storage alias field, enter tomcat.
3. In the server domain field, enter the equivalent of "mailarchiva.company.com" as domain or "*.company.com" if a wildcard certificate is to be generated.
4. Click "Get free Cert" button.
5. The following message will be outputted in the process window. 
   Please create a TXT record:_acme-challenge.gcommerce.info. IN TXT OJ_D9JF-3ctIsL1c8FLgHU-xmgyv62eJFTqcY0zXC3Q
   Challenge written to the file C:\ProgramData\Application Data\MailArchiva\central\temp\dns_challenge.txt. Please use your DNS provider utility to update your DNS record
6. The DNS challenge may either be added manually or automatically using a third-party utility (either supplied by your DNS provider or available as open source)
   1. To add the TXT record entry manually, login to your DNS provider's website, manage the domain in question, and add the TXT record with the key "_acme-challenge" and input the outputted challenge as the value.
   2. Adding the TXT record automatically will require the use of a specialized utility supplied by your DNS provider or available as open source. Write a cron-job to (a) detect the presence of the file dns_challenge.txt (b) when the file is present, automatically push the challenge to your DNS record (b) delete the dns_challenge.txt file. Every three months, MailArchiva will create a new challenge, and your utility can sync it with the DNS provider.
7. Once the process is complete, refresh the browser page in Configuration->Certificates to see the installed certificates. 
8. If you enter a storage alias of tomcat above, the server certificate storage alias will be "letsencrypt.org-server-tomcat". This is the alias name that must be entered in the Tomcat HTTP/S connector.

MailArchiva will fetch a new server certificate and all CA certificates in the trusted chain from Let's Encrypt and install them. Once the certificates are installed, MailArchiva can be configured for HTTP/S authentication. The server certificate is only valid for 3 months. A new one will be automatically generated when the old one is near to expiry. 

Generate & install server and trusted certificates

Manually generate and install a certificate by leveraging the services of a third party Certificate Authority such as Verisign, using the standard Certificate Signing Request (CSR) process. Certificates are used to secure the web console with HTTP/S.

Step 1. Generate a Certificate Signing Request (CSR)

1. In the Certificates tab of Configuration, click “New Server Cert”.

2. Choose and enter a storage alias. This alias is an arbitrary name (chosen by you) that you will later use to refer to the certificate.

3. Enter the common name of the certificate.

4. Complete all the relevant demographic information
    

5. Click the “Generate New Cert Request” to generate the Certificate Signing Request
    
6. Select and copy the certificate signing request to the clipboard. Close the New Server Cert dialog.

6. You should see a place holder for your signing certificate listed in the Server Certificates list in the Certificates tab.

Step 2. Obtain certificates from the Certificate Authority (CA)
 

1. Obtain a free 15 day trial SSL certificate / purchase a certificate from a CA such as Verisign.
    

1. Paste in the Certificate Signing Request (CSR) generated earlier.
    

3. In most cases, the server certificate and CA certificates will be mailed to you
4. Create a folder on your Desktop called Certificates
5. Open a text editor and paste the contents of the server certificate. Name the file as "server.cert" and save into the Certificates folder.
6. Similarly, copy the intermediate CA certificate to a text file called intermediate.cert.
7. Finally, copy the CA root certificate to a text file called root.cert.

Step 3. Import the certificates

MailArchiva supports importing CA and server certificates using Pkcs 12 (*.p12, *.pfx), Pkcs 7 (*.p7b),  JKS (*.jks), PEM (*.pem) and DER (*.cert) file formats. The instructions below illustrate how to import certificates in DER format (*.cert). The instructions for importing certificates may vary slightly depending on the format of the certificates supplied by your CA. 

1. Click “Import CA Cert” button, select the root.cert file, select file format DER, enter “root” as the storage alias and click Import.

2. Click “Import CA Cert”, select the intermediate.cert file, , select file format DER, enter “intermediatecert” as the storage storage and click Import.

3. Click “Import Server Cert”, select the user.cert file and select file format DER. Select the same alias as used in the CSR generation step above (e.g. tomcat).

4. If all goes well, the server certificate and CA certificates should be visible in the Certificates list. Click Save to commit your changes to the keystore.

Obtaining the keystore secret

The private key and certificates are stored in a standard Java keystore file. This file is called mailarchivacerts and is located in the Configuration directory.

Since MailArchiva's certificate store contains highly sensitive data, the following should be noted:

• The keystore itself and the server certificate's private key are password protected separately, albeit using the same password.
• The password protecting both the keystore and the private key is constructed from the volume encryption password.
• The keystore secret password can always be obtained by performing a keystore secret lookup in MailArchiva Console in Configuration->Certificates.

There are two main reasons why it may be necessary to obtain the password to MailArchiva's keystore:

• HTTP Setup - Tomcat HTTPS configuration (server.xml).
• Java keytool - Performing various maintenance functions (updating certificates, etc.)

In order to obtain the keystore secret for either of the above use-cases, follow the steps below:
 

1. In Configuration->Certificates, Click the Lookup Keystore Secret button.
2. Enter the volume encryption password entered at the time when MailArchiva was setup.
3. Click the Generate button
4. Copy the Keystore Secret string to the clipboard.

Using  Keystore Explorer
 

MailArchiva's keystore is loaded from a file called mailarchivacerts, located in the Configuration directory. This file may be opened using KeyStore Explorer, an alternate certificate management utility. To perform operations on the keystore, the explorer utility requires the secret key to unlock it. The password to the keystore, and private keys therein, may be obtained from the get keystore secret function. When importing private keys, the password to the entry must also be set to get the key store secret output. After making changes to the mailarchivacerts file, it is necessary to restart MailArchiva for the changes to be reflected.

Using the Java Keytool command

Advanced certificate management operations can be performed directly using the Java keytool utility. This utility is included with the JRE embedded in MailArchiva (e.g. /opt/mailarchiva/server/jre64/bin or C:\Program Files\MailArchiva\server\bin). The use of the keytool utility is widely documented.

To use the keytool utility in conjunction with MailArchiva's certificate store, it is necessary to obtain the secret to MailArchiva's key store described above.

There are two encryption keys associated with a Java keystore.

1. Entire keystore file is protected using a passphrase (specified by -deststorepass)
2. Individual keys can be encrypted using a passphrase (specified by -destkeypass)

MailArchiva requires that the passphrases associated with key entries are set to the same keystore password.

Listing certificates

To list the certificates in the MailArchiva keystore, obtain the key store secret as described above. Thereafter, execute the keytool list command as follows:

keytool -list -v -keystore mailarchivacerts

Enter keystore password: [enter the keystore secret]

Moving certificates and keys from an outside Keystore

The following command moves the certificate and private from an outside keystore into MailArchiva's key store:

keytool -importkeystore -srckeystore mailarchivakeystore -destkeystore mailarchivacerts -srcstorepass [srcstorepass] -deststorepass [destinationstorepass] -destkeypass [destinationstorepass]

where [destinationstorepass] above is the result of the Lookup Keystore Secret in Configuration->Certificates

Generating a certificate request & importing a certificate

1. Create a new key store:
   keytool -genkey -alias tomcat -keyalg RSA -keystore \path\to\my\keystore.jks (desired path to key store... e.g. \root\keystore.jks)
2. Generate a certificate signing request:

   keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr -keystore

3. Request a certificate using the desired reputable Certificate Authority, and paste in the CSR (outputted in step 2 above) as part of their certificate request process.
4. Save the chain in Base 64 format
5. Export each certificate in Base 64 format
6. Import the chain one certificate at a time, starting with root:

   keytool -import -alias root -keystore -trustcacerts -file b. keytool -import -alias tomcat -keystore -trustcacerts -file

7.  Setup the TLS connector in MailArchiva's embedded Tomcat server's server.xml file. This server.xml file is located at C:\Program Files\MailArchiva\Server\conf\server.xml (Windows) or /opt/mailarchiva/server/conf/server.xml (Linux)

Private key import

Under normal circumstances, to install a certificate in MailArchiva, the certificate request process must be followed. As part of the CSR process, a private key is generated and stored in the MailArchiva keystore. However, should you already possess a private key that needs to be imported into MailArchiva, it can be imported using the Private Key Import function. MailArchiva supports importing private keys using PKCS 12 (*.p12, *.pfx) format, PKCS8 (*.pem) and Java Keystore (*.jks) format. To import a private key, go to Configuration->Certificates, click the Import Private Key button. Select PKCS-12 as the import format (for example). Enter the password to the PKCS-12 file. Click Import. The contents of the PKCS-12 file will be imported into MailArchiva's keystore. Take note of the aliases used to store the certificate. Click Save to persist the changes to the keystore.