Difference between revisions of "Administration Console and CLI Certificate Tools"

(Multi-Node Commercial Certificate)
(Multi-Node Commercial Certificate)
 
(28 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{ZC}}{{Article Infobox|{{admin}}|{{ZCS 8.0}}|{{ZCS 7.0}}|{{ZCS 6.0}}|{{ZCS 5.0}}}}
+
{{BC|Certified}}
''Note: For information about iPhone SSL certificates, see http://wiki.zimbra.com/wiki/IPhone''
+
__FORCETOC__
 +
<div class="col-md-12 ibox-content">
 +
= ZCS Certificates Tools =
 +
{{KB|{{ZC}}|{{ZCS 8.6}}|{{ZCS 8.5}}|{{ZCS 8.0}}||}}
  
ZCS allows administrators to manage their certificates using either the Administration Console or the Command Line Interface (CLI). This article discusses the ZCS 7.0.x, 6.0.x, and 5.0.x Administration Console, and the CLI tools for ZCS 7.0.x, 6.0.x, 5.0.x and 4.5.x.
+
See also:
 +
* [[IPhone]] for information about iPhone SSL certificates.
 +
* [[SecureConfiguration]] for best practices when security a ZCS installation.
 +
* [[TLS/STARTTLS_Localconfig_Values]] for information about security related localconfig settings.
  
=ZCS Administration Console Certificates Tools=
+
 
The ZCS Certificates tools are located in the Navigation pane, under '''Tools>Certificates'''. Once you have selected '''Certificates''' from this menu, the Manage Certificates tab opens in the Content pane. From here, you can view your deployed certificates or install a new certificate.
+
ZCS allows administrators to manage their [https://en.wikipedia.org/wiki/Public_key_certificate certificates] using either the Administration Console or the Command Line Interface (CLI). This article discusses the ZCS 8.x, 8.0.x, 7.0.x Administration Console, and the CLI tools for ZCS 8.x, 8.0.x, 7.0.x.
 +
 
 +
== A note on CN and subjectAltName ==
 +
 
 +
By default ZCS requires valid certificates when communicating with hosts over TLS/SSL.  As such, certificates within an install should be valid (not expired and have hostnames matching the certificate).
 +
 
 +
Per https://tools.ietf.org/html/rfc2818#section-3.1
 +
<blockquote>
 +
If a subjectAltName extension of type dNSName is present, that MUST be used as the identity. Otherwise, the (most specific) Common Name field in the Subject field of the certificate MUST be used. Although the use of the Common Name is existing practice, it is deprecated and Certification Authorities are encouraged to use the dNSName instead.
 +
</blockquote>
 +
 
 +
See also [https://tools.ietf.org/html/rfc2459#section-4.2.1.7 RFC2459 section-4.2.1.7] for details on Subject Alternative Name handling and usage.
 +
 
 +
In short setting subjectAltName, it must include all host names to be trusted, not just "additional" ones beyond what is in CN (by default zmcertmgr will put `zmhostname` in the subjectAltName).
 +
 
 +
= ZCS Administration Console =
 +
 
 +
The ZCS Certificates tools are located in the Navigation pane, under '''Tools > Certificates'''. Once you have selected '''Certificates''' from this menu, the Manage Certificates tab opens in the Content pane. From here, you can view your deployed certificates or install a new certificate.
  
 
[[image:AdminConsoleManageCerts.png]]
 
[[image:AdminConsoleManageCerts.png]]
  
==Viewing Certificates==
+
In ZCS8 and above we will find the ZCS Certificates in the Navigation pane, under '''Configure>Certificates'''
 +
 
 +
[[File:SSL_Install_Web_001.png]] [[File:SSL_Install_Web_002.png]]
 +
 
 +
== Viewing Certificates ==
 
Using the Administration Console, you can view the details of certificates currently deployed.  Details include the certificate subject, issuer, validation days, and subject alternative name.
 
Using the Administration Console, you can view the details of certificates currently deployed.  Details include the certificate subject, issuer, validation days, and subject alternative name.
  
 
To view a certificate, select a service host name, either under '''Certificates''' in the Navigation pane or by selecting a Service host name in the Manage Certificates tab and clicking '''View Certificate'''.  A Certificates tab for the service host name you selected opens in the Content Pane.
 
To view a certificate, select a service host name, either under '''Certificates''' in the Navigation pane or by selecting a Service host name in the Manage Certificates tab and clicking '''View Certificate'''.  A Certificates tab for the service host name you selected opens in the Content Pane.
 +
 +
[[File:SSL_Install_Web_003.png]]
 +
 +
Information about the certificate:
 +
 +
[[File:SSL_Install_Web_004.png]]
  
 
You can refresh the currently displayed details by clicking '''Refresh''' at the top of the tab.
 
You can refresh the currently displayed details by clicking '''Refresh''' at the top of the tab.
  
==Installing Certificates==
+
== Generate a valid CSR (Certificate Signing Request) for a Commercial SSL ==
 +
Go to '''Home > Configure > Certificates''' and click in the settings icon, then click on '''Install Certificate'''
 +
 
 +
[[File:Zimbra-ssl-adminconsole-001.png|800px]]
 +
 
 +
Select the target server to generate the SSL files like the CSR and the private key:
 +
 
 +
[[File:Zimbra-ssl-adminconsole-002.png|800px]]
 +
 
 +
In the next step, select the option '''Generate the CSR for the commercial certificate authorizer'''
 +
 
 +
[[File:Zimbra-ssl-adminconsole-003.png|800px]]
 +
 
 +
In this window, you need to select the next settings:
 +
* Select digest '''SHA256''' or above, not SHA1 as is not longer considered to be secure
 +
* Key Length 2048 or above
 +
* Common Name (CN) needs to be the FQDN that you want to use, if you are using a Single-Server is recommended that the FQDN and the hostname are the same.
 +
* The checkbox about the Wildcard is if you want to use a Wildcard SSL certificate for your Zimbra, and for the rest of you other FQDN in your Company. If the hostname and the FQDN doesn't match, but are in the same domain, use this option and buy a Wildcard Certificate.
 +
* In the Subject Alternative Name (SAN), you can select another names if you will use a Multi-SAN SSL certificate, this option is indicated if you want to have mail.customer1.com, mail.customer2.com, etc.
 +
 
 +
[[File:Zimbra-ssl-adminconsole-004.png|800px]]
 +
 
 +
You can download now the CSR file, ready to send to your SSL Certificate Provider, if you miss this step, you can find the csr file in the next path '''/opt/zimbra/ssl/zimbra/commercial/commercial.csr''':
 +
 
 +
[[File:Zimbra-ssl-adminconsole-005.png|800px]]
 +
 
 +
You can check if your CSR is valid and correct using for example [https://ssltools.websecurity.symantec.com/checker/views/csrCheck.jsp the next URL]:
 +
 
 +
[[File:Zimbra-ssl-adminconsole-006.png|800px]]
 +
 
 +
== Installing Certificates ==
 
Clicking '''Install Certificate''' from either the Manage Certificates tab or a Certificates tab opens the Certificate Installation Wizard.  The Certificate Installation Wizard is a tool that will help you quickly create and deploy a certificate.
 
Clicking '''Install Certificate''' from either the Manage Certificates tab or a Certificates tab opens the Certificate Installation Wizard.  The Certificate Installation Wizard is a tool that will help you quickly create and deploy a certificate.
  
===Generating Multiple CSRs using the Administration Console===
+
=== Generating & Installing a Self-Signed Certificate ===
 +
Sometimes we want to regenerate the Self-Signed Certificate, we can do it in the Administration Console. We need to click in the '''Cog>Select Install Certificate''' and follow the steps:
 +
 
 +
The first step is select '''Install the self-signed certificate'''
 +
 
 +
[[File:SSL_Install_Web_005.png]]
 +
 
 +
Next, we need to mark the checkbox '''Replace the existing CSR'''
 +
 
 +
[[File:SSL_Install_Web_006.png]]
 +
 
 +
We need to be sure of select the Key Length at 2048, and the rest of the fields, for now have a Bug Opened in 8.5 and also if you change this values will be the same default values - [https://bugzilla.zimbra.com/show_bug.cgi?id=95450].
 +
 
 +
[[File:SSL_Install_Web_007.png]]
 +
 
 +
We can select also the time that we want to have this SSL validated, remember that is Self-Signed, if we are not planning any future change, we can select more than a year. And then press '''Install'''.
 +
 
 +
[[File:SSL_Install_Web_008.png]]
 +
 
 +
The SSL Certificate Self-Signed are now installing in our Zimbra Collaboration Server.
 +
 
 +
[[File:SSL_Install_Web_009.png]]
 +
 
 +
Once the installation has finish, the system request us a restart of the ZCS services.
 +
 
 +
[[File:SSL_Install_Web_010.png]]
 +
 
 +
Trough console by user zimbra we need to execute the next command, and wait until all services are up again:
 +
<pre>zmcontrol restart</pre>
  
Currently the Administration Console only supports having one Certificate Signing Request (CSR) and private key at a time. Generating a new CSR overrides the existing one and generates a new private key. To generate more than one CSR, move both the CSR and key from the directory it is generated in (E.g. /opt/zimbra/ssl/zimbra/commercial directory/) before generating another CSR.
+
If we will go again to our https://mail.domain.com we will have the known problem with SSL Certificate in our Web Browser:
  
==Maintaining Valid Certificates==
+
[[File:SSL_Install_Web_011.png]]
 +
 +
=== Generating Multiple CSRs using the Administration Console ===
 +
 
 +
Currently the Administration Console only supports having one Certificate Signing Request (CSR) and private key at a time. Generating a new CSR overrides the existing one and generates a new private key. To generate more than one CSR, move both the CSR and key from the directory it is generated in (e.g. /opt/zimbra/ssl/zimbra/commercial directory/) before generating another CSR.
 +
 
 +
== Maintaining Valid Certificates ==
 
It is important to keep your SSL certificates valid to ensure clients and environments work properly, as the ZCS system can become non-functional if certificates are allowed to expire. You can view deployed SSL certificates from the ZCS administrator console, including their validation days. It is suggested that certificates are checked periodically, so you know when they expire and to maintain their validity.
 
It is important to keep your SSL certificates valid to ensure clients and environments work properly, as the ZCS system can become non-functional if certificates are allowed to expire. You can view deployed SSL certificates from the ZCS administrator console, including their validation days. It is suggested that certificates are checked periodically, so you know when they expire and to maintain their validity.
  
=ZCS Certificate CLI=
+
= ZCS Certificate CLI =
The ZCS Certificate CLI commands for 7.0.x, 6.0.x and 5.0.x differ from 4.5.x. The following sections discuss the CLI tools for each version.
+
The ZCS Certificate CLI commands for ZCS5 and greater differ from ZCS4 and earlier. The following sections discuss the CLI tools for ZCS5 and above.
  
==ZCS 7.0.x, 6.0.x, and 5.0.x==
+
== zmcertmgr ==
 
 
===zmcertmgr===
 
 
This command allows you to manage certificates.
 
This command allows you to manage certificates.
  
====General Guidelines====
+
=== General Guidelines ===
 
Follow these guidelines when using this command.
 
Follow these guidelines when using this command.
*This tool must be run as root
+
* For versions before 8.7, this tool must be run as root.  '''In 8.7+, this tool is run as user zimbra.'''
=====Commercial Certificate Guidelines=====
+
 
 +
==== Commercial Certificate Guidelines ====
 
Follow these guidelines when using this command to generate a commercial certificate.
 
Follow these guidelines when using this command to generate a commercial certificate.
*The private key must exist in the '''/opt/zimbra/ssl/zimbra/commercial''' directory, and must be named '''commercial.key''' with its permission set to '''740'''
+
*The private key must exist in the '''/opt/zimbra/ssl/zimbra/commercial''' directory, and must be named '''commercial.key''' with its permission set to '''740''' before 8.7, and '''640''' in 8.7+.
*The server certificate and the chain certificate files must exist in a temp directory. (E.g. /root/certs/)
+
*The server certificate and the chain certificate files must exist in a temp directory. (E.g. /tmp/certs/)
 
*The chain certificate files must be concatenated into one file called '''commercial_ca.crt'''
 
*The chain certificate files must be concatenated into one file called '''commercial_ca.crt'''
  
====Syntax====
+
=== Syntax ===
 
zmcertmgr [options]
 
zmcertmgr [options]
  
====Description====
+
=== Description ===
 
{|style="width:100%" border="1" cellpadding="5" cellspacing="0"
 
{|style="width:100%" border="1" cellpadding="5" cellspacing="0"
! align="left" bgcolor="tan" |Name
+
! align="left" style="color:white;" bgcolor="#1785c2" |Name
! align="left" bgcolor="tan"|Description
+
! align="left" style="color:white;" bgcolor="#1785c2"|Description
 
|-
 
|-
! colspan="2" align="left" bgcolor="wheat" |General Options
+
! colspan="2" align="left" style="color:white;" bgcolor="#f15a25" |General Options
 
|-
 
|-
 
|style="background=white" |<nowiki>-help</nowiki>
 
|style="background=white" |<nowiki>-help</nowiki>
 
|Displays usage options for '''zmcertmgr'''
 
|Displays usage options for '''zmcertmgr'''
 
|-
 
|-
! colspan="2" align="left" bgcolor="wheat" |Self-Signed Certificate Options
+
! colspan="2" align="left" style="color:white;" bgcolor="#f15a25" |Self-Signed Certificate Options
 
|-
 
|-
|createca [-new] [-keysize keysize] [-digest digest] [-subject subject]
+
! colspan="2" | <nowiki>createca [-new] [-keysize keysize] [-digest digest] [-subject subject]</nowiki>
|Generates a Certificate Authority (CA). The '''-new''' option forces the generation of a new CA.
 
 
|-
 
|-
|deployca
+
|
|Deploys a CA.
+
| Generates a Certificate Authority (CA).
 
|-
 
|-
|createcsr <nowiki><self|comm> [-new] [-keysize keysize] [-digest digest] [-subject subject] [-subjectAltNames "host1,host2"]</nowiki>
+
! colspan="2" | <nowiki>deployca [-localonly]</nowiki>
|Creates a certificate signing request (CSR) for either a self or commercially signed certificate authority.  The '''<nowiki>-new</nowiki>''' option forces the generation of a new CSR. The '''<nowiki>-keysize</nowiki>''' option allows you to set the keysize, for example "-keysize 2048". Recommended keysize is 2048 - in 8.0.7, it will be the default: https://bugzilla.zimbra.com/show_bug.cgi?id=85023. The '''<nowiki>-subject</nowiki>''' option allows you to specify the path in which the certificate is valid. The '''<nowiki>-subjectAltNames</nowiki>''' option allows you to specify additional hosts that may use the certificate other than the one listed in the subject.  The default subject is "/C=US/ST=N\/A/L=N\/A/O=Zimbra Collaboration Suite/OU=Zimbra Collaboration Suite/CN=${zimbra_server_hostname}".
 
 
|-
 
|-
|createcrt [-new] [-days validation days] [-keysize keysize] [-digest digest]  [-subject subject] [-subjectAltNames "host1,host2"]
+
|
|Creates a self-signed certificate based on the CSR generated using '''createcsr'''. The '''-new''' option forces the generation of a new certificate.  The '''-days''' option assigns a number of days for which the certificate is valid.  The '''-subject''' option allows you to specify the path in which the certificate is valid.  The '''-subjectAltNames''' allows you to specify additional hosts that may use the certificate other than the one listed  in the subject.  The default subject is "/C=US/ST=N\/A/L=N\/A/O=Zimbra Collaboration Suite/OU=Zimbra Collaboration Suite/CN=${zimbra_server_hostname}".
+
| Deploys a Certificate Authority (CA).  The '''-localonly''' avoids updating any certificate related settings in LDAP.
 
|-
 
|-
|deploycrt <self>
+
! colspan="2" | <nowiki>createcsr <self|comm> [-new] [-keysize keysize] [-digest digest] [-subject subject] [-subjectAltNames "host1,host2"]</nowiki>
|Deploys a self-signed certificate.
 
 
|-
 
|-
! colspan="2" align="left" bgcolor="wheat" |Self-Signed and Commercial Certificate Options
+
|
 +
| Creates a certificate signing request (CSR) for either a self or commercially signed certificate authority.  By default the CSR
 +
subjectAltNames contains the current zmhostname (8.7 only: unless the '''-noDefaultSubjectAltName''' argument is used).
 
|-
 
|-
|deploycrt <comm> [certfile] [ca_chain_file]
+
! colspan="2" | <nowiki>createcrt [-new] [-days validation days] [-keysize keysize] [-digest digest[-subject subject] [-subjectAltNames "host1,host2"]</nowiki>
|Deploys a commercial certificate. Specify the certificate file and the certificate authority (CA) chain file.
 
 
|-
 
|-
|savecrt
+
|
|Saves a certificate
+
| Creates a self-signed certificate based on the CSR generated using '''createcsr'''.
 
|-
 
|-
|viewcsr <nowiki><self|comm></nowiki> [csr_file]
+
! colspan="2" | Where options are:
|Shows a certificate signing request (CSR). Specify '''self''' if the CSR is self-signed. Specify '''comm''' if the certificate is commercial. Specify the CSR file to view.
 
 
|-
 
|-
|viewdeployedcrt <nowiki>[all|ldap|mta|proxy|mailboxd]</nowiki>
+
| -new
|Shows a deployed certificate. This option only works for the local server.
+
| Force the generation of a new CA/Cert/CSR, overwriting existing data.
 
|-
 
|-
|viewstagedcrt <nowiki><self|comm></nowiki> [certfile]
+
| -keysize
|Shows a staged certificate. A staged certificate is placed in a staging file, where all files that will be deployed with the certificate are kept. You can use the staging area to verify that you are ready to deploy a certificateSpecify '''self''' if the certificate is self-signed. Specify '''comm''' if the certificate is commercial. Specify the certificate file to view.
+
| The RSA keysize in bits, for example "-keysize 4096". Minimum keysize is 2048Default keysize is 2048. (as of 8.0.7 https://bugzilla.zimbra.com/show_bug.cgi?id=85023)
 
|-
 
|-
|verifycrt <nowiki><self|comm></nowiki> [priv_key] [certfile]
+
| -subject
|Verifies a certificate. Specify '''self''' if the certificate is self-signed. Specify '''comm''' if the certificate is commercial. Specify the certificate key. Specify the certificate file.
+
| The X.500 distinguished name (DN). The default was "/C=US/ST=N\/A/L=N\/A/O=Zimbra Collaboration Suite/OU=Zimbra Collaboration Suite/CN=${zimbra_server_hostname}" before 8.7, and in 8.7+ is "/OU=Zimbra Collaboration Suite/CN=${zimbra_server_hostname}" after.
 
|-
 
|-
|verifycrtchain <ca_file> <certfile>
+
| &#8209;subjectAltNames
|Verifies a certificate chain. Specify '''self''' if the certificate is self-signedSpecify '''comm''' if the certificate is commercial. Specify the certificate key. Specify the certificate file.
+
| Additional host names that may use the certificate other than the one listed in the subject.  The alternate names can be specified as comma separate values (or in 8.7+ the '''-subjectAltNames''' can be used multiple times).
 +
|-
 +
! colspan="2" align="left" style="color:white;" bgcolor="#f15a25" | Self-Signed (self) and Commercial (comm) Certificate Options
 +
|-
 +
! colspan="2" | <nowiki>deploycrt <<self>|<comm [certfile ca_chain_file]>> [-allservers] [-localonly] [[-deploy $services] ...]</nowiki>
 +
|-
 +
|
 +
| Deploys a certificate.  For commercial certificates the certificate file and the certificate authority (CA) chain may be specified. For deploycrt, the use of '''-allservers''' will cause zmcertmgr to iterate through all servers in the ZCS deployment (zmprov gas, minus the initiating zmcertmgr host).
 +
|-
 +
! colspan="2" | <nowiki>getcrt <self|comm> [-allservers]</nowiki>
 +
|-
 +
! colspan="2" | <nowiki>savecrt <self|comm> [-allservers]</nowiki>
 +
|-
 +
|
 +
| Get (or Save) a certificateFor '''getcrt''' and '''savecrt''', the use of '''-allservers''' causes the configuration keys to be get/set as a global (getConfig/modifyConfig) configuration settings (zimbraSSLCertificate and zimbraSSLPrivateKey) instead of as a per-server setting (getServer/modifyServer).
 +
|-
 +
! colspan="2" | <nowiki>viewcsr <self|comm> [csr_file]</nowiki>
 +
|-
 +
|
 +
| Shows a certificate signing request (CSR). Optionally, the CSR file can be specified.
 +
|-
 +
! colspan="2" | <nowiki>viewstagedcrt <self|comm> [certfile]</nowiki>
 +
|-
 +
|
 +
| Shows a staged certificate. A staged certificate is placed in a staging file, where all files that will be deployed with the certificate are kept. You can use the staging area to verify that you are ready to deploy a certificate.
 +
|-
 +
! colspan="2" | <nowiki>verifycrt <self|comm> [[[priv_key] [certfile]] [ca_chain_file]]</nowiki>
 +
|-
 +
|
 +
| Combines '''verifycrtkey''' and '''verifycrtchain''' checks (see below).
 +
|-
 +
! colspan="2" | <nowiki>verifycrtkey <priv_key> <certfile></nowiki>
 +
|-
 +
|
 +
| Compares certificate private key and certificate file modulus digests to ensure they match.
 +
|-
 +
! colspan="2" | <nowiki>verifycrtchain <ca_chain_file> <certfile></nowiki>
 +
|-
 +
|
 +
| Verifies a certificate chain.
 +
|-
 +
! colspan="2" | <nowiki>viewdeployedcrt    [all|ldap|mailboxd|mta|proxy]</nowiki>
 +
|-
 +
|
 +
| Shows a deployed certificate on the local server.
 +
|-
 +
! colspan="2" | <nowiki>checkcrtexpiration [all|ldap|mailboxd|mta|proxy] [-days days]</nowiki>
 +
|-
 +
|
 +
| Check if certificate(s) expire within '''-days days'''
 
|}
 
|}
  
====Examples====
+
=== Examples ===
 
The following are examples of using the above options for different installation scenarios.
 
The following are examples of using the above options for different installation scenarios.
  
=====Single-Node Self-Signed Certificate=====
+
==== Single-Node Self-Signed Certificate ====
 
1. Begin by generating a new Certificate Authority (CA).
 
1. Begin by generating a new Certificate Authority (CA).
 
   /opt/zimbra/bin/zmcertmgr createca -new
 
   /opt/zimbra/bin/zmcertmgr createca -new
2. Then generate a certificate signed by the CA that expires in 365 days.
+
2. Then generate a certificate signed by the CA that expires in 1825 days.
   /opt/zimbra/bin/zmcertmgr createcrt -new -days 365
+
   /opt/zimbra/bin/zmcertmgr createcrt -new -days 1825
 
3. Next deploy the certificate.
 
3. Next deploy the certificate.
 
   /opt/zimbra/bin/zmcertmgr deploycrt self
 
   /opt/zimbra/bin/zmcertmgr deploycrt self
Line 112: Line 254:
 
   /opt/zimbra/bin/zmcertmgr viewdeployedcrt
 
   /opt/zimbra/bin/zmcertmgr viewdeployedcrt
  
=====Multi-Node Self-Signed Certificate=====
+
==== Multi-Node Self-Signed Certificate ====
 
1. Begin by generating a new Certificate Authority (CA).
 
1. Begin by generating a new Certificate Authority (CA).
 
   /opt/zimbra/bin/zmcertmgr createca -new
 
   /opt/zimbra/bin/zmcertmgr createca -new
 
   /opt/zimbra/bin/zmcertmgr deployca
 
   /opt/zimbra/bin/zmcertmgr deployca
 
2. Then generate a certificate signed by the CA that expires in 365 days with either wild-card or subject altnames.
 
2. Then generate a certificate signed by the CA that expires in 365 days with either wild-card or subject altnames.
   /opt/zimbra/bin/zmcertmgr createcrt -new -days 1825 -subjectAltNames "*.example.com"
+
   /opt/zimbra/bin/zmcertmgr createcrt -new -subjectAltNames "*.example.com"
   /opt/zimbra/bin/zmcertmgr createcrt -new -days 1825 -subject "/C=US/ST=CA/L=NVA/O=ZCS/OU=ZCS/CN=*.example.com"
+
   /opt/zimbra/bin/zmcertmgr createcrt -new -subject "/C=US/ST=CA/O=Example/CN=*.example.com"
   /opt/zimbra/bin/zmcertmgr createcrt -new -days 1825 -subjectAltNames "host1.example.com,host2.example.come"
+
   /opt/zimbra/bin/zmcertmgr createcrt -new -subjectAltNames "host1.example.com,host2.example.come"
 
3. Next, deploy the certificate to all nodes in the deployment.
 
3. Next, deploy the certificate to all nodes in the deployment.
 
   /opt/zimbra/bin/zmcertmgr deploycrt self -allserver
 
   /opt/zimbra/bin/zmcertmgr deploycrt self -allserver
Line 126: Line 268:
 
'''''Note''': The option '''viewdeployedcrt''' only works for the local server.''
 
'''''Note''': The option '''viewdeployedcrt''' only works for the local server.''
  
====== Alternate Method ======
+
===== Alternate Method =====
The "-allserver" command above doesn't always work as expected, depending on whether the ssh keys are current and working properly. One can also create the new ca first on an LDAP Master node, and then manually deploy the ca and create the self-signed certs on all the other nodes:
+
The "-allserver" command above doesn't always work as expected, depending on whether the ssh keys are current and working properly. One can also create the new CA first on an LDAP Master node, and then manually deploy the CA and create the self-signed certs on all the other nodes:
  
 
On an LDAP Master:
 
On an LDAP Master:
 
  /opt/zimbra/bin/zmcertmgr createca -new
 
  /opt/zimbra/bin/zmcertmgr createca -new
 
  /opt/zimbra/bin/zmcertmgr deployca
 
  /opt/zimbra/bin/zmcertmgr deployca
  /opt/zimbra/bin/zmcertmgr createcrt -new -days 1825 -subject "/C=US/ST=CA/L=NVA/O=ZCS/OU=ZCS/CN=*.example.com"
+
  /opt/zimbra/bin/zmcertmgr createcrt -new -subject "/C=US/ST=CA/O=Example/CN=*.example.com"
 
  OR
 
  OR
  /opt/zimbra/bin/zmcertmgr createcrt -new -days 1825 -subjectAltNames "host1.example.com,host2.example.com"
+
  /opt/zimbra/bin/zmcertmgr createcrt -new -subjectAltNames "host1.example.com,host2.example.com"
 
  OR
 
  OR
  /opt/zimbra/bin/zmcertmgr createcrt -new -days 1825 -subjectAltNames "*.example.com"
+
  /opt/zimbra/bin/zmcertmgr createcrt -new -subjectAltNames "*.example.com"
 
  /opt/zimbra/bin/zmcertmgr deploycrt self
 
  /opt/zimbra/bin/zmcertmgr deploycrt self
  
 
On all other systems:
 
On all other systems:
/opt/zimbra/bin/zmcertmgr createca
 
 
  /opt/zimbra/bin/zmcertmgr deployca -localonly
 
  /opt/zimbra/bin/zmcertmgr deployca -localonly
  /opt/zimbra/bin/zmcertmgr getcrt self
+
  /opt/zimbra/bin/zmcertmgr createcrt -new -subject "/C=US/ST=CA/O=Example/CN=*.example.com"
 
  /opt/zimbra/bin/zmcertmgr deploycrt self
 
  /opt/zimbra/bin/zmcertmgr deploycrt self
  
=====Single-Node Commercial Certificate=====
+
==== Single-Node Commercial Certificate ====
 +
We need to take care and ask for the Certificate authority for the Root and Intermediate Keys, we will need it soon.
 +
 
 +
We will use at least 2048-bit key, is the minimum for all Certificate Authorities:
 
1. Begin by generating a Certificate Signing Request (CSR).
 
1. Begin by generating a Certificate Signing Request (CSR).
  /opt/zimbra/bin/zmcertmgr createcsr comm -new -subject "/C=US/ST=CA/L=Sunnyvale/O=Yahoo/OU=Zimbra Collaboration Suite" -subjectAltNames host.example.com
+
<pre>/opt/zimbra/bin/zmcertmgr createcsr comm -new -subject "/C=US/ST=CA/L=Sunnyvale/O=Zimbra/OU=Zimbra Collaboration Suite/CN=host.example.com" -subjectAltNames host.example.com</pre>
 
2. Next, submit the CSR to the SSL provider and get a commercial certificate in PEM format. Save the new certificate to a temporary file (e.g. /tmp/commercial.crt).
 
2. Next, submit the CSR to the SSL provider and get a commercial certificate in PEM format. Save the new certificate to a temporary file (e.g. /tmp/commercial.crt).
  
Line 155: Line 299:
  
 
5. Combine root and intermediary CAs into a temporary file.
 
5. Combine root and intermediary CAs into a temporary file.
  cat /tmp/ca_intermediary.crt /tmp/ca.crt > /tmp/ca_chain.crt
+
<pre>cat /tmp/ca_intermediary.crt /tmp/ca.crt > /tmp/ca_chain.crt</pre>
 
6. Verify your commercial certificate.
 
6. Verify your commercial certificate.
  /opt/zimbra/bin/zmcertmgr verifycrt comm /opt/zimbra/ssl/zimbra/commercial/commercial.key /tmp/commercial.crt /tmp/ca_chain.crt
+
<pre>/opt/zimbra/bin/zmcertmgr verifycrt comm /opt/zimbra/ssl/zimbra/commercial/commercial.key /tmp/commercial.crt /tmp/ca_chain.crt
  **Verifying /tmp/commercial.crt against
+
**Verifying /tmp/commercial.crt against
  /opt/zimbra/ssl/zimbra/commercial/commercial.key
+
/opt/zimbra/ssl/zimbra/commercial/commercial.key
  Certificate (/tmp/commercial.crt) and private key
+
Certificate (/tmp/commercial.crt) and private key
  (/opt/zimbra/ssl/zimbra/commercial/commercial.key) match.
+
(/opt/zimbra/ssl/zimbra/commercial/commercial.key) match.
  Valid Certificate: /tmp/commercial.crt: OK
+
Valid Certificate: /tmp/commercial.crt: OK</pre>
 
7. Deploy your commercial certificate.
 
7. Deploy your commercial certificate.
  /opt/zimbra/bin/zmcertmgr deploycrt comm /tmp/commercial.crt /tmp/ca_chain.crt
+
<pre>/opt/zimbra/bin/zmcertmgr deploycrt comm /tmp/commercial.crt /tmp/ca_chain.crt
  ** Verifying /tmp/commercial.crt against
+
** Verifying /tmp/commercial.crt against
  /opt/zimbra/ssl/zimbra/commercial/commercial.key
+
/opt/zimbra/ssl/zimbra/commercial/commercial.key
  Certificate (/tmp/commercial.crt) and private key
+
Certificate (/tmp/commercial.crt) and private key
  (/opt/zimbra/ssl/zimbra/commercial/commercial.key) match.
+
(/opt/zimbra/ssl/zimbra/commercial/commercial.key) match.
  Valid Certificate: /tmpt/commercial.crt: OK
+
Valid Certificate: /tmpt/commercial.crt: OK
  **Copying commercial.crt to /opt/zimbra/ssl/zimbra/commercial/commercial.crt
+
**Copying commercial.crt to /opt/zimbra/ssl/zimbra/commercial/commercial.crt
  **Appending ca chain /tmp/ca_chain.crt to
+
**Appending CA chain /tmp/ca_chain.crt to
  /opt/zimbra/ssl/zimbra/commercial/commercial.crt
+
/opt/zimbra/ssl/zimbra/commercial/commercial.crt
  **Saving server config key zimbraSSLCeretificate…done.
+
**Saving server config key zimbraSSLCeretificate…done.
  **Saving server config key zimbraSSLPrivateKey…done.
+
**Saving server config key zimbraSSLPrivateKey…done.
  **Installing mta certificate and key…done.
+
**Installing mta certificate and key…done.
  **Installing slapd certificate and key…done.
+
**Installing slapd certificate and key…done.
  **Installing proxy certificate and key…done.
+
**Installing proxy certificate and key…done.
  **Creating pkcs12 file /opt/zimbra/ssl/zimbra/jetty.pkcs12…done.
+
**Creating pkcs12 file /opt/zimbra/ssl/zimbra/jetty.pkcs12…done.
  **Creating keystore file /opt/zimbra/mailbox/etc/keystore…done.
+
**Creating keystore file /opt/zimbra/mailbox/etc/keystore…done.
  **Installing CA to /opt/zimbra/conf/ca…done.
+
**Installing CA to /opt/zimbra/conf/ca…done.</pre>
 
8. To finish, verify the certificate was deployed.
 
8. To finish, verify the certificate was deployed.
 +
<pre>/opt/zimbra/bin/zmcertmgr viewdeployedcrt</pre>
 +
 +
==== Single-Node Wildcard Commercial Certificate ====
 +
Using a Wildcard Certificate, you will need the next files, because you probably generated the CSR in other server:
 +
* The .key file which you generated the CSR.
 +
* The .crt file that you SSL provide to you.
 +
* The CA Intermediate and the root files merged into one only file, called for example ca_chain.crt
 +
 +
1.- Backup your actual .key file located in '''/opt/zimbra/ssl/zimbra/commercial/commercial.key''':
 +
mv /opt/zimbra/ssl/zimbra/commercial/commercial.key /opt/zimbra/ssl/zimbra/commercial/commercial.key.backup
 +
2.- Move your actual .key file into the path '''/opt/zimbra/ssl/zimbra/commercial/''' with the name commercial.key:
 +
mv /tmp/wildcard.key /opt/zimbra/ssl/zimbra/commercial/commercial.key
 +
3.- Verify all the files before deploy the SSL certificate with the next command:
 +
/opt/zimbra/bin/zmcertmgr verifycrt comm /opt/zimbra/ssl/zimbra/commercial/commercial.key /tmp/wildcard.crt /tmp/ca_chain.crt
 +
4.- Then as user '''root (or zimbra for 8.7+)'''  run the next command, please be sure to use the proper path instead /tmp:
 +
/opt/zimbra/bin/zmcertmgr deploycrt comm /tmp/wildcard.crt /tmp/ca_chain.crt
 +
5.- Restart your Zimbra Collaboration server as Zimbra user:
 +
zmcontrol restart
 +
6.- To finish, verify the certificate was deployed.
 
   /opt/zimbra/bin/zmcertmgr viewdeployedcrt
 
   /opt/zimbra/bin/zmcertmgr viewdeployedcrt
  
=====Multi-Node Commercial Certificate=====
+
==== Multi-Node Commercial Certificate ====
 
1. We'll start by assuming you have your Commercial Certificate. If you don't, please see above.
 
1. We'll start by assuming you have your Commercial Certificate. If you don't, please see above.
 +
 
2. Store the certificate and CA Chain on one of your systems:
 
2. Store the certificate and CA Chain on one of your systems:
 
* Signed Certificate: /tmp/commercial.crt
 
* Signed Certificate: /tmp/commercial.crt
Line 191: Line 355:
 
* Root Certificate Authority (CA Root): /tmp/ca.crt
 
* Root Certificate Authority (CA Root): /tmp/ca.crt
 
* Any Intermediate CA Certs: /tmp/ca_intermediary.crt
 
* Any Intermediate CA Certs: /tmp/ca_intermediary.crt
 +
 
3. Combine root and intermediary CAs into a temporary file.
 
3. Combine root and intermediary CAs into a temporary file.
   # cat /tmp/ca_intermediary.crt /tmp/ca.crt > /tmp/ca_chain.crt
+
   cat /tmp/ca_intermediary.crt /tmp/ca.crt > /tmp/ca_chain.crt
 +
 
 
4. [Optional Step] If you previously had an earlier Commercial Certificate on this platform, it may help - make this easier and more consistent - to remove the old ones:
 
4. [Optional Step] If you previously had an earlier Commercial Certificate on this platform, it may help - make this easier and more consistent - to remove the old ones:
   # mv /opt/zimbra/ssl/zimbra /opt/zimbra/ssl/zimbra.old
+
   mv /opt/zimbra/ssl/zimbra /opt/zimbra/ssl/zimbra.old
 
Then recreate the directories:
 
Then recreate the directories:
   # mkdir /opt/zimbra/ssl/zimbra
+
   mkdir /opt/zimbra/ssl/zimbra
   # mkdir /opt/zimbra/ssl/zimbra/ca
+
   mkdir /opt/zimbra/ssl/zimbra/ca
   # mkdir /opt/zimbra/ssl/zimbra/commercial
+
   mkdir /opt/zimbra/ssl/zimbra/commercial
   # mkdir /opt/zimbra/ssl/zimbra/server
+
   mkdir /opt/zimbra/ssl/zimbra/server
   # chmod 740 /opt/zimbra/ssl/zimbra
+
   chmod 740 /opt/zimbra/ssl/zimbra   # chmod 750 for ZCS 8.7+
   # chmod 740 /opt/zimbra/ssl/zimbra/*
+
   chmod 740 /opt/zimbra/ssl/zimbra/*  # chmod 750 for ZCS 8.7+
 +
 
 +
4.5 If you go for step 4, copy the contents of /opt/zimbra/ssl/zimbra.old/ca/ directory to /opt/zimbra/ssl/zimbra/ca/
 +
  cp -pr /opt/zimbra/ssl/zimbra.old/ca/* /opt/zimbra/ssl/zimbra/ca/
 +
 
 
5. Copy the commercial.key to /opt/zimbra/ssl/zimbra/commercial
 
5. Copy the commercial.key to /opt/zimbra/ssl/zimbra/commercial
   # cp /tmp/commercial.key /opt/zimbra/ssl/zimbra/commercial/
+
   cp /tmp/commercial.key /opt/zimbra/ssl/zimbra/commercial/
   # chmod 640 /opt/zimbra/ssl/zimbra/commercial/commercial.key
+
   chmod 640 /opt/zimbra/ssl/zimbra/commercial/commercial.key
5. Verify your commercial certificate.
+
5. Verify your commercial certificate. (as user '''root in 8.6- or zimbra in 8.7+'''):
(as root):
+
   /opt/zimbra/bin/zmcertmgr verifycrt comm /opt/zimbra/ssl/zimbra/commercial/commercial.key /tmp/commercial.crt /tmp/ca_chain.crt
   # /opt/zimbra/bin/zmcertmgr verifycrt comm /opt/zimbra/ssl/zimbra/commercial/commercial.key /tmp/commercial.crt /tmp/ca_chain.crt
 
 
6. Deploy your commercial certificate.
 
6. Deploy your commercial certificate.
 
   /opt/zimbra/bin/zmcertmgr deploycrt comm /tmp/commercial.crt /tmp/ca_chain.crt
 
   /opt/zimbra/bin/zmcertmgr deploycrt comm /tmp/commercial.crt /tmp/ca_chain.crt
Line 214: Line 383:
 
8. In case of any issues in the Java keystore, check that the Intermediate CA was added to the keystore:
 
8. In case of any issues in the Java keystore, check that the Intermediate CA was added to the keystore:
  
   /opt/zimbra/java/bin/keytool -list -keystore \
+
   <8.7 # /opt/zimbra/java/bin/keytool -list -keystore \
   /opt/zimbra/java/jre/lib/security/cacerts -storepass changeit
+
    /opt/zimbra/java/jre/lib/security/cacerts -storepass changeit
 +
OR
 +
   8.7+ $ keytool -list -keystore \
 +
    /opt/zimbra/common/lib/jvm/java/jre/lib/security/cacerts -storepass changeit
  
 
If necessary, import the CA into the keystore:
 
If necessary, import the CA into the keystore:
  
   /opt/zimbra/java/bin/keytool -import -alias root -keystore \
+
   <8.7 # /opt/zimbra/java/bin/keytool -import -alias root -keystore \
   /opt/zimbra/java/jre/lib/security/cacerts -storepass changeit -file /opt/zimbra/conf/ca/commercial_ca.pem
+
    /opt/zimbra/java/jre/lib/security/cacerts -storepass changeit -file /opt/zimbra/conf/ca/commercial_ca.pem
 +
OR
 +
   8.7+ $ keytool -import -alias root -keystore \
 +
    /opt/zimbra/common/lib/jvm/java/jre/lib/security/cacerts -storepass changeit -file /opt/zimbra/conf/ca/commercial_ca.pem
 +
 
 
9. Copy these files to each of your other nodes, and repeat steps 4-8 on each node:
 
9. Copy these files to each of your other nodes, and repeat steps 4-8 on each node:
 
* Signed Certificate: /tmp/commercial.crt
 
* Signed Certificate: /tmp/commercial.crt
Line 226: Line 402:
 
* Certificate Chain: /tmp/ca_chain.crt
 
* Certificate Chain: /tmp/ca_chain.crt
  
==ZCS 4.5.x==
+
{{Article Footer|ZCS 8.x, 8.0.x, 7.0.x |9/10/2008}}
In ZCS 4.5.x, the task of creating a Certificate Authority, creating a self-signed certificate, and then installing the certificate is handled by three CLI commands. When you are installing a certificate, remember to stop and then restart Tomcat once the certificate has been installed.
 
 
 
===zmcreateca===
 
This command creates a Certificate Authority (CA).
 
 
 
====Syntax====
 
zmcreateca
 
 
 
===zmcreatecert===
 
This command creates a new self-signed certificate.
 
 
 
====Syntax====
 
zmcreatecert
 
 
 
===zmcertinstall===
 
This command installs a certificate.
 
 
 
'''''Note''': Tomcat must be stopped and restarted after you have installed a certificate.''
 
 
 
====Syntax====
 
zmcertinstall
 
 
 
===Example===
 
The follow example shows how to install a self-signed certificate on a ZCS 4.5.x server.
 
 
 
1. As root, type the follow commands.
 
  rm -rf /opt/zimbra/ssl
 
  mkdir /opt/zimbra/ssl
 
  chown zimbra:zimbra /opt/zimbra/ssl
 
2. Switch to the Zimbra User.
 
  su -zimbra
 
3. Type the following command.
 
  keytool -delete -alias my_ca -keystore /opt/zimbra/java/jre/lib/security/cacerts -storepass changeit
 
4. Create the Certificate Authority.
 
  zmcreateca
 
5. Create the self-signed certificate.
 
  zmcreatecert
 
'''''Note:''' You may need to type '''zmcreatecert host.domain.com''' if your host uses multiple names or aliases. (For example, if you have the hostname '''bingo.insidedomain.com''', which is aliased to '''mail.truedomain.com''', you will want to include the host and domain name for your certificate.)  When typing your domain, be sure that the hostname is the one used in the certificate.''
 
 
 
6. Install your certificate.
 
  zmcertinstall mailbox
 
7. Stop Tomcat.
 
  tomcat stop
 
8. Restart Tomcat.
 
  tomcat start
 
 
 
{{Article Footer|ZCS 4.5.x & 5.0.x|9/10/2008}}
 
  
 
[[Category:Administration]]
 
[[Category:Administration]]
Line 280: Line 409:
 
[[Category:Troubleshooting Certificates]]
 
[[Category:Troubleshooting Certificates]]
 
[[Category:Certified]]
 
[[Category:Certified]]
[[Category: ZCS 4.5]]
 
[[Category: ZCS 5.0]]
 

Latest revision as of 21:38, 18 April 2016

ZCS Certificates Tools

   KB 1312        Last updated on 2016-04-18  




0.00
(0 votes)

See also:


ZCS allows administrators to manage their certificates using either the Administration Console or the Command Line Interface (CLI). This article discusses the ZCS 8.x, 8.0.x, 7.0.x Administration Console, and the CLI tools for ZCS 8.x, 8.0.x, 7.0.x.

A note on CN and subjectAltName

By default ZCS requires valid certificates when communicating with hosts over TLS/SSL. As such, certificates within an install should be valid (not expired and have hostnames matching the certificate).

Per https://tools.ietf.org/html/rfc2818#section-3.1

If a subjectAltName extension of type dNSName is present, that MUST be used as the identity. Otherwise, the (most specific) Common Name field in the Subject field of the certificate MUST be used. Although the use of the Common Name is existing practice, it is deprecated and Certification Authorities are encouraged to use the dNSName instead.

See also RFC2459 section-4.2.1.7 for details on Subject Alternative Name handling and usage.

In short setting subjectAltName, it must include all host names to be trusted, not just "additional" ones beyond what is in CN (by default zmcertmgr will put `zmhostname` in the subjectAltName).

ZCS Administration Console

The ZCS Certificates tools are located in the Navigation pane, under Tools > Certificates. Once you have selected Certificates from this menu, the Manage Certificates tab opens in the Content pane. From here, you can view your deployed certificates or install a new certificate.

AdminConsoleManageCerts.png

In ZCS8 and above we will find the ZCS Certificates in the Navigation pane, under Configure>Certificates

SSL Install Web 001.png SSL Install Web 002.png

Viewing Certificates

Using the Administration Console, you can view the details of certificates currently deployed. Details include the certificate subject, issuer, validation days, and subject alternative name.

To view a certificate, select a service host name, either under Certificates in the Navigation pane or by selecting a Service host name in the Manage Certificates tab and clicking View Certificate. A Certificates tab for the service host name you selected opens in the Content Pane.

SSL Install Web 003.png

Information about the certificate:

SSL Install Web 004.png

You can refresh the currently displayed details by clicking Refresh at the top of the tab.

Generate a valid CSR (Certificate Signing Request) for a Commercial SSL

Go to Home > Configure > Certificates and click in the settings icon, then click on Install Certificate

Zimbra-ssl-adminconsole-001.png

Select the target server to generate the SSL files like the CSR and the private key:

Zimbra-ssl-adminconsole-002.png

In the next step, select the option Generate the CSR for the commercial certificate authorizer

Zimbra-ssl-adminconsole-003.png

In this window, you need to select the next settings:

  • Select digest SHA256 or above, not SHA1 as is not longer considered to be secure
  • Key Length 2048 or above
  • Common Name (CN) needs to be the FQDN that you want to use, if you are using a Single-Server is recommended that the FQDN and the hostname are the same.
  • The checkbox about the Wildcard is if you want to use a Wildcard SSL certificate for your Zimbra, and for the rest of you other FQDN in your Company. If the hostname and the FQDN doesn't match, but are in the same domain, use this option and buy a Wildcard Certificate.
  • In the Subject Alternative Name (SAN), you can select another names if you will use a Multi-SAN SSL certificate, this option is indicated if you want to have mail.customer1.com, mail.customer2.com, etc.

Zimbra-ssl-adminconsole-004.png

You can download now the CSR file, ready to send to your SSL Certificate Provider, if you miss this step, you can find the csr file in the next path /opt/zimbra/ssl/zimbra/commercial/commercial.csr:

Zimbra-ssl-adminconsole-005.png

You can check if your CSR is valid and correct using for example the next URL:

Zimbra-ssl-adminconsole-006.png

Installing Certificates

Clicking Install Certificate from either the Manage Certificates tab or a Certificates tab opens the Certificate Installation Wizard. The Certificate Installation Wizard is a tool that will help you quickly create and deploy a certificate.

Generating & Installing a Self-Signed Certificate

Sometimes we want to regenerate the Self-Signed Certificate, we can do it in the Administration Console. We need to click in the Cog>Select Install Certificate and follow the steps:

The first step is select Install the self-signed certificate

SSL Install Web 005.png

Next, we need to mark the checkbox Replace the existing CSR

SSL Install Web 006.png

We need to be sure of select the Key Length at 2048, and the rest of the fields, for now have a Bug Opened in 8.5 and also if you change this values will be the same default values - [1].

SSL Install Web 007.png

We can select also the time that we want to have this SSL validated, remember that is Self-Signed, if we are not planning any future change, we can select more than a year. And then press Install.

SSL Install Web 008.png

The SSL Certificate Self-Signed are now installing in our Zimbra Collaboration Server.

SSL Install Web 009.png

Once the installation has finish, the system request us a restart of the ZCS services.

SSL Install Web 010.png

Trough console by user zimbra we need to execute the next command, and wait until all services are up again:

zmcontrol restart

If we will go again to our https://mail.domain.com we will have the known problem with SSL Certificate in our Web Browser:

SSL Install Web 011.png

Generating Multiple CSRs using the Administration Console

Currently the Administration Console only supports having one Certificate Signing Request (CSR) and private key at a time. Generating a new CSR overrides the existing one and generates a new private key. To generate more than one CSR, move both the CSR and key from the directory it is generated in (e.g. /opt/zimbra/ssl/zimbra/commercial directory/) before generating another CSR.

Maintaining Valid Certificates

It is important to keep your SSL certificates valid to ensure clients and environments work properly, as the ZCS system can become non-functional if certificates are allowed to expire. You can view deployed SSL certificates from the ZCS administrator console, including their validation days. It is suggested that certificates are checked periodically, so you know when they expire and to maintain their validity.

ZCS Certificate CLI

The ZCS Certificate CLI commands for ZCS5 and greater differ from ZCS4 and earlier. The following sections discuss the CLI tools for ZCS5 and above.

zmcertmgr

This command allows you to manage certificates.

General Guidelines

Follow these guidelines when using this command.

  • For versions before 8.7, this tool must be run as root. In 8.7+, this tool is run as user zimbra.

Commercial Certificate Guidelines

Follow these guidelines when using this command to generate a commercial certificate.

  • The private key must exist in the /opt/zimbra/ssl/zimbra/commercial directory, and must be named commercial.key with its permission set to 740 before 8.7, and 640 in 8.7+.
  • The server certificate and the chain certificate files must exist in a temp directory. (E.g. /tmp/certs/)
  • The chain certificate files must be concatenated into one file called commercial_ca.crt

Syntax

zmcertmgr [options]

Description

Name Description
General Options
-help Displays usage options for zmcertmgr
Self-Signed Certificate Options
createca [-new] [-keysize keysize] [-digest digest] [-subject subject]
Generates a Certificate Authority (CA).
deployca [-localonly]
Deploys a Certificate Authority (CA). The -localonly avoids updating any certificate related settings in LDAP.
createcsr <self|comm> [-new] [-keysize keysize] [-digest digest] [-subject subject] [-subjectAltNames "host1,host2"]
Creates a certificate signing request (CSR) for either a self or commercially signed certificate authority. By default the CSR

subjectAltNames contains the current zmhostname (8.7 only: unless the -noDefaultSubjectAltName argument is used).

createcrt [-new] [-days validation days] [-keysize keysize] [-digest digest] [-subject subject] [-subjectAltNames "host1,host2"]
Creates a self-signed certificate based on the CSR generated using createcsr.
Where options are:
-new Force the generation of a new CA/Cert/CSR, overwriting existing data.
-keysize The RSA keysize in bits, for example "-keysize 4096". Minimum keysize is 2048. Default keysize is 2048. (as of 8.0.7 https://bugzilla.zimbra.com/show_bug.cgi?id=85023)
-subject The X.500 distinguished name (DN). The default was "/C=US/ST=N\/A/L=N\/A/O=Zimbra Collaboration Suite/OU=Zimbra Collaboration Suite/CN=${zimbra_server_hostname}" before 8.7, and in 8.7+ is "/OU=Zimbra Collaboration Suite/CN=${zimbra_server_hostname}" after.
‑subjectAltNames Additional host names that may use the certificate other than the one listed in the subject. The alternate names can be specified as comma separate values (or in 8.7+ the -subjectAltNames can be used multiple times).
Self-Signed (self) and Commercial (comm) Certificate Options
deploycrt <<self>|<comm [certfile ca_chain_file]>> [-allservers] [-localonly] [[-deploy $services] ...]
Deploys a certificate. For commercial certificates the certificate file and the certificate authority (CA) chain may be specified. For deploycrt, the use of -allservers will cause zmcertmgr to iterate through all servers in the ZCS deployment (zmprov gas, minus the initiating zmcertmgr host).
getcrt <self|comm> [-allservers]
savecrt <self|comm> [-allservers]
Get (or Save) a certificate. For getcrt and savecrt, the use of -allservers causes the configuration keys to be get/set as a global (getConfig/modifyConfig) configuration settings (zimbraSSLCertificate and zimbraSSLPrivateKey) instead of as a per-server setting (getServer/modifyServer).
viewcsr <self|comm> [csr_file]
Shows a certificate signing request (CSR). Optionally, the CSR file can be specified.
viewstagedcrt <self|comm> [certfile]
Shows a staged certificate. A staged certificate is placed in a staging file, where all files that will be deployed with the certificate are kept. You can use the staging area to verify that you are ready to deploy a certificate.
verifycrt <self|comm> [[[priv_key] [certfile]] [ca_chain_file]]
Combines verifycrtkey and verifycrtchain checks (see below).
verifycrtkey <priv_key> <certfile>
Compares certificate private key and certificate file modulus digests to ensure they match.
verifycrtchain <ca_chain_file> <certfile>
Verifies a certificate chain.
viewdeployedcrt [all|ldap|mailboxd|mta|proxy]
Shows a deployed certificate on the local server.
checkcrtexpiration [all|ldap|mailboxd|mta|proxy] [-days days]
Check if certificate(s) expire within -days days

Examples

The following are examples of using the above options for different installation scenarios.

Single-Node Self-Signed Certificate

1. Begin by generating a new Certificate Authority (CA).

 /opt/zimbra/bin/zmcertmgr createca -new

2. Then generate a certificate signed by the CA that expires in 1825 days.

 /opt/zimbra/bin/zmcertmgr createcrt -new -days 1825

3. Next deploy the certificate.

 /opt/zimbra/bin/zmcertmgr deploycrt self

4. Next deploy the CA.

 /opt/zimbra/bin/zmcertmgr deployca

5. To finish, verify the certificate was deployed to all the services.

 /opt/zimbra/bin/zmcertmgr viewdeployedcrt

Multi-Node Self-Signed Certificate

1. Begin by generating a new Certificate Authority (CA).

 /opt/zimbra/bin/zmcertmgr createca -new
 /opt/zimbra/bin/zmcertmgr deployca

2. Then generate a certificate signed by the CA that expires in 365 days with either wild-card or subject altnames.

 /opt/zimbra/bin/zmcertmgr createcrt -new -subjectAltNames "*.example.com"
 /opt/zimbra/bin/zmcertmgr createcrt -new -subject "/C=US/ST=CA/O=Example/CN=*.example.com"
 /opt/zimbra/bin/zmcertmgr createcrt -new -subjectAltNames "host1.example.com,host2.example.come"

3. Next, deploy the certificate to all nodes in the deployment.

 /opt/zimbra/bin/zmcertmgr deploycrt self -allserver

4. To finish, verify the certificate was deployed.

 /opt/zimbra/bin/zmcertmgr viewdeployedcrt

Note: The option viewdeployedcrt only works for the local server.

Alternate Method

The "-allserver" command above doesn't always work as expected, depending on whether the ssh keys are current and working properly. One can also create the new CA first on an LDAP Master node, and then manually deploy the CA and create the self-signed certs on all the other nodes:

On an LDAP Master:

/opt/zimbra/bin/zmcertmgr createca -new
/opt/zimbra/bin/zmcertmgr deployca
/opt/zimbra/bin/zmcertmgr createcrt -new -subject "/C=US/ST=CA/O=Example/CN=*.example.com"
OR
/opt/zimbra/bin/zmcertmgr createcrt -new -subjectAltNames "host1.example.com,host2.example.com"
OR
/opt/zimbra/bin/zmcertmgr createcrt -new -subjectAltNames "*.example.com"
/opt/zimbra/bin/zmcertmgr deploycrt self

On all other systems:

/opt/zimbra/bin/zmcertmgr deployca -localonly
/opt/zimbra/bin/zmcertmgr createcrt -new -subject "/C=US/ST=CA/O=Example/CN=*.example.com"
/opt/zimbra/bin/zmcertmgr deploycrt self

Single-Node Commercial Certificate

We need to take care and ask for the Certificate authority for the Root and Intermediate Keys, we will need it soon.

We will use at least 2048-bit key, is the minimum for all Certificate Authorities: 1. Begin by generating a Certificate Signing Request (CSR).

/opt/zimbra/bin/zmcertmgr createcsr comm -new -subject "/C=US/ST=CA/L=Sunnyvale/O=Zimbra/OU=Zimbra Collaboration Suite/CN=host.example.com" -subjectAltNames host.example.com

2. Next, submit the CSR to the SSL provider and get a commercial certificate in PEM format. Save the new certificate to a temporary file (e.g. /tmp/commercial.crt).

3. Now, download and save the root Certificate Authority (CA) from your provider to a temporary file. (e.g. /tmp/ca.crt)

4. Download any intermediary CAs from your provider to a temporary file. (e.g. /tmp/ca_intermediary.crt)

5. Combine root and intermediary CAs into a temporary file.

cat /tmp/ca_intermediary.crt /tmp/ca.crt > /tmp/ca_chain.crt

6. Verify your commercial certificate.

/opt/zimbra/bin/zmcertmgr verifycrt comm /opt/zimbra/ssl/zimbra/commercial/commercial.key /tmp/commercial.crt /tmp/ca_chain.crt
**Verifying /tmp/commercial.crt against
/opt/zimbra/ssl/zimbra/commercial/commercial.key
Certificate (/tmp/commercial.crt) and private key
(/opt/zimbra/ssl/zimbra/commercial/commercial.key) match.
Valid Certificate: /tmp/commercial.crt: OK

7. Deploy your commercial certificate.

/opt/zimbra/bin/zmcertmgr deploycrt comm /tmp/commercial.crt /tmp/ca_chain.crt
** Verifying /tmp/commercial.crt against
/opt/zimbra/ssl/zimbra/commercial/commercial.key
Certificate (/tmp/commercial.crt) and private key
(/opt/zimbra/ssl/zimbra/commercial/commercial.key) match.
Valid Certificate: /tmpt/commercial.crt: OK
**Copying commercial.crt to /opt/zimbra/ssl/zimbra/commercial/commercial.crt
**Appending CA chain /tmp/ca_chain.crt to
/opt/zimbra/ssl/zimbra/commercial/commercial.crt
**Saving server config key zimbraSSLCeretificate…done.
**Saving server config key zimbraSSLPrivateKey…done.
**Installing mta certificate and key…done.
**Installing slapd certificate and key…done.
**Installing proxy certificate and key…done.
**Creating pkcs12 file /opt/zimbra/ssl/zimbra/jetty.pkcs12…done.
**Creating keystore file /opt/zimbra/mailbox/etc/keystore…done.
**Installing CA to /opt/zimbra/conf/ca…done.

8. To finish, verify the certificate was deployed.

/opt/zimbra/bin/zmcertmgr viewdeployedcrt

Single-Node Wildcard Commercial Certificate

Using a Wildcard Certificate, you will need the next files, because you probably generated the CSR in other server:

  • The .key file which you generated the CSR.
  • The .crt file that you SSL provide to you.
  • The CA Intermediate and the root files merged into one only file, called for example ca_chain.crt

1.- Backup your actual .key file located in /opt/zimbra/ssl/zimbra/commercial/commercial.key:

mv /opt/zimbra/ssl/zimbra/commercial/commercial.key /opt/zimbra/ssl/zimbra/commercial/commercial.key.backup

2.- Move your actual .key file into the path /opt/zimbra/ssl/zimbra/commercial/ with the name commercial.key:

mv /tmp/wildcard.key /opt/zimbra/ssl/zimbra/commercial/commercial.key

3.- Verify all the files before deploy the SSL certificate with the next command:

/opt/zimbra/bin/zmcertmgr verifycrt comm /opt/zimbra/ssl/zimbra/commercial/commercial.key /tmp/wildcard.crt /tmp/ca_chain.crt

4.- Then as user root (or zimbra for 8.7+) run the next command, please be sure to use the proper path instead /tmp:

/opt/zimbra/bin/zmcertmgr deploycrt comm /tmp/wildcard.crt /tmp/ca_chain.crt

5.- Restart your Zimbra Collaboration server as Zimbra user:

zmcontrol restart

6.- To finish, verify the certificate was deployed.

 /opt/zimbra/bin/zmcertmgr viewdeployedcrt

Multi-Node Commercial Certificate

1. We'll start by assuming you have your Commercial Certificate. If you don't, please see above.

2. Store the certificate and CA Chain on one of your systems:

  • Signed Certificate: /tmp/commercial.crt
  • Certificate Key (Private): /tmp/commercial.key
  • Root Certificate Authority (CA Root): /tmp/ca.crt
  • Any Intermediate CA Certs: /tmp/ca_intermediary.crt

3. Combine root and intermediary CAs into a temporary file.

 cat /tmp/ca_intermediary.crt /tmp/ca.crt > /tmp/ca_chain.crt

4. [Optional Step] If you previously had an earlier Commercial Certificate on this platform, it may help - make this easier and more consistent - to remove the old ones:

 mv /opt/zimbra/ssl/zimbra /opt/zimbra/ssl/zimbra.old

Then recreate the directories:

 mkdir /opt/zimbra/ssl/zimbra
 mkdir /opt/zimbra/ssl/zimbra/ca
 mkdir /opt/zimbra/ssl/zimbra/commercial
 mkdir /opt/zimbra/ssl/zimbra/server
 chmod 740 /opt/zimbra/ssl/zimbra    # chmod 750 for ZCS 8.7+
 chmod 740 /opt/zimbra/ssl/zimbra/*  # chmod 750 for ZCS 8.7+

4.5 If you go for step 4, copy the contents of /opt/zimbra/ssl/zimbra.old/ca/ directory to /opt/zimbra/ssl/zimbra/ca/

 cp -pr /opt/zimbra/ssl/zimbra.old/ca/* /opt/zimbra/ssl/zimbra/ca/ 

5. Copy the commercial.key to /opt/zimbra/ssl/zimbra/commercial

 cp /tmp/commercial.key /opt/zimbra/ssl/zimbra/commercial/
 chmod 640 /opt/zimbra/ssl/zimbra/commercial/commercial.key

5. Verify your commercial certificate. (as user root in 8.6- or zimbra in 8.7+):

 /opt/zimbra/bin/zmcertmgr verifycrt comm /opt/zimbra/ssl/zimbra/commercial/commercial.key /tmp/commercial.crt /tmp/ca_chain.crt

6. Deploy your commercial certificate.

 /opt/zimbra/bin/zmcertmgr deploycrt comm /tmp/commercial.crt /tmp/ca_chain.crt

7. To finish, verify the certificate was deployed.

 /opt/zimbra/bin/zmcertmgr viewdeployedcrt

8. In case of any issues in the Java keystore, check that the Intermediate CA was added to the keystore:

 <8.7 # /opt/zimbra/java/bin/keytool -list -keystore \
   /opt/zimbra/java/jre/lib/security/cacerts -storepass changeit
OR
 8.7+ $ keytool -list -keystore \
   /opt/zimbra/common/lib/jvm/java/jre/lib/security/cacerts -storepass changeit

If necessary, import the CA into the keystore:

 <8.7 # /opt/zimbra/java/bin/keytool -import -alias root -keystore \
   /opt/zimbra/java/jre/lib/security/cacerts -storepass changeit -file /opt/zimbra/conf/ca/commercial_ca.pem
OR
 8.7+ $ keytool -import -alias root -keystore \
   /opt/zimbra/common/lib/jvm/java/jre/lib/security/cacerts -storepass changeit -file /opt/zimbra/conf/ca/commercial_ca.pem

9. Copy these files to each of your other nodes, and repeat steps 4-8 on each node:

  • Signed Certificate: /tmp/commercial.crt
  • Certificate Key (Private): /tmp/commercial.key
  • Certificate Chain: /tmp/ca_chain.crt
Verified Against: ZCS 8.x, 8.0.x, 7.0.x Date Created: 9/10/2008
Article ID: https://wiki.zimbra.com/index.php?title=Administration_Console_and_CLI_Certificate_Tools Date Modified: 2016-04-18



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