custom_trusted_oid_mapping.yaml: Short names for cert extension OIDs

The custom_trusted_oid_mapping.yaml file lets you set your own short names for certificate extension object identifiers (OIDs), which can make the $trusted variable more useful.

The file must be present on each Puppet Server infrastructure node. The compiler does not add certificate extensions to $trusted in a serverless approach such as puppet apply.

Certificate extensions

When a node requests a certificate, it can ask the CA to include some additional, permanent metadata in that cert. Puppet agent uses the csr_attributes.yaml file to decide what extensions to request.

If the CA signs a certificate with extensions included, those extensions are available as trusted facts in the top-scope $trusted variable. Your manifests or node classifier can then use those trusted facts to decide which nodes can receive which configurations.

By default, the Puppet-specific registered OIDs appear as keys with convenient short names in the $trusted[extensions] hash, and any other OIDs appear as raw numerical IDs. You can use the custom_trusted_oid_mapping.yaml file to map other OIDs to short names, which replaces the numerical OIDs in $trusted[extensions].

For more information, see CSR attributes and certificate extensions, Trusted facts, The csr_attributes.yaml file.

Limitations of OID mapping

Mapping OIDs in this file only affects the keys in the $trusted[extensions] hash. It does not affect what an agent can request in its csr_attributes.yaml file — anything but Puppet-specific registered extensions must still be numerical OIDs.

After setting custom OID mapping values and restarting puppetserver, you can reference variables using only the short name.

Location

The OID mapping file is located at $confdir/custom_trusted_oid_mapping.yaml by default. Its location is configurable with the trusted_oid_mapping_file setting.

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

Example

---
oid_mapping:
  1.3.6.1.4.1.34380.1.2.1.1:
    shortname: 'myshortname'
    longname: 'My Long Name'
  1.3.6.1.4.1.34380.1.2.1.2:
    shortname: 'myothershortname'
    longname: 'My Other Long Name'

Format

The custom_trusted_oid_mapping.yaml must be a YAML hash containing a single key called oid_mapping.

The value of the oid_mapping key must be a hash whose keys are numerical OIDs. The value for each OID must be a hash with two keys:

  • shortname for the case-sensitive one-word name that is used in the $trusted[extensions] hash.

  • longname for a more descriptive name (not used elsewhere).