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.
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:
stdlib
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
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
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': )
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',
}
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',
}
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.
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.
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.
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:
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.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.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.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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
.
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.
ssh
and the sshd
service.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.