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.

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.