Merge pull request #396 from smallstep/carl/template-update

Some clarifications in the Templates doc

Author: tashian

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 <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 
@@ -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).
@@ -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 <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
 [
@@ -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"`.