Back to top

EJBCA REST API

Endpoints to perform user and certificate management

EJBCA system administration

EJBCA version

get EJBCA version
GET/ejbca/version

Get EJBCA version

Example URI

GET /ejbca/version
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "version": "EJBCA 6.3.1.1 Community (r21429)"
}

EJBCA CA management

Certification authorities management

List all avaliable CAs
GET/ca

Example URI

GET /ca
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "CAs": [
    {
      "id": 576968287,
      "name": "IOTmidCA"
    },
    {
      "id": -1371917878,
      "name": "PROTOCOL"
    }
  ]
}

Get CA certificate

Give the PEM certificate chain of the given CA
GET/ca/

The returned certificate is a base64 string with newline characters (so that it can match PEM format).

To save the chain in a .CRT file, add the first and last line as shown below:

-----BEGIN CERTIFICATE-----
[Certificate]
-----END CERTIFICATE-----

Be careful to properly copy the first and final line: the number of dashes (-) must be exactly as shown above.

To view the contents of this certificate, execute the following command:

openssl x509 -in ./Certificate.crt.pem -text -noout

Example URI

GET /ca/
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "message": "soap message: CA with name abcde does not exist."
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "certificate": "*base64cert chain with linebreaks"
}

Certificate status

Check if a certificate is revoked
GET/ca/{cacn}/certificate/{certserial}/status

If the certificate serial number does not exist EJBCA will return ‘not revoked’. This endpoint is not working well.

Example URI

GET /ca/IOTmidCA/certificate/5017406860984553086/status
URI Parameters
HideShow
cacn
string (required) Example: IOTmidCA
certserial
string (required) Example: 5017406860984553086
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "message": "soap message: Could not find CA with name null and ID 1992101327"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "date": "2017-08-21T17:26:03.322000+00:00",
    "reason": "CERTIFICATEHOLD"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "date": "1969-12-31T23:59:59.999000+00:00",
    "reason": "NOTREVOKED"
  }
}

Certificate

Get the base64 pem certificate
GET/ca/certificate/

Example URI

GET /ca/certificate/
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "message": "soap message: Could not find CA with name null and ID 1992101327"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "certificate": {
    "certificate": null,
    "keyStore": null,
    "type": 0,
    "certificateData": "MIICozCCAYugAwIBAgIIDbsv7z5yer..."
  }
}

Revoke a certificate
DELETE/ca/certificate/?{reason}

Removes a user certificate

Example URI

DELETE /ca/certificate/?UNSPECIFIED
URI Parameters
HideShow
reason
enum (optional) Example: UNSPECIFIED

one of REVOKATION_REASON enum values. default: UNSPECIFIED

Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "message": "soap message: Could not find end entity certificate. Issuer CN=PROTOCOL, serialNo 4690394092950658023."
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "message": "soap message: Certificate is already revoked. Issuer: 'CN=PROTOCOL', serno: 5084496247959973."
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 200,
  "message": "ok"
}

CRL

Create or update current CRL
PUT/ca/crl

Example URI

PUT /ca/crl
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "message": "soap message: CA with name caname does not exist."
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 200,
  "message": "ok"
}

get a CRL
GET/ca/crl?{delta}

Use the command

… code-block:: bash openssl asn1parse -inform DER -in crl.der - dump

to visualize the CRL

Example URI

GET /ca/crl?false
URI Parameters
HideShow
delta
boolean (optional) Example: false

if a elta CRL should be used. default: false

Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "message": "soap message: CA with name caname does not exist."
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "CRL": "MIICQjCCASoCAQEwDQYJKoZIhvcNAQEFBQAwEzERMA8GA1UEAwwIUF..."
}

EJBCA user management

Create or edit user

Create or edit a user
POST/user

Example URI

POST /user
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "caName": "PROTOCOL",
  "certificateProfileName": "ENDUSER",
  "clearPwd": true,
  "email": "device21@noemail.com",
  "endEntityProfileName": "EMPTY",
  "extendedInformation": {
    "name": "somekey",
    "value": "somevalue"
  },
  "keyRecoverable": true,
  "password": "pwd12",
  "sendNotification": false,
  "status": 10,
  "subjectDN": "CN=device21",
  "tokenType": "USERGENERATED",
  "username": "device21"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 200,
  "message": "ok"
}

User CRUD

get user data
GET/user/

notice that the repsonse is a list

Example URI

GET /user/
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "user": [
    {
      "caName": "PROTOCOL",
      "cardNumber": null,
      "certificateProfileName": "ENDUSER",
      "certificateSerialNumber": null,
      "clearPwd": false,
      "email": "device21@noemail.com",
      "endEntityProfileName": "EMPTY",
      "endTime": null,
      "extendedInformation": [
        {
          "name": "subjectdirattributes",
          "value": null
        },
        {
          "name": "somekey",
          "value": "somevalue"
        }
      ],
      "hardTokenIssuerName": null,
      "keyRecoverable": false,
      "password": null,
      "sendNotification": false,
      "startTime": null,
      "status": 40,
      "subjectAltName": null,
      "subjectDN": "CN=device21",
      "tokenType": "USERGENERATED",
      "username": "device21"
    }
  ]
}

Revoke all cerificates from a user
DELETE/user/?{reason,delete}

Example URI

DELETE /user/?UNSPECIFIED&false
URI Parameters
HideShow
reason
enum (optional) Example: UNSPECIFIED

one of REVOKATION_REASON enum values. default: UNSPECIFIED

delete
boolean (optional) Example: false

True if the user should be deleted after the revocation. Default False

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 200,
  "message": "ok"
}

List user valid certificates

List user certs
GET/user/find?{valid}

Example URI

GET /user/find?true
URI Parameters
HideShow
valid
boolean (optional) Example: true

False if revoked certificates should be listed. Default True

Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "no certificates found"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "certs": [
    {
      "certificate": null,
      "keyStore": null,
      "type": 0,
      "certificateData": "MIICozCCAYugAwIBAgIIDbsv7z5yerMwDQ..."
    }
  ]
}

Sign a certificate for a user

Return the signed certificate
POST/user/pkcs10

Example URI

POST /user/pkcs10
Request
HideShow

In a csv file, generated with the command ‘openssl req -new -out server.csr -key server.key’ The base64 certificate csv is between the tags ‘-----BEGIN CERTIFICATE REQUEST-----’ and ‘-----END CERTIFICATE REQUEST-----’

Headers
Content-Type: application/json
Body
{
  "passwd": "pwd12",
  "certificate": "MIIBmzCCAQQCAQAwWzELMAkGA1UEBhMCQlIxEzARBgNVMC..."
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "message": "soap message: Got request with status GENERATED (40), NEW, FAILED or INPROCESS required: username."
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
Add a '-----BEGIN PKCS7-----' and '-----END PKCS7-----' before save the given certificate to a file.  

{
  "status": {
      "data": "MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGg...",
      "responseType": "PKCS7"
  }
}

Generated by aglio on 06 Feb 2019