4.7.4. Apply Certificates¶
All clients in a SIMP system should have Public Key Infrastructure (PKI) keypairs generated for the server. These are the referred to as the infrastructure or server keys. These certificates are used to encrypt communication and identify clients and are used by common applications such as LDAP and Apache.
Note
These keypairs are not the keys that the Puppet server uses for its operation. Do not get the two confused.
See Certificate Management for more information.
SIMP uses the pupmod-simp-pki
module to help distribute infrastructure
keypairs. The global variable, simp_options::pki
determines what parts of
the module are included. It can be overridden in hieradata at several levels
if different hosts or applications need to handle certificates differently.
simp_options::pki
can have one of three settings:
simp
- Keypairs are distributed from a central location on the Puppet master to the/etc/pki/simp/x509
directory on the client. Any applications using them will then make a copy in/etc/pki/simp_apps/<app name>/x509
with the correct permissions for an application to use.true
- Applications on the clients will copy the keypairs from a local directory on the client to/etc/pki/simp_apps/<app name>/x509
. The default local directory to copy from is/etc/pki/simp/x509
but this can be overridden by setting thesimp_options::pki::source
variable.false
- The user will have to manage keypairs themselves. You will need to look at each module that uses PKI on a client to determine what variables need to be set.Note
A setting of
false
does not disable the use of PKI in a module.
The following sections describe how to populate the central key distribution
directory that pupmod-simp-pki
uses, when simp_options::pki
is set to
simp
.
4.7.4.1. Installing Official Certificates¶
This section describes how to install infrastructure certificates from an
official certificate authority on the Puppet master for distribution to client
servers. You need to have simp_options::pki set to simp
on the client for
this to work.
The key distribution directory on the Puppet master is the pki_files/files/keydist
sub-directory located under the SIMP-specific, alternate module path,
/var/simp/environments/<environment>/site_files
. Within the keydist
directory, the SIMP system expects there to be:
- A directory named
cacerts
that contains the CA public certificates. - Client-specific directories, each of which contains the public and private
certificates for an individual client. The name of each client directory
must be the
certname
of that client, which by default is the client’s FQDN.
Here is an example key distribution directory for a simp
environment:
/var/simp/environments/simp/site_files/pki_files/files/keydist/cacerts/
/var/simp/environments/simp/site_files/pki_files/files/keydist/cacerts/cacert_a7a23f33.pem
/var/simp/environments/simp/site_files/pki_files/files/keydist/cacerts/cca9a35.0
/var/simp/environments/simp/site_files/pki_files/files/keydist/mycomputer.my.domain/
/var/simp/environments/simp/site_files/pki_files/files/keydist/mycomputer.my.domain/mycomputer.my.domain.pem
/var/simp/environments/simp/site_files/pki_files/files/keydist/mycomputer.my.domain/mycomputer.my.domain.pub
/var/simp/environments/simp/site_files/pki_files/files/keydist/yourcomputer.your.domain/
/var/simp/environments/simp/site_files/pki_files/files/keydist/yourcomputer.your.domain/yourcomputer.your.domain.pem
/var/simp/environments/simp/site_files/pki_files/files/keydist/yourcomputer.your.domain/yourcomputer.your.domain.pub
To install official certificates on the Puppet master, do the following:
Copy the certificates received from a proper CA to the SIMP server.
Add the certificates for the node to the key distribution directory in
site_files
.- Make the directory under the key distribution directory for the client’s
certificates using the client’s
certname
. - Copy the official public and private certificates to that directory.
For example to install certificates for a system named
mycomputer.my.domain
into thesimp
environment:mkdir -p /var/simp/environments/simp/site_files/pki_files/files/keydist/mycomputer.my.domain mv /dir/where/the/certs/were/myprivatecert.pem \ /var/simp/environments/simp/site_files/pki_files/files/keydist/mycomputer.my.domain/mycomputer.my.domain.pem mv /dir/where/the/certs/were/mypubliccert.pub \ /var/simp/environments/simp/site_files/pki_files/files/keydist/mycomputer.my.domain/mycomputer.my.domain.pub
- Make the directory under the key distribution directory for the client’s
certificates using the client’s
Create and populate the CA certificates directory.
- Make the CA directory,
cacerts
. - Copy the root CA public certificates into
cacerts
in Privacy Enhanced Mail (PEM) format, one per file.
cd /var/simp/environments/simp/site_files/pki_files/files/keydist mkdir cacerts cd cacerts for file in *.pem; do ln -s $file `openssl x509 -in $file -hash -noout`.0; done
- Make the CA directory,
Make sure the permissions are correct.
chown -R root.puppet /var/simp/environments/simp/site_files/pki_files/files/keydist chmod -R u=rwX,g=rX,o-rwx /var/simp/environments/simp/site_files/pki_files/files/keydist
Note
The SIMP-specific alternate modules path is configured in each environment’s
environment.conf
file. For example, for the simp
environment,
/etc/puppetlabs/code/environments/simp/environment.conf
, would contain:
modulepath = modules:/var/simp/environments/simp/site_files:$basemodulepath
4.7.4.2. Generating Infrastructure Certificates from the Fake CA¶
The Fake (self signing) Certificate Authority (Fake CA) is provided by SIMP as a way to obtain server certificates if official certificates could not be obtained at the time of client installation or the servers are operating in testing environments.
Note
This option should not be used for any operational system that can use proper enterprise PKI certificates.
Below are the steps to generate the certificates using the SIMP-provided, Fake CA.
Type
cd /var/simp/environments/simp/FakeCA
Type
vi togen
Remove old entries from the file and add the Fully Qualified Domain Name (FQDN) of the systems (one per line) for which certificates will be created.
Note
To use alternate DNS names for the same system, separate the names with commas and without spaces.
For example,
.name,alt.name1,alt.name2.
Type
wc cacertkey
Note
Ensure that the
cacertkey
file is not empty. If it is, enter text into the file; then save and close the file.Type
./gencerts_nopass.sh
Warning
If the clean.sh
command is run after the certificates have been
generated, you will not be able to generate new host certificates under the
old CA. To troubleshoot certificate problems, see the
Troubleshooting Certificate Issues section.
If issues arise while generating keys, type cd /var/simp/environments/simp/FakeCA
to navigate to the /var/simp/environments/simp/FakeCA
directory, then type
./clean.sh
to start over.
After running the clean.sh
script, type ./gencerts_nopass.sh
to
run the script again using the previous procedure table.
The certificates generated by the FakeCA in SIMP are set to expire annually. To change this, edit the following files with the number of days for the desired lifespan of the certificates:
/var/simp/environments/simp/FakeCA/CA
/var/simp/environments/simp/FakeCA/ca.cnf
/var/simp/environments/simp/FakeCA/default\_altnames.cnf
/var/simp/environments/simp/FakeCA/default.cnf
/var/simp/environments/simp/FakeCA/user.cnf
In addition, any certificates that have already been created and signed will
have a config file containing all of its details in
/var/simp/environments/simp/FakeCA/output/conf/
.
Important
Editing any entries in the above mentioned config files will not affect existing certificates. Existing certificates must be regenerated if you need to make changes.
The following is an example of how to change the expiration time from one year (the default) to five years for any newly created certificate.
for file in $(grep -rl 365 /var/simp/environments/simp/FakeCA/)
do
sed -i 's/365/1825/' $file
done