| Open API Documentation |
|---|
openapi: 3.0.0
info:
title: CM REST API
version: "1.0"
description: |
The CM REST API is a HTTP-based service used for interacting with CM.
It supports ways of performing certificate creation, searching, revocation,
reinstatement, registrations and procedure listing through HTTP REST calls.
## HTTP Client Authentication
The CM REST API requires TLS client authentication using a CM officer
certificate, to identify the caller. The client TLS certificate must be
an officer certificate, and must be issued by one of the CAs that are
present in the PGWY Tomcat trust store. The officer must have all of the
roles configured by the `requiredRoRoles` setting in `api.properties`.
## Signed requests
Furthermore, operations that are sent to the CA that write or modify data,
such as revoking, reinstating and issuing certificates requires the request
data to be signed by a CM officer when sending the command to the CA.
This signing can be done either by PGWY itself (VRO), or by PGWY requesting
a signature from the caller. Signing by caller is the default.
### VRO signing
To make PGWY sign such requests, PGWY must be configured to act as a Virtual
Registration Officer (VRO) and thereby sign the requests on the caller's
behalf. This is done by enabling server-side signing in the server
configuration (`api.properties`).
1. Example request with VRO signing:
```
POST /certificates/pkcs10
pkcs10=(binary data)
```
2. Server response:
```
(pkcs#7 data containing DER-encoded certificate)
```
### Signing by caller
If PGWY is not configured to act as VRO, then all operations that require a
signature will return the request data to the caller for signing using the
CM officer's key. The request to sign is returned as the `dataToSign`
json field, base64-encoded. The caller is then expected to sign the request
and re-send the request with the signature in a field named `signature`.
1. Example request with signature by caller:
```
POST /certificates/pkcs10
pkcs10=(binary data)
```
2. Server response:
```
Http Status: 200 (OK)
{
"error":-19,
"msg":"Sign request and send again",
"dataToSign":"MIIC8...Rva2Vu"
}
```
3. Caller signs request and sends again:
```
POST /certificates/pkcs10
pkcs10=(binary data)
signature=(base64 encoded signature)
```
4. Server response:
```
(pkcs#7 data containing DER-encoded certificate)
```
### Implementation details and example code for caller signature
Alongside this document are two examples on how to perform the CMS (PKCS#7)
based signature of the 'dataToSign' blob. The signature requires that the
original data (the 'dataToSign' blob) is encapsulated and that it is in
DER-encoded format.
1. OpenSSL:
```
See accompanied file 'APISigningWithOpenSSL.sh'
```
2. BouncyCastle:
```
See accompanied file 'APISigningWithBouncyCastle.java'
```
servers:
- url: https://{hostname}:{port}/{basePath}
description: PGWY
variables:
hostname:
default: localhost
port:
enum:
- '8444'
- '8443'
- '443'
default: '8444'
basePath:
default: pgwy/api
paths:
/certificates:
get:
operationId: listCertificates
summary: List certificates
description: |
Returns a list of certificates that match the provided search parameters.
tags:
- Certificates
parameters:
- $ref: '#/components/parameters/searchLimit'
- $ref: '#/components/parameters/searchOffset'
- name: cardSerialNumber
in: query
description: Serial number of the card the certificate is on.
schema:
type: string
- $ref: '#/components/parameters/certificateSerialNumber'
- $ref: '#/components/parameters/revocationTimeFrom'
- $ref: '#/components/parameters/revocationTimeTo'
- $ref: '#/components/parameters/revocationReason'
- $ref: '#/components/parameters/isNotRevoked'
- name: subjectCommonName
in: query
description: The common name ( CN ) of the subject of the certificate.
schema:
type: string
- name: subjectGivenName
in: query
description: The given name ( GN ) of the subject of the certificate.
schema:
type: string
- name: subjectSurName
in: query
description: The surname ( SN ) of the subject of the certificate.
schema:
type: string
- name: subjectOrganisationName
in: query
description: The name of the organisation ( O ) of the subject of the certificate.
schema:
type: string
- name: subjectOrganisationUnit
in: query
description: The name of the organisational unit ( OU ) of the subject of the certificate.
schema:
type: string
- name: subjectSerialNumber
in: query
description: The serial number of the subject of the certificate.
schema:
type: string
- name: subjectCountry
in: query
description: The country ( C ) of the subject of the certificate.
schema:
type: string
- $ref: '#/components/parameters/publicationAllowed'
- $ref: '#/components/parameters/publicationTimeFrom'
- $ref: '#/components/parameters/publicationTimeTo'
- $ref: '#/components/parameters/ocspActivationTimeFrom'
- $ref: '#/components/parameters/ocspActivationTimeTo'
- $ref: '#/components/parameters/validFromTimeFrom'
- $ref: '#/components/parameters/validFromTimeTo'
- $ref: '#/components/parameters/isNotYetValid'
- $ref: '#/components/parameters/validToTimeFrom'
- $ref: '#/components/parameters/validToTimeTo'
- $ref: '#/components/parameters/isExpired'
- $ref: '#/components/parameters/field1'
- $ref: '#/components/parameters/field2'
- $ref: '#/components/parameters/field3'
- $ref: '#/components/parameters/field4'
- $ref: '#/components/parameters/field5'
- $ref: '#/components/parameters/field6'
- $ref: '#/components/parameters/authorityKeyIdentifier'
- $ref: '#/components/parameters/subjectKeyIdentifier'
- $ref: '#/components/parameters/subjectType'
- name: issuer
in: query
description: |
Only return certificates whose issuer matches the provided DN.
The value must be a URL encoded RFC1779 string.
Example: issuer=cn%3DExample%20CM%20issuing%20CA%2Co%3DExample%20CM%2Cc%3DSE
schema:
type: string
format: RFC1779 distinguished name string.
responses:
200:
description: OK - Returns an array of certificates.
content:
application/json:
schema:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
searchHits:
description: |
The total number of search hits that the given search
parameters would yield without pagination.
type: integer
certificates:
description: Array of certificates
type: array
items:
$ref: "#/components/schemas/JsonCertificate"
example:
error: 0
msg: "Fetched certificates"
searchHits: 476
certificates: [
{
subject: "Super Officer 1, System, SE",
validfrom: 1475849262000,
certid: "10003",
certificateserialnumber: "31e96265e40b809cffa3862b073ae98b",
subjectType: EE,
validto: 1633615659000,
status: "active"
}
]
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
example:
error: -14
msg: Too many hits
/certificates/issuers:
get:
deprecated: true
operationId: listIssuers
summary: List available issuers
description: |
Returns a list of distinguished names of issuer CAs that match the provided search parameters.
tags:
- Certificates
parameters:
- $ref: '#/components/parameters/searchLimit'
- $ref: '#/components/parameters/searchOffset'
- $ref: '#/components/parameters/certificateSerialNumber'
- $ref: '#/components/parameters/revocationTimeFrom'
- $ref: '#/components/parameters/revocationTimeTo'
- $ref: '#/components/parameters/revocationReason'
- $ref: '#/components/parameters/publicationAllowed'
- $ref: '#/components/parameters/publicationTimeFrom'
- $ref: '#/components/parameters/publicationTimeTo'
- $ref: '#/components/parameters/ocspActivationTimeFrom'
- $ref: '#/components/parameters/ocspActivationTimeTo'
- $ref: '#/components/parameters/validFromTimeFrom'
- $ref: '#/components/parameters/validFromTimeTo'
- $ref: '#/components/parameters/isNotYetValid'
- $ref: '#/components/parameters/validToTimeFrom'
- $ref: '#/components/parameters/validToTimeTo'
- $ref: '#/components/parameters/isExpired'
responses:
200:
description: OK - Returns an array of issuer subjects.
content:
application/json:
schema:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
searchHits:
description: |
The total number of search hits that the given search
parameters would yield without pagination.
type: integer
subjects:
description: Array of certificate issuer DNs.
type: array
items:
$ref: "#/components/schemas/JsonIssuer"
example:
error: 0
msg: "Fetched issuers"
searchHits: 476
issuers: [
{
subjectDn: "cn=Example CM CA,o=Example CM,c=SE",
subject: {
cn: "Example CM CA",
o: "Example CM",
c: "SE"
}
}
]
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
example:
error: -14
msg: Too many hits
/certificates/{certid}/details:
get:
operationId: getCertificateDetails
summary: Certificate details
description: |
Returns information about the certificate with the provided id.
tags:
- Certificates
parameters:
- name: certid
in: path
description: Certificate id
required: true
schema:
type: string
responses:
200:
description: OK - Returns details about the requested certificate.
content:
application/json:
schema:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
certificate:
$ref: "#/components/schemas/JsonCertificate"
example:
error: 0
msg: "Fetched certificate"
certificate:
subject: "Super Officer 2, System, SE"
validfrom: 1475849262000
certid: "10003"
certificateserialnumber: "31e96265e40b809cffa3862b073ae98b"
subjectType: EE
validto: 1633615659000
status: "active"
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
example:
error: -14
msg: "No certificate found"
/certificates/{certid}/download:
get:
operationId: downloadCertificate
summary: Download certificate
description: |
Returns a certificate in binary form. For X.509 certificates, the
returned certificate encoding may be DER, PEM or MIME (pkcs#7),
depending on the media type in the provided Accept header.
tags:
- Certificates
parameters:
- name: certid
in: path
description: Certificate ID.
required: true
schema:
type: string
responses:
200:
description: OK - Returns the requested certificate.
content:
application/pkix-cert:
schema:
type: string
format: binary
application/pkcs7-mime:
schema:
type: string
format: binary
application/pem-certificate-chain:
schema:
description: Returns full chain including <br> certificate specified by certid.
type: string
format: binary
application/pem-certificate-chain;depth=<value>:
schema:
description: ;depth=0<br>Returns full chain including <br> certificate specified by certid. <br><br> ;depth=1<br>Returns certificate specified by certid. <br><br> ;depth=value bigger than 1<br>Returns part of the chain <br> up to the given depth value, if the depth value is <br> bigger than the number of certificates in the chain <br> it returns the full chain.
type: string
format: binary
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
example:
error: -14
msg: "No certificate found"
/certificates/revoke:
post:
operationId: revokeCertificate
summary: Revoke certificate
description: Revokes the certificate(s) with the matching certificate id(s).
tags:
- Certificates
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
certid:
description: Certificate id(s) to revoke.
type: array
items:
type: string
reason:
$ref: "#/components/schemas/ApiRequest_RevocationReason"
signature:
$ref: "#/components/schemas/ApiRequest_Signature"
required:
- certid
- reason
responses:
200:
description: OK - Requested certificates were revoked.
content:
application/json:
schema:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
example:
error: 0
msg: "1 certificate(s) has been revoked"
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponseWithCertIds"
example:
error: -1
msg: "Error(s) occurred during the revocation"
errors: [
{
certid: "1",
errorcode: 907,
errormessage: "The certificate was not found",
servererrormessage: "Certificate with certSerNr: 1 is not found."
}
]
/certificates/reinstate:
post:
operationId: reinstateCertificate
summary: Reinstate certificate
description: Reinstates the certificate(s) with the matching certificate id(s).
tags:
- Certificates
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
certid:
description: Certificate id(s) to reinstate
type: array
items:
type: string
signature:
$ref: "#/components/schemas/ApiRequest_Signature"
required:
- certid
responses:
200:
description: OK - Requested certificates were reinstated.
content:
application/json:
schema:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
example:
error: 0
msg: "1 certificate(s) has been reinstated"
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponseWithCertIds"
example:
error: -1
msg: "Error(s) occurred during the reinstatement"
errors: [
{
certid: "1",
errorcode: 907,
errormessage: "The certificate was not found",
servererrormessage: "Certificate with certSerNr: 1 is not found."
}
]
/certificates/pkcs10:
post:
operationId: issueCertificatePkcs10
summary: Create certificate from PKCS10 request
description: |
Creates a certificate from a PKCS10 request and returns the result as either
PKCS7 or X.509 DER or PEM encoded depending on the Accept HTTP header.
The PKCS#7 and PEM results will contain the chain if the token procedure
had store all. Otherwise, will return only the end certificate.
tags:
- Certificates
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
pkcs10:
description: PKCS10 request (Base64 encoded)
type: string
format: byte
validfrom:
description: |
X.509 "not before" point in time. Format 'ISO 8601'.
Example: 2007-03-01T13:00:00Z
type: string
format: date-time
validto:
description: |
X.509 "not after" point in time. Format 'ISO 8601'.
Example: 2008-05-11T15:30:00Z
type: string
format: date-time
procname:
description: |
Name of token procedure that should be used to issue the
certificate. If this parameter is not given, a default value
set in the server side configuration will be used
(`handler.(n).tokenprocedure` in `api.properties`).
type: string
signature:
$ref: "#/components/schemas/ApiRequest_Signature"
required:
- pkcs10
encoding:
pkcs10:
contentType: application/pkcs10
responses:
200:
description: OK - Returns a PKCS7 message or X509 the issued certificate.
content:
application/pkcs7-mime:
schema:
type: string
format: binary
application/pkix-cert:
schema:
type: string
format: binary
application/pem-certificate-chain:
schema:
type: string
format: binary
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
/certificates/pkcs10-to-pkcs12:
post:
operationId: issueCertificatePkcs10ToPkcs12
summary: Issue certificate to PKCS#12 from PKCS#10 request
description: |
Issues a certificate from a PKCS#10 request and returns the result as
PKCS#12.
This endpoint is used to issue certificates for keys that are generated
server-side by CM. For these cases, this endpoint is by default
configured to accept unsigned PKCS#10 requests that only contain the TBS
parts, and by default configured to discard the public key part
specified in the PKCS#10 request. To generate the key on the
server-side, the token procedure should specify an applicable key
procedure.
tags:
- Certificates
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
pkcs10:
description: PKCS10 request (Base64 encoded).
type: string
format: byte
validfrom:
description: |
X.509 "not before" point in time. Format 'ISO 8601'.
Example: 2007-03-01T13:00:00Z
type: string
format: date-time
validto:
description: |
X.509 "not after" point in time. Format 'ISO 8601'.
Example: 2008-05-11T15:30:00Z
type: string
format: date-time
password:
description: |
Password to be used to protect the resulting PKCS12 archive.
If this parameter is not given, the password will be
generated by the server.
type: string
format: password
procname:
description: |
Name of token procedure that should be used to issue the
certificate. If this parameter is not given, a default value
set in the server side configuration will be used
(`handler.(n).tokenprocedure` in `api.properties`).
type: string
signature:
$ref: "#/components/schemas/ApiRequest_Signature"
required:
- pkcs10
encoding:
pkcs10:
contentType: application/pkcs10
responses:
200:
description: OK - Returns a PKCS12 archive with the issued certificate and key.
content:
application/x-pkcs12:
schema:
type: string
format: binary
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
/certificates/{certid}/pkcs10-to-attr-cert:
post:
operationId: issueCertificatePkcs10ToAttrCert
summary: Issue certificate to PKCS#7 or X.509 containing attribute certificate
from PKCS#10 request
description: |
Issues an attribute certificate from a PKCS#10 request and returns the result as
PKCS#7 or X.509 DER or PEM encoded depending on the Accept HTTP header.
The PKCS#7 and PEM results will contain the chain if the token procedure
had store all. Otherwise, will return only the end certificate.
This endpoint is used to issue attribute certificates that are generated for
a base certificate on server-side by CM. For these cases, this endpoint is by default
configured to accept unsigned PKCS#10 requests that only contain the TBS
parts. A public key is required by PKCS#10, while it is not required for issuing the
attribute certificate. Therefore, by default the endpoint is configured to discard
the public key part specified in the PKCS#10 request as it is not required.
tags:
- Certificates
parameters:
- $ref: '#/components/parameters/certid'
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
pkcs10:
description: PKCS10 request (Base64 encoded).
type: string
format: byte
validfrom:
description: |
X.509 "not before" point in time. Format 'ISO 8601'.
Example: 2007-03-01T13:00:00Z
type: string
format: date-time
validto:
description: |
X.509 "not after" point in time. Format 'ISO 8601'.
Example: 2008-05-11T15:30:00Z
type: string
format: date-time
procname:
description: |
Name of token procedure that should be used to issue the
attribute certificate. If this parameter is not given, a default
value set in the server side configuration will be used
(`handler.(n).tokenprocedure` in `api.properties`).
type: string
signature:
$ref: "#/components/schemas/ApiRequest_Signature"
required:
- pkcs10
encoding:
pkcs10:
contentType: application/pkcs10
responses:
200:
description: OK - Returns a PKCS7 archive with the issued attribute certificate.
content:
application/pkcs7-mime:
schema:
type: string
format: binary
application/pkix-cert:
schema:
type: string
format: binary
application/pem-certificate-chain:
schema:
type: string
format: binary
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
/certificates/skip:
post:
operationId: secureKeyInjectionPackage
summary: Create a secure key injection package from a PKCS10 request
description: |
Creates a secure key package for IoT devices from a PKCS10 request
and return the result as PKCS7.
The PKCS10 request only need to include the public key and subject
information and no other request data.
The PKCS7 response content is an ASN.1 encoded list of the generated
device keypairs, KeyPairContainers, where the public key is an encoded
SubjectPublicKeyInfo (RFC 5280), and the private key is an encoded
EncryptedPrivateKeyInfo (RFC 5958).
KeyPairContainers ::= SEQUENCE OF KeyPairContainer
KeyPairContainer ::= SEQUENCE {
public SubjectPublicKeyInfo,
encryptedPrivate EncryptedPrivateKeyInfo
}
tags:
- Certificates
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
pkcs10:
description: |
PKCS10 request (Base64 encoded) containing the initial
public key and subject information.
type: string
format: byte
validfrom:
description: |
X.509 "not before" point in time. Format 'ISO 8601'.
Example: 2007-03-01T13:00:00Z
type: string
format: date-time
validto:
description: |
X.509 "not after" point in time. Format 'ISO 8601'.
Example: 2008-05-11T15:30:00Z
type: string
format: date-time
procname:
description: |
Name of token procedure that should be used to issue the
certificate. If this parameter is not given, a default value
set in the server side configuration will be used
(`handler.(n).tokenprocedure` in `api.properties`).
type: string
signature:
$ref: "#/components/schemas/ApiRequest_Signature"
required:
- pkcs10
encoding:
pkcs10:
contentType: application/pkcs10
responses:
200:
description: OK - Returns a PKCS7 message with the issued certificate.
content:
application/pkcs7-mime:
schema:
type: string
format: binary
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
/certificates/import-pki-x509:
post:
operationId: importPKIX509
summary: Import externally issued X.509 certificates
description: |
Imports X.509 certificates from an external PKI.
This endpoint is used to import certificate(s) to CM issued by an
external PKI. Each imported certificate may be complemented with
revocation information, such as reason code and time of revocation.
The request may specify a token procedure, which must be connected to a
CA with a SubjectDN matching imported certificates IssuerDN.
If no Token Procedure is specified, a default is used by the server.
tags:
- Certificates
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
procname:
description: |
Name of token procedure that should be used to issue the
certificate. If this parameter is not given, a default value
set in the server side configuration will be used.
type: string
importdata:
description: |
Array of certificate(s) to import.
type: array
items:
type: object
properties:
certificate:
description: |
Base64 encoded certificate.
type: string
format: byte
reason:
$ref: "#/components/schemas/ApiRequest_RevocationReason"
revocationtime:
description: |
Point in time when the certificate was revoked.
type: string
format: date-time
required:
- certificate
signature:
$ref: "#/components/schemas/ApiRequest_Signature"
required:
- importdata
responses:
200:
description: OK - successfully imported all certificates
content:
application/json:
schema:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
example:
error: 0
msg: "1 certificate(s) has been imported"
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponseWithJsonArrayIndex"
example:
error: -1
msg: "Error(s) occurred during the PKI import"
errors: [
{
arrayindex: 0,
errorcode: -14,
errormessage: "Duplicated certificate import entry",
},
{
arrayindex: 1,
errorcode: -14,
errormessage: "Unable to import certificate",
servererrormessage: "Invalid certificate issuer"
},
{
arrayindex: 2,
errorcode: -40,
errormessage: "Maximum import limit exceeded",
limit: 1
}
]
/procedures:
get:
operationId: listProcedures
summary: List procedures
description: |
Lists all token procedures that are available for the authenticated officer.
tags:
- Procedures
responses:
200:
description: OK - Returns the list of available token procedures.
content:
application/json:
schema:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
procedures:
description: Array of token procedures.
type: array
items:
type: object
properties:
procid:
type: string
description: Unique ID of the procedure.
name:
type: string
description: Human-readable name of the procedure.
example:
error: 0
msg: "Fetched procedures"
procedures: [
{
procid: "t-scep-registr-visible-p10",
name: "SCEP Registration Visible Procedure"
}
]
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
example:
error: -1
msg: "No procedures found"
/registrations/{procid}:
get:
operationId: listRegistrations
summary: List registrations
description: |
The registrations endpoint returns a list of registrations done on the
procedure with the matching token procedure id and, if given, the other
optional parameters.
tags:
- Registrations
parameters:
- $ref: '#/components/parameters/procid'
- $ref: '#/components/parameters/regid'
- $ref: '#/components/parameters/fqdn'
- $ref: '#/components/parameters/status'
- $ref: '#/components/parameters/validity'
- $ref: '#/components/parameters/officer'
- $ref: '#/components/parameters/regtype'
responses:
200:
description: OK - Returns all registrations matching the given query parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/RegistrationResponseGet'
example:
registrations:
- regid: akZShn8u3qcOetstcL7eyfD05Tk=
fqdn: 'test-1-170645'
creationdate: 1565096805000
status: closed
regtype: cmp
validity: 7
error: 0
msg: Fetched registrations
500:
$ref: '#/components/responses/ServerError'
post:
operationId: createRegistration
summary: Creates registration
description: |
Either body OR file must be set.
tags:
- Registrations
parameters:
- $ref: '#/components/parameters/procid'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRegistration'
example:
fqdn: "Device Test"
regtype: "cmp"
status: "open"
validity: "7"
signature: "MIIFuwYJK..."
responses:
200:
$ref: '#/components/responses/RegistrationPost200'
500:
$ref: '#/components/responses/RegistrationPost500'
put:
operationId: updateRegistration
summary: Update registration
description: |
Updates a registration with the given data.
tags:
- Registrations
parameters:
- $ref: '#/components/parameters/procid'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateRegistration'
example:
regid: "regid-1234"
status: "open"
validity: "always"
signature: "MIIFuwYJK..."
responses:
200:
$ref: '#/components/responses/RegistrationUpdate200'
500:
$ref: '#/components/responses/RegistrationUpdate500'
/registrations/certificate/{certid}:
get:
operationId: getRegistrationsCertId
summary: Retrieves the registration that issued the certificate.
description: Retrieves the registration that issued the certificate.
tags:
- Registrations
responses:
200:
description: OK - Returns the registration.
content:
application/json:
schema:
$ref: '#/components/schemas/RegistrationCertId'
500:
$ref: '#/components/responses/ServerError'
parameters:
- $ref: '#/components/parameters/certid'
/registrations/{procid}/scep:
get:
operationId: listRegistrationsScep
summary: List registrations under SCEP
description: |
The SCEP registrations endpoint returns a list of registrations done on the
procedure with the matching token procedure id and, if given, the other
optional parameters.
tags:
- Registrations/{procid}/SCEP
responses:
200:
description: OK - Returns all registrations matching the given query parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/RegistrationResponseGet'
example:
registrations:
- regid: CGEMNL39wUEB/srVptVCKYyD2nA=
fqdn: 'test-*.example.com'
creationdate: 1572490820000
officer: Super Officer 2
status: open
regtype: scep
validity: always
encryptedpassword: MIIB...3yv6
error: 0
msg: Fetched registrations
500:
$ref: '#/components/responses/ServerError'
parameters:
- $ref: '#/components/parameters/procid'
- $ref: '#/components/parameters/regid'
- $ref: '#/components/parameters/fqdn'
- $ref: '#/components/parameters/status'
- $ref: '#/components/parameters/validity'
- $ref: '#/components/parameters/officer'
post:
operationId: createRegistrationScep
summary: Creates registration for SCEP
description: |
Either body OR file must be set.
tags:
- Registrations/{procid}/SCEP
parameters:
- $ref: '#/components/parameters/procid'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/RegistrationScep'
required:
- fqdn
- password
example:
fqdn: "SCEP-1234"
password: "1234"
status: "open"
validity: "always"
signature: "MIIFuwYJK..."
responses:
200:
$ref: '#/components/responses/RegistrationPost200'
500:
$ref: '#/components/responses/RegistrationPost500'
put:
operationId: updateRegistrationScep
summary: Updates registration for SCEP
description: |
Updates a registration with the given data for SCEP protocol.
tags:
- Registrations/{procid}/SCEP
parameters:
- $ref: '#/components/parameters/procid'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/RegistrationScep'
required:
- regid
example:
regid: "regid-1234"
status: "open"
validity: "7"
signature: "MIIFuwYJK..."
responses:
200:
$ref: '#/components/responses/RegistrationUpdate200'
500:
$ref: '#/components/responses/RegistrationUpdate500'
/registrations/{procid}/est:
get:
operationId: listRegistrationsEst
summary: List registrations for EST
description: |
The EST registrations endpoint returns a list of registrations done on the
procedure with the matching token procedure id, and if given, the other
optional parameters.
tags:
- Registrations/{procid}/EST
responses:
200:
description: OK - Returns all registrations matching the given query parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/RegistrationResponseGet'
example:
registrations:
- regid: 2YLD25xzE9BW84WdhRSsNFyNTvk=
fqdn: 'APIClientTest_-1835737403'
creationdate: 1572490406000
officer: Super Officer 1
status: open
regtype: est
validity: always
encryptedpassword: MIIB...IX9m
error: 0
msg: Fetched registrations
500:
$ref: '#/components/responses/ServerError'
parameters:
- $ref: '#/components/parameters/procid'
- $ref: '#/components/parameters/regid'
- $ref: '#/components/parameters/fqdn'
- $ref: '#/components/parameters/status'
- $ref: '#/components/parameters/validity'
- $ref: '#/components/parameters/officer'
post:
operationId: createRegistrationEst
summary: Creates registration for EST
description: |
Either body OR file must be set.
tags:
- Registrations/{procid}/EST
parameters:
- $ref: '#/components/parameters/procid'
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/RegistrationEstHttpAuth'
- $ref: '#/components/schemas/RegistrationEstCertAuth'
required:
- fqdn
examples:
http-authentication:
value:
fqdn: "*.ad.example.com"
password: "1234"
status: "open"
validity: "7"
signature: "MIIFuwYJK..."
certificate-authentication:
value:
fqdn: "my.authentication.certificate"
subject-commonname: "my.commonname.in.csr"
status: "open"
validity: "7"
signature: "MIIFuwYJK..."
responses:
200:
$ref: '#/components/responses/RegistrationPost200'
500:
$ref: '#/components/responses/RegistrationPost500'
put:
operationId: updateRegistrationEst
summary: Updates registration for EST
description: |
Updates a registration with the given data for EST protocol.
tags:
- Registrations/{procid}/EST
parameters:
- $ref: '#/components/parameters/procid'
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/RegistrationEstHttpAuth'
- $ref: '#/components/schemas/RegistrationEstCertAuth'
required:
- regid
examples:
http-authentication:
value:
regid: "regid-1234"
fqdn: "*.ad.example.com"
status: "closed"
validity: "7"
signature: "MIIFuwYJK..."
certificate-authentication:
value:
regid: "regid-1234"
fqdn: "my.authentication.certificate"
subject-commonname: "my.new.commonname.in.csr"
status: "open"
validity: "3"
signature: "MIIFuwYJK..."
responses:
200:
$ref: '#/components/responses/RegistrationUpdate200'
500:
$ref: '#/components/responses/RegistrationUpdate500'
/registrations/{procid}/cmp:
get:
operationId: listRegistrationsCmp
summary: List registrations for CMP
description: |
The CMP registrations endpoint returns a list of registrations done on the
procedure with the matching token procedure id, and if given, the other
optional parameters.
tags:
- Registrations/{procid}/CMP
responses:
200:
description: OK - Returns all registrations matching the given query parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/RegistrationResponseGet'
example:
registrations:
- regid: JS2rc9cTa1jlAXxHdANTg7YEvu4=
fqdn: '*.vendor.com'
creationdate: 1572490601000
officer: Super Officer 2
status: open
regtype: cmp
validity: always
encryptedpassword: MIIB...fJ8D
error: 0
msg: Fetched registrations
500:
$ref: '#/components/responses/ServerError'
parameters:
- $ref: '#/components/parameters/procid'
- $ref: '#/components/parameters/regid'
- $ref: '#/components/parameters/fqdn'
- $ref: '#/components/parameters/status'
- $ref: '#/components/parameters/validity'
- $ref: '#/components/parameters/officer'
post:
operationId: createRegistrationCmp
summary: Creates registration for CMP
description: |
Either body OR file must be set.
tags:
- Registrations/{procid}/CMP
parameters:
- $ref: '#/components/parameters/procid'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/RegistrationCmp'
required:
- fqdn
example:
fqdn: "*.ad.example.com"
status: "open"
validity: "7"
signature: "MIIFuwYJK..."
responses:
200:
$ref: '#/components/responses/RegistrationPost200'
500:
$ref: '#/components/responses/RegistrationPost500'
put:
operationId: updateRegistrationCmp
summary: Updates registration for CMP
description: |
Updates a registration with the given data for CMP protocol.
tags:
- Registrations/{procid}/CMP
parameters:
- $ref: '#/components/parameters/procid'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/RegistrationCmp'
required:
- regid
example:
regid: "regid-1234"
fqdn: "*.ad.example.com"
status: "open"
validity: "7"
signature: "MIIFuwYJK..."
responses:
200:
$ref: '#/components/responses/RegistrationUpdate200'
500:
$ref: '#/components/responses/RegistrationUpdate500'
/registrations/{procid}/acme:
get:
operationId: listRegistrationsAcme
summary: List registrations for ACME
description: |
The ACME registrations endpoint returns a list of registrations done on the
procedure with the matching token procedure id, and if given, the other
optional parameters.
tags:
- Registrations/{procid}/ACME
responses:
200:
description: OK - Returns all registrations matching the given query parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/RegistrationResponseAcmeGet'
example:
registrations:
- regid: 4Lvs8mYrqi73CcZjt5UFfiIa4kc=
fqdn: 'keyId-63453491'
creationdate: 1572490404000
officer: Super Officer 1
status: open
regtype: acme
validity: always
error: 0
msg: Fetched registrations
500:
$ref: '#/components/responses/ServerError'
parameters:
- $ref: '#/components/parameters/procid'
- $ref: '#/components/parameters/regid'
- $ref: '#/components/parameters/fqdn'
- $ref: '#/components/parameters/status'
- $ref: '#/components/parameters/validity'
- $ref: '#/components/parameters/officer'
post:
operationId: createRegistrationAcme
summary: Creates registration for ACME
description: |
Either body OR file must be set.
tags:
- Registrations/{procid}/ACME
parameters:
- $ref: '#/components/parameters/procid'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/RegistrationAcme'
required:
- fqdn
- hmacKey
example:
fqdn: "*.ad.example.com"
hmacKey: "PSuC...Zoi8"
status: "open"
validity: "7"
signature: "MIIFuwYJK..."
responses:
200:
$ref: '#/components/responses/RegistrationPost200'
500:
$ref: '#/components/responses/RegistrationPost500'
put:
operationId: updateRegistrationAcme
summary: Updates registration for ACME
description: |
Updates a registration with the given data for ACME protocol.
tags:
- Registrations/{procid}/ACME
parameters:
- $ref: '#/components/parameters/procid'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/RegistrationAcme'
required:
- regid
example:
regid: "regid-1234"
fqdn: "*.ad.example.com"
status: "open"
validity: "7"
signature: "MIIFuwYJK..."
responses:
200:
$ref: '#/components/responses/RegistrationUpdate200'
500:
$ref: '#/components/responses/RegistrationUpdate500'
/registrations/{procid}/acme/accounts:
get:
operationId: listAcmeAccounts
summary: Lists ACME accounts.
description: |
Lists all ACME accounts from a registration. Search can be limited
by using the query parameter 'accountid'.
tags:
- Registrations/{procid}/ACME
parameters:
- $ref: '#/components/parameters/procid'
- $ref: '#/components/parameters/accountid'
responses:
200:
description: OK - Account(s) successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
example:
registrations:
- regid: 4Lvs8mYrqi73CcZjt5UFfiIa4kc=
fqdn: 'CnY9c9OuvSEHGT3cfRkBlQ'
creationdate: 1575278296000
officer: Super Officer 1
status: Active
keyid: 'keyId-644251404'
email: acme@example.com
regType: 'acme/account'
certIds: [10050, 10051, 11302]
error: 0
msg: Fetched registrations
500:
description: Error - Failed to retrieve accounts
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
example:
error: -14
msg: "Code -14, invalid procedure id"
components:
schemas:
ApiResponse_Error:
type: integer
description: |
Non-zero error code if the request could not be processed, or zero
if there was no error.
Possible values:
* 0 = Ok
* -1 = General error
* -7 = Missing field
* -8 = Encoding error
* -12 = Not initialized
* -14 = Bad field value
* -15 = Privilige error
* -17 = Bad signature
* -18 = Connection error
* -19 = Signature required
* -40 = Too many requests
ApiResponse_Msg:
type: string
description: Developer message describing the outcome of the request.
ApiRequest_Signature:
type: string
description: |
Signed request (Base64 encoded).
Only used when CM REST API is configured to not use VRO signing.
format: byte
writeOnly: true
ApiRequest_RevocationReason:
type: integer
minimum: 0
maximum: 10
description: |
Revocation reason code mapping
* 0: Unspecified
* 1: Key Compromise
* 3: Affiliation Changed
* 4: Superseded
* 5: Cessation Of Operation
* 6: Certificate Hold
* 9: Privilege Withdrawn
ApiErrorResponse:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
ApiErrorResponseWithCertIds:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
errors:
type: array
items:
type: object
properties:
certid:
description: Certificate ID.
type: string
errorcode:
description: |
Integer code of the problem that prevented this
certificate ID from being processed.
Possible values:
* 901 = Already Revoked
* 902 = Access Denied
* 903 = Incorrect Password
* 904 = Free text (non specific errorcode)
* 906 = Already on hold
* 907 = Certificate missing
* 908 = Request not signed
* 909 = Not visible from domain
* 910 = Not on hold
* 911 = Revocation not available extension
* -1 = General error
type: integer
errormessage:
description: |
Developer message describing the problem that
prevented this certificate ID from being
processed.
type: string
servererrormessage:
description: |
Developer message given by the server.
type: string
ApiErrorResponseWithJsonArrayIndex:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
errors:
type: array
items:
type: object
properties:
arrayindex:
description: |
Indicates the index position of the failed certificate import.
type: integer
errorcode:
description: |
Integer code of the problem that prevented this
certificate ID from being processed.
type: integer
errormessage:
description: |
Developer message describing the problem that
prevented this certificate from being processed.
type: string
servererrormessage:
description: |
Developer message given by the server.
type: string
limit:
description: |
Integer indicating the maximum allowed size of
the JsonArray in the request. The limit is added to
clarify if the error is due to the limit being exceeded.
type: integer
JsonIssuer:
type: object
description: CA details.
properties:
subject:
type: array
description: Subject
items:
type: object
description: |
Relative DN of directory attributes as per RFC1779
(for example {"cn":"somecommonname"}.)
subjectDn:
type: string
description: Full subject DN string
JsonCertificate:
type: object
description: Certificate details.
properties:
certid:
type: string
description: Unique ID of the certificate.
status:
type: string
description: Human-readable status of the certificate, revoked/active.
reason:
type: string
description: Revocation reason.
revocationtime:
type: string
format: date-time
description: Point in time when the certificate was revoked.
validto:
type: string
format: date-time
description: X.509 "not after" point in time.
validfrom:
type: string
format: date-time
description: X.509 "not before" point in time.
certificateserialnumber:
type: string
description: Certificate serial number in hex format.
subject:
type: string
description: Subject distinguished name.
issuer:
type: string
description: Issuer distinguished name.
keyusage:
type: array
items:
type: string
description: |
List of key usage names, including those from ExtendedKeyUsage
extension.
subjectType:
type: string
description: |
Identifies the subject tpye of the certificate, either an
End Entity (EE) or a Certificate Authority (CA)
extendedcertsearch:
type: object
properties:
field1:
type: string
field2:
type: string
field3:
type: string
field4:
type: string
field5:
type: string
field6:
type: string
description: |
List of extended certificate search criteria field values
authorityKeyIdentifier:
type: string
description: AuthorityKeyIdentifier in hex format
subjectKeyIdentifier:
type: string
description: SubjectKeyIdentifier in hex format
required:
- certid
- status
Regid:
type: string
description: The registration id. Created on the server side.
readOnly: true
Fqdn:
type: string
description: Fully qualified domain name.
Validity:
type: string
description: |
Determines for how long the registration will be open. Set in either
days or 'always' to be open forever.
Officer:
type: string
description: Officer who signed the request. Created on the server side.
readOnly: true
Creationdate:
type: string
description: Creation date of the registration. Created on the server side.
readOnly: true
Regtype:
type: string
enum:
- est
- cmp
- scep
- device
- acme
- acme/account
description: |
Determines which type the registration can be used with.
Status:
type: string
enum:
- open
- closed
description: |
Either 'open' or 'closed'. Determines if that registration can be
used for certificate creation.
AccountStatus:
type: string
enum:
- active
- deactivated
- revoked
description: |
Either 'active', 'deactivate' or 'revoked'. Determines if the
account registration can be used for certificate creation.
Email:
type: string
description: Email address used with the registration.
Keyid:
type: string
description: Keyid of the connected pre-registration.
Certids:
type: array
description: Array of certificate ids.
items:
type: string
readOnly: true
Accountids:
type: array
description: Array of ACME account ids.
items:
type: string
# Contains base parameters common for all types of registrations
RegistrationBase:
properties:
regid:
$ref: '#/components/schemas/Regid'
fqdn:
$ref: '#/components/schemas/Fqdn'
validity:
$ref: '#/components/schemas/Validity'
status:
$ref: '#/components/schemas/Status'
signature:
$ref: "#/components/schemas/ApiRequest_Signature"
Registration:
type: object
allOf:
- $ref: '#/components/schemas/RegistrationBase'
- properties:
regtype:
$ref: '#/components/schemas/Regtype'
officer:
$ref: '#/components/schemas/Officer'
creationdate:
$ref: '#/components/schemas/Creationdate'
certids:
$ref: '#/components/schemas/Certids'
PreRegistrationAcme:
type: object
allOf:
- $ref: '#/components/schemas/RegistrationBase'
- properties:
regtype:
$ref: '#/components/schemas/Regtype'
officer:
$ref: '#/components/schemas/Officer'
creationdate:
$ref: '#/components/schemas/Creationdate'
accountids:
$ref: '#/components/schemas/Accountids'
RegistrationScep:
type: object
allOf:
- $ref: '#/components/schemas/RegistrationBase'
- properties:
ipaddress:
type: string
description: |
IP address of the device using the registration.
email:
$ref: '#/components/schemas/Email'
serialnumber:
type: string
description: |
Serial number of the device using the registration.
password:
type: string
description: |
The password used to register.
RegistrationEstHttpAuth:
type: object
allOf:
- $ref: '#/components/schemas/RegistrationBase'
- properties:
username:
type: string
description: |
Username used with HTTP based authentication.
realm:
type: string
description: |
Realm used with HTTP based authentication.
password:
type: string
description: |
The password used to register.
RegistrationEstCertAuth:
type: object
allOf:
- $ref: '#/components/schemas/RegistrationBase'
- properties:
subject-commonname:
type: string
description: |
Commonname of the subject in the CSR to enroll for
authentication-certificate-ca:
type: string
description: |
AWB name of the CA of the device authentication certificate.
RegistrationCmp:
type: object
allOf:
- $ref: '#/components/schemas/RegistrationBase'
- properties:
password:
type: string
description: |
The password used to register.
RegistrationAcme:
type: object
allOf:
- $ref: '#/components/schemas/RegistrationBase'
- properties:
hmacKey:
type: string
format: byte
description: |
HMAC key for ACME pre-registration (32 bytes in base64 url-safe encoding).
allowedDomains:
type: string
description: |
Comma separated string of allowed domains for ACME pre-registration.
RegistrationCertId:
type: object
properties:
registration:
$ref: '#/components/schemas/Registration'
error:
$ref: '#/components/schemas/ApiResponse_Error'
msg:
$ref: '#/components/schemas/ApiResponse_Msg'
Account:
type: object
allOf:
- properties:
regid:
$ref: '#/components/schemas/Regid'
fqdn:
$ref: '#/components/schemas/Fqdn'
creationdate:
$ref: '#/components/schemas/Creationdate'
officer:
$ref: '#/components/schemas/Officer'
status:
$ref: '#/components/schemas/AccountStatus'
keyid:
$ref: '#/components/schemas/Keyid'
email:
$ref: '#/components/schemas/Email'
certids:
$ref: '#/components/schemas/Certids'
CreateRegistration:
allOf:
- $ref: '#/components/schemas/RegistrationBase'
- properties:
regtype:
$ref: '#/components/schemas/Regtype'
required:
- fqdn
- regtype
UpdateRegistration:
allOf:
- $ref: '#/components/schemas/Registration'
- properties:
regid:
readOnly: false
regtype:
readOnly: true
required:
- regid
RegistrationResponseGet:
type: object
properties:
registrations:
type: array
description: Array of registrations connected to the given procid.
items:
$ref: '#/components/schemas/Registration'
error:
$ref: '#/components/schemas/ApiResponse_Error'
msg:
$ref: '#/components/schemas/ApiResponse_Msg'
RegistrationResponseAcmeGet:
type: object
properties:
registrations:
type: array
description: Array of registrations connected to the given procid.
items:
$ref: '#/components/schemas/PreRegistrationAcme'
error:
$ref: '#/components/schemas/ApiResponse_Error'
msg:
$ref: '#/components/schemas/ApiResponse_Msg'
RegistrationResponsePostOrPut:
type: object
properties:
registration:
type: object
properties:
regid:
$ref: '#/components/schemas/Regid'
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
# Defines common parameters used by multiple GET operations
parameters:
procid:
name: procid
in: path
description: Token procedure id
required: true
schema:
type: string
regid:
name: regid
in: query
description: Registration id
schema:
type: string
certid:
name: certid
in: path
description: Certificate id
required: true
schema:
type: string
accountid:
name: accountid
in: query
description: Account id, allows wildcard(*)
schema:
type: string
fqdn:
name: fqdn
in: query
description: Fully qualified domain name.
schema:
type: string
status:
name: status
in: query
description: Registration status
schema:
enum:
- open
- closed
type: string
validity:
name: validity
in: query
description: Number of days the registration will be open or 'always'.
schema:
type: string
regtype:
name: regtype
in: query
description: Registration type of the registration.
schema:
$ref: '#/components/schemas/Regtype'
email:
name: email
in: query
description: Email address
schema:
type: string
ipaddress:
name: ipaddress
in: query
description: IP address
schema:
type: string
serialnumber:
name: serialnumber
in: query
description: Certificate serialnumber as hex.
schema:
type: string
password:
name: password
in: query
description: The password used to register.
schema:
type: string
username:
name: username
in: query
description: The username used to register.
schema:
type: string
realm:
name: realm
in: query
description: The realm the user should be connected with.
schema:
type: string
subject-commonname:
name: subject-commonname
in: query
description: The commonname of the subject to be enrolled
schema:
type: string
hmacKey:
name: hmacKey
in: query
description: |
HMAC key for ACME pre-registration (32 bytes in base64 url-safe encoding).
The HMAC Key Id must also be specified in the fqdn field.
schema:
type: string
allowedDomains:
name: allowedDomains
in: query
description: Comma separated string of allowed domains.
schema:
type: string
creationdate:
name: creationdate
in: query
description: Creation date of the registration.
schema:
type: string
officer:
name: officer
in: query
description: Officer who signed the request.
schema:
type: string
searchLimit:
name: searchLimit
in: query
description: |
The maximum number of certificates that should be returned.
Please note that the highest possible value is still limited by
server-side configuration (`certsearch.maxhits` in
`cm.conf`).
schema:
type: integer
searchOffset:
name: searchOffset
in: query
description: |
The starting offset of the first certificate that should be
returned. This may be used for pagination of the results, together
with the searchLimit parameter.
schema:
type: integer
certificateSerialNumber:
name: certificateSerialNumber
in: query
description: Serial number of the certificate.
schema:
type: string
revocationTimeFrom:
name: revocationTimeFrom
in: query
description: |
Only return certificates whose revocation time is after
the provided time.
schema:
type: string
format: date-time
revocationTimeTo:
name: revocationTimeTo
in: query
description: |
Only return certificates whose revocation time is before
the provided time.
schema:
type: string
format: date-time
revocationReason:
name: revocationReason
in: query
description: |
Only return certificates with specified revocation reasons.
Takes an array of integers in the format e.g. `1,2,3,4`.
Reason code mapping:
* 0: Unspecified
* 1: Key Compromise
* 2: Ca Compromise
* 3: Affiliation Changed
* 4: Superseded
* 5: Cessation Of Operation
* 6: Certificate Hold
* 8: Remove From CRL
* 9: Privilege Withdrawn
* 10: AACompromise
schema:
type: array
items:
type: integer
minimum: 0
maximum: 10
isNotRevoked:
name: isNotRevoked
in: query
description: |
If `true`, only certificates that are not revoked will be
returned.
schema:
type: boolean
publicationAllowed:
name: publicationAllowed
in: query
description: |
If `true`, only certificates where publication is allowed
will be returned.
schema:
type: boolean
publicationTimeFrom:
name: publicationTimeFrom
in: query
description: |
Only return certificates whose publication time is after
the provided time.
schema:
type: string
format: date-time
publicationTimeTo:
name: publicationTimeTo
in: query
description: |
Only return certificates whose publication time is before
the provided time.
schema:
type: string
format: date-time
ocspActivationTimeFrom:
name: ocspActivationTimeFrom
in: query
description: |
Only return certificates whose OCSP-activation time is after
the provided time.
schema:
type: string
format: date-time
ocspActivationTimeTo:
name: ocspActivationTimeTo
in: query
description: |
Only return certificates whose OCSP-activation time is before
the provided time.
schema:
type: string
format: date-time
validFromTimeFrom:
name: validFromTimeFrom
in: query
description: |
Only return certificates whose "valid from" (also named
"not before") is after the provided time.
schema:
type: string
format: date-time
validFromTimeTo:
name: validFromTimeTo
in: query
description: |
Only return certificates whose "valid from" (also named
"not before") is before the provided time.
schema:
type: string
format: date-time
isNotYetValid:
name: isNotYetValid
in: query
description: |
If `true`, only certificates whose "valid from" (also named
"not before") is in the future will be returned.
schema:
type: boolean
validToTimeFrom:
name: validToTimeFrom
in: query
description: |
Only return certificates whose "valid to (also named
"not after") is after the provided time.
schema:
type: string
format: date-time
validToTimeTo:
name: validToTimeTo
in: query
description: |
Only return certificates whose "valid to" (also named
"not after") is before the provided time.
schema:
type: string
format: date-time
isExpired:
name: isExpired
in: query
description: |
If `true`, only certificates that have already expired will
be returned. This implies that the certificate's "valid to"
(also named "not after") has passed.
schema:
type: boolean
field1:
name: field1
in: query
description: |
Only return certificates with the specified extended
certificate search field set
schema:
type: string
field2:
name: field2
in: query
description: |
Only return certificates with the specified extended
certificate search field set
schema:
type: string
field3:
name: field3
in: query
description: |
Only return certificates with the specified extended
certificate search field set
schema:
type: string
field4:
name: field4
in: query
description: |
Only return certificates with the specified extended
certificate search field set
schema:
type: string
field5:
name: field5
in: query
description: |
Only return certificates with the specified extended
certificate search field set
schema:
type: string
field6:
name: field6
in: query
description: |
Only return certificates with the specified extended
certificate search field set
schema:
type: string
authorityKeyIdentifier:
name: authorityKeyIdentifier
in: query
description: |
AKI to filter results on. Must be in hexadecimal format.
Example: 4A3A887184A13B28
schema:
type: string
subjectKeyIdentifier:
name: subjectKeyIdentifier
in: query
description: |
SKI to filter results on. Must be in hexadecimal format.
Example: 4A3A887184A13B28
schema:
type: string
subjectType:
name: subjectType
in: query
description: |
Allows for filtering on subject type. By default only End Entity (EE)
certificates are returned. Available values are:
* EE
* CA
Takes an array of string in the format e.g. 'EE,CA`.
Enum mapping:
* EE: End Entity
* CA: Certificate Authority
schema:
type: array
items:
type: string
# Defines common responses used by multiple PATHS
responses:
RegistrationPost200:
description: OK - Registration was successful
content:
application/json:
schema:
$ref: "#/components/schemas/RegistrationResponsePostOrPut"
example:
registration: {'regid':'kplclzbq4KeoaS86KimttAUlXKw='}
error: 0
msg: "Registration has been successful"
RegistrationPost500:
description: Error - Registration failed, invalid input parameters
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
example:
error: -14
msg: "Code -14, Registration type not supported"
RegistrationUpdate200:
description: OK - The updated registration
content:
application/json:
schema:
$ref: "#/components/schemas/RegistrationResponsePostOrPut"
example:
registration: {'regid':'kplclzbq4KeoaS86KimttAUlXKw='}
error: 0
msg: "Registration has been successful"
RegistrationUpdate500:
description: Error - Registration update failed, no such registration
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
example:
error: -14
msg: "Code -14, Registration type not supported"
ServerError:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
example:
error: -14
msg: "Code -14, Internal bad request" |
Page History
Overview
Content Tools