Vaultx.Secrets.PKI.CA (Vaultx v0.7.0)

Enterprise Certificate Authority management for HashiCorp Vault PKI.

This module provides comprehensive CA management functionality for enterprise PKI deployments, supporting complex certificate hierarchies, multi-issuer configurations, and automated CA lifecycle management. It implements industry best practices for certificate authority operations.

Enterprise CA Capabilities

Root CA Operations

Generate new root CA certificates with configurable policies
Import existing root CA certificates and private keys
Export CA certificates in multiple formats (PEM, DER, PKCS#7)
Configure advanced CA certificate policies and constraints
Support for Hardware Security Module (HSM) integration

Intermediate CA Operations

Generate intermediate CA certificate signing requests
Sign intermediate CA certificates from root or parent CAs
Build complex hierarchical PKI structures
Cross-sign certificates between different CA hierarchies
Automated intermediate CA renewal and rotation

Multi-Issuer Management

Manage multiple certificate issuers within single PKI mount
Configure issuer-specific policies and constraints
Automated issuer selection and load balancing
Certificate chain validation and trust path verification

Usage Examples

# Generate a new root CA
{:ok, ca_info} = CA.generate_root(%{
  common_name: "Example Root CA",
  ttl: "10y",
  key_type: "rsa",
  key_bits: 4096
})

# Generate an intermediate CA CSR
{:ok, %{csr: csr, private_key: key}} = CA.generate_intermediate(%{
  common_name: "Example Intermediate CA",
  key_type: "ec",
  key_bits: 256
})

# Import an existing CA certificate
:ok = CA.import_ca(ca_certificate, ca_private_key)

# Read the current CA certificate
{:ok, ca_cert} = CA.read_ca_certificate()

# Read the full CA chain
{:ok, ca_chain} = CA.read_ca_chain()

API Compliance

Fully implements HashiCorp Vault PKI CA management:

Configuration

CA operations support various configuration options:

Key Generation Options

:key_type - "rsa", "ec", or "ed25519"
:key_bits - Key size (RSA: 2048-8192, EC: 224-521)
:signature_bits - Signature hash size

Certificate Options

:common_name - CA certificate common name
:alt_names - Subject alternative names
:ip_sans - IP address SANs
:uri_sans - URI SANs
:ttl - Certificate validity period
:max_path_length - Maximum path length for intermediate CAs

Policy Options

:permitted_dns_domains - Allowed DNS domains
:excluded_dns_domains - Prohibited DNS domains
:permitted_ip_ranges - Allowed IP address ranges
:excluded_ip_ranges - Prohibited IP address ranges

Security Considerations

Root CA Security

Generate root CAs offline when possible
Use hardware security modules (HSMs) for key storage
Implement strict access controls for root CA operations
Regular backup and secure storage of root CA keys

Intermediate CA Best Practices

Use intermediate CAs for day-to-day certificate issuance
Implement shorter validity periods for intermediate CAs
Regular rotation of intermediate CA certificates
Proper certificate chain validation

Key Management

Use strong key sizes (RSA 2048+ bits, EC P-256+)
Implement proper key lifecycle management
Secure key storage and access controls
Regular key rotation and renewal procedures

Summary

Functions

generate_intermediate(opts \\ %{}, pki_opts \\ [])

Generate an intermediate CA certificate signing request (CSR).

generate_root(opts \\ %{}, pki_opts \\ [])

Generate a new root CA certificate and private key.

import_ca(certificate, private_key, pki_opts \\ [])

Import an existing CA certificate and private key.

read_ca_certificate(pki_opts \\ [])

Read the current CA certificate.

read_ca_chain(pki_opts \\ [])

Read the full CA certificate chain.

set_intermediate_certificate(certificate, pki_opts \\ [])

Set the intermediate CA certificate.

sign_intermediate(csr, opts \\ %{}, pki_opts \\ [])

Sign an intermediate CA certificate.

Functions

generate_intermediate(opts \\ %{}, pki_opts \\ [])

@spec generate_intermediate(
  map(),
  keyword()
) :: {:ok, map()} | {:error, Vaultx.Base.Error.t()}

Generate an intermediate CA certificate signing request (CSR).

Creates a new intermediate CA CSR and private key. The CSR can then be signed by a root CA or another intermediate CA to create the certificate.

Parameters

opts - CA generation options
pki_opts - PKI engine options

Returns

{:ok, %{csr: csr, private_key: key}} - CSR and private key
{:error, error} - Error information

Examples

{:ok, %{csr: csr, private_key: key}} = CA.generate_intermediate(%{
  common_name: "Example Intermediate CA",
  key_type: "rsa",
  key_bits: 2048
})

generate_root(opts \\ %{}, pki_opts \\ [])

@spec generate_root(
  map(),
  keyword()
) :: {:ok, map()} | {:error, Vaultx.Base.Error.t()}

Generate a new root CA certificate and private key.

Creates a new root CA certificate with the specified configuration. This operation generates both the certificate and private key within Vault.

Parameters

opts - CA generation options (see module documentation)
pki_opts - PKI engine options (mount_path, timeout, etc.)

Returns

{:ok, ca_info} - CA certificate information including certificate, private key, and metadata
{:error, error} - Error information

Examples

# Generate RSA root CA
{:ok, ca} = CA.generate_root(%{
  common_name: "Example Root CA",
  ttl: "10y",
  key_type: "rsa",
  key_bits: 4096
})

# Generate EC root CA with constraints
{:ok, ca} = CA.generate_root(%{
  common_name: "Example Root CA",
  ttl: "5y",
  key_type: "ec",
  key_bits: 384,
  max_path_length: 2,
  permitted_dns_domains: ["example.com", "example.org"]
})

import_ca(certificate, private_key, pki_opts \\ [])

@spec import_ca(String.t(), String.t(), keyword()) ::
  :ok | {:error, Vaultx.Base.Error.t()}

Import an existing CA certificate and private key.

Imports a CA certificate and its corresponding private key into the PKI engine. This is useful for migrating existing PKI infrastructure to Vault.

Parameters

certificate - PEM-encoded CA certificate
private_key - PEM-encoded private key
pki_opts - PKI engine options

Returns

:ok - Import successful
{:error, error} - Error information

Examples

ca_cert = File.read!("ca.pem")
ca_key = File.read!("ca-key.pem")
:ok = CA.import_ca(ca_cert, ca_key)

read_ca_certificate(pki_opts \\ [])

@spec read_ca_certificate(keyword()) ::
  {:ok, String.t()} | {:error, Vaultx.Base.Error.t()}

Read the current CA certificate.

Retrieves the CA certificate for the PKI engine in PEM format.

Parameters

pki_opts - PKI engine options

Returns

{:ok, certificate} - PEM-encoded CA certificate
{:error, error} - Error information

Examples

{:ok, ca_cert} = CA.read_ca_certificate()

read_ca_chain(pki_opts \\ [])

@spec read_ca_chain(keyword()) ::
  {:ok, [String.t()]} | {:error, Vaultx.Base.Error.t()}

Read the full CA certificate chain.

Retrieves the complete CA certificate chain including the CA certificate and any intermediate certificates in the chain.

Parameters

pki_opts - PKI engine options

Returns

{:ok, ca_chain} - List of PEM-encoded certificates in the chain
{:error, error} - Error information

Examples

{:ok, chain} = CA.read_ca_chain()

set_intermediate_certificate(certificate, pki_opts \\ [])

@spec set_intermediate_certificate(
  String.t(),
  keyword()
) :: :ok | {:error, Vaultx.Base.Error.t()}

Set the intermediate CA certificate.

Sets the intermediate CA certificate after it has been signed by a root CA or another intermediate CA. This completes the intermediate CA setup process.

Parameters

certificate - PEM-encoded signed intermediate CA certificate
pki_opts - PKI engine options

Returns

:ok - Certificate set successfully
{:error, error} - Error information

Examples

:ok = CA.set_intermediate_certificate(signed_cert)

sign_intermediate(csr, opts \\ %{}, pki_opts \\ [])

@spec sign_intermediate(String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Vaultx.Base.Error.t()}

Sign an intermediate CA certificate.

Signs an intermediate CA certificate signing request using the current CA. This creates a new intermediate CA certificate that can be used to issue end-entity certificates.

Parameters

csr - PEM-encoded certificate signing request
opts - Signing options
pki_opts - PKI engine options

Returns

{:ok, certificate_info} - Signed certificate information
{:error, error} - Error information

Examples

{:ok, cert} = CA.sign_intermediate(csr, %{
  common_name: "Intermediate CA",
  ttl: "5y",
  max_path_length: 1
})