cryptutil: add automatic certificate management (#644)

Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com>

docs/configuration/examples/config/config.example.env

@@ -15,10 +15,12 @@ export AUTHENTICATE_SERVICE_URL=https://authenticate.corp.beyondperimeter.com
 
 # Certificates can be loaded as files or base64 encoded bytes.
 # See : https://www.pomerium.io/docs/reference/certificates
-export CERTIFICATE_FILE="$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer"                      # optional, defaults to `./cert.pem`
-export CERTIFICATE_KEY_FILE="$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key" # optional, defaults to `./certprivkey.pem`
-# export CERTIFICATE="xxxxxx"                 # base64 encoded cert, eg. `base64 -i cert.pem`
-# export CERTIFICATE_KEY="xxxx"               # base64 encoded key, eg. `base64 -i privkey.pem`
+export AUTOCERT=TRUE # Use Let's Encrypt to fetch certs. Port 80/443 must be internet accessible.
+# export AUTOCERT_DIR="./certs" # The path where you want to place your certificates
+# export CERTIFICATE_FILE="xxxx"      # optional, defaults to `./cert.pem`
+# export CERTIFICATE_KEY_FILE="xxx" # optional, defaults to `./certprivkey.pem`
+# export CERTIFICATE="xxx"          # base64 encoded cert, eg. `base64 -i cert.pem`
+# export CERTIFICATE_KEY="xxx"      # base64 encoded key, eg. `base64 -i privkey.pem`
 
 # Generate 256 bit random keys  e.g. `head -c32 /dev/urandom | base64`
 export SHARED_SECRET="$(head -c32 /dev/urandom | base64)"

docs/configuration/examples/config/config.minimal.env

@@ -1,8 +1,7 @@
 #!/bin/bash
 
 # See : https://www.pomerium.io/docs/reference/certificates
-export CERTIFICATE_FILE="$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer"                      # optional, defaults to `./cert.pem`
-export CERTIFICATE_KEY_FILE="$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key" # optional, defaults to `./certprivkey.pem`
+export AUTOCERT=TRUE # Use Let's Encrypt to fetch certs. Port 80/443 must be internet accessible.
 
 # 256 bit random keys
 export SHARED_SECRET="$(head -c32 /dev/urandom | base64)"

docs/configuration/examples/config/config.minimal.yaml

@@ -4,8 +4,7 @@
 authenticate_service_url: https://authenticate.localhost.pomerium.io
 
 # certificate settings:  https://www.pomerium.io/docs/reference/certificates.html
-certificate_file: "./_wildcard.localhost.pomerium.io.pem"
-certificate_key_file: "./_wildcard.localhost.pomerium.io-key.pem"
+autocert: true
 
 # identity provider settings : https://www.pomerium.io/docs/identity-providers.html
 idp_provider: google

docs/configuration/readme.md

@@ -80,7 +80,7 @@ Enabling the debug flag will result in sensitive information being logged!!!
 
 :::
 
-By default, JSON encoded logs are produced. Debug enables colored, human-readable logs to be streamed to [standard out](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)>). In production, it's recommended to be set to `false`.
+By default, JSON encoded logs are produced. Debug enables colored, human-readable logs to be streamed to [standard out](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)>>>). In production, it's recommended to be set to `false`.
 
 For example, if `true`
 
@@ -127,23 +127,73 @@ Pomerium should _never_ be exposed to the internet without TLS encryption.
 
 :::
 
-### Certificate
+### Autocert
 
-- Environmental Variable: either `CERTIFICATE` or `CERTIFICATE_FILE`
-- Config File Key: `certificate` or `certificate_file`
-- Type: [base64 encoded] `string` or relative file location
-- Required
+- Environmental Variable: `AUTOCERT`
+- Config File Key: `autocert`
+- Type: `bool`
+- Optional
 
-Certificate is the x509 _public-key_ used to establish secure HTTP and gRPC connections.
+Turning on autocert allows Pomerium to automatically retrieve, manage, and renew public facing TLS certificates from [Let's Encrypt][letsencrypt] for each of your managed pomerium routes as well as for the authenticate service. This setting must be used in conjunction with `Certificate Folder` as Autocert must have a place to persist, and share certificate data between services. Provides [OCSP stapling](https://en.wikipedia.org/wiki/OCSP_stapling).
 
-### Certificate Key
+This setting can be useful in a situation where you do not have Pomerium behind a TLS terminating ingress or proxy that is already handling your public certificates on your behalf.
 
-- Environmental Variable: either `CERTIFICATE_KEY` or `CERTIFICATE_KEY_FILE`
-- Config File Key: `certificate_key` or `certificate_key_file`
+:::warning
+
+By using autocert, you agree to the [Let's Encrypt Subscriber Agreement](https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf). There are [_strict_ usage limits](https://letsencrypt.org/docs/rate-limits/) per domain you should be aware of. Consider testing with `autocert_use_staging` first.
+
+:::
+
+:::warning
+
+Autocert requires that port `443` be accessible from the internet in order to complete a [TLS-ALPN-01 challenge](https://letsencrypt.org/docs/challenge-types/#tls-alpn-01).
+
+:::
+
+### Autocert Foler
+
+- Environmental Variable: either `AUTOCERT_DIR`
+- Config File Key: `autocert_dir`
+- Type: `string` pointing to the path of the folder
+- Required if using Autocert setting
+- Default: [$XDG_DATA_HOME](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) or `$HOME/.local/share/pomerium`
+
+Autocert folder is path in which autocert will store x509 certificate data.
+
+### Autocert Use Staging
+
+- Environmental Variable: `AUTOCERT_USE_STAGING`
+- Config File Key: `autocert_use_staging`
+- Type: `bool`
+- Optional
+
+Let's Encrypt has strict [usage limits](https://letsencrypt.org/docs/rate-limits/). Enabling this setting allows you to use Let's Encrypt's [staging environment](https://letsencrypt.org/docs/staging-environment/) which has much more lax usage limits.
+
+### Certificates
+
+- Config File Key: `certificates` (not yet settable using environmental variables)
+- Config File Key: `certificate` / `certificate_key`
+- Config File Key: `certificate_file` / `certificate_key_file`
+- Environmental Variable: `CERTIFICATE` / `CERTIFICATE_KEY`
+- Environmental Variable: `CERTIFICATE_FILE` / `CERTIFICATE_KEY_FILE`
+- Type: array of relative file locations `string`
 - Type: [base64 encoded] `string`
-- Required
+- Type: certificate relative file location `string`
+- Required (if insecure not set)
 
-Certificate key is the x509 _private-key_ used to establish secure HTTP and gRPC connections.
+Certificates are the x509 _public-key_ and _private-key_ used to establish secure HTTP and gRPC connections. Any combination of the above can be used together, and are additive. Use in conjunction with `Autocert` to get OCSP stapling.
+
+For example, if specifying multiple certificates at once:
+
+```yaml
+certificates:
+  - cert: "$HOME/.acme.sh/authenticate.example.com_ecc/fullchain.cer"
+    key: "$HOME/.acme.sh/authenticate.example.com_ecc/authenticate.example.com.key"
+  - cert: "$HOME/.acme.sh/httpbin.example.com_ecc/fullchain.cer"
+    key: "$HOME/.acme.sh/httpbin.example.com_ecc/httpbin.example.com.key"
+  - cert: "$HOME/.acme.sh/prometheus.example.com_ecc/fullchain.cer"
+    key: "$HOME/.acme.sh/prometheus.example.com_ecc/prometheus.example.com.key"
+```
 
 ### Global Timeouts