| Info |
|---|
This article includes updates for Certificate Manager 8.1011. |
This article describes the Certificate Manager REST API (RESTful application programming interface) in Certificate Manager.
Certificate Manager REST API (RESTful application programming interface) is an HTTP-based service for x.509 and attribute certificates creation, certificate searching, certificate download, certificate revocation, certificate reinstatement, creation of PKCS#12 files and token procedure listing in Certificate Manager.
The API requires client authentication over TLS using a CM officer certificate. Write operations like revoke, reinstate and certificate issuance requires the request data to be signed by a CM officer. The REST API server can also be configured to use a CM officer for signing the requests on the caller’s behalf, enabling automated services for trusted clients.
The accompanied files APISigningWithOpenSSLAPISigningWithOpenSSL.sh and APISigningWithBouncyCastle.java referenced below can be found in a CM client installation together with the Protocol Gateway web archive file, see Install Protocol Gateway.
For more information, see:
Example: Certificate Manager (CM) REST API configuration in Protocol Gateway
Description of the Secure Key Injection Protocol (SKIP): Use the Secure Key Injection Protocol in Certificate Manager
Date-time format
The expected date-time format for time search fields is ISO 8601. Example: 2021 2021-12-20T08:01:30Z.
| Note |
|---|
This article only contains plain documentation of the Certificate Manager REST API. It is not possible to try out the commands. |
...
| Open api |
|---|
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`.
In cases where multiple CM tenants are configured, logging of the tenant
domain may be enabled in the CM REST API logging with the `showDomainInLogs`
setting in `api.properties` to indicate which domain a session belongs to.
## 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'
- $ref: '#/components/parameters/orderBy'
- $ref: '#/components/parameters/orderDescending'
- 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",
validity: "valid",
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/orderBy'
- $ref: '#/components/parameters/orderDescending'
- $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"
validity: "valid"
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/download:
get:
operationId: downloadCertificates
summary: Download certificates
description: |
Returns multiple certificate results as a compressed zip file.
Single certificate results are returned in binary certificate form.
For X.509 certificates, the encoding of each returned certificate
(whether contained in zip or single certificate) may be DER, PEM or
MIME (pkcs#7), depending on the media type in the provided Accept
header.
tags:
- Certificates
parameters:
- name: certid
in: query
description: List of certificate IDs.
required: true
schema:
type: array
items:
type: string
responses:
200:
description: OK - Returns the requested certificates.
content:
application/zip:
schema:
type: string
format: binary
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/remove:
post:
operationId: removeCertificates
summary: Remove certificates
description: Removes (deletes) 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 remove
type: array
items:
type: string
cleanAuditLog:
description: Clean the audit log for the certificate.
default: true
type: boolean
signature:
$ref: "#/components/schemas/ApiRequest_Signature"
required:
- certid
responses:
200:
description: OK - Requested certificates were removed.
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 removed"
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 removal"
errors: [
{
certid: "1",
errorcode: 513,
errormessage: "Certificate(s) not found"
}
]
/certificates/remove-subjects:
post:
operationId: removeSubjects
summary: Remove subjects
description: Removes (deletes) all data related to the subject(s) bound to the certificate(s) matching the certificate id(s).
tags:
- Certificates
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
certid:
description: Certificate id(s) for which all data related to their subject(s) shall be removed.
type: array
items:
type: string
signature:
$ref: "#/components/schemas/ApiRequest_Signature"
required:
- certid
responses:
200:
description: OK - All data related to requested subjects were removed.
content:
application/json:
schema:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
example:
error: 0
msg: "1 subject(s) has been removed"
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 removal"
errors: [
{
certid: "1",
errorcode: 513,
errormessage: "Certificate(s) 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 PKCS#7 message or X509 the issued certificate.
headers:
certId:
schema:
type: string
description: |
certid of produced 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.
headers:
certId:
schema:
type: string
description: |
certid of produced certificate
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 supports only one attribute certificate procedure in the token
procedure.
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
parameters:
- $ref: "#/components/parameters/mediaType"
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"
/procedures/{procid}/details:
get:
operationId: getProcedureDetails
summary: Procedure details
description: |
Returns information about the procedure with the provided id.
tags:
- Procedures
parameters:
- name: procid
in: path
description: Procedure id
required: true
schema:
type: string
responses:
200:
description: OK - Returns details about the requested procedure.
content:
application/json:
schema:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
procedure:
type: object
properties:
procid:
type: string
description: Unique ID of the procedure.
name:
type: string
description: Human-readable name of the procedure.
type:
type: string
description: |
The media type for the procedure
(Applies to Token Procedures only)
protocol:
type: string
enum:
- SCEP
- CMP
- DEVICE
- ACME
- EST
- ITSS
description: |
The protocol associated with the procedure, calculated
by the cpmstate setting in the corresponding
input view configuration.
certificateprocedures:
type: array
description: |
The certificate procedures
(Applies to Token Procedures only)
items:
type: object
description: A certificate procedure used by the token procedure
properties:
procid:
type: string
description: Unique ID of the certificate procedure
name:
type: string
description: The name of the certificate procedure
validity:
type: string
description: |
The validity period expressed in ISO 8601 format
keyusage:
type: array
description: |
The key usage parameters for this combination of
token procedure and certificate procedure.
items:
type: string
enum:
- digitalsignature
- nonrepudiation
- keyencipherment
- dataencipherment
- keyagreement
- keycertsign
- crlsign
- encipheronly
- decipheronly
signingprocedures:
type: array
description: |
The signing procedures
(Applies to Token Procedures only)
items:
type: object
description: A signing procedure used by the token procedure
properties:
procid:
type: string
description: Unique ID of the signing procedure
name:
type: string
description: The name of the signing procedure
issuer:
type: string
description: The signing authority subject DN
example:
error: 0
msg: "Fetched procedure"
procedure:
id: "t-1234"
name: "A token procedure"
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
example:
error: -14
msg: "No procedure found"
/signatures/{procid}:
post:
operationId: signData
summary: Sign pre-hashed data
description: |
Creates a signature from the provided pre-hashed data and returns it in the format that is specified in the response.
tags:
- Signing
parameters:
- $ref: '#/components/parameters/procid'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
hashedtbs:
description: |
JSON structure containing the hash algorithm name and the pre-hashed data to be signed.
type: object
properties:
algid:
description: |
The algorithm name of the hash algorithm used when producing the pre-hashed data.
type: string
enum:
- SHA-224
- SHA-256
- SHA-384
- SHA-512
- SHA-512/224
- SHA-512/256
- SHA3-224
- SHA3-256
- SHA3-384
- SHA3-512
hash:
description: The pre-hashed data to be signed (Base64 encoded).
type: string
format: binary
signature:
$ref: "#/components/schemas/ApiRequest_Signature"
encoding:
hashedtbs:
contentType: application/json
responses:
200:
description: OK - Returns the Base64 encoded signed data in the specified format.
content:
application/json:
schema:
type: object
properties:
response:
type: string
description: Base64 encoded response object
format:
type: string
enum:
- SignedData
- Signature
description: |
The format of the response data.
SignedData: indicates that the response is a Base64 encoded
SignedData object, see https://www.rfc-editor.org/rfc/rfc5652#section-5.1
for the definition.
Signature: indicates that the response is a Base64 encoded
raw signature.
certid:
type: string
description: |
The certId of the signing certificate. It is provided here
to see if the signer has been changed, or if you want to
download the signing certificate using the
certificates/{certId}/download endpoint.
example:
response: DVjH5MPr...NDhTqbA==
format: Signature
certid: "10003"
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
/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"
/registrations/{procid}/itss:
get:
operationId: listRegistrationsItss
summary: List registrations for ITS station
description: |
The ITS station 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}/ITSS
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: 'ITS-S canonical identifier'
creationdate: 1572490601000
officer: Super Officer 2
status: open
regtype: itss
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: createRegistrationItss
summary: Creates registration for ITS station
description: |
Either body OR file must be set.
tags:
- Registrations/{procid}/ITSS
parameters:
- $ref: '#/components/parameters/procid'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/RegistrationItss'
required:
- fqdn
- canonicalkey
- namedcurve
example:
fqdn: "ITS-S canonical identifier"
canonicalkey: "02ce16794f77...1820"
namedcurve: "nistP256"
status: "open"
validity: "7"
signature: "MIIFuwYJK..."
responses:
200:
$ref: '#/components/responses/RegistrationPost200'
500:
$ref: '#/components/responses/RegistrationPost500'
put:
operationId: updateRegistrationItss
summary: Updates registration for ITSS
description: |
Updates a registration with the given data for an ITS station.
tags:
- Registrations/{procid}/ITSS
parameters:
- $ref: '#/components/parameters/procid'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/RegistrationItss'
required:
- regid
- canonicalkey
- namedcurve
example:
regid: "regid-1234"
fqdn: "ITS-S new canonical identifier"
canonicalkey: "02ce16794f77...1820"
namedcurve: "nistP256"
status: "open"
validity: "7"
signature: "MIIFuwYJK..."
responses:
200:
$ref: '#/components/responses/RegistrationUpdate200'
500:
$ref: '#/components/responses/RegistrationUpdate500'
/registrations/v2x/{vin}:
delete:
deprecated: true
operationId: v2xRegistrationsVinDelete
summary: Removes the VIN from the system.
description: |
Removes all occasions of the VIN from the system. The vehicle will no
longer be able to request certificates or communicate with the system,
until it decides to re-initialize.
tags:
- V2X Registrations
parameters:
- name: vin
in: path
description: Vehicle Identification Number
required: true
schema:
type: string
- name: signature
in: query
description: |
Signed request (Base64 encoded).
Only used when CM REST API is configured to not use VRO signing.
schema:
$ref: '#/components/schemas/ApiRequest_Signature'
responses:
200:
description: OK - VIN successfully removed
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
example:
error: 0
msg: The specified VIN no longer exist in the system.
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
/registrations/v2x/delete:
post:
operationId: v2xRegistrationsVinDeletePost
summary: Removes all traces of the VIN from the system.
description: |
Removes all data related to, and containing the VIN from the system.
The vehicle will no longer be able to request certificates or communicate
with the system until it performs a new initialization.
tags:
- V2X Registrations
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
vin:
description: Vehicle Identification Number
type: string
signature:
$ref: "#/components/schemas/ApiRequest_Signature"
responses:
200:
description: OK - VIN successfully removed
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
example:
error: 0
msg: The specified VIN no longer exist in the system.
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
/registrations/v2x/reset:
post:
operationId: v2xRegistrationsVinReset
summary: Reset the VIN in the system.
description: |
Performs a reset of the VIN for V2x V2. This means that Enrollment Credentials (ECs) which are
associated with the VIN are revoked, registrations are deactivated and that it
is now possible to request a new EC by sending a new enrollment request.
tags:
- V2X Registrations
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
vin:
description: Vehicle Identification Number
type: string
signature:
$ref: "#/components/schemas/ApiRequest_Signature"
responses:
200:
description: OK - VIN successfully reset
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
example:
error: 0
msg: The specified VIN has been reset.
400:
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
example:
error: -14
msg: 'Error handling signed request, msg: Cannot reset: V2x V2 Init has not been performed for given VIN'
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
example:
error: -1
msg: <error description>
/statistics/certificates:
get:
operationId: statisticscertificates
summary: Counts the number of certificates per status
description: |
Gets the number of certificates per status for a given time interval
optionally filtered by CA
tags:
- Statistics
parameters:
- name: breakpoints
in: query
description: |
Specifies which timeline breakpoints to return statistics for.
Takes an array of two breakpoints in the format e.g. `20230527000000Z,20240527000000Z`
schema:
type: array
items:
type: string
- name: issuer
in: query
description: |
Specifies the DN of an issuer to filter on.
schema:
type: string
responses:
200:
description: OK - Fetched statistics
content:
application/json:
schema:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
data:
type: object
properties:
active:
description: The number of active and valid certificates
type: integer
revoked:
description: The number of revoked certificates
type: integer
closed:
description: The number of closed certificates
type: integer
expired:
description: The number of active but expired certificates
type: integer
notYetValid:
description: The number of active but not yet valid certificates
type: integer
example:
error: 0
msg: "Fetched statistics"
data:
active: 134
revoked: 12
closed: 1
expired: 5454
notYetValid: 453
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
/statistics/active-subjects:
get:
operationId: statisticsactivesubjects
summary: Counts the number of unique active subjects per CA
description: |
Gets the number of unique active subjects per CA for a given time interval
optionally filtered by CA
tags:
- Statistics
parameters:
- name: breakpoints
in: query
description: |
Specifies which timeline breakpoints to return statistics for.
Takes an array of two breakpoints in the format e.g. `20230527000000Z,20240527000000Z`
schema:
type: array
items:
type: string
- name: unique
in: query
description: |
Specifies how to calculate uniqueness of a subject.
Available values are:
* [default] - Calculates uniqueness on the subject database id
* cn - Calculates uniqueness on the subject CN
schema:
type: string
- name: issuer
in: query
description: |
Specifies the DN of an issuer to filter on.
schema:
type: string
responses:
200:
description: OK - Fetched statistics
content:
application/json:
schema:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
data:
type: object
additionalProperties:
description: Number of active subjects for the given subject DN
type: integer
example:
error: 0
msg: "Fetched statistics"
data:
"cn=ca1,o=nexus,c=se": 134
"cn=ca2,o=nexus,c=se": 12
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
/statistics/issued-certificates:
get:
operationId: issuedcertificates
summary: Counts the number of issued certificates per time interval
description: |
Gets the number of issued certificates per time interval and
optionally filtered by CA
tags:
- Statistics
parameters:
- name: breakpoints
in: query
description: |
Specifies which timeline breakpoints to return statistics for.
Takes an array of at least 3 breakpoints in the format e.g. `20230527000000Z,20240527000000Z,20250527000000Z`
schema:
type: array
items:
type: string
- name: issuer
in: query
description: |
Specifies the DN of an issuer to filter on.
schema:
type: string
responses:
200:
description: OK - Fetched statistics
content:
application/json:
schema:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
data:
type: array
items:
type: integer
example:
error: 0
msg: "Fetched statistics"
data: [23, 32]
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
/statistics/expiring-certificates:
get:
operationId: expiringcertificates
summary: Counts the number of expiring certificates per time interval
description: |
Gets the number of expiring certificates per time interval and
optionally filtered by CA
tags:
- Statistics
parameters:
- name: breakpoints
in: query
description: |
Specifies which timeline breakpoints to return statistics for.
Takes an array of at least 3 breakpoints in the format e.g. `20230527000000Z,20240527000000Z,20250527000000Z`
schema:
type: array
items:
type: string
- name: issuer
in: query
description: |
Specifies the DN of an issuer to filter on.
schema:
type: string
responses:
200:
description: OK - Fetched statistics
content:
application/json:
schema:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
data:
type: array
items:
type: integer
example:
error: 0
msg: "Fetched statistics"
data: [23, 32]
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
/statistics/revoked-certificates:
get:
operationId: revokedcertificates
summary: Counts the number of revoked certificates per time interval
description: |
Gets the number of revoked certificates per time interval and
optionally filtered by CA
tags:
- Statistics
parameters:
- name: breakpoints
in: query
description: |
Specifies which timeline breakpoints to return statistics for.
Takes an array of at least 3 breakpoints in the format e.g. `20230527000000Z,20240527000000Z,20250527000000Z`
schema:
type: array
items:
type: string
- name: issuer
in: query
description: |
Specifies the DN of an issuer to filter on.
schema:
type: string
responses:
200:
description: OK - Fetched statistics
content:
application/json:
schema:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
data:
type: array
items:
type: integer
example:
error: 0
msg: "Fetched statistics"
data: [23, 32]
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
/officers:
get:
operationId: officers
summary: Gets the officer capabilities for the logged in officer
description: |
Gets roles and certificate details for the logged in officer
tags:
- Officers
responses:
200:
description: OK - Fetched officer
content:
application/json:
schema:
type: object
properties:
error:
$ref: "#/components/schemas/ApiResponse_Error"
msg:
$ref: "#/components/schemas/ApiResponse_Msg"
officer:
type: object
properties:
id:
type: string
description: The officer ID
certid:
type: string
description: The id of the officer certificate
certserial:
type: string
description: The serial number of the officer certificate
certexpires:
type: integer
description: The time when the officer certificate expires
expires:
type: integer
description: The time when the officer role expires
description:
type: string
description: The display name of the officer
roles:
type: array
description: The officer roles
items:
type: string
enum:
- attributecert.issue
- attributecert.revoke
- attributecert.revokewithpassword
- awb.audit
- awb.cakeytask
- awb.configtask
- awb.domaintask
- awb.officertask
- awb.policytask
- awb.profiletask
- awb.use
- batch.create
- batch.execute
- cert.handover
- cert.issue
- cert.publish
- cert.publishwithpassword
- cert.republish
- cert.revoke
- cert.revokewithpassword
- client.searchexport
- client.use
- cxl.build
- dataretention.manage
- key.recover
- ppm.access
- revocationpassword.manage
example:
error: 0
msg: "Fetched officer"
officer:
id: "r1234"
certid: "10000"
certserial: "a8e917347840348bd239a8ebda7c2638"
certexpires: 1739524937000
expires: 1739487600000
description: "Officer 1"
roles: ["cert.issue", "cert.revoke"]
500:
description: Internal server error - An unexpected error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
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 type 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
validity:
type: string
enum:
- valid
- expired
- notYetValid
description: |
Displays the current certificate validity status.
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
- itss
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.
RegistrationItss:
type: object
allOf:
- $ref: '#/components/schemas/RegistrationBase'
- properties:
canonicalkey:
type: string
description: |
The hexadecimal encoded ECPoint value of the elliptic curve
canonical public key of the station. The first byte indicates
whether the key is compressed (0x02 or 0x03) or uncompressed (0x04).
namedcurve:
type: string
description: |
The name of the elliptic curve of the canonical public key,
nistP256, nistP384, brainpoolP256r1, brainpoolP384r1 or SM2.
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
orderBy:
name: orderBy
in: query
description: |
The name of a field used for sorting.
schema:
type: string
orderDescending:
name: orderDescending
in: query
description: |
If set to 'true' the sort order is reversed. Only used
in combination with the orderBy parameter.
schema:
type: boolean
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
mediaType:
name: mediaType
in: query
description: |
Selects which media type to return procedures for. Available values are:
* pkcs10 (default)
* pkcs12
* smartcard
* attributecertificate
* data
required: false
schema:
type: string
signalg:
name: signalg
in: query
description: |
Allows for filtering on signature algorithm name.
Example: SHA256withRSA
required: false
schema:
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" |
...