Merge pull request #448 from YunoHost/images_for_le

[enh] Update instructions for certificate installation

certificate.md

@@ -13,109 +13,83 @@ It could afraid a lot of users (rightly).
 To avoid this confusion, it's possible to get a signed certificate  by a "known" authority : **Gandi**, **RapidSSL**, **StartSSL**, **CaCert**.
 In these cases, the point is to replace the self-signed certificate with the one that has been certified by a certificate authority, and the users won't have this warning screen anymore.
 
-### Add a signed certificate by an authority
+To avoid this confusion, it's possible to get a certificate signed a known
+authority named **Let's Encrypt** which provide free certificates directly
+recognized by browsers. YunoHost allows to directly install this certificate
+from the web administration interface or from the command line.
 
-Get your certificate from your CA, you must get a private key, file key and a public certificate (file .crt)
+### Install a Let's Encrypt certificate
-> Be carefull, the key file is very critical, it's strictly personal and have to be secured.
 
-Copy this two files on the server, if not.
+Before attempting to install a Let's Encrypt certificate, you should make sure
+that your DNS is correctly configured (votre.domaine.tld should point to
+your server's IP) and that your domain is accessible though HTTP from outside
+your local network (i.e. at least port 80 should be forwarded to your server).
 
-```bash
+#### From the web administration interface
-scp CERTIFICAT.crt admin@DOMAIN.TLD:ssl.crt
+
-scp CLE.key admin@DOMAIN.TLD:ssl.key
+Go to the 'Domain' part of the admin interface, then in the section dedicated to
+your.domain.tld. You should find a 'SSL certificate' button :
+
+![](./images/domain-certificate-button.png)
+
+In the 'SSL certificate' section, you can see the status of the current
+certificate. If you just added the domain, it should be a self-signed
+certificate.
+
+![](./images/certificate-before-LE.png)
+
+If your domain is correctly configured, it is then possible to install the
+Let's Encrypt certificate via the green button.
+
+![](./images/certificate-after-LE.png)
+
+Once the install is made, you can check that the certificate is live via your
+browser by going to your domain in HTTPS. The certificate will automatically
+be renewed every three months.
+
+![](./images/certificate-signed-by-LE.png)
+
+#### From the command line interface 
+
+Connect to your server through SSH.
+
+You can check the status of your current certificate with :
+
+```
+yunohost domain cert-status your.domain.tld
 ```
 
-From Windows, scp can be used with putty, download [pscp](http://the.earth.li/~sgtatham/putty/latest/x86/pscp.exe)
+Install a Let's Encrypt certificate with
 
-```bash
+```
-pscp -P 22 CERTIFICAT.crt admin@DOMAIN.TLD:ssl.crt
+yunohost domain cert-install your.domain.tld
-pscp -P 22 CLE.key admin@DOMAIN.TLD:ssl.key```
+```
 
-Now the files are in the server. Open a shell on the server use [ssh](https://yunohost.org/#/ssh_fr) or locally.
+This should return :
 
-First, create a directory for archive the certificates.
+```
+Success! The SSOwat configuration has been generated
+Success! Successfully installed Let's Encrypt certificate for domain DOMAIN.TLD!
+```
 
-```bash
+Once this is done, you can check that the certificate is live via your
-sudo mkdir /etc/yunohost/certs/DOMAIN.TLD/ae_certs
+browser by going to your domain in HTTPS. The certificate will automatically
-sudo mv ssl.key ssl.crt /etc/yunohost/certs/DOMAIN.TLD/ae_certs/```
+be renewed every three months.
 
-Then go to the parent directory and go on.
+##### Troubleshooting
 
-```bash
+If due to some bad tweaking, your certificate ends up in a bad state (e.g.
-cd /etc/yunohost/certs/DOMAIN.TLD/```
+lost the certificate or unable to read the files), you should be able to clean
+the situation by regenerating a self-signed certificate :
 
-Make a backup of the YunoHost original certificates , to be safe!
+```
+yunohost domain cert-install your.domain.tld --self-signed --force
+```
 
-```bash
+If YunoHost thinks that your domain is badly configured despite the fact that
-sudo mkdir yunohost_self_signed
+you checked the DNS configuration and you have access in HTTP to your server
-sudo mv *.pem *.cnf yunohost_self_signed/```
+from outside your local network, then you can :
 
-Depends on the CA, intermediate certificates and root have to be downloaded.
+- add a line `127.0.0.1 your.domain.tld` to the file `/etc/hosts` on your server ;
-
+- if the certificate installation still doesn't work, you can disable the checks with `--no-checks` after the `cert-install` command.
-> **StartSSL**
-> ```bash
-> sudo wget http://www.startssl.com/certs/ca.pem -O ae_certs/ca.pem
-> sudo wget http://www.startssl.com/certs/sub.class1.server.ca.pem -O ae_certs/intermediate_ca.pem```
-
-> **Gandi**
-> ```bash
-> sudo wget https://www.gandi.net/static/CAs/GandiStandardSSLCA.pem -O ae_certs/intermediate_ca.pem```
-
-> **RapidSSL**
-> ```bash
-> sudo wget https://knowledge.rapidssl.com/library/VERISIGN/INTERNATIONAL_AFFILIATES/RapidSSL/AR1548/RapidSSLCABundle.txt -O ae_certs/intermediate_ca.pem```
-
-> **Cacert**
-> ```bash
-> sudo wget http://www.cacert.org/certs/root.crt -O ae_certs/ca.pem
-> sudo wget http://www.cacert.org/certs/class3.crt -O ae_certs/intermediate_ca.pem```
-
-Intermediate certificates and root must be merged with certificates obtained to create a unified chain certificates.
-
-```bash
-cat ae_certs/ssl.crt ae_certs/intermediate_ca.pem ae_certs/ca.pem | sudo tee crt.pem```
-
-
-The private key have to be converted in PEM format.
-
-```bash
-sudo openssl rsa -in ae_certs/ssl.key -out key.pem -outform PEM```
-
-Check certificates syntaxe, check file contents.
-
-```bash
-cat crt.pem key.pem```
-
-Certificates and private key look like this :
-
-`-----BEGIN CERTIFICATE-----`    
-`MIICVDCCAb0CAQEwDQYJKoZIhvcNAQEEBQAwdDELMAkGA1UEBhMCRlIxFTATBgNV`
-`BAgTDENvcnNlIGR1IFN1ZDEQMA4GA1UEBxMHQWphY2NpbzEMMAoGA1UEChMDTExC`
-`MREwDwYDVQQLEwhCVFMgSU5GTzEbMBkGA1UEAxMSc2VydmV1ci5idHNpbmZvLmZy`
-`MB4XDTA0MDIwODE2MjQyNloXDTA0MDMwOTE2MjQyNlowcTELMAkGA1UEBhMCRlIx`
-`FTATBgNVBAgTDENvcnNlIGR1IFN1ZDEQMA4GA1UEBxMHQWphY2NpbzEMMAoGA1UE`
-`ChMDTExCMREwDwYDVQQLEwhCVFMgSU5GTzEYMBYGA1UEAxMPcHJvZi5idHNpbmZv`
-`LmZyMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDSUagxPSv3LtgDV5sygt12`
-`kSbN/NWP0QUiPlksOkF2NkPfwW/mf55dD1hSndlOM/5kLbSBo5ieE3TgikF0Iktj`
-`BWm5xSqewM5QDYzXFt031DrPX63Fvo+tCKTQoVItdEuJPMahVsXnDyYHeUURRWLW`
-`wc0BzEgFZGGw7wiMF6wt5QIDAQABMA0GCSqGSIb3DQEBBAUAA4GBALD640iwKPMf`
-`pqdYtfvmLnA7CiEuao60i/pzVJE2LIXXXbwYjNAM+7Lov+dFT+b5FcOUGqLymSG3`
-`kSK6OOauBHItgiGI7C87u4EJaHDvGIUxHxQQGsUM0SCIIVGK7Lwm+8e9I2X0G2GP`    
-`9t/rrbdGzXXOCl3up99naL5XAzCIp6r5`  
-`-----END CERTIFICATE-----`
-
-At last, secure files of your certificate
-
-```bash
-sudo chown root:metronome crt.pem key.pem
-sudo chmod 640 crt.pem key.pem
-sudo chown root:root -R ae_certs
-sudo chmod 600 -R ae_certs```
-
-Reload Nginx configuration to take into account the new certificate.
-
-```bash
-sudo service nginx reload```
-
-Your certificate is ready to serve. You can check that every thing is correct byan external service like <a href="https://www.geocerts.com/ssl_checker" target="_blank">geocerts</a>
 

certificate_fr.md

@@ -10,113 +10,86 @@ En effet, les utilisateurs devront passer par un écran de ce type :
 Cet écran revient à demander **« Avez-vous confiance au serveur qui héberge ce site ? »**.
 Cela peut effrayer vos utilisateurs (à juste titre).
 
-Pour éviter cette confusion, il est possible d’obtenir un certificat signé par une autorité « connue » : **Gandi**, **RapidSSL**, **StartSSL**, **Cacert**.    
+Pour éviter cette confusion, il est possible d’obtenir un certificat signé par
-Dans ce cas, il s’agira de remplacer le certificat auto-signé par celui qui a été reconnu par une autorité de certification, et vos utilisateurs n’auront plus à passer par cet écran d’avertissement.
+une autorité « connue » qui est **Let's Encrypt** et qui propose des
+certificats gratuits et reconnus directement par les navigateurs. YunoHost
+permet d'installer directement un tel certificat depuis l'interface
+d'administration ou la ligne de commande.
 
-### Ajout d’un certificat signé par une autorité
+### Installer un certificat Let's Encrypt
 
-Après création du certificat auprès de votre autorité d’enregistrement, vous devez être en possession d’une clé privée, le fichier key et d’un certificat public, le fichier crt.
+Avant de chercher à installer un certificat Let's Encrypt, assurez vous que
-> Attention, le fichier key est très sensible, il est strictement personnel et doit être très bien sécurisé.
+votre DNS est correctement configuré (votre.domaine.tld doit pointer sur l'IP
+de votre serveur) et que votre site est accessible en HTTP depuis l'extérieur
+(i.e. qu'au moins le port 80 est correctement redirigé vers votre serveur).
 
-Ces deux fichiers doivent être copiés sur le serveur, s’ils ne s’y trouvent pas déjà.
+#### Via l'interface d'administration web
 
-```bash
+Rendez-vous dans la partie 'Domaine' de l'interface d'administration, puis dans
-scp CERTIFICAT.crt admin@DOMAIN.TLD:ssl.crt
+la section dédiée à votre domaine. Vous trouverez un bouton 'Certificat SSL'.
-scp CLE.key admin@DOMAIN.TLD:ssl.key
+
+![](./images/domain-certificate-button-fr.png)
+
+Dans la section 'Certificat SSL', vous pourrez voir l'état actuel du certificat.
+Si vous venez d'ajouter le domaine, il dispose d'un certificat auto-signé.
+
+![](./images/certificate-before-LE-fr.png)
+
+Si votre domaine est correctement configuré, il vous est alors possible de
+passer à un certificat Let's Encrypt via le bouton vert.
+
+![](./images/certificate-after-LE-fr.png)
+
+Une fois l'installation effectuée, vous pouvez vous rendre sur votre domaine
+via votre navigateur, en HTTPS, pour vérifier que votre certificat est bien
+signé par Let's Encrypt. Le certificat sera renouvelé automatiquement tous les
+trois mois environ.
+
+![](./images/certificate-signed-by-LE.png)
+
+#### Via la ligne de commande
+
+Connectez-vous sur votre serveur en SSH.
+
+Vous pouvez vérifier le statut actuel de votre certificat via
+
+```
+yunohost domain cert-status votre.domaine.tld
 ```
 
-Depuis Windows, scp est exploitable avec putty, en téléchargeant l’outil [pscp](http://the.earth.li/~sgtatham/putty/latest/x86/pscp.exe)
+Installez le certificat Let's Encrypt via
 
-```bash
+```
-pscp -P 22 CERTIFICAT.crt admin@DOMAIN.TLD:ssl.crt
+yunohost domain cert-install votre.domaine.tld
-pscp -P 22 CLE.key admin@DOMAIN.TLD:ssl.key```
+```
 
-Dès lors que les fichiers sont sur le serveur, le reste du travail se fera sur celui-ci. En [ssh](https://yunohost.org/#/ssh_fr) ou en local.
+Cette commande doit retouner :
 
-Tout d’abord, créez un dossier pour stocker les certificats obtenus.
+```
+Success! The SSOwat configuration has been generated
+Success! Successfully installed Let's Encrypt certificate for domain DOMAIN.TLD!
+```
 
-```bash
+Une fois l'installation effectuée, vous pouvez vous rendre sur votre domaine
-sudo mkdir /etc/yunohost/certs/DOMAIN.TLD/ae_certs
+via votre navigateur, en HTTPS, pour vérifier que votre certificat est bien
-sudo mv ssl.key ssl.crt /etc/yunohost/certs/DOMAIN.TLD/ae_certs/```
+signé par Let's Encrypt. Le certificat sera renouvelé automatiquement tous les
+trois mois environ.
 
-Puis allez dans le dossier parent pour poursuivre.
+##### En cas de problème
 
-```bash
+Si suite à une mauvaise manipulation, un certificat se retrouve dans une
-cd /etc/yunohost/certs/DOMAIN.TLD/```
+situation fâcheuse (e.g. perte du certificat ou impossible de lire le
+certificat), il est possible de repartir sur des bases propres en regénérant un
+certificat auto-signé :
 
-Faites une sauvegarde des certificats d’origine de yunohost, par précaution.
+```
+yunohost domain cert-install votre.domaine.tld --self-signed --force
+```
 
-```bash
+Si YunoHost trouve que votre domaine est mal configuré quand bien même vous
-sudo mkdir yunohost_self_signed
+avez bien vérifié votre configuration DNS et avez bien accès à votre serveur en
-sudo mv *.pem *.cnf yunohost_self_signed/```
+HTTP depuis l'extérieur, vous pouvez tenter :
 
-En fonction de l’autorité d’enregistrement, des certificats intermédiaires et racines doivent être obtenus.
+- d'ajouter une ligne `127.0.0.1 votre.domaine.tld` au fichier `/etc/hosts` sur votre serveur ;
+- si l'installation ne fonctionne toujours pas, désactiver les vérifications en ajouter `--no-checks` à la commande `cert-install`.
 
-> **StartSSL**
-> ```bash
-> sudo wget http://www.startssl.com/certs/ca.pem -O ae_certs/ca.pem
-> sudo wget http://www.startssl.com/certs/sub.class1.server.ca.pem -O ae_certs/intermediate_ca.pem```
-
-> **Gandi**
-> ```bash
-> sudo wget https://www.gandi.net/static/CAs/GandiStandardSSLCA.pem -O ae_certs/intermediate_ca.pem```
-> Attention si votre certificat expire après le 01/01/2017, choisissez le certificat intermédiaire SHA2 suivant (à la place du certificat SHA1 précédent)
-> ```bash
-> sudo wget https://www.gandi.net/static/CAs/GandiStandardSSLCA2.pem -O ae_certs/intermediate_ca.pem```
-
-> **RapidSSL**
-> ```bash
-> sudo wget https://knowledge.rapidssl.com/library/VERISIGN/INTERNATIONAL_AFFILIATES/RapidSSL/AR1548/RapidSSLCABundle.txt -O ae_certs/intermediate_ca.pem```
-
-> **Cacert**
-> ```bash
-> sudo wget http://www.cacert.org/certs/root.crt -O ae_certs/ca.pem
-> sudo wget http://www.cacert.org/certs/class3.crt -O ae_certs/intermediate_ca.pem```
-
-Les certificats intermédiaires et root doivent être réunis avec le certificat obtenu pour créer une chaîne de certificats unifiés.
-
-```bash
-cat ae_certs/ssl.crt ae_certs/intermediate_ca.pem ae_certs/ca.pem | sudo tee crt.pem```
-
-La clé privée doit être, elle, convertie au format pem.
-
-```bash
-sudo openssl rsa -in ae_certs/ssl.key -out key.pem -outform PEM```
-
-Afin de s’assurer de la syntaxe des certificats, vérifiez le contenu des fichiers.
-
-```bash
-cat crt.pem key.pem```
-
-Les certificats et la clé privée doivent ressembler à cela :
-
-`-----BEGIN CERTIFICATE-----`    
-`MIICVDCCAb0CAQEwDQYJKoZIhvcNAQEEBQAwdDELMAkGA1UEBhMCRlIxFTATBgNV`
-`BAgTDENvcnNlIGR1IFN1ZDEQMA4GA1UEBxMHQWphY2NpbzEMMAoGA1UEChMDTExC`
-`MREwDwYDVQQLEwhCVFMgSU5GTzEbMBkGA1UEAxMSc2VydmV1ci5idHNpbmZvLmZy`
-`MB4XDTA0MDIwODE2MjQyNloXDTA0MDMwOTE2MjQyNlowcTELMAkGA1UEBhMCRlIx`
-`FTATBgNVBAgTDENvcnNlIGR1IFN1ZDEQMA4GA1UEBxMHQWphY2NpbzEMMAoGA1UE`
-`ChMDTExCMREwDwYDVQQLEwhCVFMgSU5GTzEYMBYGA1UEAxMPcHJvZi5idHNpbmZv`
-`LmZyMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDSUagxPSv3LtgDV5sygt12`
-`kSbN/NWP0QUiPlksOkF2NkPfwW/mf55dD1hSndlOM/5kLbSBo5ieE3TgikF0Iktj`
-`BWm5xSqewM5QDYzXFt031DrPX63Fvo+tCKTQoVItdEuJPMahVsXnDyYHeUURRWLW`
-`wc0BzEgFZGGw7wiMF6wt5QIDAQABMA0GCSqGSIb3DQEBBAUAA4GBALD640iwKPMf`
-`pqdYtfvmLnA7CiEuao60i/pzVJE2LIXXXbwYjNAM+7Lov+dFT+b5FcOUGqLymSG3`
-`kSK6OOauBHItgiGI7C87u4EJaHDvGIUxHxQQGsUM0SCIIVGK7Lwm+8e9I2X0G2GP`    
-`9t/rrbdGzXXOCl3up99naL5XAzCIp6r5`  
-`-----END CERTIFICATE-----`
-
-Enfin, sécurisez les fichiers de votre certificat.
-
-```bash
-sudo chown root:metronome crt.pem key.pem
-sudo chmod 640 crt.pem key.pem
-sudo chown root:root -R ae_certs
-sudo chmod 600 -R ae_certs```
-
-Rechargez la configuration de nginx pour prendre en compte le nouveau certificat.
-```bash
-sudo service nginx reload```
-
-
-Votre certificat est prêt à servir. Vous pouvez toutefois vous assurez de sa mise en place en testant le certificat à l’aide du service de <a href="https://www.geocerts.com/ssl_checker" target="_blank">geocerts</a>.