csr_attributes.yaml: Certificate extensions

The csr_attributes.yaml file defines custom data for new certificate signing requests (CSRs).

The csr_attributes.yaml file can set:

  • CSR attributes (transient data used for pre-validating requests)

  • Certificate extension requests (permanent data to be embedded in a signed certificate)

This file is only consulted when a new CSR is created, for example when an agent node is first attempting to join a Puppet deployment. It cannot modify existing certificates.

For information about using this file, see CSR attributes and certificate extensions.

Location

The csr_attributes.yaml file is located at $confdir/csr_attributes.yaml by default. Its location is configurable with the csr_attributes setting.

The location of the confdir depends on your operating system. See the confdir documentation for details.

Example

---
custom_attributes:
  1.2.840.113549.1.9.7: 342thbjkt82094y0uthhor289jnqthpc2290
extension_requests:
  pp_uuid: ED803750-E3C7-44F5-BB08-41A04433FE2E
  pp_image_name: my_ami_image
  pp_preshared_key: 342thbjkt82094y0uthhor289jnqthpc2290

Format

The csr_attributes file must be a YAML hash containing one or both of the following keys:

  • custom_attributes

  • extension_requests

The value of each key must also be a hash, where:

  • Each key is a valid object identifier (OID). Note that Puppet-specific OIDs can optionally be referenced by short name instead of by numeric ID. In the example above, pp_uuid is a short name for a Puppet-specific OID.

  • Each value is an object that can be cast to a string. That is, numbers are allowed but arrays are not.

Allowed OIDs for custom attributes

Custom attributes can use any public or site-specific OID, with the exception of the OIDs used for core X.509 functionality. This means you can’t re-use existing OIDs for things like subject alternative names.

One useful OID is the “challengePassword” attribute — 1.2.840.113549.1.9.7. This is a rarely-used corner of X.509 which can be repurposed to hold a pre-shared key. The benefit of using this instead of an arbitrary OID is that it appears by name when using OpenSSL to dump the CSR to text; OIDs that openssl req can’t recognize are displayed as numerical strings.

Also note that the Puppet-specific OIDs listed below can also be used in CSR attributes.

Allowed OIDs for extension requests

Extension request OIDs must be under the “ppRegCertExt” (1.3.6.1.4.1.34380.1.1) or “ppPrivCertExt” (1.3.6.1.4.1.34380.1.2) OID arcs.

Puppet provides several registered OIDs (under “ppRegCertExt”) for the most common kinds of extension information, as well as a private OID range (“ppPrivCertExt”) for site-specific extension information. The benefits of using the registered OIDs are:

  • They can be referenced in csr_attributes.yaml using their short names instead of their numeric IDs.

  • When using Puppet tools to print certificate info, they appear using their descriptive names instead of their numeric IDs.

The private range is available for any information you want to embed into a certificate that isn’t already in wide use elsewhere. It is completely unregulated, and its contents are expected to be different in every Puppet deployment.

The “ppRegCertExt” OID range contains the following OIDs.
Numeric ID Short name Descriptive name
1.3.6.1.4.1.34380.1.1.1 pp_uuid Puppet node UUID
1.3.6.1.4.1.34380.1.1.2 pp_instance_id Puppet node instance ID
1.3.6.1.4.1.34380.1.1.3 pp_image_name Puppet node image name
1.3.6.1.4.1.34380.1.1.4 pp_preshared_key Puppet node preshared key
1.3.6.1.4.1.34380.1.1.5 pp_cost_center Puppet node cost center name
1.3.6.1.4.1.34380.1.1.6 pp_product Puppet node product name
1.3.6.1.4.1.34380.1.1.7 pp_project Puppet node project name
1.3.6.1.4.1.34380.1.1.8 pp_application Puppet node application name
1.3.6.1.4.1.34380.1.1.9 pp_service Puppet node service name
1.3.6.1.4.1.34380.1.1.10 pp_employee Puppet node employee name
1.3.6.1.4.1.34380.1.1.11 pp_created_by Puppet node created_by tag
1.3.6.1.4.1.34380.1.1.12 pp_environment Puppet node environment name
1.3.6.1.4.1.34380.1.1.13 pp_role Puppet node role name
1.3.6.1.4.1.34380.1.1.14 pp_software_version Puppet node software version
1.3.6.1.4.1.34380.1.1.15 pp_department Puppet node department name
1.3.6.1.4.1.34380.1.1.16 pp_cluster Puppet node cluster name
1.3.6.1.4.1.34380.1.1.17 pp_provisioner Puppet node provisioner name
1.3.6.1.4.1.34380.1.1.18 pp_region Puppet node region name
1.3.6.1.4.1.34380.1.1.19 pp_datacenter Puppet node datacenter name
1.3.6.1.4.1.34380.1.1.20 pp_zone Puppet node zone name
1.3.6.1.4.1.34380.1.1.21 pp_network Puppet node network name
1.3.6.1.4.1.34380.1.1.22 pp_securitypolicy Puppet node security policy name
1.3.6.1.4.1.34380.1.1.23 pp_cloudplatform Puppet node cloud platform name
1.3.6.1.4.1.34380.1.1.24 pp_apptier Puppet node application tier
1.3.6.1.4.1.34380.1.1.25 pp_hostname Puppet node hostname
The “ppAuthCertExt” OID range contains the following OIDs:
1.3.6.1.4.1.34380.1.3.1 pp_authorization Certificate extension authorization
1.3.6.1.4.1.34380.1.3.13 pp_auth_role Puppet node role name for authorization. For PE internal use only.