doc/certmanager.md

Certificate management

Managing certificates with Yunohost

The main feature of the certificate manager is to allow you to install Let's Encrypt certificate on your domains without plain. You can use it from the web administration (SSL certificate on a given domain info page), or from the command line with yunohost domain cert-status, cert-install and cert-renew.

What is required to be able to have a Let's Encrypt certificate ?

Your server needs to be reachable from the rest of Internet on port 80 (and 443), and make your domain.tld points to your server's public IP in your DNS configuration. See this documentation if you need help.

Will my certificate be automatically be renewed ?

Yes. Right now, Let's Encrypt certificates are valid 90 days. A cron job will run every day and attempt to renew any certificate that will expire in less than 15 days. An email will be sent to the root user if a renewal fails.

I want/need to use a certificate from a different CA than Let's Encrypt.

This is not supported yet. You might need to manually create Certificate Signing Request (CSR) to be given to your CA, and manually import the certificate you got from it. Check out this page for more info. This process might made easier by Yunohost in the future.

Migration procedure

Because of the current rate limits on new Let's Encrypt certificate emissions, we recommend that you do not migrate to the new built-in management feature as long as you don't need to. This is especially true for nohost.me / noho.st users (and other domains services sharing a common subdomain). If too many people migrate during the same period of time, you might get stuck with a self-signed certificate for a few days !

I used the letsencrypt_ynh app.

You will be asked to uninstall the app before being able to use the new management feature. You can do it from the web administration interface, of from the command line with :

yunohost app remove letsencrypt
yunohost domain cert-install

Be aware that the first command will revert your domains to self-signed certificate. The second command will attempt to reinstall a Let's Encrypt certificate on all your domains which have self-signed certificate.

I manually installed my certificates.

You should go in your nginx configuration, and remove the letsencrypt.conf (or whatever you called the file containing the location '/.well-known/acme-challenge' block) for each of your domains. Remove your certificate renewer cron job in /etc/cron.weekly/, and backup and remove your /etc/letsencrypt/ folder.

Then run :

yunohost domain cert-install your.domain.tld --force

for each of your domains you want a Let's Encrypt certificate.

Troubleshooting

Admin interfaces says the letsencrypt app is installed, but it's not, and I can't access the certificate management interface !

Make sure you refresh the cache of your browser (Ctrl + Shift + R on Firefox), and report the issue on the forum or on the bugtracker. You can work around the issue by using yunohost domain cert-install your.domain.tld from the command line.

I tried to uninstall the letsencrypt app, but it broke my nginx conf !

Sorry about that. Some user reported that this happens when the uninstallation script fails to find a backup of your self-signed certificate. Running yunohost domain cert-install should work anyway...

I get "Too many certificates already issued", what's happening ?

Currently, Let's Encrypt has a rate limit of issuing no more than 20 new certificates by period of 7 days for a given subdomains. For example, nohost.me and noho.st are already considered as subdomains themselves, meaning all users of the nohost.me / noho.st service share the same common limit. According to Let's Encrypt, this applies for new certificates, but not for renewals or duplicates. If you encounter this limit, there isn't much to do except retrying a few days later.

Certificate installation fails, says "Wrote file to 'some path', but couldn't download 'some url'" !

This should be fixed in the future, but for now you might need to manually add the following line in your /etc/hosts :

127.0.0.1 your.domain.tld

About certificates and Let's Encrypt

What is HTTPS ? What's the point of SSL certificates ?

HTTPS is the secure version of the HTTP protocol, which describes how a client (e.g. a web browser) and a server (e.g. nginx running on your Yunohost instance) can talk to each other. HTTPS heavily relies on asymmetric cryptography to achieve two things :

• confidentiality, meaning that an attacker will not be able to decrypt the content of the communication if it is intercepted ;
• server's identification, meaning that a server can prove he is who it says it is, thus protecting against man-in-the-middle attacks.

SSL certificates is the technology used for server to prove their identity. The whole process relies on trust in third parties called Certification Authorities (CA), whose role is to verify the server identity (e.g. that a given machine effectively controls the domain ilikecoffee.com) before delivering cryptographic certificates.

Why do browsers complain about self-signed certificate ?

Self-signed certificates are, as their name says, self-signed, meaning that you were your own certification authority in the process. Such a certificate does not allow to verify your server's identity, since it could have easily been generated by an attacker on its own, attempting to perform man-in-the-middle attacks.

What's up with Let's Encrypt ?

Historically, the process of verifying the identity of a server often required human intervention, time and money.

In 2015, Let's Encrypt, developped a protocol called ACME, that allow to automatically verify that a machine controls a domain and deliver certificates for free, drastically reducing the cost of setting up a SSL certificate.

How does Let's Encrypt works ?

To verify your server's identity and deliver the certificate, Let's Encrypt uses the ACME protocol. It basically works as follow (it's simplified, but you get the idea) :

• A program running on your server contacts the Let's Encrypt CA server, ask for a certificate for domain ilikecoffee.com.
• The Let's Encrypt CA server generates a random string such as A84F2D0B, and tells the program on your server to prove it operates the domain ilikecoffee.com by making the URI http://ilikecoffee.com/.well-known/acme-challenge/A84F2D0B accessible.
• The program on your server edit/creates files accordingly.
• The Let's Encrypt CA server attempt to access the URI. If it works, then it concludes the program indeed operates the domain ilikecoffee.com. It delivers a certificate.
• The program on your server obtains the certificate and setups it.

Do we really need Certification Authorities ?

The reliance on Certification Authorities can be criticized, as they represent points of failure in the security scheme. Some trusted CAs have been found to issue rogue certificates in the past, sometimes with critical implications [1, 2].

Alternatives have been proposed, such as DANE/DNSSEC, which is based on the DNS system does not require certification authorities.