Usage

Getting the certificates

First-time run and regular use

If you have just installed the client (or asked your system administrator to install it for you), you can start creating your certificates. First make sure that you are accepting Let's Encrypt TOS (pdf). Then write down the domain name you want your certificate for. If it is a second-level domain, like mydomain.com, then you would probably want your certificate to contain both names: mydomain.com and www.mydomain.com. If it is a sub-domain like myserver.somedomain.com, then use just that name alone. In the examples below we will use both names.

Before we begin, a few words about the keys. Even though le.pl can create your keys for you, it is recommended to create them in advance, using the following commands:

  • To generate an account key - openssl genrsa -out account.key 4096
  • To generate a domain key - openssl genrsa -out mydomain.key 2048

You only need to generate your account key once. Domain key is best to be created for every separate set of names you are creating certificates for. Note the difference in key length - in the example given, it is 2048 bits for the domain key. You can use 4096 bits too, but you need to keep in mind that Amazon Web Services (such as CloudFront), some Cisco IOS versions and some Control Panels cannot use the keys longer than 2048 bits. Andditionally, longer keys produce slightly more overhead on connection "handshake" (even though it is still pretty fast). On the other hand, longer keys are considered a bit more "future-proof" and SSL Labs "Key Exchange" test will give 100% score only if 4096 bits key is in use. If you don't want to create the keys by yourself, le.pl will create them for you by generating 4096 bits keys using Crypt::OpenSSL::RSA library (with importing random seed from Crypt::OpenSSL::Random).

To have your certificate issued, the certificate authority must verify that you are the owner of the domains in question. The easiest way to do that is to have verification file(s) temporarily placed into certain directory in the 'webroot' of your website. Webroot basically means the directory where your website pages are. For example, if your pages are located in '/var/www/html/', then you need to create a directory for challenge files as "mkdir -p /var/www/html/.well-known/acme-challenge/" (the dot before "well" is important).

Now you are ready to start getting your free certificates! Run the following command:

le.pl --key account.key --csr mydomain.csr --csr-key mydomain.key --crt mydomain.crt --domains "www.mydomain.com,domain.com" --path /var/www/html/.well-known/acme-challenge/ --generate-missing --unlink --live

Note: It is advised before issuing an actual certificate to test the process first. To do so, just remove --live from the command line. The testing process is pretty much the same as the process of getting an actual certificate, but the retrieved test certificate will not be 'trusted' by browsers.

With the command above, the client will generate an account key for you (keep the 'account.key' file safe) and, assuming that verification process has been finished successfully, it will produce the domain key ('mydomain.key') and the domain certificate ('mydomain.crt'). You can then install the certificate on your web server(*) or ask your system administrator to install it for you. You will need your 'account.key' to get more certificates, to renew the existing certificates and to revoke previously issued certificates if needed.

Once your account key has been generated and registered during the first-time run, you just need to have that key available on any subsequent run of the client. Everything else can be generated again if needed, though there is no harm in re-using previously generated files. You will also need your domain certificate file available if you are going to revoke it.

DNS verification

If you prefer not to use http verification or maybe you cannot (for some reason) put verification files into the proper directory on your server, you can try using DNS verification instead. That requires having access to your DNS settings, which is normally available through your registrar or some DNS hosting service you might be using. All you have to do is to create a TXT record, wait a few minutes until it propagates and then proceed with validation. The value for the record will be given you by the client.

DNS verification is supported out of the box through the provided plugin. To use it, the command might look like this:

le.pl --key account.key --csr mydomain.csr --csr-key mydomain.key --crt mydomain.crt --domains "www.mydomain.com,domain.com" --generate-missing --handle-with Crypt::LE::Challenge::Simple --handle-as dns --live

Certificate renewal

The certificates are issued for 90 days, so it makes sense to renew them sometime before they expire. It is as easy as to issue ones, you will just need one more option added to the command line - "--renew XX", where XX is the amount of days before expiration for the renew process to proceed. Let's say you want renew to happen 10 or fewer days before the certificate expiration date. The command line will be the same as earlier, except for the added option:

le.pl --key account.key --csr mydomain.csr --csr-key mydomain.key --crt mydomain.crt --domains "www.mydomain.com,domain.com" --path /var/www/html/.well-known/acme-challenge/ --generate-missing --unlink --renew 10 --live

If you run this command for example 20 days before expiration, it will inform you that it is too early for renewal. If you run it when it is 10 or fewer days are left before the expiration date, then your new certificate will be retrieved. Please note that if your old mydomain.key and mydomain.csr files from previous runs are not available during renewal, then your domain key ('mydomain.key') will also be updated, not only the domain certificate ('mydomain.crt'). This command can be run automatically and it is safe to put it into cron for example to be run daily.

Please note that normally you wouldn't need to re-verify the domain for about a year - the client supports this by default and will not ask for verification unless it is actually needed.

Certificate revocation

In the rare case when you need some of your certificates revoked, you can do it with the following command:

le.pl --key account.key --crt mydomain.crt --revoke --live

Just make sure that the certificate file ('mydomain.crt') is available.

Integration options

If you decide to implement some specific automation or add specific triggers (for example to run something or send an email when you get or renew your sertificate), then it can be easily done by using external modules. Please see the "integration options" document for details.

Installing certificates on the web server

While getting the certificate does not require any specific technical knowledge, installing the certificate might require a bit of it. Normally you would need to locate where your web server configuration files are and make a few small changes to them. Usually configuration files contain commented out examples of configurations, which you can use as a template. Two most common web servers are Apache and Nginx.

Apache

Assuming that you are using a more or less recent version of Apache (2.4.8 or better), your key and the certificate are ready to be used. Below is the example of a minimal configuration:

Listen 443
<VirtualHost *:443>
        ServerName www.mydomain.com mydomain.com
        SSLEngine on
        SSLCertificateFile "/path/to/mydomain.crt"
        SSLCertificateKeyFile "/path/to/mydomain.key"
        SSLCipherSuite HIGH:!aNULL:!MD5
        SSLProtocol All -SSLv2 -SSLv3
        SSLHonorCipherOrder on
</VirtualHost>

For the advanced options see the documentation or use Mozilla SSL Configuration Generator.

Nginx

server {
        listen       443 ssl;
        server_name  www.mydomain.com mydomain.com;
        ssl          on;
        ssl_certificate      /path/to/mydomain.crt;
        ssl_certificate_key  /path/to/mydomain.key;
        ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
        ssl_ciphers 'HIGH:!aNULL:!MD5:!kEDH';
}

For the advanced options see the documentation or use Mozilla SSL Configuration Generator.

Prev: Installation Next: Integration