While intuitive at first, using periods in subdomains for environment hostnames can lead to some undesireable consequences. Use hyphens instead.
TL;DR: Using periods in subdomains adds complexity to SSL/TLS certificate management and cannot be used more than four times (fourthLabel.thirdLabel.secondLabel.firstLabel.domain.top-LevelDomain). Using hyphens can accommodate most existing, contextual (i.e. “your company’s…”) naming conventions and is easily scalable from a SSL/TLS certificate management perspective. Any trade offs are easily mitigated.
This summer I have been putting an online course together. As is prudent for publishing anything on the internet that’s pedagogical I am double and triple checking my choices align with industry standards and best practices. At one point the course demonstrates creating several non-production environments with associated pipelines, automation, and other accoutrements. I want the hostnames of these environments to align as clearly as possible with how I would reference them verbally. In the workplace I’ve accomplished this partially by separating “words” in the hostname with periods. When the URL was sent to others, particularly non-technical folks, the URL would be semantic enough to clearly reflect the purpose of the environment, such as [Product Name].[Environment Type].[Company Name].[Top-level Domain] (i.e. companywiki.testing.bigcorp.com) . This provided clarity to folks in the workplace who could be working with tens of products at a time or more (change management folks, middle managers, security professionals, etc. ).
Little did I know using periods sets one up for significant additional complexity in managing TLS/SSL certificates for non-prod environments and significantly limits naming convention possibilities (gasp!). Most industry content around naming is the different, contextual naming conventions teams have come up with. I didn’t come across content about translating these naming conventions into hostnames while avoiding traps (cue Admiral Ackbar).
Environment hostname naming conventions can be scaled with one SSL/TLS certificate (i.e. “cert”) up to one 63 character subdomain, presuming the cert has a wildcarded subdomain (i.e. *.domain.top-levelDomain). Any use of periods in the subdomain will create another “label” (also called a “fragment”, example: label.domain.top-LevelDomain). Each one of these labels can have up to 63 characters, however the total of all the labels, plus the periods that separate them, plus the domain name, plus the top-level domain cannot exceed 253 characters. In other words, label4.label3.label2.label1.domain.top-LevelDomain must be less than 253 characters. An example of a 63 character valid label would be “what-is-a-ballons-least-favorite-genre-of-music—-pop-hahahaha”. Seems like that’s long enough to accommodate most company naming convention use cases if it can accommodate smart speaker jokes!
Any label after the first will not be covered by the SSL/TLS certificate that has a wildcard on the first label (*gasps again*!). Approached from another angle, if you want to have more than one label in a hostname, you need to have a SSL/TLS certificate that denotes what the first label should be with a wildcard for the second label (i.e. *.labelOne.domain.top-levelDomain). The same is true for wildcarding the third or fourth label, each with a separate, properly “wildcarded” TLS/SSL certificate. This is where competent certificate management comes in if you want to scale your company’s naming convention to cover multiple labels.
However, I’d put forward an adequate alternative approach to using periods in subdomains is to use hyphens instead of periods in your first label. This will allow you up to 63 characters to express the environment with the hostname’s first label, allowing you to encrypt communications over all the environments using one SSL/TLS certificate. Cue third gasp, standing ovation, and profits! You’re welcome.
The total amount of string permutations is quite a large number. I posted a Math Stack Exchange question asking how to get this number. Here’s some scrappy JavaScript that resulted in 6.435878542419158e+98 permutations:
const firstLoop = 36;
// ^36 because Hypens can't begin a label
const otherLoops = 37;
const maxLabelLength = 63;
let sum = 0;
for(let i=1; i<=maxLabelLength; i++) {
sum += i==0
? firstLoop ** i
: otherLoops ** i
};
Either way, it’s one of those numbers that’s so big it’s tough to represent. This number is effectively doubled as a second label is wildcarded and associated with a specific first label (*.specificFirstLabel.domain.top-levelDomain). Obviously, all of these naming permutations wouldn’t be practical. I dare you, reader, to make a list of the practical ones! Lol jk, don’t worry about it. But if you do let me know; That would be a fun browse.
The approach of using hyphens instead of periods in hostnames naming conventions of non-prod environments allows for:
- Enough creative surface area for contextualized naming conventions in the subdomain
- Secure communications with the simplest TLS/SSL certificate management approach possible (i.e. only one, maybe two TLS/SSL certs to manage (two if you want to separate production & non-production TLS/SSL certificates)
- Is easily scalable by adding a TLS/SSL certificate for a specific first label with a “wildcarded” second label
- Can accommodate any current naming convention that doesn’t typically exceed 63 characters
One can pay for “Subject Alternative Names“, which is a service I saw provided by at least one Certificate Authority. It basically abstracts the certificate management, making it appear as if you’re able to use nested wildcards of labels without additional certificates. It is a way to solve this problem with money. With so many permutations offered within the 63-character label limit I’d posit most IT budgets could find better uses for the money.
I suppose teams could choose to use HTTP for their non-production environments to forego the certificate management altogether. Is that really a wise choice though? Besides sending visible web traffic and opting out of environment parity with production, any benefits of HTTP/2 in non-production environments can only be used by serving non-production environments over HTTPS. So sure, it’s an option. Is managing one TLS/SSL certificate really too much to ask in lieu of all these gains? Enjoy that Friday deployment when you learn the hard way you have external assets that are referenced using HTTP URLs.
Arguably, the hyphen is only for readability. One could forego including hyphens to save characters if the 63 character label limit can’t accommodate some longer, hopefully edge case naming conventions. My guess is the semantic exchange would not be worth it though as…
figuringoutwhat63characterstringssayeverydaywouldmakemyeyescross
That’s 64 characters, but you get the point. Literally had to format that string to break over multiple lines to keep it from messing up the user interface of this blog post on mobile. Add accommodating huge, single-line strings in company interfaces to the growing list of negatives.
For brevity’s sake, here’s a list of some trade offs to using one SSL/TLS certificate for securing multiple environment hostnames:
- If the private key of your SSL/TLS certificate is compromised all HTTPS communication transmitted using that certificate could have been compromised and a new SSL/TLS certificate should be rolled out to all environments ASAP. A mitigation is to have two separate SSL/TLS certificates for production (domain.top-LevelDomain & www.domain.top-LevelDomain) and non-prod environments (*.domain.top-LevelDomain). Secure them adequately, but separately.
- Any issues with SSL/TLS renewal will effect all environments. A mitigation is to automatically renew SSL/TLS certificates at a third of their expiration lifespan, at least, and confirm the certificate is actually renewed at a similar frequency.
Hope this sheds some light on the consequences of a seemingly harmless and intuitive choice to use periods in subdomains! Hyphens for the win!
Useful sources/links:
Is there a security issue in using the same certificate for all a company’s services? (Information Security Stack Exchange thread)
Can You Create A Wildcard SSL Certificate For Two Levels? Useful blog post with this illuminating quote:
“The reasons it is not possible to have a “double wildcard” SSL certificate is that the placeholder, the asterisk, can only stand in for one field in the name submitted to the CA. After all, the CA has to verify all information, and too many variables in the certificate would decrease the security and confidence the certificate provides.”
gitlab pages: dots in subdomain break tls, need to sanitize periods (.) to hypens (-) in pages subdomain (Relevant Gitlab Pages real-world issue)
