Simon Marsh
7228e0a1d6
All checks were successful
continuous-integration/drone/push Build is passing
168 lines
6.1 KiB
Markdown
168 lines
6.1 KiB
Markdown
---
|
|
title: "ACME"
|
|
geekdocDescription: "ACME Service"
|
|
weight: 55
|
|
---
|
|
burble.dn42 provides an [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment)
|
|
service using an intermediate certificate issued by the
|
|
[dn42 certificate authority](https://dn42.dev/services/Certificate-Authority) and implemented using
|
|
a [HashiCorp Vault](https://vaultproject.io/) cluster to provide a highly available service.
|
|
|
|
The following ACME challenge types are supported:
|
|
|
|
- http-01
|
|
- dns-01
|
|
- tls-alpn-01
|
|
|
|
## dn42 endpoint
|
|
|
|
- <https://acme.burble.dn42/v1/dn42/acme/directory>
|
|
|
|
The dn42 endpoint serves certificates signed by an intermediate certificate issued by the
|
|
[dn42 certificate authority](https://dn42.dev/services/Certificate-Authority).
|
|
|
|
{{<hint info>}}
|
|
Note that certificates are issued with a validity period of **30 days**, which is
|
|
shorter than most clearnet ACME services.
|
|
|
|
The recommended interval to check for expiry is 5 days.
|
|
{{</hint>}}
|
|
|
|
## Staging endpoint
|
|
|
|
- <https://acme.burble.dn42/v1/staging/acme/directory>
|
|
|
|
The staging endpoint can be used for testing and issues junk certificates.
|
|
The service uses an internal certificate authority that is specific to the staging service
|
|
and should not be trusted.
|
|
|
|
The staging service issues short lived certificates with a validity period of a few days.
|
|
|
|
## Certificate Transparency
|
|
|
|
**TODO** A simpler process will be provided at a future stage, in the meantime the vault
|
|
API can be queried manually to list issued certificates.
|
|
|
|
--
|
|
|
|
Vault provides an API for listing issued certificates, however the process for doing this
|
|
is somewhat complicated if you have not used vault before. The instructions below detail
|
|
how to interrogate the service using the vault CLI, however it is also possible to run
|
|
through the same process via the
|
|
[HTTP API](https://developer.hashicorp.com/vault/api-docs?product_intent=vault).
|
|
|
|
```sh
|
|
# The API endpoint to list issued certificates is an authenticated
|
|
# endpoint that requires a vault token to access it.
|
|
#
|
|
# The burble.dn42 service includes an anonymous login that can be
|
|
# used to obtain a suitable token.
|
|
|
|
# set the VAULT_ADDR environment variable to the ACME service
|
|
|
|
$ export VAULT_ADDR="https://acme.burble.dn42"
|
|
|
|
# you can also set VAULT_SKIP_VERIFY=1 if you do not have the
|
|
# dn42 certificate authority installed.
|
|
|
|
# Issue an anonymous token and store it in the VAULT_TOKEN env variable
|
|
|
|
$ export VAULT_TOKEN=$(vault write -field token auth/approle/login role_id=anonymous)
|
|
|
|
# now the vault API can be accessed
|
|
|
|
|
|
# list issued certificates
|
|
|
|
$ vault list dn42/certs
|
|
|
|
Keys
|
|
----
|
|
06:72:54:74:02:eb:68:da:62:76:14:92:b4:84:19:36:b1:d1:d0:5c
|
|
0c:bb:39:a0:0a:aa:9c:d9:06:e8:9e:87:ff:54:73:c4:a6:42:9c:f0
|
|
13:91:4f:f7:3a:0b:ca:38:cd:c6:6e:7d:4d:fb:c5:7c:ed:b0:79:1b
|
|
39:5c:46:16:27:d8:f7:30:cc:64:1a:3c:6c:ff:c4:ac:f9:3c:3c:9c
|
|
4b:24:32:48:d0:64:55:3b:dd:b3:00:c6:33:2d:0f:3e:eb:d7:50:02
|
|
4c:8f:ce:e6:18:7a:05:c1:a3:11:45:c9:3c:34:0f:50:e0:75:6d:fd
|
|
5a:03:a9:5b:07:60:d0:fb:25:28:4b:e9:93:a8:22:cd:78:d1:29:b2
|
|
5d:26:b4:47:59:0c:0a:e9:88:b6:97:1d:2a:2b:e5:cb:d2:90:34:9e
|
|
65:c8:33:07:fc:9a:aa:fd:85:6b:fd:b4:de:29:71:e3:8e:6c:f2:11
|
|
68:e1:a6:4a:e1:58:ee:71:c7:a6:12:48:e2:7a:c5:84:c1:7c:21:5e
|
|
75:cf:16:f9:06:71:ea:86:1c:51:95:89:c9:1d:ea:a1:eb:f5:6f:83
|
|
76:91:6e:6a:23:14:00:7c:5f:c7:de:91:c4:40:73:d9:51:b4:f8:4d
|
|
|
|
# view an invidual certificate
|
|
|
|
$ vault read -field certificate "dn42/cert/76:91:6e:6a:23:14:00:7c:5f:c7:de:91:c4:40:73:d9:51:b4:f8:4d"
|
|
|
|
-----BEGIN CERTIFICATE-----
|
|
MIIDTTCCAjWgAwIBAgIUdpFuaiMUAHxfx96RxEBz2VG0+E0wDQYJKoZIhvcNAQEL
|
|
BQAwVTELMAkGA1UEBhMCWEQxDTALBgNVBAoTBGRuNDIxFDASBgNVBAsTC2J1cmJs
|
|
|
|
...snip...
|
|
|
|
yait1CFFq4g9/bvsNfIsvN6EJ/BGXqqww6BzKt/ioSLj
|
|
-----END CERTIFICATE-----
|
|
|
|
# human readable output using the step CLI (https://smallstep.com/)
|
|
|
|
$ vault read -field certificate "dn42/cert/06:72:54:74:02:eb:68:da:62:76:14:92:b4:84:19:36:b1:d1:d0:5c" | step certificate inspect
|
|
Certificate:
|
|
Data:
|
|
Version: 3 (0x2)
|
|
Serial Number: 36803586486229131299250018793512622456839458908 (0x672547402eb68da62761492b4841936b1d1d05c)
|
|
Signature Algorithm: SHA256-RSA
|
|
Issuer: C=XD,O=dn42,OU=burble.dn42,CN=burble.dn42 staging ACME
|
|
Validity
|
|
Not Before: Oct 2 18:21:36 2023 UTC
|
|
Not After : Nov 3 18:22:06 2023 UTC
|
|
Subject: CN=drone.git.dn42
|
|
Subject Public Key Info:
|
|
Public Key Algorithm: RSA
|
|
Public-Key: (4096 bit)
|
|
Modulus:
|
|
...snip...
|
|
Exponent: 65537 (0x10001)
|
|
X509v3 extensions:
|
|
X509v3 Key Usage: critical
|
|
Digital Signature, Key Encipherment, Key Agreement
|
|
X509v3 Extended Key Usage:
|
|
Server Authentication
|
|
X509v3 Subject Key Identifier:
|
|
01:4A:7E:02:F3:B7:78:03:66:F9:21:97:4B:31:34:7C:31:DE:BB:86
|
|
X509v3 Authority Key Identifier:
|
|
keyid:94:D1:C3:60:C7:88:81:A6:8C:37:AE:40:42:22:48:6B:5F:36:8F:CC
|
|
Authority Information Access:
|
|
OCSP - URI:https://acme.burble.dn42/v1/dn42/ocsp
|
|
CA Issuers - URI:https://acme.burble.dn42/v1/dn42/ca
|
|
X509v3 Subject Alternative Name:
|
|
DNS:drone.git.dn42
|
|
X509v3 CRL Distribution Points:
|
|
Full Name:
|
|
URI:https://acme.burble.dn42/v1/dn42/crl
|
|
Signature Algorithm: SHA256-RSA
|
|
...snip...
|
|
```
|
|
|
|
## Implementation
|
|
|
|
The ACME implementation is provided by a 3-node [HashiCorp Vault](https://www.vaultproject.io/)
|
|
cluster behind the [burble.dn42 traefik load balancer](/services/internal/#traefik--traefik-eu--traefik-na). Together they provide a global,
|
|
high availability service.
|
|
|
|
The cluster currently runs on the following nodes:
|
|
|
|
- ch-zur2
|
|
- de-fra1
|
|
- fr-par1
|
|
|
|
At any time the cluster has one leader which processes all requests and replicates state to the
|
|
cluster members. The leader node automatically switches to one of the backup servers should
|
|
a failure occur.
|
|
|
|
The traefik load balancer runs health checks against the vault servers and automatically redirects
|
|
users to the vault cluster leader.
|
|
|
|
See the [vault HA reference architecture](https://developer.hashicorp.com/vault/tutorials/day-one-raft/raft-reference-architecture) for more details.
|
|
|