Ansible Role - Public Key Infrastructure (PKI)

This role helps set up and manage one or more PKIs on your server.

The EasyRSA script is used in the background to make automation easier.

Molecule Logs: Short, Full

Tested on:

• Debian 11

Installation

# To install the latest version
ansible-galaxy role install git+https://github.com/ansibleguy/infra_pki

# To install from Galaxy
ansible-galaxy install ansibleguy.infra_pki

# To install in a custom role path
ansible-galaxy install ansibleguy.infra_pki --roles-path ./roles

# To install dependencies
ansible-galaxy install -r requirements.yml

Usage

Looking for a simple Ansible GUI? Check out my Ansible WebUI.

Configuration

Set up your configuration as needed:

Example

More detailed examples can be found here: Example

Minimal Setup

pki:
  crl_distribution:
    domain: 'crl.ansibleguy.net'

  instances:
    root:
      pwd_ca: !vault |
        $ANSIBLE_VAULT;1.1;AES256
        ...

      sub_cas:
        main:
          pwd_ca: !vault |
            $ANSIBLE_VAULT;1.1;AES256
            ...

          certs:
            server:  # Server certificates
              ansibleguy_net:
                cn: 'AnsibleGuy Website'
                san:
                  dns: ['www.ansibleguy.net', 'ansibleguy.net']
                  ip: '135.181.170.217'
                  uri: 'https://www-ansibleguy.net'

            client:  # Client certificates
              workstation1:
                cn: 'AnsibleGuy Workstation'

Consider using 'ansible-vault' to encrypt your passwords:

ansible-vault encrypt_string

Execution

Run the playbook:

ansible-playbook -K -D -i inventory/hosts.yml playbook_pki.yml

There’s also an option to manage single certificates, which can be handy if they're managed by other roles:

# To run it interactively
ansible-playbook -K -D -i inventory/hosts.yml playbook_single_cert.yml

You can use the following tags for specific actions:

• instances => skip basic tasks but handle all PKI instances (RootCA)
• subcas => skip basic and instance tasks but handle all SubCA tasks
• certs => process tasks related to managing certificates
• certs_create => create any missing certificates
• certs_renew => renew certificates marked as 'renewed'
• certs_revoke => revoke certificates marked as 'revoked' or 'absent'

For debugging errors, set the 'debug' variable:

# WARNING: Will log passwords!
ansible-playbook -K -D -i inventory/hosts.yml playbook.yml -e debug=yes

Note: The --check mode is not supported because the role relies on command tasks.

Functionality

• Package installation

  • OpenSSL

• Configuration

  • Use a group for read-only access to public keys

• Default config:

  • Paths:
    • PKI base directory: '/var/local/lib/pki'
    • Script: '/usr/local/sbin/easyrsa'
  • PKI user: 'pki'
  • Read-only group: 'pki_read'
  • EasyRSA Variables:
    • Expiration:
      • Root-CA: 20 years
      • Sub-CA: 15 years
      • Certificates: 3 years
    • Digest:
      • Root-CA: sha512
      • Sub-CA/Certificates: sha256
    • Algorithm: rsa
    • Key size: 4096
  • Certificates:
    • Do not use password encryption on certificate private keys
    • Export formats:
      • pkcs12 (e.g. private/.p12)
      • certificate chain (e.g. issued/.chain.crt)

• Default Options:

  • Creates a dedicated PKI user and read-only group
  • Saves CA/Sub-CA/Certificate passwords to files for easier automation
  • Installation and setup of an Nginx webserver to serve CRLs and CA Public Keys (not implemented yet)

• Default Exclusions:

  • Removing unused (orphaned) certificates
  • Encrypting non-CA/Sub-CA certificate private keys

Information

• Note: You can enable or disable most features.

  For all options, check the default config in the main defaults file!

• Info: This role's configuration is tested using Molecule to ensure it behaves as expected.

  For example: It checks certificate attributes, file/directory permissions, and ownership after generating certificates with multiple Root and Sub-CAs.

  See Verification Tests.

• Warning: Not all settings/variables are validated. A bad configuration can break the role!

• Note: For more about PKIs and certificates:

  • EasyRSA has great documentation
  • For (x509) certificates, see the OpenSSL documentation.
  • For 'keyUsage' and 'extendedKeyUsage' details, check this StackExchange answer: LINK.
  • For a clean example of creating a PKI/SubCA using EasyRSA, see @QueuingKoala's example: GitHub Gist.

• Warning: To improve security against CA compromise, follow these steps:

  1. Ensure all necessary Sub-CAs are created by this role.

  2. Copy the CA private key (${path_base}/ca/private/ca.key) to an offline location (consider redundancy).

  3. Save the CA initialization password (not on the same device).

  4. Securely delete the ca.key file from your online system using a tool like 'shred':

     shred -vzu -n10 ca.key
     

• Note: You have several options for providing CA/Sub-CA/Certificate passwords:

  • If 'save_passwords' is set to true, the password will be saved after CA initialization.
  • As an inventory variable (encrypted with ansible-vault).
  • As --extra-vars during runtime.
  • If no password is provided, the role will ask for one at runtime.

• Note: Certificate variables set at:

  • Global level will apply to all instances and their sub-CAs.
  • Instance-level will apply to its sub-CAs.
  • Specific instance/subCA configurations will always override inherited settings.

• Note: There are scripts for automating certificate expiration monitoring that can integrate with systems like Zabbix located at files/usr/local/bin/monitoring.

• Warning: Changing CRL-Distribution settings is not easy.

  Existing certificates need to be re-generated if you change these settings.

• Note: The 'cert_expire' variable for the root CA will set the expiration time for sub-CAs!

• Note: Passwords for CA/Sub-CA/Certificate encryption must meet the following rules:

  • At least 8 characters
  • Must include:
    • A number
    • An uppercase letter
    • A lowercase letter

• Note: Certificate states can be set to:

  • 'present' or 'created' to ensure a certificate exists
  • 'absent' or 'revoked' to ensure a certificate does not exist
  • 'renewed' for renewing a certificate