Certification authority (CA)¶
Zentyal uses OpenSSL® [4] for the management of the Certification Authority and the life cycle of the issued certificates issued.
| [4] | http://www.openssl.org/ |
Certification Authority configuration with Zentyal¶
In Zentyal, the Certification Authority module is self-managed, which means that it does not need to be enabled in Module status. However, you have to initialize the CA to make the functionality of the module available to other services.
Go to Certification Authority ‣ General and you will find the form to create the CA. You are requested to fill in the Organization Name and Days to expire fields. Optionally, it is possible to specify the Country code (a two-letter acronym following the ISO-3166-1 standard [5]), City and State.
Create the CA certificate
When setting the expiration date, take into account that all certificates issued by this CA will be revoked upon expiration, stopping all services depending on those certificates.
Once the CA has been initialised, you will be able to issue certificates. The required data are the Common Name of the certificate and the Days to expire. This last field is limited by the fact that no certificate can be valid for a longer time than the CA. In case you are using the certificate for a service such as a mail server, the Common Name of the certificate should match the domain name of that server. For example, if you are using the domain name hq.zentyal.org to access your mail server in Zentyal, you will need a certificate with the same Common Name. In case you are setting a user certificate, the Common Name will usually be the user’s email address.
Optionally, you could set Subject Alternative Names [6] for the certificate. These are useful when setting common names to a certificate, for instance an email address when signing email messages.
Warning
All the certificates issued by the new CA won’t be recognised by third party software like web browsers or mail clients. This is because the CA that Zentyal creates isn’t official, however, all the traffic will be encrypted.
Common warning when the CA module is used
Tip
Let’s Encrypt [7] is a free, automated, and open certificate authority (CA) that provides trusted certificate. In the last section of this document you can see an implementation guide.
Once the certificate is issued, it will appear in the list of certificates and it will be available for the administrator and for the rest of modules. Through the certificate list you can perform several actions on the certificates:
- Download the public key, private key and the certificate.
- Renew the certificate.
- Revoke the certificate.
- Reissue a previously revoked or expired certificate.
Certificate list page
The package with the keys contains also a PKCS12 file with the private key and the certificate and it can be installed directly into other programs such as web browsers, mail clients, etc.
If you renew a certificate, the current certificate will be revoked and a new one with the new expiration date will be issued. And if you renew the CA, all certificates will be renewed with the new CA trying to keep the old expiration date. If this is not possible because it is after the date of expiry of the CA, then the date of expiration is set as the one of the CA.
Renew a certificate
If you revoke a certificate you will not be able to use it anymore as this action is permanent and it can not be undone. Optionally, you can select the reason of the certificate revocation:
- unspecified: reason non specified,
- keyCompromise: the private key has been compromised,
- CACompromise: the private key for the certification authority has been compromised,
- affilliationChanged: the issued certificate has changed its affiliation to another certification authority from other organization,
- superseded: the certificate has been renewed and it is now replaced by a new one,
- cessationOfOperation: the certification authority has ceased its operations,
- certificateHold: certified suspended,
- removeFromCRL: currently unimplemented, it provides delta CRLs support, that is, lists of certificates whose revoked status has changed.
Revoke a certificate
When a certificate expires all the modules are notified. The expiration date of each certificate is automatically checked once a day and every time you access the certificate list page.
| [5] | ISO_3166-1 http://en.wikipedia.org/wiki/ISO_3166-1 |
| [6] | Subject alternative names http://www.openssl.org/docs/apps/x509v3_config.html#Subject_Alternative_Name |
| [7] | Let’s Encrypt https://letsencrypt.org/ |
| [8] | Certbot https://certbot.eff.org/lets-encrypt/ubuntubionic-apache.html |
Services Certificates¶
On Certification Authority ‣ Services Certificates you can find the list of Zentyal modules using certificates for their operation. Each module generates its own self-signed certificates, but you can replace them with others issued by your CA.
You can generate a certificate for each service by defining its Common Name. If a previous certificate with the name does not exist, the CA will create it automatically.
Services Certificates
Once enabled, you need to restart the service to force the module to use the new certificate. This also applies if you renew a certificate for a module.
As mentioned before, to use the secure version of multiple protocols (like mail) it is important that the name that appears in the “Common name” of the certificate matches with the name requested by the client. For example, if the Common name of your mail certificate is hq.zentyal.org and the client types in his client mail.hq.zentyal.org, the client will show a security alert (or reject the connection) and the certificate will be considered as a not valid one.
Service certificate checklist:
- The Certification Authority is created, service module is installed.
- You have created a DNS name for the service (A or CNAME) that the client can resolve, for example ‘mail.hq.zentyal.org’.
- You issue a certificate for the specific service, let’s say ‘Mail’ with Common Name ‘mail.hq.zentyal.org’, and after that you enable the certificate you should be able to see it going to Certification Authority ‣ General.
- You have enabled the secure protocols for mail.
- You have imported the CA certificate (not the service certificate) on the client’s system, or client application, let’s say the mail client.
- User configures mail as mail.hq.zentyal.org.
- User is able to resolve the DNS to an IP address, the Common Name perfectly matches what he/she typed “mail.hq.zentyal.org”, and the certificate presented by the service is signed by a trusted Authority.
- User’s application is able to start a secure session without displaying any security warnings
Let’s Encrypt configuration¶
Let’s Encrypt [8] is a non-profit certificate authority run by Internet Security Research Group (ISRG) that provides X.509 certificates for Transport Layer Security (TLS) encryption at no charge. The certificate is valid for 90 days, during which renewal can take place at any time. The offer is accompanied by an automated process designed to overcome manual creation, validation, signing, installation, and renewal of certificates for secure websites.
Before describing in detail how Let’s Encrypt should de deployed on Zentyal 6.1, you should be aware of the following considerations:
- Domain to which certificates are to be issued must be accessible from the Internet.
- Ports 80 and 443 must be open for Let’s Encrypt to verify the information it needs.
- Let’s Encrypt is a third-party software that is not integrated into Zentyal, so any incident in this regard will be the responsibility of the technician in charge of managing the Zentyal Server.
- You can find more information about Let’s Encrypt here [9]
The steps to install Let’s Encrypt in Zentyal 6.1 are:
Install the required software packages:
sudo apt-get install software-properties-common
Add to your repositories the Let’s Encrypt repository:
sudo add-apt-repository ppa:certbot/certbot
Install the necessary package to generate certificates:
sudo apt-get update sudo apt-get install python-certbot-apache
Once Let’s Encrypt has been installed, you can proceed to generate the certificates. See the example below:
certbot --apache -m abraham@zentyal-domain.com
When the certificate has been correctly issued and stored on your Zentyal Server, the next step is to configure the services to use this certificate. Below you can find some of the most common paths used to establish the certificate:
- For the Zentyal Webadmin module: /usr/share/zentyal/stubs/core/nginx.conf.mas .
- For the Zentyal Mail (SMTP) module: /usr/share/zentyal/stubs/mail/main.cf.mas .
- For the Zentyal Mail (IMAP/POP) module: /usr/share/zentyal/stubs/mail/dovecot.conf.mas .
- For the Zentyal Sogo module: /etc/apache2/sites-enabled/default-ssl.conf .
- For the Zentyal Jabber module: /usr/share/zentyal/stubs/jabber/ejabberd.yml.mas .
Warning
Some configuration files are managed by Zentyal, so you have to make the changes through configuration templates by using stubs. [10]
| [9] | Let’s Encrypt https://letsencrypt.org/about/ |
| [10] | Stubs https://doc.zentyal.org/en/appendix-c.html#stubs |
Information about Certificate Revocation List (CRL)¶
In versions prior to Zentyal 6.2, this module had the crl_default_days configuration parameter value set to 30 days, which caused the following error in the Virtual private network (VPN) service with OpenVPN module:
Sun May 3 12:11:13 2020 41.56.2.24:60271 VERIFY ERROR: depth=0, error=CRL has expired: C=ZA, ST=Free
The reason for this error is that if in the last 30 days there was no revoked or expired certificates, the /var/lib/zentyal/CA/crl/latest.pem file was not modified and therefore caused the error.
If you are hitting this issue, you simply have to create and revoke a certificate. This way the file will be updated and the connections can be established again.
In the latest CA module versions (6.2.0 and 6.1.1) this value has been set to 10 years to avoid the issue. However, we recommend that before configuring the CA module you analyse whether you want to modify this value.