DOCSEARCHbyAlgolia
Submit Docs

easy-rsa

repository·master·Indexed 26 days ago

https://github.com/openvpn/easy-rsa

A CLI utility for managing a Public Key Infrastructure (PKI) Certificate Authority. It enables the creation, signing, and revocation of certificates, as well as the management of certificate revocation lists (CRL). Easy-RSA is tightly coupled with OpenSSL and provides configuration via command-line options, environment variables, and 'vars' files.

Tokens
7K
Snippets
19
Records
50
Agent score
88%

What's inside easy-rsa

  1. Overview of easy-rsa

    master
    easy-rsa is a command-line interface (CLI) utility designed to build and manage a Public Key Infrastructure (PKI) Certificate Authority (CA). It allows users to create a root certificate authority, request and sign certificates (including intermediate CAs), and manage certificate revocation lists (CRL).

  2. Understand PKI Terminology in Easy-RSA

    master

    To work with Easy-RSA, you must understand the following core concepts of Public Key Infrastructure (PKI):

    • PKI: The collection of files and associations between the CA, keypairs, requests, and certificates.
    • CA (Certificate Authority): The 'master cert' at the root of a PKI. Its private key is used to sign all issued certificates.
    • cert (Certificate): A request that has been signed by a CA. It contains the public key, descriptive details, and a digital signature from the CA.
    • request (Certificate Request/req): A request for a certificate sent to a CA for signing. It contains desired certificate information and a digital signature from the requester's private key.
    • keypair: An asymmetric cryptographic pair consisting of a public key (included in requests and certificates) and a private key (kept secret by the owner).

  3. Use "Org" style DN flexibility

    master
    In Easy-RSA 3, when using "org" DN mode, the requester is no longer required to match specific field values (like Country, State, or Org) used by the CA. This allows for easier remote generation as the requester does not need to know the CA's specific DN values in advance. If strict matching is required, you must manually verify the DN during the signing process or modify the OpenSSL configuration.

  4. Build a Certificate Authority (CA)

    master

    To create a new CA within your initialized PKI, use the build-ca command.

    During this process:

    • You will be prompted to enter a strong passphrase to protect the CA private key (private/ca.key). You must remember this passphrase for all future signing operations.
    • You will be asked to provide a Common Name (CN) for the CA, which is used for display purposes.
    ./easyrsa build-ca

  5. Understand the Request-Import-Sign workflow

    master

    Easy-RSA 3 supports a more secure workflow where keypairs are generated on the target system where they will be used, eliminating the need to transfer private keys between hosts.

    When using Easy-RSA as a CA, the recommended workflow is:

    1. Import: Import the request from the client.
    2. Sign: Sign the request using the CA.
    3. Return: Return the issued certificate and the CA certificate to the client.

    Individual requesting systems can also use Easy-RSA without a CA to generate their own keypairs and requests.

  6. Initialize a new PKI and CA

    master

    To start a new Public Key Infrastructure (PKI) and create your Certificate Authority (CA), run the following commands on your designated CA system:

    1. Initialize the PKI directory: ./easyrsa init-pki
    2. Build the CA: ./easyrsa build-ca
    ./easyrsa init-pki
./easyrsa build-c

  7. How Mutual Authentication Works via CA Trust

    master

    In a PKI, two entities can mutually authenticate without prior direct exchange of security information by using a shared CA trust.

    The Authentication Process:

    1. Cert Chain Exchange: During a TLS handshake, each side presents its certificate chain to the remote end.
    2. CA Validation: Each side checks the received certificate against its own copy of the CA certificate. If the certificate is signed by the trusted CA, the peer is authenticated.
    3. Proof of Possession: The remote end proves its identity by signing data using its own private key. Since only the legitimate holder of the certificate possesses the corresponding private key, the authenticity of the system is verified.

  8. Renew the CA Certificate

    master

    Easy-RSA 3.2.2+

    Use the renew-ca command to create a new CA certificate using the existing original CA key. This replaces the previous CA certificate. The old CA certificate is archived in pki/expired-ca.list.

    Manual CA Replacement (Recommended for OpenVPN)

    If you need to replace an expiring CA while minimizing work for clients, follow this workflow:

    1. BACKUP your current PKI.
    2. Reset PKI while preserving requests: Use init-pki soft. This keeps your vars file and CSRs in pki/reqs. Existing TLS keys are moved to pki/easyrsa-keepsafe-tls.key.
    3. Build new CA: Use build-ca to create a new CA certificate and private key. Use --days to set the new lifetime.
    4. Re-sign all certificates: Use sign-req <TYPE> <NAME> for every existing user/server request. This generates new certificates using the new CA without requiring new private keys from the users.
    5. Distribute new inline files: Provide the new inline files to all clients and servers.

  9. Locate and Use a 'vars' File

    master

    A vars file (named exactly vars with no extension) is used for external configuration. Easy-RSA searches for it in the following order, using only the first one found:

    1. The file specified by the --vars CLI option.
    2. The file specified by the EASYRSA_VARS_FILE environment variable.
    3. The directory specified by the --pki CLI option (Recommended).
    4. The directory specified by the EASYRSA_PKI environment variable.
    5. The directory specified by the EASYRSA environment variable.
    6. The default PKI directory at $PWD/pki.
    7. The default working directory at $PWD.

    Important Notes:

    • To prevent sourcing any vars file, define the EASYRSA_NO_VARS environment variable.
    • If using a vars file located at $PWD/pki/vars, it is forbidden from changing the current PKI directory defined by EASYRSA_PKI.
    • Best Practice: Use --pki=DIR to define your PKI at runtime. This automatically loads the vars file found within that directory and avoids potential verification issues in multi-PKI installations.

  10. Manage x509-type Configuration Files

    master

    Easy-RSA uses specific files to configure the SSL library, including openssl-easyrsa.cnf and various x509-types (e.g., ca, server, client, COMMON).

    Since version 3.2.0, these are created on-demand. To use custom versions, place them in supported locations (prioritizing EASYRSA_PKI).

    To generate these files in your current PKI:

    • Use easyrsa write legacy to create them.
    • Use easyrsa write legacy-hard to overwrite any existing files in the current PKI. Overwritten files take priority over system-wide versions.

  11. Configure Easy-RSA via Configuration Sources

    master

    Easy-RSA resolves configuration settings using a specific hierarchy. The first method that provides a definition wins:

    1. Command-line option (Highest priority)
    2. Environmental variable
    3. 'vars' file (if present)
    4. Built-in default (Lowest priority)

    Note: Not every configuration option can be set via every method, but any environment variable can be added to a vars file even if it is not shown by default.

  12. Install and run Easy-RSA

    master

    Easy-RSA does not require a formal installation process. To use it, download the compressed package (.tar.gz for Linux/Unix or .zip for Windows) and extract it to your desired location.

    Important:

    • Run Easy-RSA as a non-root (non-Administrator) account; root access is not required.
    • On Windows, use the EasyRSA Start.bat program to provide the necessary POSIX-shell environment.
    • In Unix-like environments, you must use the ./ prefix when invoking the script.