Edit : this thread is now outdated since Let’s encrypt certificate management is a built-in feature since Yunohost 2.5. More info here
Again: this thread is oudated, uses the buildin let’sencrypt support of YunoHost +2.5!
(English version)
Hi everyone,
Let’s encrypt went into public beta recently, which means anybody can use their services now to get “trusted” certificates and get rid of self-signed certificates. There are only sparse documentation on the internet now (and most of them not so newbies-friendly ?), so I’m opening this thread to help people who are willing to understand how this works, and get the certificates running including the few tweaks specific to YunoHost.
Disclaimer: this thread in work in progress, I’ll update it as my understanding improves and feedback is received. I’m a noob myself, so kindly correct anything wrong I’m saying 
. Also: let’s encrypt is still in beta, so be patient if it’s not perfect.
/!\ An experimental package available here tries to automatize the following instructions
0. Why is let’s encrypt great ?
To understand what let’s encrypt is about, you need to understand the problematic behind HTTPS/SSL/TLS certificates. To avoid possible attackers to generate certificates for websites they don’t own, browsers rely on certification authorities which are “trusted”. These CA can deliver certificate to website owner, so that the visitor’s browser is happy with the certificate. Prior to delivering the certificate, the CA is obviously expected to check that the person it delivers the certificate to actually owns the server/domain.
This last point was not easy to automatize, required human intervention, and was why you had to pay for your certificates. Now Let’s encrypt came out with a way to automatize this with a protocol (ACME) to automatize interaction between a certification authority and a script running on your server, effectively allowing to check that you own the domain name, and deliver certificates (among other things), for free. In this thread, we use the official let’s encrypt ACME client, but keep in mind that other clients exist.
1. Install let’s encrypt
Get on your server as root, then :
# Make sure your system is up to date, shouldn't hurt
$ apt-get update
$ apt-get upgrade
# Go to root home
$ cd
# Clone lets encrypt git repository
$ git clone https://github.com/letsencrypt/letsencrypt
# Call let's encrypt auto : it will install what it needs.
# It might take a few minutes !
$ cd letsencrypt/
$ ./letsencrypt-auto --help
2. Edit Nginx and SSOwat configuration
To check that you actually are the one running yourDomain.tld, Let’s encrypt is going to add files to some URL of your server and try to access it from its servers. From what I understood, if your server runs Apache you can have letsencrypt-auto do everything itself, but the support for nginx isn’t here yet so we have to tweak things manually.
We have to make the URL yourDomain.tld/.well-known/acme-challenge accessible, and the corresponding content will be stored in /tmp/letsencrypt-auto. Add a nginx config file, for instance called letsencrypt.conf (e.g. with nano : nano /etc/nginx/conf.d/yourDomain.tld.d/letsencrypt.conf) and add the new location block :
location '/.well-known/acme-challenge' {
default_type "text/plain";
root /tmp/letsencrypt-auto;
}
In the context of YunoHost, we also need to tweak the SSOwat conf so that the Let’s encrypt server aren’t redirected to the SSO login interface when trying to access .well-known/acme-challenge. Open the persistent rules configuration for SSOwat (/etc/ssowat/conf.json.persistent), and add a new unprotected_urls rule :
{
"unprotected_urls" : [
"yourDomain.tld/.well-known/acme-challenge"
]
}
Beware of the syntax if you already have some content in your conf.json.persistent : you need to add the lines inside the { }. (c.f. this thread)
Check that your nginx conf looks valid with nginx -t and restart the daemon with service nginx restart. (You don’t need to do anything for SSOwat)
3. Get the certificates
Now we actually ask the Let’s encrypt CA for the certificate. Create a config file, for instance /etc/letsencrypt/conf.ini, with the following content :
#################################
# Let's encrypt configuration #
#################################
# Key size
rsa-key-size = 4096
# Email for notifications and contact if needed
email = some_admin_user@yourDomain.tld
# Use text interface, agree to Terms of Service
text = True
agree-tos = True
# Use the webroot authenticator
# with content located in /tmp/letsencrypt-auto
authenticator = webroot
webroot-path = /tmp/letsencrypt-auto
# (Staging server, to be used for test only. If you use it,
# your cert won't actually be valid)
# server = https://acme-staging.api.letsencrypt.org/directory
Don’t forget to change the email in the config file. Back to the command line, let us now list the domains you want a certificate for :
# If you have several, just put -d domain1.tld -d domain2.tld ...
$ export DOMAINS="-d yourDomain.tld"
Let’s now ask the CA for the certificate. We indicate the config file and the domains :
$ cd ~/letsencrypt/
$ mkdir -p /tmp/letsencrypt-auto
$ ./letsencrypt-auto certonly --config /etc/letsencrypt/conf.ini $DOMAINS
-
If you see an error message like
Error: The client lacks sufficient authorization, it means that the Let’s encrypt servers couldn’t reachyourDomain.tld/.well-known/acme-challengeurl. You should check your nginx config, the permissions of/tmp/letsencrypt-auto, and your ssowat config. You can get clues by trying to access yourself the url, and looking at the nginx logs :tail -n 50 /etc/nginx/yourDomain.tld-*.log. -
If you see a Congratulations!, it means your certificates should now be available in
/etc/letsencrypt/live/.
4. Use the certificates
Backup your current certificates :
$ mv /etc/yunohost/certs/yourDomain.tld /root/certsBackupForDomainDotTLD
Now link the new letsencrypt certificates :
$ mkdir /etc/yunohost/certs/yourDomain.tld
$ cd /etc/yunohost/certs/yourDomain.tld
$ ln -s /etc/letsencrypt/live/yourDomain.tld/fullchain.pem ./crt.pem
$ ln -s /etc/letsencrypt/live/yourDomain.tld/privkey.pem ./key.pem
Check that nginx is happy with nginx -t and restart it with service nginx restart. Then open your website in your browser, and hopefully enjoy that the certificate used is the new one, signed by Let’s encrypt and automatically trusted by browsers ! (click on the padlock near the URL to see the info)
If you use XMPP, we also need to give the permissions to Metronome (the XMPP server) to use the certificates (thanks to tostaki for the tip):
$ chown root:metronome /etc/letsencrypt/archive/
$ chown root:metronome /etc/letsencrypt/live/
$ chmod g+rx /etc/letsencrypt/archive/
$ chmod g+rx /etc/letsencrypt/live/
and restart metronome :
$ service metronome restart
5. Automatically renew the certificate
To encourage automation, let’s encrypt certificates are valid only 90 days and should be renewed after they expire. In the future, this duration might even get shorter.
One can setup a cron job to regularly check the validity of your certificates and renew them if needed. There are many scripts out there, and many more will probably appear.
Here’s what I suggest :
# Get the script
$ wget https://raw.githubusercontent.com/alexAubin/letsencrypt_ynh/131a7071faea0f1374faf04784024e7cab69703a/sources/certificateRenewer
# Open the script with your favorite editor
# and check the configuration is okay !
$ nano certificateRenewer
# In particular :
# > replace DOMAIN_NAME in the EMAIL_ALERT_FROM
# > put your mail adress in EMAIL_ALERT_TO
# > you might want to remove the dot in LEBIN (.letsencrypt -> letsencrypt)
# Move it to the weekly cron jobs folder
$ chmod +x certificateRenewer
$ mv certificateRenewer /etc/cron.weekly
# If you want you can launch it manually (to check if it seems to run fine)
$ /etc/cron.weekly/certificateRenewer
Known issues
- Breaks OpenVPN ? See here
(Version francaise)
Salut tout le monde,
Let’s encrypt est passé en bêta publique récemment, ce qui veut dire que tout le monde peut désormais utiliser leur service pour obtenir des certificats reconnus par les navigateurs, et se débarrasser des certificats auto-signés. Il y a pour le moment relativement peu de documentation sur Internet (et la plupart pas complètement newbies-friendly ?), donc j’ouvre ce post pour aider les gens souhaitant comprendre comment ça marche, et comment obtenir et utiliser les certificats - y compris avec les quelques spécificités de YunoHost.
Disclaimer : ce post est en construction continue et sera mis a jour au fur et à mesure que ma compréhension s’améliore et que je reçois des commentaires. Je suis un noob moi-même, donc n’hésitez pas a me corriger gentiment si je raconte n’importe quoi . Aussi, gardez à l’esprit que let’s encrypt est toujours en bêta, donc soyez patient si ce n’est pas parfait.
Un package expérimental disponible ici tente d’automatiser les instructions qui sont décrites ci-après.
0. Pourquoi est-ce que Let’s encrypt est si bien ?
Pour comprendre la nouveauté apportée par Let’s encrypt, il faut d’abord comprendre la problématique derrière les certificats HTTPS/SSL/TLS. Pour empêcher un attaquant de générer des certificats pour des sites qu’il ne possède pas, les navigateurs web reposent sur des autorités de certifications (CA) auxquelles ils font « confiance ». Ces CA peuvent délivrer des certificats aux propriétaires de sites web, et ainsi le visiteur fait confiance au certificat fourni. Pour délivrer ces certificats, le CA doit évidemment vérifier que la personne à qui elle fourni le certificat possède bien le site/serveur/domaine.
C’est ce dernier point qui n’était pas facile à automatiser et requierait une intervention humaine, et était ce pour quoi il fallait payer pour obtenir un certificat. Let’s Encrypt a créé une façon d’automatiser cela, grâce à un protocole (nommé ACME) entre une autorité de certification et un programme (le client) qui tourne sur votre serveur, qui permet donc de vérifier automatiquement que vous contrôlez un nom de domaine, et de délivrer le certificat correspondant (et aussi de le renouveler, etc…) - gratuitement. Dans ce post, nous utilisons le client ACME officiel de Let’s encrypt (il existe d’autres clients).
Plus d’informations ici, ici et ici.
1. Installer le client Let’s encrypt
Connectez vous en root sur votre serveur, puis :
# Assurez-vous que votre système est à jour, ca ne devrait pas faire de mal
$ apt-get update
$ apt-get upgrade
# Allez dans votre home (en tant que root)
$ cd
# Clonez le dépôt git de Let's encrypt
$ git clone https://github.com/letsencrypt/letsencrypt
# Appelez letsencrypt-auto pour qu'il installe ses dépendances.
# (Ça peut prendre quelques minutes)
$ cd letsencrypt/
$ ./letsencrypt-auto --help
2. Éditez la configuration de Nginx et de SSOwat
Pour verifier que vous êtes effectivement propriétaire de votreDomaine.tld, le client de Let’s encrypt va ajouter des fichiers sur votre serveur et auxquels l’autorité de certification de Let’s encrypt pourra accéder.
Nous allons rendre l’URL votreDomaine.tld/.well-known/acme-challenge accessible, et le contenu correspondant sera stocké dans /tmp/letsencrypt-auto. Ajoutez un fichier de config nginx, par exemple nommé letsencrypt.conf, via nano /etc/nginx/conf.d/votreDomaine.tld.d/letsencrypt.conf. Dans ce fichier, ajoutez ce bloc :
location '/.well-known/acme-challenge' {
default_type "text/plain";
root /tmp/letsencrypt-auto;
}
Dans le contexte de YunoHost, nous devons aussi modifier la configuration SSOwat pour que les serveurs de Let’s encrypt ne soient pas redirigés vers l’interface de login en tentant d’accéder à .well-known/acme-challenge. Ouvrez le fichier de règles persistantes pour SSOwat (nano /etc/ssowat/conf.json.persistent), et ajoutez une nouvelle règle unprotected_urls :
{
unprotected_urls : [
"votreDomaine.tld/.well-known/acme-challenge"
]
}
Attention à la syntaxe, si vous avez déjà des choses dans votre conf.json.persistent : il faut ajouter le unprotected_urls dans les { } (c.f. ce post)
Vérifiez que votre configuration nginx est valide avec nginx -t puis redémarrez le daemon avec service nginx restart. (Pas besoin de faire quoi que ce soit pour SSOwat)
3. Obtenir les certificats
Maintenant nous allons effectivement demander le certificat à l’autorité de certification. Créez un fichier de configuration, par exemple /etc/letsencrypt/conf.ini, avec le contenu suivant :
#################################
# Let's encrypt configuration #
#################################
# Taille de la clef
rsa-key-size = 4096
# Email de notification / contact si nécessaire dans le futur
email = some_admin_user@votreDomaine.tld
# Utiliser l'interface texte
text = True
# Accepter les Conditions d'Utilisation du service
agree-tos = True
# Utiliser la méthode d'authentification webroot
# avec le contenu dans /tmp/letsencrypt-auto
authenticator = webroot
webroot-path = /tmp/letsencrypt-auto
# (Serveur de test uniquement : si vous l'utilisez,
# votre certificat ne sera pas vraiment valide)
# server = https://acme-staging.api.letsencrypt.org/directory
(N’oubliez pas de changer l’adresse email dans le fichier de configuration.) De retour à la ligne de commande, listons les domaines pour lesquels vous souhaitez un certificat :
# Si plusieurs, mettre -d domaine1.tld -d domaine2.tld ...
$ export DOMAINS="-d votreDomaine.tld"
Récupérons maintenant le certificat, en indiquant le fichier de config et les domaines dans les options :
$ cd ~/letsencrypt/
$ mkdir -p /tmp/letsencrypt-auto
$ ./letsencrypt-auto certonly --config /etc/letsencrypt/conf.ini $DOMAINS
-
Si vous voyez un message d’erreur comme
Error: The client lacks sufficient authorization, cela signifie que les serveurs de Let’s encrypt n’ont pas réussi a joindre l’urlvotreDomaine.tld/.well-known/acme-challenge. Vous devriez vérifier votre configuration nginx, les permissions de/tmp/letsencrypt-auto, et votre configuration SSOwat. Vous pouvez obtenir des indices en essayant d’accéder vous-même à l’URL, et en regardant les logs de nginx :tail -n 50 /etc/nginx/votreDomaine.tld-*.log. -
Si vous voyez un Congratulations!, cela signifie que vos certificats devraient être disponibles dans
/etc/letsencrypt/live/.
4. Utiliser vos certificats
Faites une sauvegarde de vos certificats actuels :
$ mv /etc/yunohost/certs/votreDomaine.tld /root/backupCertificatsPourVotreDomainePointTLD
Maintenant, créez des liens symboliques vers vos nouveaux certificats :
$ mkdir /etc/yunohost/certs/votreDomaine.tld
$ cd /etc/yunohost/certs/votreDomaine.tld
$ ln -s /etc/letsencrypt/live/votreDomaine.tld/fullchain.pem ./crt.pem
$ ln -s /etc/letsencrypt/live/votreDomaine.tld/privkey.pem ./key.pem
Vérifiez que nginx est content avec nginx -t et redémarrez-le avec service nginx restart. Ensuite, ouvrez votre site dans votre navigateur et vous devriez normalement avoir un certificat signé par Let’s encrypt et reconnu automatiquement ! (cliquez sur le cadenas à côté de l’URL pour voir les infos)
Si vous utilisez XMPP, il faut également donner les permissions à Metronome (le serveur XMPP) d’utiliser les certificats (merci tostaki pour l’info) :
$ chown root:metronome /etc/letsencrypt/archive/
$ chown root:metronome /etc/letsencrypt/live/
$ chmod g+rx /etc/letsencrypt/archive/
$ chmod g+rx /etc/letsencrypt/live/
et redémarrez Metronome :
$ service metronome restart
5. Renouveler automatiquement ses certificats
Pour encourager l’automatisation, les certificats de Let’s encrypt ne sont valides que 90 jours et doivent être renouvelé après cette période. Dans le futur, cette durée sera peut-être même plus courte.
Il est possible de mettre en place un cron job (tache automatique périodique) pour vérifier la validité de votre certificat et le renouveler s’ils sont sur le point d’expirer. Il y a plusieurs méthodes et scripts disponibles sur les Internets, voici ce que je propose :
# Récuperer le script
$ wget https://raw.githubusercontent.com/alexAubin/letsencrypt_ynh/131a7071faea0f1374faf04784024e7cab69703a/sources/certificateRenewer
# Ouvrez le script avec votre éditeur favoris
# et vérifiez que la configuration semble ok !
$ nano certificateRenewer
# En particulier :
# > remplacer DOMAIN_NAME dans EMAIL_ALERT_FROM
# > mettre votre adresse mail dans EMAIL_ALERT_TO
# > possiblement enlever le . dans LEBIN (.letsencrypt -> letsencrypt)
# Deplacez le script dans les jobs hebdomadaires
$ chmod +x certificateRenewer
$ mv certificateRenewer /etc/cron.weekly
# Si vous voulez, lancez le script manuellement (pour voir s’il semble fonctionner)
$ /etc/cron.weekly/certificateRenewer
Problemes connus
- Casse OpenVPN ? Voir ici
References / more stuff
- Let’s encrypt client documentation
- Let’s encrypt forum
- Instructions / comparison of different ACME client, some lighter than the official let’s encrypt tool
- Full list of ACME clients
- (in french) Une critique de certains point de Let’s encrypt (c.f. aussi les commentaires sur l’article)/
.
.