EJBCA Certificate Operations Using REST API

EJBCA provides a REST API that allows you to enroll, renew, revoke, and manage certificates. To access the API, authenticate with a client certificate that has the required EJBCA administrator role permissions (for example, the Super Administrator certificate) over mTLS.

This section shows how to use the EJBCA REST API and curl to enroll, renew, revoke, and check the status of certificates.

Prerequisites

Before you begin, complete the following prerequisites:

  • Enable the REST protocol in EJBCA. In the EJBCA Admin GUI, navigate to System Configuration > Protocol Configuration > REST Certificate Management, and then select Enabled.

  • Export the Super Administrator certificate and private key from the cluster to your local machine. For instructions, see Export Superadmin Credentials.

  • Obtain the system-local-ca.pem certificate and use it as the TLS CA trust anchor.

  • Set the required environment variables for the EJBCA hostname, REST base URL, and credentials. For details, see Setup the Environment Variables.

Note

The REST API endpoint /v1/endentity for creating end entities is not available in EJBCA Community Edition. Use the CLI to create end entities before enrolling certificates using the REST API.

Export Superadmin Credentials

Export the superadmin certificate and key from the cluster to your local machine:

~(keystone_admin)]$ kubectl get secret -n ejbca ejbca-superadmin-cert \
    -o jsonpath='{.data.tls\.crt}' | base64 -d > superadmin.crt.pem
~(keystone_admin)]$ kubectl get secret -n ejbca ejbca-superadmin-cert \
    -o jsonpath='{.data.tls\.key}' | base64 -d > superadmin.key.pem

Setup the Environment Variables

Define the environment variables that the examples in this topic use to connect to EJBCA and authenticate REST API requests:

$ export EJBCA_HOSTNAME="ejbca.example.com:7443"
$ export REST_BASE="https://${EJBCA_HOSTNAME}/ejbca/ejbca-rest-api"
$ export SUPERADMIN_CERT="./superadmin.crt.pem"
$ export SUPERADMIN_KEY="./superadmin.key.pem"
$ export CA_NAME="test-ca"
$ export CERT_PROFILE="test-cert-profile"
$ export EE_PROFILE="test-entity-profile"

Enroll a Certificate

Create the end entity using the CLI, then enroll the certificate using the REST API:

# Step 1: Create the end entity (CLI — required for CE)
$ export ENTITY="test-ca-cert01"
$ export ENTITY_PWD="changeit"

~(keystone_admin)]$ kubectl exec ejbca-0 -c ejbca -n ejbca -- /opt/keyfactor/bin/ejbca.sh ra addendentity \
    --username ${ENTITY} \
    --password ${ENTITY_PWD} \
    --dn "CN=${ENTITY}" \
    --caname ${CA_NAME} \
    --type 1 \
    # --token USERGENERATED: user-generated key pair
    --token USERGENERATED \
    --certprofile ${CERT_PROFILE} \
    --eeprofile ${EE_PROFILE}

# Step 2: Generate key and CSR
$ export KEY_FILE="${ENTITY}.key.pem"
$ export CSR_FILE_DER="${ENTITY}.csr.der"
$ export CERT_FILE="${ENTITY}.cert.pem"

$ openssl genrsa -out ${KEY_FILE} 4096
$ openssl req -new -key ${KEY_FILE} \
    -subj "/CN=${ENTITY}" \
    -addext "subjectAltName=DNS:${ENTITY}" \
    -outform |DER| -out ${CSR_FILE_DER}

# Step 3: Enroll via REST API (pkcs10enroll accepts a |P10| —
# the standard format for certificate signing requests)
$ CSR_B64=$(base64 -w0 ${CSR_FILE_DER})

$ curl \
    --cacert ./system-local-ca.pem \
    --cert ${SUPERADMIN_CERT} --key ${SUPERADMIN_KEY} \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X POST "${REST_BASE}/v1/certificate/pkcs10enroll" \
    -d "{
      \"certificate_request\": \"${CSR_B64}\",
      \"certificate_profile_name\": \"${CERT_PROFILE}\",
      \"end_entity_profile_name\": \"${EE_PROFILE}\",
      \"certificate_authority_name\": \"${CA_NAME}\",
      \"username\": \"${ENTITY}\",
      \"password\": \"${ENTITY_PWD}\",
      \"include_chain\": true
    }" | python3 -m json.tool

The response returns the certificate in base64-encoded DER format. Decode and display it using:

# Extract the certificate field from the JSON response, decode, and display
$ echo "<base64-certificate-from-response>" | base64 -d | \
    openssl x509 -inform |DER| -text -noout

Note

Include the end_entity_profile_name field in every request. If you omit it, EJBCA returns a 500 Internal Server Error with a NullPointerException.

Renew a Certificate

To renew a certificate, generate a new key pair and CSR, and then re-enroll through the pkcs10enroll endpoint (the EJBCA REST endpoint for PKCS#10 Certificate Signing Request enrollment). The REST API manages the end entity status automatically, so you do not need to reset it to NEW.

# Generate new key and CSR
$ openssl genrsa -out ${ENTITY}-renewed.key.pem 4096
$ openssl req -new -key ${ENTITY}-renewed.key.pem \
    -subj "/CN=${ENTITY}" \
    -addext "subjectAltName=DNS:${ENTITY}" \
    -outform |DER| -out ${ENTITY}-renewed.csr.der

# Re-enroll via REST API
$ CSR_B64=$(base64 -w0 ${ENTITY}-renewed.csr.der)

$ curl \
    --cacert ./system-local-ca.pem \
    --cert ${SUPERADMIN_CERT} --key ${SUPERADMIN_KEY} \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X POST "${REST_BASE}/v1/certificate/pkcs10enroll" \
    -d "{
      \"certificate_request\": \"${CSR_B64}\",
      \"certificate_profile_name\": \"${CERT_PROFILE}\",
      \"end_entity_profile_name\": \"${EE_PROFILE}\",
      \"certificate_authority_name\": \"${CA_NAME}\",
      \"username\": \"${ENTITY}\",
      \"password\": \"${ENTITY_PWD}\",
      \"include_chain\": true
    }" | python3 -m json.tool

Revoke a Certificate

To revoke a certificate, extract the serial number and issuer DN from the certificate file, then submit a REST API revocation request.

# Get certificate serial number and issuer DN
$ SERIAL=$(openssl x509 -in ${CERT_FILE} -noout -serial | cut -d= -f2)
$ ISSUER_DN=$(openssl x509 -in ${CERT_FILE} -noout -issuer | sed 's/issuer=//')
# URL-encode the issuer DN for use in the REST path
$ ISSUER_ENC=$(python3 -c "from urllib.parse import quote; print(quote('${ISSUER_DN}', safe=''))")

$ curl \
    --cacert ./system-local-ca.pem \
    --cert ${SUPERADMIN_CERT} --key ${SUPERADMIN_KEY} \
    -H "Accept: application/json" \
    -X PUT \
    "${REST_BASE}/v1/certificate/${ISSUER_ENC}/${SERIAL}/revoke?reason=UNSPECIFIED" \
    | python3 -m json.tool

The supported revocation reasons are:

  • UNSPECIFIED

  • KEY_COMPROMISE

  • CA_COMPROMISE

  • AFFILIATION_CHANGED

  • SUPERSEDED

  • CESSATION_OF_OPERATION

  • CERTIFICATE_HOLD

  • PRIVILEGES_WITHDRAWN

Check Certificate Status

To verify the status of an issued or revoked certificate, query the EJBCA REST API revocation status endpoint:

$ curl \
    --cacert ./system-local-ca.pem \
    --cert ${SUPERADMIN_CERT} --key ${SUPERADMIN_KEY} \
    -H "Accept: application/json" \
    "${REST_BASE}/v1/certificate/${ISSUER_ENC}/${SERIAL}/revocationstatus" \
    | python3 -m json.tool

Note

For the complete REST API reference, see: https://docs.keyfactor.com/ejbca/latest/protocols/ejbca-rest-interface

Related Information