ejbca_vault_pki_engine

EJBCA PKI Secrets Engine for HashiCorp Vault

The EJBCA PKI Secrets Engine for HashiCorp Vault enables DevOps teams to request and retrieve certificates from EJBCA using HashiCorp Vault, while security teams retain control over backend PKI operations.

The secrets engine is built on top of the EJBCA REST API and uses the EJBCA Go Client SDK for programmatic access. The EJBCA PKI Secrets Engine is a Vault plugin that replicates the built-in Vault PKI secrets engine, but processes requests through EJBCA instead of through Vault. The plugin was designed to be swapped for the built-in Vault PKI secrets engine with minimal changes to existing Vault configurations.

Community supported

We welcome contributions.

The EJBCA PKI Secrets Engine for HashiCorp Vault is open source and community supported, meaning that there is no SLA applicable for these tools.

Requirements

To build

• Git
• Golang >= v1.19

To use

• Keyfactor EJBCA >= v7.7
• HashiCorp Vault >= v1.11.0

Installation

From Source

Clone the repository and build the plugin.

git clone https://github.com/Keyfactor/ejbca-vault-pki-engine.git
cd ejbca-vault-pki-engine

Build the plugin for your platform.

go build -o ejbca-vault-pki-engine cmd/ejbca-pki/main.go

Calculate the SHA256 checksum of the plugin.

SHA256=$(sha256sum ejbca-vault-pki-engine | cut -d ' ' -f1)

From GitHub Release

Download and extract the latest release for your platform.

OS=$(go env GOOS)
ARCH=$(go env GOARCH)
curl -L https://github.com/Keyfactor/ejbca-vault-pki-engine/releases/latest/download/ejbca-vault-pki-engine-$OS-$ARCH.tar.gz
tar xzf ejbca-vault-pki-engine-$OS-$ARCH.tar.gz

Retrieve the SHA256 checksum of the plugin.

curl -L -o ejbca-sha256sums.txt https://github.com/Keyfactor/ejbca-vault-pki-engine/releases/latest/download/ejbca-vault-pki-engine_SHA256SUMS
SHA256=$(grep ejbca-vault-pki-engine-$OS-$ARCH.tar.gz ejbca-sha256sums.txt | cut -d ' ' -f1)

(the goreleaser currently calculates the hash of the whole .tar.gz file. for now, use the following command to calculate the hash of the plugin binary)

SHA256=$(sha256sum ejbca-vault-pki-engine | cut -d ' ' -f1)

Install the plugin

Move the plugin to the Vault plugin directory.

sudo mv ejbca-vault-pki-engine </path/to/vault/plugins>

Register SHA256 checksum of the plugin with Vault.

vault write sys/plugins/catalog/secret/ejbca-vault-pki-engine sha_256=$SHA256 command="ejbca-vault-pki-engine"

Mount the secrets engine and choose a prefix for the path (recommended is ejbca).

vault secrets enable -path=ejbca -plugin-name=ejbca-vault-pki-engine plugin

Configuration

Before using the EJBCA PKI Secrets Engine, you must configure it by providing the following information:

• EJBCA Hostname
• Client Certificate
• Client Private Key
• Default CA Certificate (used as issuer_ref if not configured in role)
• Default End Entity Profile (used as end_entity_profile_name if not configured in role)
• Default Certificate Profile (used as certificate_profile_name if not configured in role)

Use the following vault command to create the config object:

vault write ejbca/config \
	ejbca_hostname="https://ejbca.example.com:8443/ejbca" \
	client_cert=@/path/to/client/cert.pem \
	client_key=@/path/to/client/key.pem \
	ca_cert=@/path/to/ca/cert.pem \
	end_entity_profile_name="MyEndEntityProfile" \
	certificate_profile_name="MyCertificateProfile"

Roles

The EJBCA PKI Secrets Engine supports the same role configuration as the built-in Vault PKI secrets engine, and can be used as a drop-in replacement. Use the following command to get descriptions for these fields:

vault path-help ejbca/roles/name

The following example creates a basic role that can be used for issuance:

vault write ejbca/roles/example-dot-com \
    allow_any_name=true \
    allow_subdomains=true \
    max_ttl=8760h \
    key_type="rsa" \
    key_bits=2048 \
    signature_bits=256 \
    use_pss=false

The EJBCA PKI Secrets Engine also supports the following additional role fields:

• end_entity_profile_name - The name of the EJBCA End Entity Profile to use for certificate issuance.
• certificate_profile_name - The name of the EJBCA Certificate Profile to use for certificate issuance.
• account_binding_id - EJBCA Account Binding ID.

📌 Note: If left blank, the end_entity_profile_name and certificate_profile_name fields will default to the values configured in the config object.

Path Overview

Once the EJBCA PKI Secrets Engine is configured and roles are created, you can use the following paths to issue and sign certificates, list certificates, and revoke certificates.

Issue/Sign Paths

The following paths can be used to issue and sign certificates. The :role_name parameter is required for all paths except sign-verbatim. Paths that require the :issuer_ref parameter will use the provided name as the EJBCA CA name for certificate issuance.

📌 Note: The /issue paths generate the CSR and private key on the Vault server.

The following example issues a certificate using the example-dot-com role:

vault write ejbca/issue/example-dot-com \
    common_name="example.com" \
    alt_names="*.example.com" \
    format="pem_bundle" \
    account_binding_id="abc123"

📌 Note: For more information on any of the parameters used in the above example or in the table, use the vault path-help ejbca/<path> command.

Revoke Paths

The following path can be used to revoke certificates. Either the serial_number or certificate parameter is required.

📌 Note: The EJBCA PKI Secrets Engine cannot revoke certificates that were not issued by the EJBCA PKI Secrets Engine.

Fetch Paths

The following paths can be used to fetch CA certificates. The paths that specify a Content-Type cannot be consumed using the vault command, and must be consumed using the Vault HTTP API.

The following paths can be used to fetch certificates.

📌 Note: The fetch methods will never return a private key. Private keys are only returned with the issue methods.

Serial numbers of certificates and revoked certificates can be found using the following paths.