Tuesday, June 16, 2015

SSL / TLS on Google App Engine Custom Domains

Using Wildcard Certificates signed by GoDaddy

SSL and TLS -- technologies used to encrypt and secure network transmissions -- and Custom Domains hosted on Google App Engine can be a challenge to configure.  This article describes the nuances and gotchas that can come up during the deployment of SSL certificates on Custom Domains hosted on Google App Engine.

Wildcard certificates -- certificates that can be used to secure multiple subdomains -- can greatly simplify the administration of multiple subdomains, websites, web applications, etc.  This article also covers the steps required to create keys and certificate signing requests for SSL / TLS (including wildcard certificates) and to use GoDaddy to validate the key and provide a cryptographically signed certificate.

1. Private Key

First, acquire a private key for use with the domain that's being secured.  If one doesn't already exist, create one using the OpenSSL tool:

# generate a new 2048 bit RSA key file 

openssl genrsa -out wildcard.example.com.key 2048

2. Certificate Signing Request (CSR)

Next, find the existing Certificate Signing Request (CSR) file if the certificate is being renewed; if one doesn't yet exist, create one using the openssl command line tool:

# generate a new CSR for the key (the command is all on one line)

openssl req -new -key wildcard.example.com.key -out wildcard.example.com.csr -subj "/C=US/ST=New York/L=Utica/O=KDA Web Technologies/OU=Web Development/CN=*.example.com"

Non-Interactive CSR Subject Specification

The following values may be used when specifying the subject for the CSR:

New York
Locality (e.g., City)
Organization's name
KDA Web Technologies
Organizational Unit
Web Development
Common Name (domain name)

The OpenSSL command will provide an interactive prompt for values not specified in the subject.

The CN field is used to specify the Common Name for the CSR.   The Common Name is the domain name that the certificate will secure.  For example, a CN of test.example.com may be used for connections to the host 'test.example.com.'  For wildcard certificates, use a CN of *.domain.tld.  

Note that the HTTP over TLS specification asserts that the '*' wildcard and apply to one domain name component.  That is, *.example.com may be used to secure example.com, www.example.com, and test.example.com; however, it may not be used to secure multiple domain name components.  For example, *.example.com may not be used to secure foo.bar.example.com.  To secure a second level of subdomain, a second certificate (or one certificate with multiple Subject Alternative Names (SANs)), use a CN of *.*.example.com.

3. Send CSR to Domain Name Registrar

Next, have the CSR signed by a recognized domain name registrar.  In this case, GoDaddy was used.

GoDaddy-specific Steps

When the certificate is ready, GoDaddy provides a .zip file containing two files, the certificate plus the intermediate key chain.

Google Apps (and Google App Engine) requires that the certificate be fully chained; therefore, the certificates from GoDaddy need to be merged into a single certificate.  

# use cat to merge both files together (the command is all on one line)

cat wildcard.example.com.crt gd_bundle-g2-g1.crt > fully_chained_wildcard.example.com.crt

4. Decrypt Private Key

Then, Google Apps (and, again, Google App Engine) requires the private key to be unencrypted.  The OpenSSL tool can be used for this:

# decrypt private key

openssl rsa -in wildcard.example.com.key -out unencrypted-wildcard.example.com.key

5. Upload Private Key and Certificate

Next, upload the new certificate.  The menu for configuring an SSL certificate for a custom domain can be found through the admin panel (https://admin.google.com/) under Security | SSL for Custom Domains:

Choose SSL for Custom Domains from the security section of the Google Apps admin panel
Choose SSL for Custom Domains from the security section of the Google Apps admin panel

For the "PEM encoded X509 certificate," select the fully chained certificate; for the "Unencrypted PEM encoded RSA private key," select the unencrypted file.  Click 'Upload' to upload the files.

Uploading a TLS / SSL certificate to Google Apps
Uploading a TLS / SSL certificate to Google Apps

6. Set Serving State

Finally, change the 'Current state' option from 'Not serving' to the serving state of choice (typically SNI Only), and click the 'Assign all matching URLs' link at the bottom of the menu.

At this point, the new SSL / TLS certificate should be serving when agents attempt to load content from the application hosted on Google App Engine.

Wes Dean is Principal of KDA Web Technologies, a Google Cloud Platform Development Partner and a Google Apps Authorized Reseller. To learn how Wes and KDA Web Technologies can help you, go to www.kdaweb.com.

"System Lock" photo by Yuri Samoilov and used here with Creative Commons license.