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

(Editing first half of article for grammar & formatting)
(Editing for grammar and formatting)
Line 18: Line 18:
 
*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 concatinated 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:
 
  <span style="background-color:green;color:white">/opt/zimbra/bin/zmcertmgr verifycrt comm commercial.crt commercial_ca.crt</span>
 
  <span style="background-color:green;color:white">/opt/zimbra/bin/zmcertmgr verifycrt comm commercial.crt commercial_ca.crt</span>
Line 66: Line 66:
 
Once you have uploaded these files, restart Zimbra services.
 
Once you have uploaded these files, restart Zimbra services.
  
= Network Solutions Certificate=  
+
=Network Solutions Certificate=  
<span style="background-color:green;color:white">
+
1. Rename the <server_name.crt> file to '''commercial.crt''' and place it in the '''/opt/zimbra/ssl/zimbra/commercial'''
(1) rename this file <server_name.crt> 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) concatenated the chain files into one file and called 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 commrecial_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
+
/opt/zimbra/bin/zmcertmgr verifycrt comm
  /opt/zimbra/bin/zmcertmgr verifycrt comm
+
6. At this point and if the output looks promising, go ahead and deploy the cert.
(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
  /opt/zimbra/bin/zmcertmgr deploycrt comm commercial.crt commercial_ca.crt
+
7. Restart the Zimbra services.
(7) and restarted the zimbra services
+
su - zimbra
    su - zimbra
+
zmcontrol stop
    zmcontrol stop
+
zmcontrol start
    zmcontrol start
+
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</span>
+
 
 +
'''''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=
[[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==
+
=Troubleshooting=
That means zimbra can't read the key or the cert of the ldap/imapproxy service on startup.
+
 
 +
==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:
 
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.
 
<span style="background-color:green;color:white">
 
    (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</span>
 
  (3) restart the zimbra services.
 
== failed to create jetty.pkcs12==
 
If you are seeing this error when you try to install the certificate via the admin 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'''''
+
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.
 +
<span style="background-color:green;color:white">(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</span>
 +
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`
  
Check the following:
+
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]].
(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 [[http://bugzilla.zimbra.com/show_bug.cgi?id=27581]].
 
==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.  
+
==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==
 
==Problem with Certificate can cause MTA Failure==
[[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 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.
+
==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
 
For more info on certificate path verification, please take a look at this url http://www.herongyang.com/crypto/openssl_verify.html
 
  
 
=Misc=
 
=Misc=
Inspect your csr
+
*Inspect your CSR
  openssl req -in <server.csr> -noout -text
+
openssl req -in <server.csr> -noout -text
  
Inspect your certificate
+
*Inspect your certificate
  openssl x509 -in <server.crt> -noout -text
+
openssl x509 -in <server.crt> -noout -text
  
Clear the passphrase of the private key
+
*Clear the passphrase of the private key
 
  openssl rsa -in <server.key> -out <server.key.decr>
 
  openssl rsa -in <server.key> -out <server.key.decr>
  
Get jetty keystore password
+
*Get Jetty keystore password
 
  zmlocalconfig -s -m nokey mailboxd_keystore_password
 
  zmlocalconfig -s -m nokey mailboxd_keystore_password
  
Create a csr via the cli
+
*Create a CSR via the CLI
  sudo /opt/zimbra/bin/zmcertmgr createcsr <self|comm> [-new] [subject] [-subjectAltNames "host1,host2"]
+
sudo /opt/zimbra/bin/zmcertmgr createcsr <self|comm> [-new] [subject] [-subjectAltNames "host1,host2"]
  
View deployed certificate via the command line
+
*View deployed certificate via the command line
 
   sudo /opt/zimbra/bin/zmcertmgr viewdeploycrt
 
   sudo /opt/zimbra/bin/zmcertmgr viewdeploycrt
  

Revision as of 21:00, 5 May 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 <cert file> <ca_chain file>
(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
    • <server_name>.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
  • <server_name>.crt

Once you have uploaded these files, restart Zimbra services.

Network Solutions Certificate

1. Rename the <server_name.crt> 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 commrecial_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 <server.csr> -noout -text
  • Inspect your certificate
openssl x509 -in <server.crt> -noout -text
  • Clear the passphrase of the private key
openssl rsa -in <server.key> -out <server.key.decr>
  • Get Jetty keystore password
zmlocalconfig -s -m nokey mailboxd_keystore_password
  • Create a CSR via the CLI
sudo /opt/zimbra/bin/zmcertmgr createcsr <self|comm> [-new] [subject] [-subjectAltNames "host1,host2"]
  • View deployed certificate via the command line
 sudo /opt/zimbra/bin/zmcertmgr viewdeploycrt
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-05-05



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