4.x Commercial Certificates Guide

Revision as of 22:56, 26 January 2007 by Marcmac (talk | contribs) (Commercial SSL Certificate Procedure)

Commercial SSL Certificate Procedure

Using a pre-existing certificate from another server

If you already have a certificate for this servername, and want to re-use it, [this forum thread] may help.


1. Generate a CSR for tomcat

A. Create a commercial keystore

su - zimbra
keytool -genkey -alias tomcat -keyalg RSA -keystore /opt/zimbra/ssl/ssl/commercial.keystore

Use "zimbra" for the keystore password, and the name of your host for the first/last name. If your organization is Acme Co in San Francisco CA, with the zimbra mail server mailhost.domain.com, the process will look like this:

  zimbra@mailhost$ keytool -genkey -alias tomcat -keyalg RSA -keystore /opt/zimbra/ssl/ssl/commercial.keystore
  Enter keystore password:  zimbra
  What is your first and last name?
    [Unknown]:  mailhost.domain.com
  What is the name of your organizational unit?
    [Unknown]:  Acme Co
  What is the name of your organization?
    [Unknown]:  Acme Co
  What is the name of your City or Locality?
    [Unknown]:  San Francisco
  What is the name of your State or Province?
    [Unknown]:  CA
  What is the two-letter country code for this unit?
    [Unknown]: US
  Is CN=mailhost.domain.com, OU=Acme Co, O=Acme Co, L=San Francisco, ST=CA, C=US correct?
    [no]:  y
  Enter key password for <tomcat>
         (RETURN if same as keystore password):  

B. Create the certificate request file

Remember the password is "zimbra"; this should all be on one line:

keytool -certreq -keyalg RSA -alias tomcat -file /opt/zimbra/ssl/ssl/commercial.csr -keystore /opt/zimbra/ssl/ssl/commercial.keystore

The result is in the file commercial.csr:

cat /opt/zimbra/ssl/ssl/commercial.csr

-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBsTCCARoCAQAwcTELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExDTALBgNVBAcT
BEhlcmUxEDAOBgNVBAoTB0NvbXBhbnkxEDAOBgNVBAsTB0NvbXBhbnkxGjAYBgNVBAMTEW15aG9z
dC5kb21haW4uY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDGFzdhsPg/h5qtpkd9F4wB
IIiajDCLEgfbbwUgBaCb8XiZ6KQEb7cJXrqBqNtJsEPghtLsV52YDmHcNruKWEFRPJdJBM8gHR7p
cFHjYcKJyCa77yhBILqg3iNenRTJNIUXVYzwuBJsa2QWbp8dDbRU5aEn3seFGY/FkeA44KA9UwID
AQABoAAwDQYJKoZIhvcNAQEEBQADgYEAb/nHJZxNpJsP6b2PHVubljRKyxyHDbAopvMLHAgkRxH8
OWOgG/yRJ5Q28csCDAQc/5+Rp/Fn0YDxyqgiAHqQRwCz4QcUSgLSGRijsjNzWhGtQhUzNS1qCgPK
FjfnosOkkGmm51RrPcHCLcjBjhWn4oHZ93NUoTW1hdl6ERc6a6c=
-----END NEW CERTIFICATE REQUEST-----

2. Acquire and install the certificate

Note: You may want to save your existing certs; see the page about Cert Issues

A. Submit the CSR to the certificate authority of choice

To turn that into a certificate, you'll need to paste it into the web form of your favorite certificate vendor (verisign.com, godaddy, etc.) and they'll take some money from you and return a certificate as a file we'll call foo.crt.

B. Import the cert into the commercial keystore

keytool -import -alias tomcat -keystore /opt/zimbra/ssl/ssl/commercial.keystore -trustcacerts -file foo.crt -storepass zimbra

Note: depending on source of CA-signed certificate, you may have issue with cert not being properly DER-encoded for import into your keystore. The error will be "keytool error: java.security.cert.CertificateParsingException: invalid DER-encoded certificate data".

Please check following URL for details on how to convert PEM-encoded to DER-encoded. Keep in mind that default encoding for OpenSSL is PEM (ie. a OpenSSL produced signed cert will produce error above upon import). http://www.modssl.org/docs/2.8/ssl_faq.html#ToC36

successful signed certificate install will return following from above command: "Certificate reply was installed in keystore"

C. Copy the commercial keystore over the zimbra tomcat keystore

cp /opt/zimbra/ssl/ssl/commercial.keystore /opt/zimbra/tomcat/conf/keystore
tomcat restart

Voila! the commercial cert is installed for tomcat.


Note: keep in mind this certificate install process only applies to Zimbra web-based end-user interface (ie. the Tomcat service). In order for certificate to work with other Zimbra network services (SMTP, IMAP proxy, etc), you'll need to follow steps in the "other services" section below. For those with Zimbra Support contract, you may want to contact Support and have them export key/cert from keystore (ie. easier than doing it yourself).

CACert SSL Certificate Procedure

For those who would like to use CACert signed certificate for their Zimbra.

Add CACert's Root CA certificates

Remove the self signed CA.

keytool -delete -alias my_ca -keystore /opt/zimbra/java/jre/lib/security/cacerts -storepass changeit

Download CACert's Root CAs from Class 1 PKI Key and Class 3 PKI Key and save them to a file.

Import these two CAs into Java.

keytool -import -alias cacertclass1ca -keystore /opt/zimbra/java/jre/lib/security/cacerts -import -trustcacerts -file root.crt
keytool -import -alias cacertclass3ca -keystore /opt/zimbra/java/jre/lib/security/cacerts -import -trustcacerts -file class3.crt

Generate a CSR for tomcat

Same as in case of Generate a CSR for tomcat.

Submit the CSR to CACert certificate authority

  • Login to CACert.
  • Select "Server Certificates" or "Org Server Certs" New
  • Paste the content of your /opt/zimbra/ssl/ssl/commercial.csr and Submit it.
  • Copy the content between the begin and end marker (including them)
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

into a file my.crt.

Install your new CRT

Note: You may want to save your existing certs (see the page about Cert Issues)

Import the new CRT

Import the new CRT into the commercial keystore.

keytool -import -alias tomcat -keystore /opt/zimbra/ssl/ssl/commercial.keystore -trustcacerts -file my.crt -storepass zimbra

Copy it into tomcat.

cp /opt/zimbra/ssl/ssl/commercial.keystore /opt/zimbra/tomcat/conf/keystore

You can use the same CRT for other services.

In this case you have to get the key from /opt/zimbra/ssl/ssl/commercial.keystore (this can be a bit complicated.) More complete instructions at Mark Foster's page, or here is an abbreviated version that will work on most UN*Xes:

wget http://mark.foster.cc/pub/java/ExportPriv.java
javac ExportPriv.java
java ExportPriv /opt/zimbra/ssl/ssl/commercial.keystore tomcat zimbra > my.key


Decrypt the certificate key.

openssl rsa -in my.key -out my.key.dec

Add in any intermediate certificates to your .crt file.

If you have a GoDaddy cert or any other certificate that requires an intermediate certificate, append the intermediate certificate to the end of my.crt. Otherwise the certificate chain will be incomplete and you won't be any better off than if you were self-signed.

Install your key and crt for other apps.

cp my.crt /opt/zimbra/conf
cp my.key.dec /opt/zimbra/conf/my.key
cd /opt/zimbra/conf
chmod 444 my.crt
chmod 400 my.key
chown zimbra:zimbra my.crt
chown zimbra:zimbra my.key
ln -s my.crt smtpd.crt
ln -s my.key smtpd.key
ln -s my.crt slapd.crt
ln -s my.key slapd.key
ln -s my.crt perdition.pem
ln -s my.key perdition.key

Restart tomcat (or even better the whole Zimbra server).

Enjoy!


PEM Format Commercial SSL Cert Install Procedure

Jetty

Download the Jetty package, as it contains a useful class that can convert PKCS12 format certificates to JKS format certificates.

Delete Existing Certs

keytool -delete -alias my_ca -keystore /opt/zimbra/java/jre/lib/security/cacerts -storepass changeit
keytool -delete -alias tomcat -keystore /opt/zimbra/tomcat/conf/keystore -storepass zimbra

Add the CA certificate

keytool -import -keystore /path/to/keystore -import -trustcacerts -file /path/to/cacert.cer

Commercial SSL Certificates for Tomcat / Java

If you receive your certificates in the more or less standard PEM format, you need to do the following:

Convert your certificate and key files to a combined PKCS12 format certificate:

openssl pkcs12 -inkey /path/to/file.key -in /path/to/file.crt -export -out file.pkcs12

Convert the PKCS12 certificate to a Java Keystore format (JKS):

java -classpath $JETTY_HOME/lib/org.mortbay.jetty.jar org.mortbay.util.PKCS12Import file.pkcs12 keystore

Note: make sure to set to the keystore password to whatever Zimbra expects (usually "zimbra")


Clone the new keystore certificate stored under the alias "1" to the alias "tomcat":

keytool -keystore keystore -keyclone -alias 1 -dest tomcat

Delete the certificate stored under the "1" alias:

keytool -delete -alias 1 -keystore keystore


Alternative: Use this source to directly create a keystore without having to download jetty.

- Tip: when creating file.pkcs12, set "zimbra" as password.

- First, replace "file.pkcs12" in source code with the name of the certificate you created and compile by executing:

export CLASSPATH=/opt/zimbra/java/lib/tools.jar:.
/opt/zimbra/java/bin/javac AddCertToKeystore.java

- Second, execute newly created .class file to generate new keystore (called keystore-new)

/opt/zimbra/java/bin/java AddCertToKeystore

- Copy new keystore-new to /opt/zimbra/tomcat/conf/keystore. I suggest to backup your old keystore before.

- Restart tomcat.

Source code for AddCertToKeystore.java

import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.security.Key;
import java.security.KeyStore;
import java.security.Security;
import java.security.cert.Certificate;
import java.util.Enumeration;

class AddCertToKeystore
{

public static void main(String[] args) throws Exception
{
Security.addProvider(new com.sun.net.ssl.internal.ssl.Provider());

// Load the pfx file containing Certificate + Private Key
KeyStore temp = KeyStore.getInstance("PKCS12", "SunJSSE");
temp.load(new FileInputStream("file.pkcs12"), "zimbra".toCharArray());

// Create a new Keystore
KeyStore keyStore = KeyStore.getInstance("JKS");
keyStore.load(null, "zimbra".toCharArray());

// Find the alias name of the certificate from the pfx file
Enumeration aliasNames = temp.aliases();
String alias = (String) aliasNames.nextElement();

// Get the certificate chain from .pfx
Certificate c[] = temp.getCertificateChain(alias);
Key key = temp.getKey(alias, "zimbra".toCharArray());

// Store the Private Key + Certificate Chain in the Keystore
keyStore.setKeyEntry("tomcat", key, "zimbra".toCharArray(), c);

// Create the Keystore
keyStore.store(new FileOutputStream("keystore-new"), "zimbra".toCharArray());
}
}

Commercial SSL Certificates for Postfix

If you receive your certificates in the more or less standard PEM format, you need to do the following:

Decrypt the certificate key:

openssl rsa -in file.key -out file.key.decrypted

Move the cert and decrypted key into place:

mv file.crt /opt/zimbra/conf/smtpd.crt
mv file.key.decrypted /opt/zimbra/conf/smtpd.key

QuickSSL References

  1. QuickSSL Homepage
  2. QuickSSL Knowledgebase - search for tomcat installation.

GoDaddy Instructions

(You will be prompted for passwords. Use zimbra for all passwords)

1. Create keystore:

su - zimbra

keytool -genkey -alias tomcat -keyalg RSA -keystore /opt/zimbra/ssl/ssl/commercial.keystore

2. Create CSR (you are creating the commercial.csr file):

keytool -certreq -keyalg RSA -alias tomcat -file /opt/zimbra/ssl/ssl/commercial.csr -keystore /opt/zimbra/ssl/ssl/commercial.keystore

Note: when it asks you for your first and last name use the common name of your server. For example, if you will ultimately use zimbra.company.com as the URL then that is your common name.

3. Open the contents of the commercial.csr file and copy and paste into GoDaddy's CSR submission form.

4. Receive digital cert from GoDaddy as a zip file. Unzip and copy the cert and intermediate cert to a directory on the server. For simplicity, complete the commands below from that directory.

5. Import intermediate and root certs from GoDaddy. The intermediate cert is included in the zip file. The root cert is not. Download the root cert for GoDaddy from: https://certificates.starfieldtech.com/Repository.go

To import root cert: keytool -import -alias root -keystore /opt/zimbra/ssl/ssl/commercial.keystore -trustcacerts -file valicert_class2_root.crt

To import intermediate cert: keytool -import -alias intermed -keystore /opt/zimbra/ssl/ssl/commercial.keystore -trustcacerts -file sf_issuing.crt

6. Import digital cert into keystore:

keytool -import -alias tomcat -keystore /opt/zimbra/ssl/ssl/commercial.keystore -trustcacerts -file [FileNameofCert] -storepass zimbra

7. Copy the keystore to zimbra Tomcat keystore:

cp /opt/zimbra/ssl/ssl/commercial.keystore /opt/zimbra/tomcat/conf/keystore

8. Tomcat restart

9. To turn on HTTPS you must use the zmtlsctl https to allow http and https logins OR zmtlsctl mixed to force https logins but all other traffic will be http.


Mac OSX Note

In order for any changes on this page to go into the appropriate cacerts keystore, the following two paths must be exchanged in order to add the cert to the java trustedcerts...

Linux standard (from doc): /opt/zimbra/java/jre/lib/security/cacerts

OS X location: /System/Library/Frameworks/JavaVM.framework/Versions/1.5/Home/lib/security/cacerts

For example, the command to add a GoDaddy root cert from Valicert to the cacerts keystore would look like:

keytool -import -alias tomcat -keystore /System/Library/Frameworks/JavaVM.framework/Versions/1.5/Home/lib/security/cacerts -trustcacerts -file /opt/zimbra/ssl/<your ssl root_keys path>/valicert_class2_root.crt -storepass changeit

Relevant Documents

  1. Apache Jakarta Tomcat documentation
Jump to: navigation, search