mirror of
https://github.com/YunoHost/doc.git
synced 2024-09-03 20:06:26 +02:00
178 lines
8 KiB
Markdown
178 lines
8 KiB
Markdown
|
|
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 pain. 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](hdiagnostic) 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 cannot be done automatically for now. You will need to manually create a
|
|
Certificate Signing Request (CSR) to be given to your CA, and manually import
|
|
the certificate you get from it. Check out [this page](certificate) for more
|
|
info. This process might be made easier by Yunohost in the future.
|
|
|
|
Migration procedure
|
|
--------------------
|
|
|
|
> Because of the current [rate limits](https://letsencrypt.org/docs/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, or from
|
|
the command line with :
|
|
|
|
```bash
|
|
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 a self-signed certificate.
|
|
|
|
|
|
#### I manually installed my Let's Encrypt 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 :
|
|
|
|
```bash
|
|
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` :
|
|
|
|
```bash
|
|
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](https://en.wikipedia.org/wiki/Public-key_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](https://en.wikipedia.org/wiki/Man-in-the-middle_attack).
|
|
|
|
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](https://en.wikipedia.org/wiki/Public_key_certificate).
|
|
|
|
#### Why do browsers complain about self-signed certificates ?
|
|
|
|
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](https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment),
|
|
which allows 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](https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment). It
|
|
basically works as follow (it's simplified, but you'll 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](http://www.darkreading.com/endpoint/authentication/fake-google-digital-certificates-found-and-confiscated/d/d-id/1297165),
|
|
[2](https://reflets.info/microsoft-et-ben-ali-wikileaks-confirme-les-soupcons-d-une-aide-pour-la-surveillance-des-citoyens-tunisiens/)].
|
|
|
|
Alternatives have been proposed, such as
|
|
[DANE/DNSSEC](https://en.wikipedia.org/wiki/DNS-based_Authentication_of_Named_Entities),
|
|
which is based on the DNS system does not require certification authorities.
|
|
|
|
|