Whitelabel Domain with TLS

Checklist for whitelabel sites

There are three parties that must work in concert to bring an online product: The DNS provider, The SSL/TLS Certificate provider and the hosting provider. We can't just randomly pick any three and hope they miraculously all work out together. For the impatient, let's start with the checklist of questions to ask ourselves and the provider we would like to use.

1. Does the DNS provider support top level ALIAS or ANAME?
2. What is the maximum key size (in bits) allowed by the SSL/TLS Certificate provider?
3. Will the SSL/TLS Certificate provider sign both, the top level domain name and www. subdomain?
4. Does the hosting provider guarentees a fixed IP address or does it provide a subdomain URL?
5. Does the hosting provider support upload of our own SSL/TLS certificates?

The remainder of the post will go through the rationale behind this checklist.

Domain Name association

The first and easiest thing to do to start a business on the Internet is to register a domain name. GoDaddy, DynDNS and other DNS providers offer to rent any available .com domain. For more fancy domains such as .it, .io, etc. we might have to search longer for an appropriate retailer but it is definitely possible.

Armed with a domain name, we need to associate the machine that will answer to that name. Imagine, in the physical world, we registered the AwesomePetFood brand. The first thing we will do is rent a space or a mail box so that customers can walk in or mail their orders to AwesomePetFood. On the Internet we need a machine to "pick up the phone" whenever a customer types AwesomePetFood.com in their web browser.

If we have a physical machine sitting in a data-center and it has a fixed IP address (ex: 192.168.144.1), for all intended purposes we can consider browsing to AwesomePetFood.com or browsing to 192.168.144.1 directly (no DNS resolution) equivalent - a bit like 1-800-PET-FOOD and 1-800-738-3663 are the same number, the first one just easier to remember.

How do we associate our domain name (AwesomePetFood.com) with the machine hosting our product? We create an "A RECORD" into the domain name service "Zone File".

AwesomePetFood.com. IN A 192.168.144.1

Renting a bare bone cloud machine from Amazon, Rackspace or DigitalOcean works almost the same way. Technically you get a machine with a dynamic IP address but that address does not change as long as the machine is running. Now your business looks more like a food truck than a physical retail store. Every time we shut down and re-open, customers find us at a new address. That is a bit inconvenient. Most cloud providers thus give you a way to also rent an "Elastic IP", lingo to mean a fixed IP you can associate to a cloud server.

AwesomePetFood.com.     IN CNAME    www.AwesomePetFood.com
www.AwesomePetFood.com. IN CNAME    AwesomePetFood.com

www.AwesomePetFood.com. IN CNAME    AwesomePetFood.djaodjin.com

URL redirect http://AwesomePetFood.com to http://www.AwesomePetFood.com

SSL/TLS Certificate

We are asking customers to enter their password in order to login. We might even ask them to enter their credit card to pay for our product. Both requires a certain level of trust that we are who we say we are and that the information customers hand to us is handled with care.

AwesomePetFood.djaodjin.com is already HTTPS enabled. A customer can type either http:// or https:// and it will be connected securely to https://AwesomePetFood.djaodjin.com. A green bar https:// means both that the identity of AwesomePetFood.djaodjin.com was verified and the communication to AwesomePetFood.djaodjin.com is encrypted between the customer browser and our server.

Since we are interested customers see https://www.AwesomePetFood.com in their URL bar, we must insure browsers can verify the identity of www.AwesomePetFood.com itself.

There is a lot of math involved. We need to generate a private key, then send a certificate signing request to a SSL provider like DigiCert or GoDaddy, and finally install the resulting public certificate on our server.

Let's decompose those steps in the context of getting a Driver's license after marriage. Alice has been married for a year, it is time to renew her driver license. She will take this opportunity to change her maiden name to her new family name.

To generate a private key and a certificate signing request for it on a Mac OSX machine, we just open the Terminal.app application and type:

$ openssl req -new -sha256 -newkey rsa:2048 -nodes \
    -keyout AwesomePetFood.com.key -out AwesomePetFood.com.csr

Here we are asked a few questions about the business, website and contact information. The only important thing to remember is to enter the www prefixed domain name (i.e. www.AwesomePetFood.com) when asked for the Common Name.

-----
Country Name (2 letter code) [XX]:
State or Province Name (full name) []:
Locality Name (eg, city) [Default City]:
Organization Name (eg, company) [Default Company Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (eg, your name or your server's hostname) []: www.AwesomePetFood.com
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

Remember AwesomePetFood.com and www.AwesomePetFood.com are different names as far as the certification authority is concerned. Technically you would need to get two certificates, one for AwesomePetFood.com and one for www.AwesomePetFood.com. Since a domain name and its www prefixed version are so common, most certificate authorities will generate both public certificates in a single file for a single payment, purely on a business rationale.

Armed with our private key and certificate signing request (CSR), we can go through the certificate authority flow, copy/paste the content of the CSR file when asked, and download the resulting public certificate when available.

In the middle of this process, the certificate authority will verify our identity in different ways. It can range from an e-mail to the administrator, a request to do some changes in the DNS record, put an HTML file on the server, or even a phone call.

The different price level and features for certification (EV / Premium Certificate, etc.) only have to do with the number and complexity of the checks done by the Certificate Authority before delivering a signed public certificate. This might show up differently in the browser URL bar. The underlying cryptography and security remains unchanged between all types of certificates. None-the-less if you want that "Green bar" look, a Certificate Authority will require to verify your business street address. This usually involved registering with Google Business and a verification code sent by physical mail.

Typically the Certificate Authority will generate a zip package that contains two files: the actual signed public certificate and a certificate chain. We drop the chain file and just copy the public certificate in place. Many times our site works after that, until someone complains the iPhone is not happy with our secure site. Why is that?

That is where the certificate chain comes in. There is a whole tree, a whole forest, of Certificate Authorities. Any hacker that manages to steal a Certificate Authority master key could impersonate any sites that authority signed, including our AwesomePetFood.com site. Getting a Certificate Authority master key is the holly grail of web hackers. It is like getting your hands on the machine making government issued driving license. Better there would be no way to tell a real from a fake driving license. Both would be as legitimate even though one was issued by the government, the other manufactured by a hacker.

Certificate Authorities create trees to mitigate the risks if something would go horribly wrong. Our freshly baked AwesomePetFood.com public certificate is a leaf in that tree. A browser will need to walk all the way up the chain from our AwesomePetFood.com to the root, verifying signature along the way before assuring AwesomePetFood.com is legitimate.

Some browser cache the most common trees and some don't. It is better to assume our server will have to send the whole chain from the AwesomePetFood.com leaf to the root. We thus run the following command to create the final AwesomePetFood.com.crt file we will upload to the service.

$ cat fe03ea125cd0493b.crt gd_bundle-g2-g1.crt > AwesomePetFood.com.crt

fe03ea125cd0493b.crt is our public certificate, gd_bundle-g2-g1.crt is the certificate chain provided to us, by GoDaddy in this case, as part of the zip file.

The private key (AwesomePetFood.com.key) and public certificate (AwesomePetFood.com.crt) must make it to the server responding to our domain name so they can be used.

Each service has a different way to import keys and certificates. On DjaoDjin, it is as simple as drag-n-drop the files on the domain configuration page. Services like Heroku enable developers to upload both keys and certificates through command line tools.

Once the key and certificates are in place, we then test various configuration. At our surprise we get the following results:

The browser is not happy with https://AwesomePetFood.com. We configured the DNS service to do an URL forward on AwesomePetFood.com. As a URL forward, the browser expects the DNS service to send AwesomePetFood.com public certificate back but it is not there. It is solely on our server which never saw that request.

How do we fix that? It depends. If we are lucky to have chosen a DNS provider that support ALIAS or ANAME, we should replace the URL forward by an ALIAS or ANAME configuration depending on the DNS service provider. Otherwise we should switch DNS provider or learn to live with the constraint.

More to read

If you are looking for more posts about what it is like to build a boutique subscription product on the Internet, you might enjoy How to bring your own service online and Back to school: lessons learned this summer.

More business lessons we learned running a SaaS application hosting platform are also available on the DjaoDjin blog. For our fellow engineers, there are in-depth technical posts available.