Let's Encrypt is a completely free Certificate Authority (CA) who distributed free and trusted TLS server certificates for website owners around the world to use. The process of using their certificate on a Google App Engine (GAE) hosted site, however, was a little tricky and thus I will record the steps I have done in order to achieve this.
Obtain an ACME Client
First things first, Let's Encrypt does not have any web form for obtaining a certificate. In order to do so, you have to use so called an Automated Certificate Management Environment (ACME) client to talk with Let's Encrypt's server, which implements the ACME server side protocol. After you have proven the ownership of your domain, the server will automatically signs your private key and the whole process takes less than 5 min to complete.
In order to download the official ACME client made by the Let's Encrypt project, go to their GitHub and follow the instructions on there.
Once you have a working ACME client, next thing you will need to do is to run the ACME client in "Certificate Only" and "Manual Authentication Mode. " The reason for this being that Let's Encrypt was created as a "fool proof" one-liner solution that will ideally obtain and install a TLS certificate on your website automatically in a typical setup. Unfortunately, as GAE user, we do not have direct control over the server hosting our website and thus we would have to do those process by ourself.
Obtain the Certificate
Let's run the ACME client in the mode we have mentioned above:
[datong@localhost letsencrypt]$ ./letsencrypt-auto certonly --manual
Give few seconds for any output to come back since this command will do some auto-update work before invoking the actual ACME client program. If you are prompted to enter a
sudo password, this is perfectly normal since Let's Encrypt's ACME client stores the generated private key in a location only accessible by
root by default in order to protect it.
If you are running this in a Terminal window and everything goes smoothly, you will see an old school
ncurses style text based GUI. The first thing it will ask you is the domain name(s) you would like to sign for in your requested certificate. If you provide multiple ones, the resulted certificate will be containing an extra "Subject Alternative Names (SAN)" field which allows it to work with multiple domain names. Since today we are only encrypting one website, I will just put one domain name
www.cyfly.org inside the box.
After that, you will be presented to agree their terms and verify your ownership of the domain. Different from most of the public CAs out there, which uses Email Validation, Let's Encrypt used the HTTP File Validation method. In order to prove your ownership of the website, Let's Encrypt will instruct you to do something like the following:
Make sure your web server displays the following content at http://www.cyfly.org/.well-known/acme-challenge/vjiHqi5E9FfiNjOe2yajth-eVzxS1oHfMCBwj6HVQoE before continuing: vjiHqi5E9FfiNjOe2yajth-eVzxS1oHfMCBwj6HVQoE.2GhklWKkNkag5BcFx95RAhNTluIbbubTNSXlUR_dsNY
Configure GAE to Serve Our Token File
In order to let GAE serve this file over the specified URL by Let's Encrypt, we need to find a convenient location under your application directory that will be used to store the actual file. I created a sub-directory called
static for this purpose.
Please note that you do not have to and can not create a directory starting with
.. Doing so will make
appcfg.py ignore this directory during the scanning peocess and the directory will never be uploaded to Google's Server! This is why I created a directory called
well-known, omitting the leading dot.
To map the URL
/.well-known to the directory we newly created, we simply add a new static file handler in our
- url: /.well-known static_dir: application/static/well-known mime_type: text/plain secure: always
Remember to change the
static_dir section to match your actual setup. Also
secure are not technically required but it allows you to check the content of the file using your browser easily and thus was added.
Next, we need to create the
acme-challenge/vjiHqi5E9FfiNjOe2yajth-eVzxS1oHfMCBwj6HVQoE file under
well-known as requested by the ACME client. Use whatever editor of your choice but remember this file contains only one line of content and do not put a newline character after the first line. The content of the file will be:
as required by the client.
After that, update your GAE application and make sure
http://www.cyfly.org/.well-known/acme-challenge/vjiHqi5E9FfiNjOe2yajth-eVzxS1oHfMCBwj6HVQoE is indeed accessible and contains the correct file format. After that let the ACME client to continue and if you did everything correctly, you will get a new certificate within couple of seconds.
Installing the Certificate
By default, the ACME client stores the certificate along with it's private key under
/etc/letsencrypt/live/<your domain name>/. Navigate to that directory as root,
fullchain.pem file contains the certificate along with any required intermediates for your certificate and should almost always be used.
privkey.pem is your private key.
When uploading your certificate to Google, the certificate file will simply be
fullchain.pem. For the private key, however, you will have to run a simple command to get rid of the extra OID indicating the type of key first before Google would accept it. Currently Google only accepts RSA private key for custom TLS and Let's Encrypt only signs certificates using RSA public key so should work out pretty well.
[root@localhost www.cyfly.org]# openssl rsa -in privkey.pem -check
Simply copy the content from
-----BEGIN RSA PRIVATE KEY----- to
-----END RSA PRIVATE KEY----- and paste it into the Google form and it should work right away.
After that, enable your new certificate and make sure it works by checking your website using ssllabs.com. You can keep or remove the authentication file safely on your website since it is only used once by Let's Encrypt and does not contain any useful information regarding your website.