EasyRSA

This charm delivers the EasyRSA application to act as a Certificate Authority (CA) and create certificates for related charms.

How EasyRSA Works

What is EasyRSA?

EasyRSA is a command-line tool from the OpenVPN project for managing a Public Key Infrastructure (PKI). The charm packages EasyRSA as a Juju resource (easyrsa.tgz) and automates certificate operations through Juju relations and reactive handlers. The charm supports EasyRSA versions v3.0.1 through v3.0.9.

Charm Lifecycle and Certificate Operations

The EasyRSA charm performs the following operations automatically:

1. Installation: When deployed, the charm extracts EasyRSA to <charm_dir>/EasyRSA/ and initializes a new PKI by running ./easyrsa --batch init-pki.

2. Configuration: The charm modifies the OpenSSL configuration (openssl-*.cnf) to enable extension copying for CSR requests and updates the x509-types/server file to include clientAuth in the extendedKeyUsage field.

3. CA Creation: On the leader unit, when no CA exists or after initial relation setup, the charm generates a self-signed CA using:

   ./easyrsa --batch "--req-cn=<unit-ip>" build-ca nopass
   

4. Server Certificates: When a related charm requests a server certificate, the charm runs:

   ./easyrsa --batch --req-cn=<cn> --subject-alt-name=<sans> build-server-full <name> nopass
   

5. Client Certificates: When a related charm requests a client certificate, the charm runs:

   ./easyrsa build-client-full <name> nopass
   

6. Certificate Revocation: If certificate data changes (e.g., SANs update), the charm revokes the existing certificate with ./easyrsa --batch revoke <name> and regenerates it.

PKI Directory Structure

All PKI files are stored on the EasyRSA unit under <charm_dir>/EasyRSA/pki/:

The <charm_dir> is typically /var/lib/juju/agents/unit-easyrsa-0/charm/.

Leadership Data Storage

The leader unit persists critical PKI data to the Juju controller’s leadership database. This allows recovery if the unit is replaced:

Inspecting Certificates

To inspect the PKI on the EasyRSA unit:

# SSH into the unit
juju ssh easyrsa/0

# View the CA certificate
openssl x509 -in /var/lib/juju/agents/unit-easyrsa-0/charm/EasyRSA/pki/ca.crt -text -noout

# List all issued certificates
ls -la /var/lib/juju/agents/unit-easyrsa-0/charm/EasyRSA/pki/issued/

# Check a specific certificate's details
openssl x509 -in /var/lib/juju/agents/unit-easyrsa-0/charm/EasyRSA/pki/issued/<name>.crt -text -noout

# View certificate expiration dates
for cert in /var/lib/juju/agents/unit-easyrsa-0/charm/EasyRSA/pki/issued/*.crt; do
  echo "=== $(basename $cert) ==="
  openssl x509 -in "$cert" -noout -dates
done

Backup Recommendations

Regular backups are essential for PKI disaster recovery. The critical data to preserve is:

• Entire pki/ directory: Contains all certificates, keys, and PKI state
• Minimum required files for restore:
  • pki/ca.crt - CA certificate
  • pki/private/ca.key - CA private key
  • pki/private/client.key - Global client key
  • pki/issued/client.crt - Global client certificate
  • pki/serial - Serial number file

Backups created by the backup action are stored in /home/ubuntu/easyrsa_backup/ on the EasyRSA unit. It is recommended to copy backups off the unit for safekeeping using juju scp.

Deployment

To deploy EasyRSA:

juju deploy easyrsa

Using the EasyRSA charm

The EasyRSA charm will become a Certificate Authority (CA) and generate a CA certificate. Other charms need only to relate to EasyRSA with a requires using the tls-certificates interface.

To get a server certificate from EasyRSA, a charm must include the interface:tls-certificates interface in its layer.yaml file. The charm must also require the tls interface, in its metadata.yaml. The relation name may be named what ever you wish. Assume the relation is named “certificates” for these examples.

CA

The interface will generate a CA certificate immediately. If another charm requires a CA certificate the code must react to the flag certificates.ca.available. The relationship object has a method named get_ca which returns the CA certificate.

@when('certificates.ca.available')
def store_ca(tls):
    '''Read the certificate authority from the relation object and install it
    on this system.'''
    # Get the CA from the relationship object.
    ca_cert = tls.get_ca()
    write_file('/usr/local/share/ca-certificates/easyrsa.crt', ca_cert)

Client certificate and key

The EasyRSA charm generates a client certificate after the CA certificate is created. If another charm needs the CA the code must react to the flag certificates.client.cert.available. The relationship object has a method that returns the client cert and client key called get_client_cert.

@when('certificates.client.cert.available')
def store_client(tls):
    '''Read the client certificate from the relation object and install it on
    this system.'''
    client_cert, client_key = tls.get_client_cert()
    write_file('/home/ubuntu/client.crt', client_cert)
    write_file('/home/ubuntu/client.key', client_key)

Request a server certificate

The interface will set certificates.available flag on a relation. The reactive code should send three values on the relation to request a certificate. Call the request_server_cert method on the relationship object. The three values are: Common Name (CN), a list of Subject Alt Names (SANs), and the file name of the certificate (the unit name with the ‘/’ replaced with an underscore). For example a client charm would send:

@when('certificates.available')
def send_data(tls):
    # Use the public ip of this unit as the Common Name for the certificate.
    common_name = hookenv.unit_public_ip()
    # Get a list of Subject Alt Names for the certificate.
    sans = []
    sans.append(hookenv.unit_public_ip())
    sans.append(hookenv.unit_private_ip())
    sans.append(socket.gethostname())
    # Create a path safe name by removing path characters from the unit name.
    certificate_name = hookenv.local_unit().replace('/', '_')
    # Send the information on the relation object.
    tls.request_server_cert(common_name, sans, certificate_name)

Server certificate and key

The Easy-RSA charm generates the server certificate and key after the request have been made. If another charm needs the server certificate the code must react to the flag {relation_name}.server.cert.available. The relationship object has a method that returns the server cert and server key called get_server_cert.

@when('certificates.server.cert.available')
def store_server(tls):
    '''Read the server certificate from the relation object and install it on
    this system.'''
    server_cert, server_key = tls.get_server_cert()
    write_file('/home/ubuntu/server.cert', server_cert)
    write_file('/home/ubuntu/server.key', server_key)

Backup/Restore the PKI

This charm includes actions which support creating and managing snapshots of the Easy-RSA PKI. Refer to the PKI Directory Structure section for details on what files are included in the backup.

The backup is a compressed tarball of the entire pki/ directory. On restore, the charm:

1. Verifies the backup contains all required PKI files
2. Replaces the current pki/ directory with the backup contents
3. Updates the leadership database with CA cert, key, serial, and global client credentials
4. Notifies all related charms about the certificate change
5. Generates new certificates for any units that joined after the backup was created

Their usage is explained in the following sections:

Create backups

Use the charm’s backup action to capture current snapshot of the Easy-RSA PKI. This will generate a file in the directory /home/ubuntu/easyrsa_backup on the relevant unit. The backup file follows the naming convention: easyrsa-YYYY-MM-DD_HH-MM-SS.tar.gz.

For example:

juju run-action --wait easyrsa/0 backup

For convenience, the output of the backup action will output the exact juju scp command to download the created file to your local machine.

List backups

To list all the available backup files stored on the unit, run the following:

juju run-action --wait easyrsa/0 list-backups

This will output a list of filenames. These filenames are relative to the unit’s /home/ubuntu/easyrsa_backup/ directory.

The names can be used either directly as a parameters for the restore and delete-backup actions or as part of a juju scp command to download the backup files. For example, to download a backup named easyrsa-2020-12-10_16-37-54.tar.gz, the corresponding juju scp command would be:

juju scp easyrsa/0:/home/ubuntu/easyrsa_backup/easyrsa-2020-12-10_16-37-54.tar.gz .

Delete backups

To delete a backup file stored on the unit, simply run action delete-backup with parameter name=<backup_name>. List of all available backups can be obtained by running action list-backups. To remove all the backups from the unit, you can specify parameter all=true.

Removing a single backup:

juju run-action --wait easyrsa/0 delete-backup name=easyrsa-2020-12-10_16-37-54.tar.gz

Removing all backups:

juju run-action --wait easyrsa/0 delete-backup all=true

Restore backups

To restore a backup, run the restore action. This action takes one parameter, name, which specifies the backup file to be restored. This file must exist on the easyrsa unit for the action to succeed. A list of the available backups can be obtained by running the list-backups action.

For example:

juju run-action --wait easyrsa/0 restore name=easyrsa-2020-06-10_16-37-54.tar.gz

In the case where the backup file is available locally, it can be copied to the relevant unit before running the restore action by using the juju scp command. For example:

juju scp easyrsa-2020-12-10_16-37-54.tar.gz easyrsa/0:/home/ubuntu/easyrsa_backup/

In the case where units have been added to the Juju model since the backup was created, Easy-RSA will issue new certificates to these units.

Actions

This section covers Juju actions supported by the charm. Actions allow specific operations to be performed on a per-unit basis. To display action descriptions you can run juju actions easyrsa.