1# `ceremony`
2
3```
4ceremony --config path/to/config.yml
5```
6
7`ceremony` is a tool designed for Certificate Authority specific key and certificate ceremonies. The main design principle is that unlike most ceremony tooling there is a single user input, a configuration file, which is required to complete a root, intermediate, or key ceremony. The goal is to make ceremonies as simple as possible and allow for simple verification of a single file, instead of verification of a large number of independent commands.
8
9`ceremony` has these modes:
10* `root` - generates a signing key on HSM and creates a self-signed root certificate that uses the generated key, outputting a PEM public key, and a PEM certificate. After generating such a root for public trust purposes, it should be submitted to [as many root programs as is possible/practical](https://github.com/daknob/root-programs).
11* `intermediate` - creates a intermediate certificate and signs it using a signing key already on a HSM, outputting a PEM certificate
12* `cross-csr` - creates a CSR for signing by a third party, outputting a PEM CSR.
13* `cross-certificate` - issues a certificate for one root, signed by another root. This is distinct from an intermediate because there is no path length constraint and there are no EKUs.
14* `ocsp-signer` - creates a delegated OCSP signing certificate and signs it using a signing key already on a HSM, outputting a PEM certificate
15* `crl-signer` - creates a delegated CRL signing certificate and signs it using a signing key already on a HSM, outputting a PEM certificate
16* `key` - generates a signing key on HSM, outputting a PEM public key
17* `ocsp-response` - creates a OCSP response for the provided certificate and signs it using a signing key already on a HSM, outputting a base64 encoded response
18* `crl` - creates a CRL with the IDP extension and `onlyContainsCACerts = true` from the provided profile and signs it using a signing key already on a HSM, outputting a PEM CRL
19
20These modes are set in the `ceremony-type` field of the configuration file.
21
22This tool always generates key pairs such that the public and private key are both stored on the device with the same label. Ceremony types that use a key on a device ask for a "signing key label". During setup this label is used to find the public key of a keypair. Once the public key is loaded, the private key is looked up by CKA\_ID.
23
24## Configuration format
25
26`ceremony` uses YAML for its configuration file, mainly as it allows for commenting. Each ceremony type has a different set of configuration fields.
27
28### Root ceremony
29
30- `ceremony-type`: string describing the ceremony type, `root`.
31- `pkcs11`: object containing PKCS#11 related fields.
32 | Field | Description |
33 | --- | --- |
34 | `module` | Path to the PKCS#11 module to use to communicate with a HSM. |
35 | `pin` | Specifies the login PIN, should only be provided if the HSM device requires one to interact with the slot. |
36 | `store-key-in-slot` | Specifies which HSM object slot the generated signing key should be stored in. |
37 | `store-key-with-label` | Specifies the HSM object label for the generated signing key. Both public and private key objects are stored with this label. |
38- `key`: object containing key generation related fields.
39 | Field | Description |
40 | --- | --- |
41 | `type` | Specifies the type of key to be generated, either `rsa` or `ecdsa`. If `rsa` the generated key will have an exponent of 65537 and a modulus length specified by `rsa-mod-length`. If `ecdsa` the curve is specified by `ecdsa-curve`. |
42 | `ecdsa-curve` | Specifies the ECDSA curve to use when generating key, either `P-224`, `P-256`, `P-384`, or `P-521`. |
43 | `rsa-mod-length` | Specifies the length of the RSA modulus, either `2048` or `4096`.
44- `outputs`: object containing paths to write outputs.
45 | Field | Description |
46 | --- | --- |
47 | `public-key-path` | Path to store generated PEM public key. |
48 | `certificate-path` | Path to store signed PEM certificate. |
49- `certificate-profile`: object containing profile for certificate to generate. Fields are documented [below](#certificate-profile-format).
50
51Example:
52
53```yaml
54ceremony-type: root
55pkcs11:
56 module: /usr/lib/opensc-pkcs11.so
57 store-key-in-slot: 0
58 store-key-with-label: root signing key
59key:
60 type: ecdsa
61 ecdsa-curve: P-384
62outputs:
63 public-key-path: /home/user/root-signing-pub.pem
64 certificate-path: /home/user/root-cert.pem
65certificate-profile:
66 signature-algorithm: ECDSAWithSHA384
67 common-name: CA intermediate
68 organization: good guys
69 country: US
70 not-before: 2020-01-01 12:00:00
71 not-after: 2040-01-01 12:00:00
72 key-usages:
73 - Cert Sign
74 - CRL Sign
75```
76
77This config generates a ECDSA P-384 key in the HSM with the object label `root signing key` and uses this key to sign a self-signed certificate. The public key for the key generated is written to `/home/user/root-signing-pub.pem` and the certificate is written to `/home/user/root-cert.pem`.
78
79### Intermediate or Cross-Certificate ceremony
80
81- `ceremony-type`: string describing the ceremony type, `intermediate` or `cross-certificate`.
82- `pkcs11`: object containing PKCS#11 related fields.
83 | Field | Description |
84 | --- | --- |
85 | `module` | Path to the PKCS#11 module to use to communicate with a HSM. |
86 | `pin` | Specifies the login PIN, should only be provided if the HSM device requires one to interact with the slot. |
87 | `signing-key-slot` | Specifies which HSM object slot the signing key is in. |
88 | `signing-key-label` | Specifies the HSM object label for the signing keypair's public key. |
89- `inputs`: object containing paths for inputs
90 | Field | Description |
91 | --- | --- |
92 | `public-key-path` | Path to PEM subject public key for certificate. |
93 | `issuer-certificate-path` | Path to PEM issuer certificate. |
94- `outputs`: object containing paths to write outputs.
95 | Field | Description |
96 | --- | --- |
97 | `certificate-path` | Path to store signed PEM certificate. |
98- `certificate-profile`: object containing profile for certificate to generate. Fields are documented [below](#certificate-profile-format).
99
100Example:
101
102```yaml
103ceremony-type: intermediate
104pkcs11:
105 module: /usr/lib/opensc-pkcs11.so
106 signing-key-slot: 0
107 signing-key-label: root signing key
108inputs:
109 public-key-path: /home/user/intermediate-signing-pub.pem
110 issuer-certificate-path: /home/user/root-cert.pem
111outputs:
112 certificate-path: /home/user/intermediate-cert.pem
113certificate-profile:
114 signature-algorithm: ECDSAWithSHA384
115 common-name: CA root
116 organization: good guys
117 country: US
118 not-before: 2020-01-01 12:00:00
119 not-after: 2040-01-01 12:00:00
120 ocsp-url: http://good-guys.com/ocsp
121 crl-url: http://good-guys.com/crl
122 issuer-url: http://good-guys.com/root
123 policies:
124 - oid: 1.2.3
125 - oid: 4.5.6
126 cps-uri: "http://example.com/cps"
127 key-usages:
128 - Digital Signature
129 - Cert Sign
130 - CRL Sign
131```
132
133This config generates an intermediate certificate signed by a key in the HSM, identified by the object label `root signing key` and the object ID `ffff`. The subject key used is taken from `/home/user/intermediate-signing-pub.pem` and the issuer is `/home/user/root-cert.pem`, the resulting certificate is written to `/home/user/intermediate-cert.pem`.
134
135Note: Intermediate certificates always include the extended key usages id-kp-serverAuth as required by 7.1.2.2.g of the CABF Baseline Requirements. Since we also include id-kp-clientAuth in end-entity certificates in boulder we also include it in intermediates, if this changes we may remove this inclusion.
136
137### Cross-CSR ceremony
138
139- `ceremony-type`: string describing the ceremony type, `cross-csr`.
140- `pkcs11`: object containing PKCS#11 related fields.
141 | Field | Description |
142 | --- | --- |
143 | `module` | Path to the PKCS#11 module to use to communicate with a HSM. |
144 | `pin` | Specifies the login PIN, should only be provided if the HSM device requires one to interact with the slot. |
145 | `signing-key-slot` | Specifies which HSM object slot the signing key is in. |
146 | `signing-key-label` | Specifies the HSM object label for the signing keypair's public key. |
147- `inputs`: object containing paths for inputs
148 | Field | Description |
149 | --- | --- |
150 | `public-key-path` | Path to PEM subject public key for certificate. |
151- `outputs`: object containing paths to write outputs.
152 | Field | Description |
153 | --- | --- |
154 | `csr-path` | Path to store PEM CSR for cross-signing, optional. |
155- `certificate-profile`: object containing profile for certificate to generate. Fields are documented [below](#certificate-profile-format). Should only include Subject related fields `common-name`, `organization`, `country`.
156
157Example:
158
159```yaml
160ceremony-type: cross-csr
161pkcs11:
162 module: /usr/lib/opensc-pkcs11.so
163 signing-key-slot: 0
164 signing-key-label: intermediate signing key
165inputs:
166 public-key-path: /home/user/intermediate-signing-pub.pem
167outputs:
168 csr-path: /home/user/csr.pem
169certificate-profile:
170 common-name: CA root
171 organization: good guys
172 country: US
173```
174
175This config generates a CSR signed by a key in the HSM, identified by the object label `intermediate signing key`, and writes it to `/home/user/csr.pem`.
176
177### OCSP Signing Certificate ceremony
178
179- `ceremony-type`: string describing the ceremony type, `ocsp-signer`.
180- `pkcs11`: object containing PKCS#11 related fields.
181 | Field | Description |
182 | --- | --- |
183 | `module` | Path to the PKCS#11 module to use to communicate with a HSM. |
184 | `pin` | Specifies the login PIN, should only be provided if the HSM device requires one to interact with the slot. |
185 | `signing-key-slot` | Specifies which HSM object slot the signing key is in. |
186 | `signing-key-label` | Specifies the HSM object label for the signing keypair's public key. |
187- `inputs`: object containing paths for inputs
188 | Field | Description |
189 | --- | --- |
190 | `public-key-path` | Path to PEM subject public key for certificate. |
191 | `issuer-certificate-path` | Path to PEM issuer certificate. |
192- `outputs`: object containing paths to write outputs.
193 | Field | Description |
194 | --- | --- |
195 | `certificate-path` | Path to store signed PEM certificate. |
196- `certificate-profile`: object containing profile for certificate to generate. Fields are documented [below](#certificate-profile-format). The key-usages, ocsp-url, and crl-url fields must not be set.
197
198When generating an OCSP signing certificate the key usages field will be set to just Digital Signature and an EKU extension will be included with the id-kp-OCSPSigning usage. Additionally an id-pkix-ocsp-nocheck extension will be included in the certificate.
199
200Example:
201
202```yaml
203ceremony-type: ocsp-signer
204pkcs11:
205 module: /usr/lib/opensc-pkcs11.so
206 signing-key-slot: 0
207 signing-key-label: intermediate signing key
208inputs:
209 public-key-path: /home/user/ocsp-signer-signing-pub.pem
210 issuer-certificate-path: /home/user/intermediate-cert.pem
211outputs:
212 certificate-path: /home/user/ocsp-signer-cert.pem
213certificate-profile:
214 signature-algorithm: ECDSAWithSHA384
215 common-name: CA OCSP signer
216 organization: good guys
217 country: US
218 not-before: 2020-01-01 12:00:00
219 not-after: 2040-01-01 12:00:00
220 issuer-url: http://good-guys.com/root
221```
222
223This config generates a delegated OCSP signing certificate signed by a key in the HSM, identified by the object label `intermediate signing key` and the object ID `ffff`. The subject key used is taken from `/home/user/ocsp-signer-signing-pub.pem` and the issuer is `/home/user/intermediate-cert.pem`, the resulting certificate is written to `/home/user/ocsp-signer-cert.pem`.
224
225### CRL Signing Certificate ceremony
226
227- `ceremony-type`: string describing the ceremony type, `crl-signer`.
228- `pkcs11`: object containing PKCS#11 related fields.
229 | Field | Description |
230 | --- | --- |
231 | `module` | Path to the PKCS#11 module to use to communicate with a HSM. |
232 | `pin` | Specifies the login PIN, should only be provided if the HSM device requires one to interact with the slot. |
233 | `signing-key-slot` | Specifies which HSM object slot the signing key is in. |
234 | `signing-key-label` | Specifies the HSM object label for the signing keypair's public key. |
235- `inputs`: object containing paths for inputs
236 | Field | Description |
237 | --- | --- |
238 | `public-key-path` | Path to PEM subject public key for certificate. |
239 | `issuer-certificate-path` | Path to PEM issuer certificate. |
240- `outputs`: object containing paths to write outputs.
241 | Field | Description |
242 | --- | --- |
243 | `certificate-path` | Path to store signed PEM certificate. |
244- `certificate-profile`: object containing profile for certificate to generate. Fields are documented [below](#certificate-profile-format). The key-usages, ocsp-url, and crl-url fields must not be set.
245
246When generating a CRL signing certificate the key usages field will be set to just CRL Sign.
247
248Example:
249
250```yaml
251ceremony-type: crl-signer
252pkcs11:
253 module: /usr/lib/opensc-pkcs11.so
254 signing-key-slot: 0
255 signing-key-label: intermediate signing key
256inputs:
257 public-key-path: /home/user/crl-signer-signing-pub.pem
258 issuer-certificate-path: /home/user/intermediate-cert.pem
259outputs:
260 certificate-path: /home/user/crl-signer-cert.pem
261certificate-profile:
262 signature-algorithm: ECDSAWithSHA384
263 common-name: CA CRL signer
264 organization: good guys
265 country: US
266 not-before: 2020-01-01 12:00:00
267 not-after: 2040-01-01 12:00:00
268 issuer-url: http://good-guys.com/root
269```
270
271This config generates a delegated CRL signing certificate signed by a key in the HSM, identified by the object label `intermediate signing key` and the object ID `ffff`. The subject key used is taken from `/home/user/crl-signer-signing-pub.pem` and the issuer is `/home/user/intermediate-cert.pem`, the resulting certificate is written to `/home/user/crl-signer-cert.pem`.
272
273### Key ceremony
274
275- `ceremony-type`: string describing the ceremony type, `key`.
276- `pkcs11`: object containing PKCS#11 related fields.
277 | Field | Description |
278 | --- | --- |
279 | `module` | Path to the PKCS#11 module to use to communicate with a HSM. |
280 | `pin` | Specifies the login PIN, should only be provided if the HSM device requires one to interact with the slot. |
281 | `store-key-in-slot` | Specifies which HSM object slot the generated signing key should be stored in. |
282 | `store-key-with-label` | Specifies the HSM object label for the generated signing key. Both public and private key objects are stored with this label. |
283- `key`: object containing key generation related fields.
284 | Field | Description |
285 | --- | --- |
286 | `type` | Specifies the type of key to be generated, either `rsa` or `ecdsa`. If `rsa` the generated key will have an exponent of 65537 and a modulus length specified by `rsa-mod-length`. If `ecdsa` the curve is specified by `ecdsa-curve`. |
287 | `ecdsa-curve` | Specifies the ECDSA curve to use when generating key, either `P-224`, `P-256`, `P-384`, or `P-521`. |
288 | `rsa-mod-length` | Specifies the length of the RSA modulus, either `2048` or `4096`.
289- `outputs`: object containing paths to write outputs.
290 | Field | Description |
291 | --- | --- |
292 | `public-key-path` | Path to store generated PEM public key. |
293
294Example:
295
296```yaml
297ceremony-type: key
298pkcs11:
299 module: /usr/lib/opensc-pkcs11.so
300 store-key-in-slot: 0
301 store-key-with-label: intermediate signing key
302key:
303 type: ecdsa
304 ecdsa-curve: P-384
305outputs:
306 public-key-path: /home/user/intermediate-signing-pub.pem
307```
308
309This config generates an ECDSA P-384 key in the HSM with the object label `intermediate signing key`. The public key is written to `/home/user/intermediate-signing-pub.pem`.
310
311### OCSP Response ceremony
312
313- `ceremony-type`: string describing the ceremony type, `ocsp-response`.
314- `pkcs11`: object containing PKCS#11 related fields.
315 | Field | Description |
316 | --- | --- |
317 | `module` | Path to the PKCS#11 module to use to communicate with a HSM. |
318 | `pin` | Specifies the login PIN, should only be provided if the HSM device requires one to interact with the slot. |
319 | `signing-key-slot` | Specifies which HSM object slot the signing key is in. |
320 | `signing-key-label` | Specifies the HSM object label for the signing keypair's public key. |
321- `inputs`: object containing paths for inputs
322 | Field | Description |
323 | --- | --- |
324 | `certificate-path` | Path to PEM certificate to create a response for. |
325 | `issuer-certificate-path` | Path to PEM issuer certificate. |
326 | `delegated-issuer-certificate-path` | Path to PEM delegated issuer certificate, if one is being used. |
327- `outputs`: object containing paths to write outputs.
328 | Field | Description |
329 | --- | --- |
330 | `response-path` | Path to store signed base64 encoded response. |
331- `ocsp-profile`: object containing profile for the OCSP response.
332 | Field | Description |
333 | --- | --- |
334 | `this-update` | Specifies the OCSP response thisUpdate date, in the format `2006-01-02 15:04:05`. The time will be interpreted as UTC. |
335 | `next-update` | Specifies the OCSP response nextUpdate date, in the format `2006-01-02 15:04:05`. The time will be interpreted as UTC. |
336 | `status` | Specifies the OCSP response status, either `good` or `revoked`. |
337
338Example:
339
340```yaml
341ceremony-type: ocsp-response
342pkcs11:
343 module: /usr/lib/opensc-pkcs11.so
344 signing-key-slot: 0
345 signing-key-label: root signing key
346inputs:
347 certificate-path: /home/user/certificate.pem
348 issuer-certificate-path: /home/user/root-cert.pem
349outputs:
350 response-path: /home/user/ocsp-resp.b64
351ocsp-profile:
352 this-update: 2020-01-01 12:00:00
353 next-update: 2021-01-01 12:00:00
354 status: good
355```
356
357This config generates a OCSP response signed by a key in the HSM, identified by the object label `root signing key` and object ID `ffff`. The response will be for the certificate in `/home/user/certificate.pem`, and will be written to `/home/user/ocsp-resp.b64`.
358
359### CRL ceremony
360
361- `ceremony-type`: string describing the ceremony type, `crl`.
362- `pkcs11`: object containing PKCS#11 related fields.
363 | Field | Description |
364 | --- | --- |
365 | `module` | Path to the PKCS#11 module to use to communicate with a HSM. |
366 | `pin` | Specifies the login PIN, should only be provided if the HSM device requires one to interact with the slot. |
367 | `signing-key-slot` | Specifies which HSM object slot the signing key is in. |
368 | `signing-key-label` | Specifies the HSM object label for the signing keypair's public key. |
369- `inputs`: object containing paths for inputs
370 | Field | Description |
371 | --- | --- |
372 | `issuer-certificate-path` | Path to PEM issuer certificate. |
373- `outputs`: object containing paths to write outputs.
374 | Field | Description |
375 | --- | --- |
376 | `crl-path` | Path to store signed PEM CRL. |
377- `crl-profile`: object containing profile for the CRL.
378 | Field | Description |
379 | --- | --- |
380 | `this-update` | Specifies the CRL thisUpdate date, in the format `2006-01-02 15:04:05`. The time will be interpreted as UTC. |
381 | `next-update` | Specifies the CRL nextUpdate date, in the format `2006-01-02 15:04:05`. The time will be interpreted as UTC. |
382 | `number` | Specifies the CRL number. Each CRL should have a unique monotonically increasing number. |
383 | `revoked-certificates` | Specifies any revoked certificates that should be included in the CRL. May be empty. If present it should be a list of objects with the fields `certificate-path`, containing the path to the revoked certificate, `revocation-date`, containing the date the certificate was revoked, in the format `2006-01-02 15:04:05`, and `revocation-reason`, containing a non-zero CRLReason code for the revocation taken from RFC 5280. |
384
385Example:
386
387```yaml
388ceremony-type: crl
389pkcs11:
390 module: /usr/lib/opensc-pkcs11.so
391 signing-key-slot: 0
392 signing-key-label: root signing key
393inputs:
394 issuer-certificate-path: /home/user/root-cert.pem
395outputs:
396 crl-path: /home/user/crl.pem
397crl-profile:
398 this-update: 2020-01-01 12:00:00
399 next-update: 2021-01-01 12:00:00
400 number: 80
401 revoked-certificates:
402 - certificate-path: /home/user/revoked-cert.pem
403 revocation-date: 2019-12-31 12:00:00
404```
405
406This config generates a CRL that must only contain subordinate CA certificates signed by a key in the HSM, identified by the object label `root signing key` and object ID `ffff`. The CRL will have the number `80` and will contain revocation information for the certificate `/home/user/revoked-cert.pem`. Each of the revoked certificates provided are checked to ensure they have the `IsCA` flag set to `true`.
407
408### Certificate profile format
409
410The certificate profile defines a restricted set of fields that are used to generate root and intermediate certificates.
411
412| Field | Description |
413| --- | --- |
414| `signature-algorithm` | Specifies the signing algorithm to use, one of `SHA256WithRSA`, `SHA384WithRSA`, `SHA512WithRSA`, `ECDSAWithSHA256`, `ECDSAWithSHA384`, `ECDSAWithSHA512` |
415| `common-name` | Specifies the subject commonName |
416| `organization` | Specifies the subject organization |
417| `country` | Specifies the subject country |
418| `not-before` | Specifies the certificate notBefore date, in the format `2006-01-02 15:04:05`. The time will be interpreted as UTC. |
419| `not-after` | Specifies the certificate notAfter date, in the format `2006-01-02 15:04:05`. The time will be interpreted as UTC. |
420| `ocsp-url` | Specifies the AIA OCSP responder URL |
421| `crl-url` | Specifies the cRLDistributionPoints URL |
422| `issuer-url` | Specifies the AIA caIssuer URL |
423| `policies` | Specifies contents of a certificatePolicies extension. Should contain a list of policies with the fields `oid`, indicating the policy OID, and a `cps-uri` field, containing the CPS URI to use, if the policy should contain a id-qt-cps qualifier. Only single CPS values are supported. |
424| `key-usages` | Specifies list of key usage bits should be set, list can contain `Digital Signature`, `CRL Sign`, and `Cert Sign` |
View as plain text