diff --git a/step-ca/templates.mdx b/step-ca/templates.mdx index 03c08fb3..1ed8afc3 100644 --- a/step-ca/templates.mdx +++ b/step-ca/templates.mdx @@ -2,6 +2,7 @@ title: Configuring `step-ca` Templates html_title: Configuring open source step-ca Templates description: Learn how to configure step-ca Templates +updated_at: March 26, 2025 --- People use private CAs for all sorts of things, in many different contexts: @@ -126,7 +127,7 @@ The following snippet shows a provisioner with custom X.509 and SSH templates: - **_relative to the execution directory of `step-ca`_**: e.g. `./path/to/file.tpl` or `../path/to/file.tpl` - **templateData**: defines variables that can be used in the template. - In the example above, you will be able to use the defined organizational unit as the variable `{{ .OrganizationalUnit }}`, + In the example above, you are able to use the defined organizational unit as the variable `{{ .OrganizationalUnit }}`, for example in a template like: ```json @@ -212,21 +213,23 @@ See [the complete list of fields supported in `step-ca` templates](https://githu In templates, some variables are prefixed with .Insecure. They contain information that has not been cryptographically signed by a source that the CA trusts. - For example, the .Insecure.CR variable holds the user-supplied Certificate Request. + For example, the .Insecure.CR map holds the user-supplied Certificate Request. -Here are some common variables available in X.509 certificate templates: +Here are some variables available in X.509 certificate templates: - **.Subject**: - This is the subject that was passed in to `step certificate` or `step ca certificate`. Specifically, - `.Subject.CommonName` contains the Common Name for the certificate. + The subject that was passed in to `step certificate` or `step ca certificate`. Specifically, + `.Subject.CommonName` contains the Common Name for the certificate. By default, a passed-in subject + value must match a value from a trusted source in order to be added to the certificate. - **.SANs**: Subject Alternative Names. This is a list of maps containing SANs for the certificate. Unless SANs are specified (using the `--san` flag, for example), - the `.Subject.CommonName` is the default SAN. + the `.Subject.CommonName` is the default SAN. By default, a passed-in subject + value must match a value from a trusted source in order to be added to the certificate. - **.Token**: If a signed token was used to obtain the certificate @@ -244,6 +247,8 @@ Here are some common variables available in X.509 certificate templates: this is an array of the certificate chain from the request. This chain connects the authorization certificate to the root CA configured in the provisioner. +- **.Insecure** These variables are marked insecure because they contain client-supplied data that is not signed by a trusted party. + - **.Insecure.CR**: ☠️ This holds the Certificate Request (CSR) received from the client. `.Insecure.CR` is a [`crypto/x509` CertificateRequest](https://pkg.go.dev/crypto/x509#CertificateRequest). @@ -384,7 +389,7 @@ For more details on ASN.1 types and their meanings, see [ASN.1 Types](https://ww #### asn1Marshal -`asn1Marshal` simplifies the encoding of Go variables into ASN.1. +`asn1Marshal` simplifies the encoding of Go values into ASN.1. For example, if you want to encode the Not After value in an X5C authorization certificate, without converting it to a string first, `asn1Marshal .AuthorizationCrt.NotAfter` will do the trick. @@ -706,21 +711,21 @@ certificate subject on `step-ca` if a template is provided in the `ca.json`, and it will set the Subject Alternative Name extension to critical if the subject is empty. -#### User-Provided Variables in Signing Requests +#### User-Provided Values in Signing Requests -In `step-ca`, X.509 templates can also be parameterized with variables that will be +In `step-ca`, X.509 templates can also be parameterized with values provided by `step` at certificate creation time. A common use case for -variables is when you receive a CSR from another team, or a CSR embedded in +values is when you receive a CSR from another team, or a CSR embedded in hardware, and you need to define a SAN for it. -For example, below is an X.509 template that accepts the user variable `dnsName` -but falls back to the default leaf template if it's not present: +For example, below is an X.509 template that accepts the user-supplied value `dnsName` +but it falls back to the default leaf template value if it's not present: ```json { "subject": {{ toJson .Subject }}, {{- if .Insecure.User.dnsName }} - "dnsNames": {{ toJson .Insecure.User.dnsName}}, + "dnsNames": {{ toJson .Insecure.User.dnsName }}, {{- else }} "sans": {{ toJson .SANs }}, {{- end }} @@ -743,13 +748,13 @@ $ step ca sign --set-file vars.json input.csr output.crt ``` Both flags, `--set ` and `--set-file ` are available in -[`step ca certificate`](../step-cli/reference/ca/certificate) and [`step ca sign`](../step-cli/reference/ca/sign). If you need to pass more than one -variable, you can use `--set` multiple times or use a JSON file with multiple -properties. +[`step ca certificate`](../step-cli/reference/ca/certificate) and [`step ca sign`](../step-cli/reference/ca/sign). +If you need to pass more than one value, +you can use `--set` multiple times or use a JSON file with multiple properties. It's worth mentioning the while we used `"dnsNames"` instead of `"sans"` in the example above, both can -be used. `"dnsNames"` is an array of strings (or just one string if only one is -required), while `"sans"` is an array of objects like: +be used. `"dnsNames"` is a list of strings (or just one string if only one is +required), while `"sans"` is an list of maps: ```json [ @@ -760,8 +765,8 @@ required), while `"sans"` is an array of objects like: ] ``` -The variable `.SANs` is generated by the provisioners with the values of the -trusted names. +The list `.SANs` is generated by the provisioner, +containing the values of the trusted names. Besides `"dnsNames"`, you can also use `"emailAddresses"`, `"ipAddresses"`, and `"uris"`.