Resources

The certificate management REST API provides the following base resource URLs:

Each resource provides endpoints of interaction:

• Endpoints under the /ca_management/ resource allow manipulating CAs, for example activating and deactivating a CA. ENTERPRISE

• The /ca/ resource allows retrieving CA certificates, CRLs, and so on. ENTERPRISE

• The /certificate/ resource handles certificate enrollment, revocation and other workflows related to managing certificates.

• The /configdump/ resource handles import and export of configurations (publishers, certification authorities, roles etc) via the ConfigDump tool. ENTERPRISE

• The /cryptotoken/ resource handles crypto token activation, deactivation, and crypto token key generation. ENTERPRISE

• The /endentity/ resource handles end entity management. ENTERPRISE

For a full set of all endpoints, required input, responses, and other endpoint descriptions, see REST API Reference or try it out in the Swagger UI.

Generate a CSR and Request a Certificate using Bash

You can use OpenSSL, jq, and cURL ( version >7.57) to create a key and a CSR, create a JSON payload containing the CSR, and then enroll for a TLS server certificate using the configuration file and script below.

Revocation Workflow Example

Follow the example below to first check the revocation status of a certificate and then revoke the certificate.

In this example, the certificate's DN is CN=CA1 and serial number (in hex) is 5CB3D42686039768D973E5694BF205377AF6.

1. To check the revocation status of the certificate, call the GET /v1/certificate/{issuer_dn}/{certificate_serial_number}/revocationstatus REST method:

   curl -X GET -s \

   --cert-type P12 \

   --cert "/opt/jboss/p12/SuperAdmin.p12:foo123" \

   -H "accept: application/json"

   "https://localhost:8443/ejbca/ejbca-rest-api/v1/certificate/CN%3DCA1/5CB3D42686039768D973E5694BF205377AF6/revocationstatus"

2. From the response below, you can confirm that the certificate is active.

   {

   "issuer_dn": "CN=CA1",

   "serial_number": "5CB3D42686039768D973E5694BF205377AF6",

   "revocation_reason": "NOT_REVOKED",

   "revoked": false

   }

3. To revoke the certificate, call the PUT /v1/certificate/{issuer_dn}/{certificate_serial_number}/revoke REST method:

   curl -X PUT -s \

   --cert-type P12 \

   --cert "/opt/jboss/p12/SuperAdmin.p12:foo123" \

   -H "accept: application/json"

   "https://localhost:8443/ejbca/ejbca-rest-api/v1/certificate/CN%3DCA1/5CB3D42686039768D973E5694BF205377AF6/revoke?reason=KEY_COMPROMISE"

4. Confirm from the response that the certificate has been successfully revoked:

   {

   "issuer_dn": "CN=HT_REMOVAL_CA",

   "serial_number": "5CB3D42686039768D973E5694BF205377AF6",

   "revocation_reason": "KEY_COMPROMISE",

   "revocation_date": "2019-05-27T15:02:56Z",

   "message": "Successfully revoked",

   "revoked": true

   }

Request a PKCS#12 Keystore Using Python

To request a PKCS#12 keystore using Python, do the following:

1. Install the module requests_pkcs12 using pip.

   pip3 install requests_pkcs12

2. Authenticate with the client certificate stored in superadmin.p12 and request a PKCS12 file for the end entity python.

   import json

   from requests_pkcs12 import post

   response = post('https://myca:8443/ejbca/ejbca-rest-api/v1/certificate/enrollkeystore',

   json={

   'username': 'python',

   'password': 'foo123',

   'key_alg': 'RSA',

   'key_spec': '2048'

   },

   headers={

   'content-type': 'application/json'

   },

   pkcs12_filename='/srv/superadmin.p12',

   pkcs12_password='foo123',

   verify='/srv/truststore.pem')

    

   print(json.dumps(json.loads(response.content), indent=4, sort_keys=True))

Request a PKCS#12 Keystore Using Node.js

To request a PKCS#12 keystore using Node.js, do the following:

1. Install the node.js module called node-fetch.

   npm install node-fetch

2. Create a script which looks something like this:

   const fs = require('fs');

   const https = require('https');

   const fetch = require('node-fetch');

    

   // Load the keystore used to authenticate to the REST API

   const pfx = fs.readFileSync('RA_Administrator.p12');

   const passphrase = 'foo123';

   const agent = https.Agent({ pfx, passphrase });

    

   // Load the enrollment code for the end entity

   const enrollmentCode = 'foo123'

    

   // Name of the end entity

   const deviceName = 'Company Device 1'

    

   // Request renewal of the device certificate

   fetch('https://nautilus:8443/ejbca/ejbca-rest-api/v1/endentity/' + deviceName + '/setstatus', {

   agent: agent,

   method: 'post',

   body: JSON.stringify({

   "password": enrollmentCode,

   "token": "P12",

   "status": "NEW"

   }),

   headers: { 'Content-Type': 'application/json' },

   })

   .then(res => {

   if (res.status != 200) {

   console.log('Renewal failed with status code ' + res.status + '.')

   } else {

   console.log('Renewal succeeded! Requesting new device certificate from EJBCA...')

   fetch('https://nautilus:8443/ejbca/ejbca-rest-api/v1/certificate/enrollkeystore', {

   agent: agent,

   method: 'post',

   body: JSON.stringify({

   "username": deviceName,

   "password": enrollmentCode,

   "key_alg": "RSA",

   "key_spec": "2048"

   }),

   headers: { 'Content-Type': 'application/json' },

   })

   .then(res => res.json())

   .then(json => console.log(json))

   .catch(error => console.log(error))

   }

   })

   .catch(error => console.log(error))

Search for Certificates

To search for certificates with multiple search criteria, use the search method.

Search for Certificates Version 2

To search for certificates with multiple search criteria, pagination and sorting use the search method version 2.

Search for End Entities

End entities can be searched using v1 API. Supported search criterias are:

• QUERY

• END_ENTITY_PROFILE

• CERTIFICATE_PROFILE

• CA, STATUS

• MODIFIED_BEFORE

• MODIFIED_AFTER

Note that, QUERY allows search with end entity name, subject distinguished name and subject alternate name.

Search for End Entities Version 2

The v2 search API additionally supports sort operation. Sorting is allowed by:

• USERNAME

• SUBJECT_DN

• SUBJECT_ALT_NAME

• END_ENTITY_PROFILE

• CERTIFICATE_PROFILE

• STATUS

• UPDATE_TIME

• CREATED_TIME

and the results can be sorted ascending(ASC) or descending(DESC) manner. Note that in v2 search the current_page parameter must start at 1 and if more results are needed the page number should be increased sequentially in future queries. Skipping pages or jumping to arbitrary pages when searching using this end point is not supported.

Add End Entity

ENTERPRISE This is an EJBCA Enterprise feature.

To add an end entity using the endentity endpoint, a JSON like this can be used:

and cURL:

After adding an end entity like that, you can enroll for a PKCS#12 keystore with the certificate/enrollkeystore endpoint:

and cURL:

Exporting Configuration with ConfigDump

ENTERPRISE This is an EJBCA Enterprise feature.

Export and import of configurations support parameters like ignoreerrors, include, exclude, and so on. For more information about available parameters, see Swagger UI, the generated REST API Reference, or ConfigDump Tool.

The configuration can be exported in different ways: the whole configuration, by type, by type and setting, or as a ZIP file containing YAML formatted ConfigDump export.

Importing Configuration with ConfigDump

ENTERPRISE This is an EJBCA Enterprise feature.

JSON data for the body part of an import POST request follows the convention: attribute values are exactly the same as when importing and/or exporting through the ConfigDump CLI with YAML files.

An example JSON body for importing a single approval profile:

And the expected cURL command for the above JSON body:

Certificate Request Encoding

An exception like the following may be caused by an encoding issue:

IOException while decoding certificate request from PEM: -----END CERTIFICATE REQUEST

The issue can be resolved by manually replacing the linebreaks with \n.

Finding the Cause of Error Codes Returned to the Client

When you get an error message back, such as an HTTP 404 (BAD_REQUEST) the cause of the error can often be found in a message returned as part of the HTTP error. The full cause of the error is also typically visible in the server log file for administrators to see.

Converting DER format responses into PEM

Binary DER files have usually .cer, .crt or .der extensions, while PEM is strictly specified with PEM headers -----BEGIN / END CERTIFICATE----- and line breaks every 64 characters. More details in RFC7468.

Some REST calls return a DER certificate encoded in base64 within the JSON response body, in order to transfer the binary data in a JSON structure. It is identified with “response_format": "DER” in the JSON itself, and can be converted to PEM where required.

For instance, after a successful call to /v1/certificate/pkcs10enroll, the JSON output will contain a certificate object in base64, which can be extracted:

The base64 data can be decoded into the binary DER format:

You can convert it to PEM, for example with openssl:

and openssl can also be used to back and forth between PEM and DER: