# Certificates
Certificates and TLS play a vital role in zero-trust networks, and in Pomerium. This document covers how to generate and set up wild-card certificates suitable for working with pomerium.
This guide uses the following tools and resources:
- LetsEncrypt is a public certificate authority that issues free certificates trusted by the major browsers. Other private or public CAs would also be fine.
- Google Domains registrar will be used to set up our wildcard domain and certificate validation. But any registrar would do and some providers support automatic renewal.
- acme.sh will be used to retrieve the wild-card domain certificate. Any LetsEncrypt client that supports wildcard domains would work.
It should be noted that there are countless ways of building and managing public-key infrastructure. And although we hope this guide serves as a helpful baseline for generating and securing pomerium with certificates, these instructions should be modified to meet your own organization's tools, needs, and constraints.
WARNING
LetsEncrypt certificates must be renewed every 90 days.
# Why
Since one of Pomerium's core principles is to treat internal and external traffic impartially, Pomerium uses mutually authenticated TLS ubiquitously. For example, Pomerium uses mTLS between:
- end-user and Pomerium
- Pomerium's services regardless of if the network is "trusted"
- Pomerium and the destination application
# How
First, you'll want to set a CNAME record for wild-card domain name you will be using with Pomerium.
Once you've setup your wildcard domain, we can use acme.sh to create a certificate-signing request with LetsEncrypt.
# Requires acme.sh @ https://github.com/Neilpang/acme.sh
# Install (after reviewing, obviously) by running :
# $ curl https://get.acme.sh | sh
$HOME/.acme.sh/acme.sh \
--issue \
-k ec-256 \
-d '*.corp.example.com' \
--dns \
--yes-I-know-dns-manual-mode-enough-go-ahead-please
Creating domain key
The domain key is here: $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key
Single domain='*.corp.example.com'
Getting domain auth token for each domain
Getting webroot for domain='*.corp.example.com'
Add the following TXT record:
Domain: '_acme-challenge.corp.example.com'
TXT value: 'Yz0B1Uf2xjyUI7Cr9-k96P2PQnw3RIK32dMViuvT58s'
Please be aware that you prepend _acme-challenge. before your domain
so the resulting subdomain will be: _acme-challenge.corp.example.com
Please add the TXT records to the domains, and re-run with --renew.
Please check log file for more details: $HOME/.acme.sh/acme.sh.log
Removing DNS records.
Not Found domain api file:
LetsEncrypt will respond with the corresponding TXT
record needed to verify our domain.
It may take a few minutes for the DNS records to propagate. Once it does, you can run the following command to complete the certificate request process.
# Complete the certificate request now that we have validated our domain
$HOME/.acme.sh/acme.sh \
--renew \
--ecc \
-k ec-256 \
-d '*.corp.example.com' \
--dns \
--yes-I-know-dns-manual-mode-enough-go-ahead-please
Renew: '*.corp.example.com'
Single domain='*.corp.example.com'
Getting domain auth token for each domain
Verifying: *.corp.example.com
Success
Verify finished, start to sign.
Cert success.
-----BEGIN CERTIFICATE-----
.... snip...
-----END CERTIFICATE-----
Your cert is in $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.cer
Your cert key is in $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key
The intermediate CA cert is in $HOME/.acme.sh/*.corp.example.com_ecc/ca.cer
And the full chain certs is there: $HOME/.acme.sh/*.corp.example.com_ecc/fullchain.cer
Here's how the above certificates signed by LetsEncrypt correspond to their respective Pomerium configuration settings:
Pomerium Config | Certificate file |
---|---|
CERTIFICATE | $HOME/.acme.sh/*.corp.example.com_ecc/fullchain.cer |
CERTIFICATE_KEY | $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key |
CERTIFICATE_AUTHORITY | $HOME/.acme.sh/*.corp.example.com_ecc/ca.cer |
OVERRIDE_CERTIFICATE_NAME | *.corp.example.com |
Your end users will see a valid certificate for all domains delegated by Pomerium.
# Resources
Certificates, TLS, and Public Key Cryptography is a vast subject we cannot adequately cover here so if you are new to or just need a brush up, the following resources may be helpful:
- Why HTTPS for Everything? The US government's CIO office has an excellent guide covering HTTPS and why future government sites will all be HTTPS.
- Is TLS Fast debunks the performance myth associated with HTTPS.
- Use TLS covers why TLS should be used everywhere; not just for securing typical internet traffic but for securing service communication in both "trusted" and adversarial situations.
- Everything you should know about certificates and PKI but are too afraid to ask