Config files: custom_trusted_oid_mapping.yaml

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.

It is only valid on a Puppet master server. In Puppet apply, the compiler doesn’t add certificate extensions to $trusted.

More about 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 will replace the numerical OIDs in $trusted[extensions].

The output of puppet cert print reflects changes made in custom_trusted_oid_mapping.yaml immediatly without requiring a restart.

For more information, see:

• CSR Attributes and Certificate Extensions
• The csr_attributes.yaml File
• Trusted Facts

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 restarting puppetserver once custom OID mapping values are set, 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 will be used in the $trusted[extensions] hash.
• longname for a more descriptive name (not currently used for anything).