Extension requests (permanent certificate data)

Extension requests are pieces of data that are transferred as extensions to the final certificate, when the CA signs the CSR. They persist as trusted, immutable data, that cannot be altered after the certificate is signed.

They can also be used by the CA when deciding whether or not to sign the certificate.

Default behavior

When signing a certificate, Puppet’s CA tools transfer any extension requests into the final certificate.

You can access certificate extensions in manifests as $trusted["extensions"]["<EXTENSION OID>"].

Select OIDs in the ppRegCertExt and ppAuthCertExt ranges. See the Puppet-specific Registered IDs. By default, any other OIDs appear as plain dotted numbers, but you can use the custom_trusted_oid_mapping.yaml file to assign short names to any other OIDs you use at your site. If you do, those OIDs appear in $trusted as their short names, instead of their full numerical OID.

For more information about $trusted, see Facts and built-in variables.

The visibility of extensions is limited:

The puppetserver ca list command does not display custom attributes for any pending CSRs, and basic autosigning (autosign.conf) doesn’t check them before signing. Either use policy-based autosigning or inspect CSRs manually with the openssl command (see below).

Puppet’s authorization system (auth.conf) does not use certificate extensions, but Puppet Server’s authorization system, which is based on trapperkeeper-authorization, can use extensions in the ppAuthCertExt OID range, and requires them for requests to write access rules.

Configurable behavior

If you use policy-based autosigning, your policy executable receives the complete CSR in pem format. The executable can extract and inspect the extension requests, and use them when deciding whether to sign the certificate.

Manually checking for extensions in CSRs and certificates

You can check for extension requests in a CSR by running the OpenSSL command to dump a CSR in pem format to text format:

openssl req -noout -text -in <name>.pem

In the output, look for a section called Requested Extensions, which appears below the Subject Public Key Info and Attributes blocks:

Requested Extensions:
    pp_uuid:
    .$ED803750-E3C7-44F5-BB08-41A04433FE2E
    1.3.6.1.4.1.34380.1.1.3:
    ..my_ami_image
    1.3.6.1.4.1.34380.1.1.4:
    .$342thbjkt82094y0uthhor289jnqthpc2290

Every extension is preceded by any combination of two characters (.$ and .. in the example above) that contain ASN.1 encoding information. Because OpenSSL is unaware of Puppet’s custom extensions OIDs, it’s unable to properly display the values.

Any Puppet-specific OIDs (see below) appear as numeric strings when using OpenSSL.

You can check for extensions in a signed certificate by running:

/opt/puppetlabs/puppet/bin/openssl x509 -noout -text -in $(puppet config print signeddir)/<certname>.pem

In the output, look for the X509v3 extensions section. Any of the Puppet-specific registered OIDs appear as their descriptive names:

X509v3 extensions:
    Netscape Comment:
        Puppet Ruby/OpenSSL Internal Certificate
    X509v3 Subject Key Identifier:
        47:BC:D5:14:33:F2:ED:85:B9:52:FD:A2:EA:E4:CC:00:7F:7F:19:7E
    Puppet Node UUID:
        ED803750-E3C7-44F5-BB08-41A04433FE2E
    X509v3 Extended Key Usage: critical
        TLS Web Server Authentication, TLS Web Client Authentication
    X509v3 Basic Constraints: critical
        CA:FALSE
    Puppet Node Preshared Key:
        342thbjkt82094y0uthhor289jnqthpc2290
    X509v3 Key Usage: critical
        Digital Signature, Key Encipherment
    Puppet Node Image Name:
        my_ami_image

Recommended OIDs for extensions

Extension request OIDs must be under the ppRegCertExt (1.3.6.1.4.1.34380.1.1), ppPrivCertExt (1.3.6.1.4.1.34380.1.2), or ppAuthCertExt (1.3.6.1.4.1.34380.1.3) OID arcs.

Puppet provides several registered OIDs (under ppRegCertExt) for the most common kinds of extension information, a private OID range (ppPrivCertExt) for site-specific extension information, and an OID range for safe authorization to Puppet Server (ppAuthCertExt).

There are several benefits to using the registered OIDs:

You can reference them in the csr_attributes.yaml file with their short names instead of their numeric IDs.
You can access them in $trusted[extensions] with 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 widely used already. It is completely unregulated, and its contents are expected to be different in every Puppet deployment.

You can use the custom_trusted_oid_mapping.yaml file to set short names for any private extension OIDs you use. Note that this enables only the short names in the $trusted[extensions] hash.