CSR attributes and certificate extensions

Default behavior

The puppet cert list command doesn’t display custom attributes for pending CSRs, and basic autosigning (autosign.conf) doesn’t check them before signing.

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 custom attributes, and use them to decide whether to sign the certificate.

The simplest method is to embed a pre-shared key of some kind in the custom attributes. A policy executable can compare it to a list of known keys and autosign certificates for any pre-authorized nodes.

A more complex use might be to embed an instance-specific ID and write a policy executable that can check it against a list of your recently requested instances on a public cloud, like EC2 or GCE.

If you use Puppet Server 2.5.0 or higher, you can also sign requests using authorization extensions and the --allow-authorization-extensions flag for puppet cert sign.

Manually checking for custom attributes in CSRs

You can check for custom attributes by using OpenSSL to dump a CSR in pem format to text format, by running this command:

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

In the output, look for the Attributes section which appears below the Subject Public Key Info block:

Attributes:
    challengePassword        :342thbjkt82094y0uthhor289jnqthpc2290

Recommended OIDs for 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 that can easily 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.

You can also use the Puppet-specific OIDs.

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>].

Any OIDs in the ppRegCertExt range appear using their short names. 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 will appear in $trusted as their short names, instead of their full numerical OID.

For more information about $trusted, see facts and special variables.

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

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

You can check for extensions in a signed certificate by running puppet cert print <name>. 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).

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 only enables the short names in the $trusted[extensions] hash.

Recovering from failed data embedding

When testing this feature for the first time, you might not embed the right information in a CSR, or certificate, and might want to start over for your test nodes. This is not really a problem once your provisioning system is changed to populate the data, but it can easily happen when doing things manually.

To start over, do the following.

After you’ve done that, you can start over.