From 1a5bfe71ff550df5f8160f6305867f667371e3fa Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Thu, 22 Dec 2016 12:01:11 -0500 Subject: [PATCH 1/3] Add documentation / FAQ about certificate management in yunohost --- certmanager.md | 178 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 certmanager.md diff --git a/certmanager.md b/certmanager.md new file mode 100644 index 00000000..62fc433c --- /dev/null +++ b/certmanager.md @@ -0,0 +1,178 @@ + +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](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 is not supported yet. You might need to manually crate Certificate Signing +Request (CSR) to be given to your CA, and manually import the certificate you +got from it. Check out [this page](certificate) for more info. This process +might 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, of 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 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 : + +```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 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](https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment), +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](https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment). 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](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. + + From adaafda428bc8cbe99641c2c849b8328936242b5 Mon Sep 17 00:00:00 2001 From: "ljf (zamentur)" Date: Tue, 10 Jan 2017 15:07:09 +0100 Subject: [PATCH 2/3] [fix] Typo --- certmanager.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/certmanager.md b/certmanager.md index 62fc433c..ecf47f80 100644 --- a/certmanager.md +++ b/certmanager.md @@ -25,7 +25,7 @@ run every day and attempt to renew any certificate that will expire in less than #### 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 crate Certificate Signing +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](certificate) for more info. This process might made easier by Yunohost in the future. From 742532acae8e3c9a92ff60e2ebe97889d4c632bf Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Sat, 14 Jan 2017 19:54:39 +0100 Subject: [PATCH 3/3] Typos / comments from @julienmalik --- certmanager.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/certmanager.md b/certmanager.md index ecf47f80..e0a4fb5a 100644 --- a/certmanager.md +++ b/certmanager.md @@ -6,7 +6,7 @@ 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 +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`. @@ -25,10 +25,10 @@ run every day and attempt to renew any certificate that will expire in less than #### 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](certificate) for more info. This process -might made easier by Yunohost in the future. +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 -------------------- @@ -40,10 +40,10 @@ This is especially true for nohost.me / noho.st users (and other domains service 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. +#### 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 +management feature. You can do it from the web administration interface, or from the command line with : ```bash @@ -53,10 +53,10 @@ 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. +certificate on all your domains which have a self-signed certificate. -#### I manually installed my certificates. +#### 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 @@ -126,7 +126,7 @@ whole process relies on trust in third parties called Certification Authorities 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 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 @@ -141,7 +141,7 @@ human intervention, time and money. In 2015, Let's Encrypt, developped a protocol called [ACME](https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment), -that allow to automatically verify that a machine controls a domain and deliver +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. @@ -150,7 +150,7 @@ certificate. 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 get the idea) : +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