4.7.5. 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 hiera data at several levels if different hosts or applications need to handle certificates differently.

simp_options::pki can have one of three settings:

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

  2. 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 the simp_options::pki::source variable.

  3. 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.5.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 site_files/pki_files/files/keydist sub-directory located under the SIMP Secondary Environment, /var/simp/environments/<environment>. 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 production SIMP Omni-Environment:

/var/simp/environments/production/site_files/pki_files/files/keydist/cacerts/
/var/simp/environments/production/site_files/pki_files/files/keydist/cacerts/cacert_a7a23f33.pem
/var/simp/environments/production/site_files/pki_files/files/keydist/cacerts/cca9a35.0
/var/simp/environments/production/site_files/pki_files/files/keydist/mycomputer.my.domain/
/var/simp/environments/production/site_files/pki_files/files/keydist/mycomputer.my.domain/mycomputer.my.domain.pem
/var/simp/environments/production/site_files/pki_files/files/keydist/mycomputer.my.domain/mycomputer.my.domain.pub
/var/simp/environments/production/site_files/pki_files/files/keydist/yourcomputer.your.domain/
/var/simp/environments/production/site_files/pki_files/files/keydist/yourcomputer.your.domain/yourcomputer.your.domain.pem
/var/simp/environments/production/site_files/pki_files/files/keydist/yourcomputer.your.domain/yourcomputer.your.domain.pub

To install official certificates on the Puppet master, do the following:

  1. Copy the certificates received from a proper CA to the SIMP server.

  2. Add the certificates for the node to the key distribution directory in site_files.

    1. Make the directory under the key distribution directory for the client’s certificates using the client’s certname.
    2. Copy the official public and private certificates to that directory.

    For example to install certificates for a system named mycomputer.my.domain into the production environment:

    mkdir -p /var/simp/environments/production/site_files/pki_files/files/keydist/mycomputer.my.domain
    mv /dir/where/the/certs/were/myprivatecert.pem \
       /var/simp/environments/production/site_files/pki_files/files/keydist/mycomputer.my.domain/mycomputer.my.domain.pem
    mv /dir/where/the/certs/were/mypubliccert.pub \
       /var/simp/environments/production/site_files/pki_files/files/keydist/mycomputer.my.domain/mycomputer.my.domain.pub
    
  3. Create and populate the CA certificates directory.

    1. Make the CA directory, cacerts.
    2. Copy the root CA public certificates into cacerts in Privacy Enhanced Mail (PEM) format, one per file.
    cd /var/simp/environments/production/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
    
  4. Make sure the permissions are correct.

    chown -R root.puppet /var/simp/environments/production/site_files/pki_files/files/keydist
    chmod -R u=rwX,g=rX,o-rwx /var/simp/environments/production/site_files/pki_files/files/keydist
    

Note

The site_files sub-directory of the SIMP Secondary Environment is configured as another module path in each Puppet Environment’s environment.conf file. For example, for the production environment, /etc/puppetlabs/code/environments/production/environment.conf would contain:

modulepath = modules:/var/simp/environments/production/site_files:$basemodulepath

4.7.5.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. These steps assume the production environment.

  1. Type cd /var/simp/environments/production/FakeCA

  2. Type vi togen

  3. 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 omit any spaces.

    For example, .name,alt.name1,alt.name2.

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

  5. 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/production/FakeCA to navigate to the /var/simp/environments/production/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/production/FakeCA/CA
  • /var/simp/environments/production/FakeCA/ca.cnf
  • /var/simp/environments/production/FakeCA/default\_altnames.cnf
  • /var/simp/environments/production/FakeCA/default.cnf
  • /var/simp/environments/production/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/production/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/production/FakeCA/)
do
   sed -i 's/365/1825/' $file
done