Difference between revisions of "5.x Commercial Certificates Guide"

(Undo revision 8818 by Anup@zimbra.com (Talk))
Line 1: Line 1:
 
=General Overview=
 
=General Overview=
 
Installing a commercial certificate in ZCS version 5.0.0_GA and above is a straightforward process.  The following is an overview of the steps you will take to install a commercial certificate.  
 
Installing a commercial certificate in ZCS version 5.0.0_GA and above is a straightforward process.  The following is an overview of the steps you will take to install a commercial certificate.  
#Generate a CSR via the '''Administration Console Certificates''' or via the '''zmcertmgr''' command line utility.
+
#Generate a CSR via the '''Administration Console Certificates''' or via the '''zmcertmgr''' command line utility.
 
#Receive the signed certificate.
 
#Receive the signed certificate.
 
#Receive the chain_certificates (if applicable).
 
#Receive the chain_certificates (if applicable).
Line 11: Line 11:
 
If the Administration Console Certificates Wizard is not doing the job, we then resort to the command line.   
 
If the Administration Console Certificates Wizard is not doing the job, we then resort to the command line.   
  
'''''Note:''' This tool must be run as root.''   
+
'''''Note:''' This tool must be run as root.''   
  
 
It requires the following:
 
It requires the following:
  
*The private key must exist in '''/opt/zimbra/ssl/zimbra/commercial''' directory and must be named '''commercial.key''' with permission set to '''740'''.
+
*The private key must exist in '''/opt/zimbra/ssl/zimbra/commercial''' directory and must be named '''commercial.key''' with permission set to '''740'''.
*The server certificate and the chain cert files must exist in a temp directory. E.g. '''/root/certs'''
+
*The server certificate and the chain cert files must exist in a temp directory. E.g. '''/root/certs'''
*The server cert must be named '''commercial.crt'''.
+
*The server cert must be named '''commercial.crt'''.
 
*The chain cert files must be concatenated into one file called commercial_ca.crt.
 
*The chain cert files must be concatenated into one file called commercial_ca.crt.
 
*Verify that the cert and the key match using this command:
 
*Verify that the cert and the key match using this command:
  /opt/zimbra/bin/zmcertmgr verifycrt comm /opt/zimbra/ssl/zimbra/commercial/commercial.key commercial.crt commercial_ca.crt  
+
  /opt/zimbra/bin/zmcertmgr verifycrt comm commercial.crt commercial_ca.crt  
 
*From the temp directory, deploy the cert and restart the zimbra services.
 
*From the temp directory, deploy the cert and restart the zimbra services.
 
  (a) sudo zmcertmgr deploycrt comm   
 
  (a) sudo zmcertmgr deploycrt comm   
Line 52: Line 52:
 
**gd_cross_intermediate.crt
 
**gd_cross_intermediate.crt
 
**gd_intermediate.crt
 
**gd_intermediate.crt
**server-name.crt
+
** .crt
 
**gd_bundle.crt
 
**gd_bundle.crt
*The /opt/zimbra/ssl/zimbra/commercial has two files:
+
*The '''/opt/zimbra/ssl/zimbra/commercial''' has two files:
 
**commercial.key
 
**commercial.key
 
**commercial.crt
 
**commercial.crt
Line 62: Line 62:
 
*gd_cross_intermediate.crt
 
*gd_cross_intermediate.crt
 
*gd_intermediate.crt
 
*gd_intermediate.crt
*server_name.crt
+
* .crt
  
 
Once you have uploaded these files, restart Zimbra services.
 
Once you have uploaded these files, restart Zimbra services.
 
 
----
 
For Zimbra 5.0.5, the above didn't work.  I had to use the following:
 
 
*Root Certificate = gd-class2-root.crt
 
*Server Cert = server_name.crt
 
*Intermediate Cert = gd_bundle.crt
 
  
 
=Network Solutions Certificate=  
 
=Network Solutions Certificate=  
1. Rename the  file to '''commercial.crt''' and place it in the '''/opt/zimbra/ssl/zimbra/commercial'''
+
1. Rename the  file to '''commercial.crt''' and place it in the '''/opt/zimbra/ssl/zimbra/commercial'''
 
2. chmod 700 commercial.crt
 
2. chmod 700 commercial.crt
3. Concatenate the chain files into one file and call it '''commercial_ca.crt'''
+
3. Concatenate the chain files into one file and call it '''commercial_ca.crt'''
  cat AddTrustExternalCARoot.crt NetworkSolutions_CA.crt UTNAddTrustServer_CA.crt commercial_ca.crt
+
  cat AddTrustExternalCARoot.crt NetworkSolutions_CA.crt UTNAddTrustServer_CA.crt commercial_ca.crt
4. cp commrecial_ca.crt /opt/zimbra/ssl/zimbra/commercial
+
4. cp commercial_ca.crt /opt/zimbra/ssl/zimbra/commercial
 
  chmod 700 commercial_ca.crt
 
  chmod 700 commercial_ca.crt
 
5. Run a check against the cert files.
 
5. Run a check against the cert files.
Line 91: Line 83:
 
8. Verify that the Web interface is loading correctly with the new certificate.
 
8. Verify that the Web interface is loading correctly with the new certificate.
  
'''''Note:''' This assumes that you have the private key in '''/opt/zimbra/ssl/zimbra/commercial''' named as '''commercial.key''' with the correct permissions.''
+
'''''Note:''' This assumes that you have the private key in '''/opt/zimbra/ssl/zimbra/commercial''' named as '''commercial.key''' with the correct permissions.''
  
 
=Install Verisign Test Certificate on Zimbra Server=
 
=Install Verisign Test Certificate on Zimbra Server=
Line 98: Line 90:
 
=Troubleshooting=
 
=Troubleshooting=
  
==LDAP/Nginx won't start and asks for a password==
+
==LDAP/Nginx won't start and asks for a password==
That means Zimbra can't read the key or the cert of the LDAP/IMAP proxy service on startup.
+
That means Zimbra can't read the key or the cert of the LDAP/IMAP proxy service on startup.
  
 
Here is what you can do:
 
Here is what you can do:
Line 113: Line 105:
  
 
==Failed to create jetty.pkcs12==
 
==Failed to create jetty.pkcs12==
If you are seeing the following error when you try to install the certificate via '''Administration Console Certificates''',
+
If you are seeing the following error when you try to install the certificate via '''Administration Console Certificates''',
  
 
  Your certificate was not installed due to the error : system failure: XXXXX ERROR: failed to create jetty.pkcs12  
 
  Your certificate was not installed due to the error : system failure: XXXXX ERROR: failed to create jetty.pkcs12  
Line 122: Line 114:
 
Check the following:
 
Check the following:
  
1. Make sure the permissions of the '''/opt/zimbra/mailboxd/webapps/zimbraAdmin/tmp/''' directory is set to '''644 zimbra:zimbra'''.
+
1. Make sure the permissions of the '''/opt/zimbra/mailboxd/webapps/zimbraAdmin/tmp/''' directory is set to '''644 zimbra:zimbra'''.
  
 
2. Clear all the current aliases in the mailboxd keystore except for the jetty alias.
 
2. Clear all the current aliases in the mailboxd keystore except for the jetty alias.
 
  keytool -delete -alias tomcat -keystore /opt/zimbra/mailboxd/etc/keystore -storepass `zmlocalconfig -s -m nokey mailboxd_keystore_password`
 
  keytool -delete -alias tomcat -keystore /opt/zimbra/mailboxd/etc/keystore -storepass `zmlocalconfig -s -m nokey mailboxd_keystore_password`
  
3. If you are running ZCS version 5.0.5, comment out line #539 of the '''/opt/zimbra/bin/zmcertmgr''' utility before deploying the cert. This is bug 27581 [[http://bugzilla.zimbra.com/show_bug.cgi?id=27581]].
+
3. If you are running ZCS version 5.0.5, comment out line #539 of the '''/opt/zimbra/bin/zmcertmgr''' utility before deploying the cert. This is bug 27581 [[http://bugzilla.zimbra.com/show_bug.cgi?id=27581]].
  
 
==Private key and certificate mismatch==
 
==Private key and certificate mismatch==
Line 143: Line 135:
 
If you are getting this error as you deploy the certificate:
 
If you are getting this error as you deploy the certificate:
 
  XXXXX ERROR: Invalid Certificate:....error 20 at 0 depth lookup:unable to get local issuer certificate
 
  XXXXX ERROR: Invalid Certificate:....error 20 at 0 depth lookup:unable to get local issuer certificate
  XXXXX ERROR: provided cert isn't valid.  
+
  XXXXX ERROR: provided cert isn't valid.  
  
 
or this error,
 
or this error,
Line 165: Line 157:
  
 
*Create a CSR via the CLI
 
*Create a CSR via the CLI
  sudo /opt/zimbra/bin/zmcertmgr createcsr  [-new] [subject] [-subjectAltNames "host1,host2"]
+
  sudo /opt/zimbra/bin/zmcertmgr createcsr  [-new] [subject] [-subjectAltNames "host1,host2"]
  
 
*View deployed certificate via the command line
 
*View deployed certificate via the command line

Revision as of 19:04, 9 June 2008

General Overview

Installing a commercial certificate in ZCS version 5.0.0_GA and above is a straightforward process. The following is an overview of the steps you will take to install a commercial certificate.

  1. Generate a CSR via the '''Administration Console Certificates''' or via the '''zmcertmgr''' command line utility.
  2. Receive the signed certificate.
  3. Receive the chain_certificates (if applicable).
  4. Install the certificate.

TOOLS

Admininstration Console Certificates

This is the preferred method for installing commercial certificates. You simply start the Wizard and upload all the cert files and restart the Zimbra Services.

/opt/zimbra/bin/zmcertmgr

If the Administration Console Certificates Wizard is not doing the job, we then resort to the command line.

'''''Note:''' This tool must be run as root.''

It requires the following:

  • The private key must exist in '''/opt/zimbra/ssl/zimbra/commercial''' directory and must be named '''commercial.key''' with permission set to '''740'''.
  • The server certificate and the chain cert files must exist in a temp directory. E.g. '''/root/certs'''
  • The server cert must be named '''commercial.crt'''.
  • The chain cert files must be concatenated into one file called commercial_ca.crt.
  • Verify that the cert and the key match using this command:
/opt/zimbra/bin/zmcertmgr verifycrt comm commercial.crt commercial_ca.crt 
  • From the temp directory, deploy the cert and restart the zimbra services.
(a) sudo zmcertmgr deploycrt comm  
(b) zmcontrol stop ; zmcontrol start 

Certificate Upgrade Issues

If you are upgrading from 4.5x to 5.0.x and the cert failed to upgrade successfully, you need to re-install the cert. You will need these pieces:

  1. The private key. This can be extracted from the Tomcat keystore. Zimbra Support can help with this process if you send the Tomcat keystore.
  2. The server certificate
  3. The chain cert files

With these pieces in hand, we can use the zmcertmgr to install the certificate as explained in #Importing commercial certificates from other mail systems to Zimbra 5.x.

Check to make sure that only the jetty alias exists in the keystore.

keytool -list -keystore /opt/zimbra/mailboxd/etc/keystore -storepass  `zmlocalconfig -s -m nokey mailboxd_keystore_password` 

Delete the tomcat alias, if exists, with the following command.

keytool -delete -alias tomcat -keystore /opt/zimbra/mailboxd/etc/keystore -storepass `zmlocalconfig -s -m nokey mailboxd_keystore_password` 

Importing commercial certificates from other mail systems to Zimbra 5.x

The steps are the same as the ones under #/opt/zimbra/bin/zmcertmgr.

GoDaddy Certificate in 5.x

Assuming the following is correct:

  • This is a new certificate.
  • You generated the CSR via the Administration Console.
  • You sent the CSR to get it signed and you received the following files:
    • gd_cross_intermediate.crt
    • gd_intermediate.crt
    • .crt
    • gd_bundle.crt
  • The '''/opt/zimbra/ssl/zimbra/commercial''' has two files:
    • commercial.key
    • commercial.crt

You can install the certificate by logging in to the Administration Console and uploading the following files.

  • RootCA
  • gd_cross_intermediate.crt
  • gd_intermediate.crt
  • .crt

Once you have uploaded these files, restart Zimbra services.

Network Solutions Certificate

1. Rename the file to '''commercial.crt''' and place it in the '''/opt/zimbra/ssl/zimbra/commercial''' 2. chmod 700 commercial.crt 3. Concatenate the chain files into one file and call it '''commercial_ca.crt'''

cat AddTrustExternalCARoot.crt NetworkSolutions_CA.crt UTNAddTrustServer_CA.crt commercial_ca.crt

4. cp commercial_ca.crt /opt/zimbra/ssl/zimbra/commercial

chmod 700 commercial_ca.crt

5. Run a check against the cert files.

/opt/zimbra/bin/zmcertmgr verifycrt comm

6. At this point and if the output looks promising, go ahead and deploy the cert.

/opt/zimbra/bin/zmcertmgr deploycrt comm commercial.crt commercial_ca.crt

7. Restart the Zimbra services.

su - zimbra
zmcontrol stop
zmcontrol start

8. Verify that the Web interface is loading correctly with the new certificate.

'''''Note:''' This assumes that you have the private key in '''/opt/zimbra/ssl/zimbra/commercial''' named as '''commercial.key''' with the correct permissions.''

Install Verisign Test Certificate on Zimbra Server

See Install Verisign Test Certificate on Zimbra Server

Troubleshooting

LDAP/Nginx won't start and asks for a password

That means Zimbra can't read the key or the cert of the LDAP/IMAP proxy service on startup.

Here is what you can do:

1. You want to check to make sure the private key is not encrypted.

2. Manually link the cert to the services OR simply redeploy the certificate to relink the cert to the services.

(a)cp /opt/zimbra/ssl/zimbra/commercial/commercial.key /opt/zimbra/conf/sldapd.key
(b)cp /opt/zimbra/ssl/zimbra/commercial/commercial.key /opt/zimbra/conf/slapd.crt
(c)cp /opt/zimbra/ssl/zimbra/commercial/commercial.key /opt/zimbra/conf/nginx.key
(d)cp /opt/zimbra/ssl/zimbra/commercial/commercial.crt /opt/zimbra/conf/ngix.crt 

3. Restart the Zimbra services.

Failed to create jetty.pkcs12

If you are seeing the following error when you try to install the certificate via '''Administration Console Certificates''',

Your certificate was not installed due to the error : system failure: XXXXX ERROR: failed to create jetty.pkcs12 
Message: Your certificate was not installed due to the error : system failure: XXXXX ERROR: failed to create jetty.pkcs12 
Error code: ZaCertWizard.prototype.installCallback Method: AjxException.UNKNOWN_ERROR Details:system failure: XXXXX 
ERROR: failed to create jetty.pkcs12

Check the following:

1. Make sure the permissions of the '''/opt/zimbra/mailboxd/webapps/zimbraAdmin/tmp/''' directory is set to '''644 zimbra:zimbra'''.

2. Clear all the current aliases in the mailboxd keystore except for the jetty alias.

keytool -delete -alias tomcat -keystore /opt/zimbra/mailboxd/etc/keystore -storepass `zmlocalconfig -s -m nokey mailboxd_keystore_password`

3. If you are running ZCS version 5.0.5, comment out line #539 of the '''/opt/zimbra/bin/zmcertmgr''' utility before deploying the cert. This is bug 27581 [[1]].

Private key and certificate mismatch

If you are seeing this error as you deploy the certificate:

Your certificate was not installed due to the error : system failure: XXXXX ERROR: Unmatching certificate
(/opt/zimbra/mailboxd/webapps/zimbraAdmin/tmp/current.crt) and private key (/opt/zimbra/ssl/zimbra/commercial/commercial.key) 
pair. Error code: ZaCertWizard.prototype.installCallback...

You need to regenerate the CSR, which will create a new key, and submit it to the CA to get it signed. You simply start the certificate installation again.

Problem with Certificate can cause MTA Failure

See Problem with Certificate can cause MTA Failure

Unable to get issuer certificate

If you are getting this error as you deploy the certificate:

XXXXX ERROR: Invalid Certificate:....error 20 at 0 depth lookup:unable to get local issuer certificate
XXXXX ERROR: provided cert isn't valid. 

or this error,

this alternate error error 2 at 1 depth lookup

That means the certificate path or chain is broken and you are missing certificate files. In most cases the intermediate cert. For more info on certificate path verification, please take a look at this url http://www.herongyang.com/crypto/openssl_verify.html

Misc

  • Inspect your CSR
openssl req -in  -noout -text
  • Inspect your certificate
openssl x509 -in  -noout -text
  • Clear the passphrase of the private key
openssl rsa -in  -out 
  • Get Jetty keystore password
zmlocalconfig -s -m nokey mailboxd_keystore_password
  • Create a CSR via the CLI
sudo /opt/zimbra/bin/zmcertmgr createcsr  [-new] [subject] [-subjectAltNames "host1,host2"]
  • View deployed certificate via the command line
 sudo /opt/zimbra/bin/zmcertmgr viewdeployedcrt
  • Convert the cert format from DER to PEM
openssl x509 -in input.cer -inform DER -out output.cer -outform PEM
Verified Against: Zimbra Collaboration Suite 5.x Date Created: 1/16/2008
Article ID: https://wiki.zimbra.com/index.php?title=5.x_Commercial_Certificates_Guide Date Modified: 2008-06-09



Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »

Jump to: navigation, search