As described in the background reference article about certificates and PKI, certificates are documents containing a public key, metadata, and a signature.

This appendix will inspect two certificates and point out notable pieces of metadata, explaining their significance to Puppet’s SSL usage when applicable.

A Master or Agent Certificate

The certificates used by puppet master servers and puppet agent nodes are essentially the same; the only real difference is that puppet master certs sometimes contain alternate DNS names the master is allowed to use.

In this case, we will be inspecting the certificate of a node named magpie.example.com, which is allowed to present itself as a puppet master via the hostnames magpie, magpie.example.com, puppet, and puppet.example.com.

PEM File

A certificate is stored on disk as a .pem file in puppet’s certdir. The certdir is part of Puppet’s ssldir hierarchy, which is documented elsewhere (Puppet reference manual » important directories and files » ssldir). Another copy of the certificate is stored in the CA’s signed directory. (The puppet cert print command uses this copy, which is why it can only be used on the CA node.)

The name of the “privacy enhanced mail” (PEM) extension is somewhat misleading, since it has nothing to do with email; it’s just a historical quirk of X.509 implementations.

Text Output

To inspect a certificate, you must first dump it to a text format.

On the CA puppet master node, this can be done with the puppet cert print <name> command.

The openssl x509 -text -noout -in <file> command will also work and is not restricted to the CA puppet master, although it requires a full file path. Note that it also will not use friendly names for any Puppet-specific certificate extensions (explained further below).

The Subject (DN, CN, Certname, etc.)

Subject: CN=magpie.lan

The subject is the owner of the certificate, and the “Subject” field of the certificate contains the subject’s distinguished name (DN).

The DN is a string that represents the subject’s identity. It can consist of several different chunks of information, which are identified by one- or two-letter codes. Any number of these chunks can be appended together (separated by commas) to form a complete DN.

You won’t see multiple certificates with the same DN very frequently, since the DN represents the cert owner’s identity. Usually a reused DN means that an entity’s certificate has been reissued, due to expiration or revocation.

The common name (CN) is the most important piece of info in the DN. In this example, the node’s CN is magpie.example.com.

The CN is the only part of the DN used by Puppet. Puppet’s settings and documentation often refer to the CN as the certname — when a node sends a CSR to the CA, it uses the certname setting to decide what to request as the CN portion of its DN. (Again, note that Puppet nodes will never request other DN components; Puppet only cares about the CN.)

In a certificate presented by a puppet master, the CN will be interpreted as one of the legal hostnames at which the puppet master can provide services. In a certificate presented by a puppet agent node, the CN will be interpreted as that node’s name, which is used when finding node definitions and querying an ENC.

This DN includes information about the country (C), state (ST), locality (L), organization (O), and organizational unit (OU). The CN also includes an email address field, which Puppet doesn’t do.

Issuer

Issuer: CN=Puppet CA: magpie.example.com

This is the distinguished name of the certificate authority (CA) that signed the certificate. It is used to decide which CA certificate to use when validating the certificate.

In Puppet, generally only one CA certificate is in use within a given deployment. If a node is presented with a certificate whose issuer doesn’t match the CA it knows about, it will reject the connection. This can be a problem when moving nodes between deployments with distinct CAs, or if you attempt to replace the entire PKI of a Puppet deployment but miss a few files.

Validity Period

SSL certificates are only valid within a specific span of time, which is set by the CA when it signs the certificate. In Puppet, the duration is configurable, and the validity period always begins at the time at which the CA signs the certificate.

Note that if nodes disagree about what time it is, they may reject otherwise-valid certificates. For example, if a CA is living in the future when it signs a certificate, any nodes living in the present will think that certificate has not become valid yet and will reject it.

Alternative DNS Names

This field is listed under the “X509v3 extensions” section of the certificate.

This optional field contains other names that the certificate’s owner is allowed to use.

Various types of names exist in the X.509 spec, but in Puppet, only the DNS: prefix is used, and each name represents a hostname that the owner is allowed to use when acting as a puppet master server.

This section should generally only be present in a puppet master certificate. Its contents can be configured with the dns_alt_names setting, which can be specified in the config file or on the command line — when a node compiles its CSR, it will request any alternate names listed in that setting. The CA will see the requested alternate names, and will decide accordingly whether to sign the certificate.

(Agent nodes are all configured to reach their puppet master at a specific hostname. When the master presents its certificate, they check to make sure the name they called is included in this section of the certificate. This helps prevent man-in-the-middle impersonations of the puppet master — a certificate that wasn’t issued to the puppet master shouldn’t have the puppet master’s hostname included here.)

CA Permissions

This field is listed under the “X509v3 extensions” section of the certificate.

X509v3 Basic Constraints: critical
CA:FALSE

This field states whether the certificate can be used to sign new certificates. In Puppet agent and master certificates, it should always be false — this is a CA-only permission.

Key Usage

These fields are listed under the “X509v3 extensions” section of the certificate.

This defines the things the certificate can be used for. If you’ve read the series of background articles on SSL, there should be no major surprises here. However, one note is that both agent and master certificates have both server and client authentication listed. This is because:

The puppet master cert is also used by puppet agent running on the puppet master node, in order to request a catalog. (From itself, but rules are rules: it still uses HTTPS to do so.)

The puppet master server process can sometimes act as a client, requesting services provided by a PuppetDB server, a different puppet master server, or another HTTPS service.

In certain configurations (mostly the deprecated “puppet kick” feature), the puppet agent process can run an HTTPS server that listens for requests on port 8139.

Puppet-Specific Certificate Extensions

These fields are listed under the “X509v3 extensions” section of the certificate.

A CA Certificate

CA certificates are similar to other certificates, with a few critical differences. CA certs include different sets of permissions, and may have a circular “Issuer” reference.

PEM File

In Puppet, CA certificate PEM files are stored the same way other certificate PEM files are. The only difference is that the name of the file is ca.pem. We’ll skip the non-human-readable gibberish this time.

The Subject

Much like in other certificates, the “Subject” field contains the owner’s distinguished name. Note that the CA’s DN matches the “Issuer” field in the earlier certificate.

When creating a CA, Puppet will only fill in the common name (CN) portion of the CA’s DN — in this case, the value of the CN is Puppet CA: magpie.example.com. This value is taken from the value of the ca_name setting at the time the CA is initialized.

In Puppet, the CA certificate’s CN has no particular meaning; it’s just a unique descriptive string. (Unlike agent and master certificates, where the CN is treated as a hostname.)