Introduction ************ This is to help you use Let's Encrypt when working with Apache (2.2 and 2.4). New instructions included for nginx, tested 1.13.2. Take references to Apache as meaning you do similar for Nginx. Let's Encrypt provide free SSL certificates. These let you make secure https:// web sites. You don't want to use Let's Encrypt's certbot because: * it is too complicated, too hard to audit - these scripts are easy to check * you do not want certbot to edit your configuration - you keep control For a description on how to use this see: https://www.phcomp.co.uk/Tutorials/Web-Technologies/Configure-Lets-Encrypt-with-acme_tiny.html This uses acme_tiny which you can see at https://github.com/diafygi/acme-tiny Some configuration snippets are provided that you can copy into your Apache or Nginx config. Sections below: * Quick Install * Files Created * Debugging * Warning * Chained Certificates * Certificates for use in a non web environment * License Quick Install ************* The shell used below must be sufficiently powerful. ash & dash are not good enough. If in doubt use bash or ksh. You might need to do this on Ubuntu or FreeBSD. If this was installed from an RPM start at (3). 0) You have grabbed & unpacked the tar file. A web server is installed on your machine, eg Apache or Nginx this will be running as one the users www www-data wwwrun apache nginx lighttpd If running under freeBSD: create the users rsa & acme with home probably /usr/local/www Both must be in the same group. 1) Review & correct the first few lines of bin/InitialSetup In particular the value of ApacheGroup The script should work out a good value. Note that the scripts take the option: --help 2) As root run the InitialSetup script with the tar file as argument, eg: # sh /tmp/x/bin/InitialSetup /tmp/phcl_acme-1.10.tar.gz This creates two users (default: rsa & acme) and puts some files in their $HOME. Note that these files need certain ownerships and permissions for this to work, the script does that. It also downloads the letsencrypt cross signing certificate. Email may be sent to the user acme from cron jobs. acme email must be forwarded to where it will be read. Look at /etc/aliases 3) Create a SSL configuration file in SSLConfigs/ Copy EXAMPLE.cnf to get you started, eg create SSLConfigs/my-family.cnf It should be mode 440 and owner.group should be rsa.rsa A family is a set of related web sites that share the same key. my-family is an example of family, eg: www.example.com example.com www.example.co.uk A family name should contain alph-numerics, '.' '-' '_', not start with '-'. 4) As user rsa generate a Certificate Signing Request, eg: # su rsa -c 'bin/CreateSigningRequests my-family' 5) Configure Apache so that Let's Encrypt can validate the request. InitialSetup will have generated the file httpd.conf.challenge that might help. If you use nginx look at nginx.conf.add-ssl NOTE that at this stage the SSL virtual host must be commented out. It will not work without the certificate - that you do not yet have. You can check that your web server configuration works by: # su rsa -c 'bin/CheckSiteAccess my-family' 6) As user acme get Let's Encrypt to sign the certificate, eg: # su acme -c 'bin/GetSignedCertificate my-family' This will: * Generate a Let's Encrypt account key for my-family 7) Check that the cross signing certificate was downloaded correctly. If not use: wget https://letsencrypt.org/certs/lets-encrypt-x3-cross-signed.pem or: curl --output lets-encrypt-x3-cross-signed.pem https://letsencrypt.org/certs/lets-encrypt-x3-cross-signed.pem This file needs to be readable by Apache. 8) Configure Apache to serve up SSL files. There is further discussion in the tutorial (see above). The previous change that you made must be left in so that certificate renewal works. The file vhosts-port-80-and-443.conf might help. You will need a GenericSSL.conf, an example is provided in the directory DIST. Beware: what this contains will need to change depending on current best advice. Mozilla has a configuration generator that can help: https://wiki.mozilla.org/Security/Server_Side_TLS 9) Set a cron job running as user acme, see Renewal.crontab The script bin/RenewCertificates will renew certificates before they get too old. 10) Arrange for your web server to restart daily so that it sees new certificates. Files Created ************* Within /var/www/acme/ For family 'my-family': LetsEncryptAccounts/my-family.key Let's Encrypt account key RSAprivateKeys/my-family.key Private key Apache config SSLCertificateKeyFile CertificateSigningRequests/my-family.csr Signing request SignedCertificates/my-family.crt Signed key + Let's Encrypt chain certificate Apache config SSLCertificateFile SignedCertificates/my-family-chained.crt Signed key + Let's Encrypt chain certificate lets-encrypt-x3-cross-signed.pem Let's Encrypt chain certificate Apache config SSLCertificateChainFile Beware that some of these directories have specific ownerships, some are set group id. If running SELinux you may need to use the restorecon command, eg: restorecon -FRv /etc/httpd/conf Debugging ********* The script RenewCertificates is where hard to diagnose errors may be found. To get tracing create a file called VERBOSE - messages to stderr. If a writable file TRACEFILE exists, messages will also be appended there. Warning ******* The script that renews certificates deduces the age of the certificate from the age of the certificate file in the directory SignedCertificates/ If you alter these files' modification time this script will draw the wrong conclusion - ie your certificates might expire. At the time of writing what will happen to the cross signing certificate is not clear. I believe that the hope is that it will not be needed as everything will recognise it. It will currently expire in March 2021. The RenewCertificates script will warn when the certificate is close to expiry. This is in the file lets-encrypt-x3-cross-signed.pem Chained Certificates ******************** Some SSL users need to have the Let's Encrypt chaining or cross signing certificate. This is because their web browser does not recognise Let's Encrypt as a trusted certificate authority. The chaining certificate says that Let's Encrypt is to be trusted - IdenTrust provides this and will be trusted by browsers. The chained certificate should be appended to the certificate. For every certificate file created a chained file will be created, eg SignedCertificates/my_site-chained.crt See: https://letsencrypt.org/certificates/ Certificates for use in a non web environment ********************************************* These certificates can be used for things like email (SMTPS and IMAPS). You will often need to use a chained certificate. You will need to add the names used to the appropriate configuration file, eg add to SSLConfigs/phcl.conf DNS.6 = submit.phcomp.co.uk For others its own family, eg SSLConfigs/imap.conf All of the names will have to have a web site for Let's Encrypt to validate; even if that is the only thing that the web site shows. Eg for use in exim, put in /etc/exim/exim.conf: tls_certificate = /var/www/acme/SignedCertificates/phcl-chained.crt tls_privatekey = /var/www/acme/RSAprivateKeys/phcl.key Eg for dovecot, put in /etc/dovecot/conf.d/10-ssl.conf: ssl_key = ; Parliament Hill Computers Ltd; February 2018, 2020 All of the Parliament Hill Computers Ltd code is released under the GPL version 3 or any later version. See: https://www.gnu.org/licenses/gpl-3.0.txt acme_tiny.py is released under an MIT license: https://github.com/diafygi/acme-tiny/blob/master/LICENSE SCCS: @(#)README 1.17 05/05/20 01:15:58