Skip to main content

Generate an SSL Keystore

Mango uses a Java KeyStore (JKS) file to store SSL/TLS certificates for HTTPS connections. This guide explains how to create a keystore from commercial SSL certificates (.cer and .ca-bundle files) and configure Mango to use it. For free certificates from Let's Encrypt, see SSL with Certbot instead.

Prerequisites​

  • A private key that was used to generate the Certificate Signing Request (CSR).
  • The signed certificate file (.cer or .crt) from your certificate authority.
  • The CA bundle file (.ca-bundle) containing intermediate certificates.
  • OpenSSL installed on your system.
  • Java's keytool utility (included with the JDK).

Step 1: Generate a Certificate Signing Request (CSR)​

If you have not already generated a CSR, create one using OpenSSL. The Common Name should be the domain name or URL that Mango will be accessed at.

openssl req -new -newkey rsa:2048 -nodes -keyout server.key -out server.csr

Submit the server.csr file to your certificate authority (CA) to obtain the signed certificate. For detailed instructions on CSR generation, see Namecheap's guide for Apache/OpenSSL/Nginx.

Step 2: Create a PKCS12 Keystore​

Combine the signed certificate, private key, and CA bundle into a PKCS12 keystore:

openssl pkcs12 -export \
  -certfile YOUR_DOMAIN.ca-bundle \
  -inkey server.key \
  -in YOUR_DOMAIN.crt \
  -name mango \
  -out keystore.p12 \
  -passout pass:YOUR_STRONG_PASSWORD

Replace YOUR_DOMAIN with your actual certificate filenames and YOUR_STRONG_PASSWORD with a password of at least 6 characters.

note

If you have .pem files instead of .cer and .ca-bundle, use the certificate .pem for the -in argument and the key .pem for -inkey.

Step 3: Convert to a Java Keystore (JKS)​

Use Java's keytool (found in your JDK's bin directory) to import the PKCS12 keystore into a JKS keystore:

keytool -importkeystore \
  -destkeystore /path/to/keystore.jks \
  -srckeystore keystore.p12 \
  -srcstoretype PKCS12 \
  -alias mango \
  -srcstorepass YOUR_STRONG_PASSWORD

When prompted, enter a destination keystore password (use the same password or a new strong password).

Step 4: Deploy the Keystore​

  1. Copy the keystore.jks file to a secure location within your Mango installation directory (e.g., MA_HOME/overrides/properties/).
  2. Set appropriate file permissions so only the Mango user can read it:
chown mango:mango /path/to/keystore.jks
chmod 400 /path/to/keystore.jks

Step 5: Configure Mango​

Edit your mango.properties file to enable SSL and point to the keystore:

ssl.on=true
ssl.port=443
ssl.keystore.location=/path/to/keystore.jks
ssl.keystore.password=YOUR_STRONG_PASSWORD

If the key inside the keystore has a different password than the keystore itself, also set:

ssl.key.password=YOUR_KEY_PASSWORD

Step 6: Restart Mango​

Restart Mango for the SSL configuration to take effect. Access Mango at https://your-domain.com.

Verifying the Certificate​

After restarting, verify the certificate is working correctly:

  • Navigate to https://your-domain.com in a browser and check that the padlock icon appears.
  • Use OpenSSL to verify the certificate chain: openssl s_client -connect your-domain.com:443
  • If using a self-signed certificate, the browser will show a security warning. This is expected for self-signed certificates.

Troubleshooting​

Port Permission Error on Linux​

Binding to port 443 requires root privileges on Linux. Either:

  • Run Mango as root (not recommended for production).
  • Use setcap to allow the Java binary to bind to privileged ports: sudo setcap 'cap_net_bind_service=+ep' $(readlink -f $(which java))
  • Use a reverse proxy on port 443 that forwards to Mango on a high port. See Reverse Proxy Configuration.

Keystore Password Mismatch​

If Mango fails to start with a "Keystore was tampered with, or password was incorrect" error, verify the password in mango.properties matches the password you used when creating the keystore.

Certificate Chain Incomplete​

If browsers report "certificate not trusted," ensure the CA bundle (intermediate certificates) was included when creating the PKCS12 keystore in Step 2.