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

 

Note: This Get Free Certificate feature is only available in MailArchiva V8

 

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.

 

 

  1. Choose and enter a storage alias name. It is customary, though not required, to use the alias "tomcat".
  2. Enter the fully qualified domain name (FQDN) of the server specified in Step 4 above.
  3. Click "Get free Cert" button.
  4. Once the process is complete, refresh the browser page in Configuration->Certificates to see the installed certificates. 
  5. 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. 

 

DNS Utility Ideas (all these utilities are untested by us. Use at your own risk):
Godaddy - https://github.com/zxvv/dehydrated-godaddy-dns-01/blob/master/godaddy.sh
Namecheap - https://github.com/Bemmu/PyNamecheap
Name.com - https://github.com/aelindeman/namedns

 

 

Generate & install server and trusted certificates

 

Subject Alternative Name (SAN) DNS Field Required: Certificates used in modern web browsers must include a Subject Alternative Name (SAN) DNS extension. Browsers no longer rely on the Common Name (CN) field for hostname validation and require the SAN extension to explicitly list all valid hostnames or IP addresses. The SAN extension should include entries such as *.yourdomain.local to ensure compatibility across all subdomains.

 

 

Manually generate and install a certificate by leveraging the services of a third party Certificate Authority (eg. Sectigo, RapidSSL or 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”.
Note: If creating a wildcard certificate, set the common name to be domain name prepended with a star (e.g. *.mailarchiva.com). If creating a standard certificate, set the common name to the fully qualified domain name (FQDN) of the server (e.g. mailarchiva.mailarchive.com).

 

New Server Certificate

 

  1. 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.

 

If you're setting up HTTPS, use "tomcat" as the alias.

 

  1. Enter the common name of the certificate.

 

If you're setting up HTTPS,  the common name should be the FQDN of the server (e.g. mailarchiva.stimulussoft.com)

 

  1. Complete all the relevant demographic information
     
Avoid entering abbreviated names for cities and states, as many CA's will not accept the signing request.

 

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

Certificate Signing Request

 

  1. 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. Purchase a certificate from a Certificate Authority (e.g. Sectigo, Rapid SSL or Verisign)
  2. Paste in the Certificate Signing Request (CSR) generated earlier.

Verisign CSR

 

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

 

Certificate Copy

 

When using Verisign, the links to download the intermediate and CA certificates are included in the email containing your server certificate.

 

When using RapidSSL, you need to install three CA certificates: the intermediate certificate copied from the email, a Geotrust intermediate and the Equifax CA certificate downloaded from the GeoTrust website. (see: https://www.geotrust.com/resources/root-certificates/).

 

 

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.

 

Finding all required CA certificates: To establish a chain of trust, you need to ensure the server certificate connects back to the root CA certificate. The process begins with understanding that the chain starts from the server certificate and ends at the root CA certificate, with all intermediate CA certificates between them needing to be present. To trace the chain, examine the issuer DN (Distinguished Name) of the server certificate and find a CA certificate whose subject DN matches this issuer DN. Repeat this process for each subsequent CA certificate until you reach the root CA certificate. If you cannot find a matching CA certificate, visit the CA’s website or search online to download the required intermediate or root CA certificates. The root CA certificate is self-signed, meaning its issuer DN and subject DN are identical. When importing certificates, start with the root CA certificate and then import each intermediate CA certificate in sequence, following the chain, until the server certificate is included. This ensures the chain of trust is complete and valid.

 

Import ordering: The order in which certificates are imported is significant. First import the root CA certificate, then the intermediate CA certificate and finally the server certificate. If when importing a certificate, the message "Failed to establish chain from reply" is outputted, it either means the certificates are being imported in the wrong order, or there is a missing certificate in the chain. Sometimes it is necessary to visit your CA website to obtain an additional intermediate certificate.

 

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

 

 

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

 

Note: If there is the need to import more than one intermediate certificate, choose a different Storage Alias for each certificate. For example: intermediate2, .. and so forth.

 

  1. 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).

 

 

  1. 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.


Certificate List

 

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.

Keystore secret

 

Note: For security reasons, MailArchiva will not inform you whether the encryption passphrase is correct or not. If you enter an incorrect passphrase, an incorrect secret will be generated. In such a circumstance, the Tomcat application server would be unable to access the certificates and keys in the keystore.

 

Note: For additional certificate management functions, such as key and certificate export, please refer to the keystore utility included with the Java Runtime.

 

Note: If an incorrect password to the keystore is inputted into the Tomcat TLS connector in Tomcat's server.xml file, the MailArchiva server will not start at all. The error " java.io.IOException: Keystore was tampered with, or password was incorrect" will appear in the catalina.out file (found in /var/opt/mailarchiva/tomcat/logs/catalina.out (Linux) or C:\ProgramData\MailArchiva\Tomcat\logs\catalina.out (Windows). The resolution is to re-enable the 8090 connector, disable the TLS connector, restart the server and perform another keystore lookup using the correct volume encryption password (supplied in the install wizard during the setup of the product).

 

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

 

Note: Do not use quotes when specifying the parameters above.

 

Note: MailArchiva will not be able to access the certificate's private key if the password protecting the key entry is either not set, or set to a password other than the output of Lookup Keystore Secret in Configuration->Certificates.
 
 
Generating a certificate request & importing a certificate

 

MailArchiva On-Premise Hint: Instead of entering the first and last name when prompted to do so, enter the fully qualified domain name (FQDN) of the mailarchiva server (e.g. mailarchiva.company.com)

 

MailArchiva Multitenant (MT) Hint: Instead of entering the first and last name when prompted to do so, enter the domain name the mailarchiva server prefixed with an asterisk. (e.g. *.company.com)

 

Subject Alternative Name (SAN) DNS Field Required: Certificates used in modern web browsers must include a Subject Alternative Name (SAN) DNS extension. Browsers no longer rely on the Common Name (CN) field for hostname validation and require the SAN extension to explicitly list all valid hostnames or IP addresses. The SAN extension should include entries such as *.yourdomain.local to ensure compatibility across all subdomains.

 

 

 

  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.

 

 

 

© 2005 - 2024 ProProfs

Found this information useful? Visit mailarchiva.com to learn more about MailArchiva.

-