Keymaster

The Keymaster Puppet module is intended to manage the deployment and redeployment of keys, certificate, and other security tokens across Puppet nodes, services, applications, and users.

Keymaster will generate self-signed keys and deploy them, or can deploy keys that have been pre-generated and seeded into it's keystore.

Initially Keymaster will handle SSH keys and certificates for users and host SSH keys and certificates for nodes. The intent is to be sure that these keys are well known to the Puppet manifest and can be used and deployed through the Puppet infrastructure. At this stage Keymaster only covers the creation of self signed certificates and the distribution of pregenerated certificates seeded into it's keystore. Keymaster does not check for certificate expiry, revocation, or that certificates have the correct attributes. These functions have not yet been added or are better performed by monitor or alerting modules.

It is the intention that using Keymaster means that the content of a key or certificate not be stored in a Puppet manifest or Hiera data store.

This module does not install the ssh client, sshd service, or the OpenSSH packages. The saz-ssh module is recommended for managing the ssh client and service.

Background

This module implements and expands the OpenSSH key store and generation as described in this article on ssh::auth.

This module is mostly derived from the good work that Ashley Gould did on puppet-sshauth, but a rework was required to meet the following goals:

• Update style to meed now Puppet standards as enforced by puppet-lint
• Use new code features in Puppet and the Puppetlabs stdlib
• To include a full suite of unit tests with rspec-puppet and Travis-CI
• To move SSH keys into a their own name space to allow planned features
• Explicitly failing with messages rather than letting exceptions fall through for Puppet to handle.

Usage

Installing the Module

Install the keymaster module into a Puppet manifest by:

• With librarian-puppet

• The command line

  $ cd /etc/puppet/modules
  $ puppet module install Aethylred-keymaster
  

• Cloning from the git repository

  $ git clone https://github.com/Aethylred/puppet-keymaster.git /etc/puppet/modules/keymaster
  

Setting up the Keymaster

The Keymaster module requires that a Puppetmaster be set up as the Keymaster by including the keymaster class. All other operations with the Keymaster library require that a Keymaster is defined somewhere in a Puppet manifest. The minimum requirement would be:

include keymaster

Defining an OpenSSH Key

An OpenSSH key can be defined anywhere in a puppet manifest as it creates a collection of stored and virtual resources that can be realised where they are required, however they still must be defined and the virtual resources have to be collected and generated by the Keymaster before they are deployed. This includes the use of keys stored on the Keymaster, and generating them when they do not exist. Declaring the key only makes a key ready for use, and does not install or otherwise copy it to a node. A minimal key declaration would be:

keymaster::openssh::key('key_name': )

Assigning an OpenSSH Key to a User

A previously defined key (i.e. a key that has been defined in any part of a Puppet manifest) can be installed into a user's account. This copies the key's public and private parts to the user's .ssh directory. The minimal manifest to install a key in a user's account would be:

user{'your_name_here': }
keymaster::openssh::key{'key_name': }
keymaster::openssh::deploy_pair{'key_name':
  user => 'your_name_here',
}

Authorizing a Key to Access a User Account

The public part of a previously defined key can be injected into a user's ~/.ssh/authorized_keys file to allow holders of the private part of that key to use SSH to access that user account. The minimal manifest to authorize a key would be:

user{'your_name_here': }
keymaster::openssh::key{'key_name': }
keymaster::openssh::authorize{'key_name':
  user => 'your_name_here',
}

Seeding Keys

If a key is not present in the Keymaster Server's key store, the keymaster class will generate self-signed keys as required. These keys will persist and be reissued where ever a Puppet manifest says they should be deployed. This makes it possible to be sure that the same key is deployed without defining, or even knowing, its contents.

Seeding OpenSSH Keys

In those cases where a known and previously generated key is required, create a directory that represents the key's name (this_key in the example below) in the keystore hierarchy and copy in the private and public parts of the key. For an OpenSSH key (where the private part is the file key and the public part is the file key.pub) the result should be similar to:

/var/lib/keymaster/openssh-+-a_key
                           |
                           +-another_key
                           |
                           +-this_key-+-key
                                      |
                                      +-key.pub

Once the keystore is pre-seeded with the known key then in the puppet manifest the following entry in any node manifest would define the resource (the parameters should be used to make puppet aware of the nature of the key's content):

keymaster::openssh::key{'this_key': }

NOTE: When using a pre-seeded key it is not advisable to use the force, mindate or maxdays parameter otherwise Keymaster will revoke and regenerate these keys when they exceed the age defined by these parameters.

NOTE: When creating the directory that holds the key pair, substitute _at_ for the @ character. The @ character may not be safely supported in some file systems.

Seeding Host Keys

In most cases this is done to preserve the host's SSH key so that it is reissued on redeployment, however keymaster uses the saz-ssh module so host keys will also be populated into every other node's known hosts file. This removes the need to deal with the 'add host' dialogue when a user uses ssh to access a node for the first time.

Seeding x509 Keys

The expected scenario for seeding x509 certificates is to distribute properly signed x509 certificates that come from a trusted Certificate Authority. It is important that the parameters of the keymaster::x509::cert resource match the attributes of the certificate and that the certificate files are copied into a directory that has the same name as the resource title in the /var/lib/keymaster/x509 directory. The Keymaster module requires that the certificate files use an expected naming convention:

• The certificate configuration file (config.cnf) is generated according to the parameters provided to the keymaster::x509::cert resource declared in a manifest and may be overwritten by Puppet. When seeding x509 certificates the configuration file is not required and will be regenerated by Puppet.
• The private key has to be copied to key.pem and should be a PEM file. If the key provided is in another format, it must be converted to the PEM format while the certificate is being seeded into the Keymaster x509 keystore. When seeding x509 certificates the private key is required and must be provided.
• The certificate request file is generated by Puppet using the config file (config.cnf) and the private key (key.pem), however the Keymaster module should not overwrite the file if it already exists. When seeding x509 certificates the configuration file is not required and will be regenerated by Puppet.
• The certificate file (certificate.crt) contains the certificate itself in the DER format. If the certifcate is provided in another format, it must be converted to the DER format while the certificate is being seeded into the Keymaster x509 keystore. When seeding x509 certificates the certificate file is required and must be provided. If the certificate is to be provided in the P12, PFX or PKCS#12 format or the PEM file format, it is recommended that the key is copied into the keystore in it's original format and this is used to generate the required DER version.

/var/lib/keymaster/x509-+-a_key
                        |
                        +-another_key
                        |
                        +-this_key-+-config.cnf
                                   |
                                   +-key.pem
                                   |
                                   +-request.csr
                                   |
                                   +-certificate.crt

Classes

keymaster

The keymaster class prepares a Puppet master to act as a Keymaster key store. This class prepares and secures a directory (/var/lib/keymaster) to store the files used by the other resources defined in this module. The keymaster class realises the virtual and stored classes created by the resources defined in this module, making them available to be deployed by Puppet.

Parameters

user

This is the user that runs the Puppetmaster service, by default this is set to puppet. If Puppetmaster is being run under Apache or ngnix then this must be changed to match the user running these services.

group

This is the primary group of the user that runs the Puppetmaster service, by default this is set to puppet. If Puppetmaster is being run under Apache or ngnix then this must be changed to match the primary group of the user running these services.

Public Resources for SSH Keys

These resources are used in Puppet manifests and node definitions to deploy keys that have been defined with the Keymaster module.

keymaster::openssh::authorize

This will deploy the public part of a key pair in to the targeted user's ~/.ssh/authorized_keys file, which will allow user accounts holding the private part of the key SSH access to the targeted user's account.

The name of this resource must match the name of a keymaster::openssh::key resourced defined elsewhere in the Puppet manifest.

Parameters

user

This parameter targets the user which will receive the public part of the key into their ~/.ssh/authorized_keys file. The named user must be defined in a node's Puppet manifest. This is a required parameter.

ensure

This parameter ensures if the key authorization entry is present or absent in the targeted user's ~/.ssh/authorized_keys file. The default is present. This may not work as expected if the named key ensure parameter is set as absent.

options

This sets the option string that can be set when a key is authorized to access a user account or service. The default is undefined, which sets no option string. This parameter will override the option parameter of the previously defined keymaster::openssh::key being authorized.

keymaster::openssh::deploy_pair

This resource will deploy both the public and private parts of a key pair into the targeted user's ~/.ssh directory. This will grant the targeted user access to other user accounts that have the public part of the key in their ~/.ssh/authorized_keys file.

The name of this resource must match the name of a keymaster::openssh::key resourced defined elsewhere in the Puppet manifest.

Parameters

user

This parameter targets the user which will receive the key pair into their ~/.ssh directory. The named user must be defined in a node's Puppet manifest. This is a required parameter.

ensure

This parameter ensures that a key pair is present or absent in the targeted user's ~/.ssh directory. The default is present. This may not work as expected if the named key ensure parameter is set as absent.

filename

This parameter sets the base file name that the key pair uses when deployed to nodes. The private part uses the file name, while the public part appends the .pub extension. The default is undefined, in which case the file name is derived from the keytype (either id_rsa or id_dsa). This parameter will override the filname parameter of the previously defined keymaster::openssh::key being deployed.

keymaster::openssh::key

This resource defines an OpenSSH key and creates the virtual resources that are used to generate and deploy the key. In order to deploy this key to nodes defined in the Puppet manifest, there must be matching keymaster::openssh::deploy_pair or keymaster::openssh::authorize definitions with the same resource name.

NOTE: the defined key will not be available to be installed until there is a puppet run on the puppet master to trigger the key generation.

Parameters

ensure

This parameter defines if a key should be present or absent. When revoking a key, switching the ensure parameter to absent will set Puppet to actively remove keys from nodes. Just deleting or commenting out Keymaster classes and resources will stop Puppet from managing those keys, but will not make puppet remove them. Accepted values are present and absent, the default value is present.

filename

This parameter sets the base file name that the key pair uses when deployed to nodes. The private part uses the file name, while the public part appends the .pub extension. The default is undefined, in which case the file name is derived from the keytype (either id_rsa or id_dsa).

keytype

This parameter accepts rsa or dsa to define key type. The rsa key type is recommended and the default value is rsa.

length

This sets the bit length of the key. Values of less than 2048 are not recommended. When the key type is set to dsa this value is overridden and set to 1024. The default value is 2048.

maxdays

When set, the Keymaster server will regenerate a key when it exceeds the age set by the maxage parameter on the next puppet run. Nodes that deploy the key will update the key on the next puppet run. There may be an interim period where systems and services may be disrupted as the key redeploys across managed systems. The default is undefined which does not trigger a key refresh. It is not recommended that the maxdays parameter is used with pre-seeded keys.

mindate

Setting mindate will regenerate the key if it was created before the specified date. There may be an interim period where systems and services may be disrupted as the key redeploys across managed systems. The default is undefined which does not trigger a key refresh. It is not recommended that the mindate parameter is used with pre-seeded keys.

force

This parameter forces a key to be regenerated by the Keymaster. There may be an interim period where systems and services may be disrupted as the key redeploys across managed systems. The default is false which does not trigger a key refresh. It is not recommended that the force parameter is used with pre-seeded keys.

options

This sets the option string that can be set when a key is authorized to access a user account or service. The default is undefined, which sets no option string.

Public Resources for Host Keys

These resources manage and issue host keys via the saz-ssh module. Keymaster can use pre-seeded keys, or will generate a new one as required. Keys defined with Keymaster will be deployed as known hosts when the storeconfigs_enabled parameter is set to true when managing SSH with the ssh, ssh::client or ssh::server classes from saz-ssh. While the Keymaster module is dependent on saz-ssh it does not require any of it's classes or resources to be declared, though using saz-ssh to manage SSH configuration is recommended.

keymaster::host_key::key

This resource defines an OpenSSH host key and creates the virtual resources that are used to generate and deploy the key. In order to deploy this key to nodes defined in the Puppet manifest, there must be matching keymaster::host_key::redeploy definitions with the same resource name, or the deploy parameter set to true.

NOTE: the defined key will not be available to be installed until there is a puppet run on the puppet master to trigger the key generation.

Parameters

ensure

This parameter defines if a key should be present or absent. When revoking a key, switching the ensure parameter to absent will set Puppet to actively remove keys from nodes. Just deleting or commenting out Keymaster classes and resources will stop Puppet from managing those keys, but will not make puppet remove them. Accepted values are present and absent, the default value is present.

keytype

This parameter accepts rsa or dsa to define key type. The rsa key type is recommended and the default value is rsa.

length

This sets the bit length of the key. Values of less than 2048 are not recommended. When the key type is set to dsa this value is overridden and set to 1024. The default value is 2048.

maxdays

When set, the Keymaster server will regenerate a key when it exceeds the age set by the maxage parameter on the next puppet run. Nodes that deploy the key will update the key on the next puppet run. There may be an interim period where systems and services may be disrupted as the key redeploys across managed systems. The default is undefined which does not trigger a key refresh. It is not recommended that the maxdays parameter is used with pre-seeded keys.

mindate

Setting mindate will regenerate the key if it was created before the specified date. There may be an interim period where systems and services may be disrupted as the key redeploys across managed systems. The default is undefined which does not trigger a key refresh. It is not recommended that the mindate parameter is used with pre-seeded keys.

force

This parameter forces a key to be regenerated by the Keymaster. There may be an interim period where systems and services may be disrupted as the key redeploys across managed systems. The default is false which does not trigger a key refresh. It is not recommended that the force parameter is used with pre-seeded keys.

deploy

When set to true the key will also be deployed on the node that declares it. The default is false. This may cause errors until puppet runs on the Keymaster and generates a key or verifies it exists in the keystore.

keymaster::host_key::redeploy

This resources installs a previously defined host key on a node that matches the name of this resource. This should allow the reuse of the same host key on multiple nodes where shared identities across multiple machines is required.

Parameters

ensure

This parameter defines if a key should be present or absent. When revoking a key, switching the ensure parameter to absent will set Puppet to actively remove keys from nodes. Just deleting or commenting out Keymaster classes and resources will stop Puppet from managing those keys, but will not make puppet remove them. Accepted values are present and absent, the default value is present.

Public Resources for x509 Certificates

keymaster::x509::cert

This resource defines an x509 certificate and creates the virtual resources that are used to generate and deploy the certificate and private key. In order to deploy this certificate to nodes defined in the Puppet manifest, there must be matching keymaster::x509::deploy definitions with the same resource name, or the deploy_cert and/or deploy_key parameters set to true. X509 certificates are generated in the DER format and private keys in the PEM format.

NOTE A puppet run on the Keymaster may be required before the certificate can be deployed.

Parameters

commonname

This is a required parameter that sets the commmonName attribute of the certificate.

ensure

If set to present the certificate files will be generated on the Keymaster in the keystore if they have not already been seeded. If set to absent these files will be permanently deleted. The default value is present

NOTE Setting ensure to absent will irretrievably delete certificate files from the Keymaster keystore. Alternately, set deploy_cert and deploy_key to false and use keymaster::x509::deploy to remove certificate files from a node.

country

This sets the countryName attribute of the certificate. The default value is undefined.

organization

This sets the organizationName attribute of the certificate. The default value is undefined.

type

Sets the type of certificate to be deployed, as well as performing the required conversion on the Keymaster. Accepted values are pem,cer,crt,der,p12 and pfx. The default value is crt.

state

This sets the stateOrProvinceName attribute of the certificate. The default value is undefined.

locality

This sets the localityName attribute of the certificate. The default value is undefined.

aliases

This sets any aliases for the certificate using the subjectAltName attribute. It takes a list of DNS names as a list of strings. The default value is an empty list.

email

This sets the emailAddress attribute of the certificate. The default value is undefined.

days

This sets how long the certificate is valid for in days. The default value is 365.

password

This sets a password or pass-phrase for the certificate. The default value is undefined which results in a certificate with no password.

cert_path

This is the path that the certificate will be deployed to. The default value is undefined, which uses a OS distribution specific deployment path.

key_path

This is the path that the private key will be deployed to. The default value is undefined, which uses a OS distribution specific deployment path.

owner

Sets the owner of the deployed files. The default value is undefined, which will default to root.

group

Sets the group of the deployed files. The default value is undefined, which will default to root.

deploy_cert

If set to true the keymaster::x509::cert declaration will also deploy the certificate on the node. The default value is true.

deploy_key

If set to true the keymaster::x509::cert declaration will also deploy the private key on the node. The default value is true.

keymaster::x509::deploy

This resources installs a previously defined x509 certificate and/or private key on a node that matches the name of this resource. This should allow the reuse of the same x509 certificate and/or private key on multiple nodes where shared identities across multiple machines is required.

This resources also overrides some parameters set when the certificate was declared with the keymaster::x509::cert resource without impacting the state of the certificate stored in the Keymaster.

Parameters

ensure

If set to present this will deploy the certificate files to the node. If set to absent the certificate files will be deleted, but can be redeployed from the Keymaster. The default value is present.

type

Sets the type of certificate to be deployed, as well as performing the required conversion on the Keymaster. Accepted values are pem,cer,crt,der,p12 and pfx. The default value is crt.

NOTE A puppet run on the Keymaster may be required before the certificate can be deployed.

cert_path

This is the path that the certificate will be deployed to. The default value is undefined, which uses a OS distribution specific deployment path.

key_path

This is the path that the private key will be deployed to. The default value is undefined, which uses a OS distribution specific deployment path.

owner

Sets the owner of the deployed files. The default value is undefined, which will default to root.

group

Sets the group of the deployed files. The default value is undefined, which will default to root.

deploy_cert

If set to true the keymaster::x509::cert declaration will also deploy the certificate on the node. The default value is true.

deploy_key

If set to true the keymaster::x509::cert declaration will also deploy the private key on the node. The default value is true.

Private Resources

These private resources are used internally within the other Keymaster classes and resources. Calling them directly is unlikely to result in predictable outcomes.

keymaster::openssh::key::authorized_key

This private resource is created as a stored resource by the keymaster::openssh::key resource that is realised by the keymaster::openssh::authorize resource and inserts the public part of a key in to a user's ~/.ssh/authorized_keys file.

keymaster::openssh::key::deploy

This private resource is created as a stored resource by the keymaster::openssh::key resource that is realised by the keymaster::openss::deploy_pair resource where it deploys the public and private parts of a key into a user's ~/.ssh directory.

keymaster::openssh::key::generate

This private resource is created as a stored resource by the keymaster::openssh::key resource that is realised by the keymaster class where it verifies if a key exists in the Keymaster keystore, and generates a key if the named key does not exist.

keymaster::host_key::key::deploy

This private resource is created as a stored resource by the keymaster::host_key::key resource that is realised by the keymaster::host_key::redeploy resource where it deploys a key as a node's host key.

keymaster::host_key::key::generate

This private resource is created as a stored resource by the keymaster::host_key::key resource that is realised by the keymaster class where it verifies if a key exists in the Keymaster keystore, and generates a key if the named key does not exist.

keymaster::x509::cert::deploy

This private resource is created as a stored resource by the keymaster::x509::cert resource that is realised by the keymaster::x509::deploy resource where it deploys the x509 certificate to the node.

keymaster::x509::cert::generate

This private resource is created as a stored resource by the keymaster::x509::cert resource that is realised by the keymaster class where it verifies if a x509 certificate exists in the Keymaster keystore, and generates a certificate if the named certificate does not exist. This includes generating a configuration file (config.cnf), a private key (key.pem), a certificate request (request.csr), and the certificate itself (certificate.crt).

keymaster::x509::cert::p12

This private resource is created as a stored resource by the keymaster::cert::deploy resource if the certificate type of p12 or pfx is specified as a parameter. This resource is realised by the keymaster class where it copies and converts a DER format certificate file to a PKCS#12 formatted file in the Keymaster keystore if the PKCS#12 files do not exist.

keymaster::x509::cert::pem

This private resource is created as a stored resource by the keymaster::cert::deploy resource if the certificate type of pem is specified as a parameter. This resource is realised by the keymaster class where it copies and converts a DER format certificate file to a PKCS#12 formatted file in the Keymaster keystore if the PKCS#12 files do not exist.

keymaster::x509::key::deploy

This private resource is created as a stored resource by the keymaster::x509::cert resource that is realised by the keymaster::x509::deploy resource where it deploys the x509 private key to the node.

To Do

• Done

References

• ssh::auth
• saz-ssh This module is recommended for installing and configuring ssh and the sshd service.
• ashleygould puppet-sshauth
• Aethylred puppet-sshauth
• vurbia puppet-sshauth

Attribution

puppet-blank

This module is derived from the puppet-blank module by Aaron Hicks (aethylred@gmail.com)

This module has been developed for the use with Open Source Puppet (Apache 2.0 license) for automating server & service deployment.

• http://puppetlabs.com/puppet/puppet-open-source/