User:Callek/How To:Setup the PuppetAgain CA
This doc is designed to assist in setup of a new PuppetAgain Master, or entire PuppetAgain Cluster.
These instructions are not needed to be followed strictly, as long as your end result looks the same as ReleaseEngineering/PuppetAgain/Certificate_Chaining#Certificate_Hierarchy we expect.
The presumtions included are that you understand the overall concepts of Certificate chaining, as well as the differences between and definitions of CA, cert, key, CRL.
Helpful but not required are knowledge of the configuration and command syntax for openssl.
Before performing any steps - be sure you have read all the steps you will need and understand them.
Contents
The Root CA
Skip this section if you are not setting up a new cluster, and just adding to an existing cluster.
Except where noted, these steps should *not* be done on the puppetmaster you are setting up.
Create the Root Certificate Authority
# cd to a protected dir, exact dir doesn't really matter mkdir -p /root/rootca; cd /root/rootca # Best to change the name here, to distinguish from MoCo CA ROOT_CA_SUBJ="/CN=PuppetAgain Base CA, OU=Release Engineering, O=Mozilla, Inc." ROOT_KEY_PATH=./root.key ROOT_CERT_PATH=./root.crt openssl req -new -newkey rsa -days 3650 -x509 \ -subj "$ROOT_CA_SUBJ" -keyout $ROOT_KEY_PATH -out $ROOT_CERT_PATH # You will be prompted for a passphrase, choose a secure and confidential one! # Don't lose the passphrase as you will need it later # (and if you ever need to build new puppetmasters)
Create the Root CA's CRL
We will also need a Certificate Revocation List for the root CA...
First the pre-req setup
# (continue with vars set from previous step) # text database of issued certificates INVENTORY_DB=./inventory.txt # text file containing the next serial number to use in hex SERIAL_FILE=./serial # output CRL File ROOT_CRL_FILE=./root.crl touch $INVENTORY_DB echo 0001 > $SERIAL_FILE mkdir ./certs # Create the openssl.conf for the CRL cat <<EOF > "./openssl.conf" [ca] default_ca = puppetagain-root-ca [puppetagain-root-ca] certificate = $ROOT_CERT_PATH private_key = $ROOT_KEY_PATH database = ./inventory.txt new_certs_dir = ./certs serial = ./serial default_crl_days = 3650 default_days = 1825 default_md = sha1 policy = general_policy x509_extensions = general_exts [general_policy] commonName = supplied emailAddress = supplied organizationName = supplied organizationalUnitName = supplied [general_exts] authorityKeyIdentifier=keyid,issuer:always basicConstraints = critical,CA:true keyUsage = keyCertSign, cRLSign EOF
Now gen the actual CRL
openssl ca -config ./openssl.conf -gencrl -out $ROOT_CRL_FILE # You will be prompted for a passphrase you created above
You now have a *.key (private key - keep this secret!), *.crt (certificate), and *.crl (CRL) file for your root CA.
Save Information Locally
If the above was done on a puppetmaster, you'll want to securely save the created files locally, keeping special attention to the .key file to be securely saved. The key is needed to setup new puppetmasters and everything else is kept as a backup.
Inform the Puppetmaster about the Root CA
You need to copy the *.crt file to where the puppetmaster can find it, and make sure its accessible by puppet.
This step should be done after puppet is installed, and masterize.sh
prompts you for it with the following message:
The root CA certificate 'root.crt' is not in ${ca_certs_dir}. If this is present on another master, then wait for the sync cron job to copy it here. Otherwise, you will need to generate this root certificate and a corresponding key, and keep them in a safe place. For example: openssl req -new -newkey rsa -days 3650 -x509 -subj "/CN=PuppetAgain Root CA" \ -keyout "/root/root.key" -out "${root_ca_cert}" # also copy in the CRL at "${root_ca_crl}" chown -R puppetsync:puppetsync ${ca_certs_dir} Move /root/root.key somewhere safe and private and re-run puppet.
Note the comment about the CRL! Copy the root certificate to the path suggested (/var/lib/puppetmaster/ssl/git/ca-certs/root.crt) and copy the root CRL to root.crl in the same directory. Then fix up the permissions:
chown -R puppetsync:puppetsync /var/lib/puppetmaster/ssl/git/ca-certs/
Create the individual puppetmaster CA
Each separate puppetmaster will have its own CA, which is signed by the parent (root) CA we created above.
You will need:
- the root.crt
- the root.key
- the passphrase for root.ket
- the fqdn of the new puppetmaster.
This is mostly done for you, with some prompting from Puppet, using the following prompt
The master CA certificate '${fqdn}.crt' is not in '${ca_certs_dir}'. You will need to generate this certificate and sign it with the root certificate. Here's how. openssl genrsa -out ${master_ca_key} 2048 openssl req -new -subj "/CN=CA on ${fqdn}" -key ${master_ca_key} -out master-ca.csr openssl req -text -in master-ca.csr chown -R puppetsync:puppetsync ${ca_certs_dir} Check the request's contents in the dump, and then sign it with the root CA. Then copy/paste the resulting .crt back to ${master_ca_cert} and re-run puppet.
Note the these instructions generate a master private key at the appropriate location. That's important - Puppet will use it later! The instructions generate a CSR in master-ca.csr, which you will need to sign with the root CA. Back on the machine hosting the root CA, copy that CSR as ${fqdn}-ca.csr,
fqdn="master's fqdn" # remember fqdn is that of the puppetmaster openssl ca -config openssl.conf \ -in ${fqdn}-ca.csr -notext \ -out ${fqdn}-ca.crt -batch
copy the resulting ${fqdn}-ca.crt back to the puppet master at the path given (${master_ca_cert}).
Don't forget to reset the perms:
chown -R puppetsync:puppetsync ${ca_certs_dir}
Puppet will take it from here.