Skip to content

Some clarifications in the Templates doc #396

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tashian merged 5 commits into from
Mar 27, 2025
Merged

Some clarifications in the Templates doc #396

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
e824507
Templates receive constants, not variables
tashian Mar 24, 2025
481f932
Note about SAN and subject values
tashian Mar 24, 2025
9333f62
Merge branch 'main' into carl/template-update
tashian Mar 25, 2025
bd86fd6
Clarifications
tashian Mar 25, 2025
2deb681
Constants -> variables
tashian Mar 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 25 additions & 20 deletions step-ca/templates.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -212,21 +213,23 @@ See [the complete list of fields supported in `step-ca` templates](https://githu
In templates, some variables are prefixed with <code>.Insecure</code>.
They contain information that has not been cryptographically signed
by a source that the CA trusts.
For example, the <code>.Insecure.CR</code> variable holds the user-supplied Certificate Request.
For example, the <code>.Insecure.CR</code> map holds the user-supplied Certificate Request.
</div>
</Alert>

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
Expand All @@ -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**<Reference id="star11" marker="*" />: ☠️
This holds the Certificate Request (CSR) received from the client.
`.Insecure.CR` is a [`crypto/x509` CertificateRequest](https://pkg.go.dev/crypto/x509#CertificateRequest).
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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 }}
Expand All @@ -743,13 +748,13 @@ $ step ca sign --set-file vars.json input.csr output.crt
```

Both flags, `--set <name=value>` and `--set-file <path>` 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
[
Expand All @@ -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"`.
Expand Down