Skip to content

Instantly share code, notes, and snippets.

@cslauritsen

cslauritsen/cagw-swagger.json

Created October 9, 2020 15:40
Show Gist options
  • Save cslauritsen/51d70a2970b9e86acb2dd3bc38e4d569 to your computer and use it in GitHub Desktop.
Save cslauritsen/51d70a2970b9e86acb2dd3bc38e4d569 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
cagw-swagger.json
{
"openapi": "3.0.0",
"info": {
"description": "<h1>API Overview</h1>\r\n\r\nThe CA Gateway API is a RESTful Web service API that provides a range of certificate issuance and management functions. The API fronts multiple issuing Certification Authorities (CAs) and accommodates a range of public key algorithms, request/response formats, and certificate contents. A suitable authenticated client of the API can:\r\n\r\n<ul>\r\n<li>query available Certification Authorities (CAs)</li>\r\n<li>query CA artifacts, such as CA certificate chains and revocation lists (CRLs)</li>\r\n<li>query available Certificate Profiles for each CA</li>\r\n<li>submit Enrollment Requests for certificates with client-generated or server-generated key pairs (which may or may not be backed up for subsequent recovery)</li>\r\n<li>submit Recovery Requests for keys that have been stored by the CA</li>\r\n<li>submit Certificate Management Requests for revoking certificates, putting certificates on hold, or taking certificates off hold (resulting in an updated CRL)</li>\r\n</ul>\r\n\r\n<h1>Definitions</h1>\r\n\r\n<p>The following terms are used throughout the documentation and the API.</p>\r\n\r\n<p><b>Issuing Certification Authority:</b> The CA that signs certificates and revocation lists. Each CA has a unique identifying name within the API.</p>\r\n\r\n<p><b>Root Certification Authority:</b> The trust anchor CA that forms the root of trust. The root CA may be the same CA as the issuing CA, or it may be a separate superior CA. If the root CA is the same CA as the issuing CA, the issuing CA's certificate will be self-signed. A trust chain is formed from the series of certificates from the issued certificate up to the root CA's self-signed certificate.</p> \r\n\r\n<p><b>Certificate Revocation List (CRL):</b> A list of certificate serial numbers signed by the issuing CA. The list is formed from certificates that are no longer trusted by the CA, either temporarily through suspension (certificate hold) or permanently through revocation. New CRLs containing the updated list are issued frequently for distribution to relying parties.</p>\r\n\r\n<p><b>Certificate Profile:</b> An object available through the API that describes a particular type of certificate intended for a particular purpose. For example, a device authentication certificate profile defines a certificate for authenticating devices over a network. For another example, an S/MIME email encryption certificate profile defines a certificate for encrypting email messages. Certificate requests are associated with the desired certificate profile, and the certificate returned will reflect the purpose defined by the certificate profile. Each Certificate Profile contains information that must be provided by the client in the certificate request, such as naming information. Each Certificate Profile also specifies information used to generate the certificate, such as algorithms, key lengths, policy, and so on. Each Certificate Profile has a unique identifying name within the API.</p>\r\n\r\n<p><b>Subject Distinguished Name:</b> The name in certificates that identifies the owner or holder of the certificate. For example, \"cn=John Doe, ou=Issuing CA, o=Example, c=US\".</p>\r\n\r\n<p><b>Issuer Distinguished Name:</b> The name in certificates that identifies the issuing CA. For example, \"ou=Issuing CA, o=Example, c=US\".</p>\r\n\r\n<p><b>Subject Alternative Name:</b> A list of alternative names for the end entity certificate owner which are also to be contained within the certificate. There may be several Subject Alternative Names depending on the type of certificate, and they reflect the application or purpose of the certificate. For example, Subject Alternative Names can include Email addresses (RFC 822 addresses), DNS Names, IP Addresses, and so on.</p>\r\n\r\n<p><b>Certificate Request (PKCS #10 CSR):</b> When requesting a certificate using a profile that specifies that the key pair should be generated by the client, then the public key is submitted to the API in PKCS #10 CSR format. The CSR should be signed by the private key in order to prove that the client is in possession of the private key.</p>\r\n\r\n<h1>Common formats in the API</h1>\r\n\r\n<h2>CA Identifier</h2>\r\n<p>CA Identifiers used in the URI of a request must be encoded in UTF8 and percent encoded.</p>\r\n\r\n<h2>Distinguished Names (DNs)</h2>\r\n<p>Certificate issuer and subject identities are represented by distinguished names (DNs), as specified in the X.500 standard. For example: \"ou=Issuing CA, o=Example, c=US\". Subject DNs are supplied to the API as strings, and any Subject DNs containing non-alphanumeric characters or punctuation must be encoded according to RFC 2253 (https://tools.ietf.org/html/rfc2253). These characters can be escaped by enclosing them within double quotes, for example:</p>\r\n\r\n<ul>\r\n<li>If the DN is in the request path: cn=\"LastName, FirstName\",ou=YourDepartment,o=YourCorp,c=US</li>\r\n<li>If the DN is in the request body: \"subjectDn\": \"cn=\\\"LastName, FirstName\\\",ou=mkusers,o=acmeone,c=ca\"</li>\r\n</ul>\r\n\r\n<p>The following characters are currently NOT supported in a Subject Distinguished Name by the CA Gateway:</p>\r\n<ul>\r\n<li>quotation marks (\")</li>\r\n<li>backslash (\\\\)</li>\r\n<li>forward slash (/)</li>\r\n<li>number sign (#)</li>\r\n<li>percent (%)</li>\r\n<li>question mark (?)</li>\r\n<li>semicolon (;)</li>\r\n</ul>\r\n\r\n<h2>Dates and Times</h2>\r\n<ul>\r\n<li>All dates in the CA Gateway API must be in ISO 8601 format.</li> \r\n<li>Durations shall conform to the duration section of ISO 8601.</li>\r\n<li>Intervals shall conform to the interval section of ISO 8601.</li>\r\n</ul>\r\n\r\n<h2>Certificate Serial Number</h2>\r\n<p>When a certificate's serial number is used in an URI, the serial number must:</p>\r\n<ul>\r\n<li>be in hexadecimal format</li>\r\n<li>use only lowercase letters</li>\r\n<li>contain no colons or other separators</li>\r\n<li>be between 2 and 40 digits in length</li>\r\n</ul>\r\n\r\n<h1>Common Use Cases</h1>\r\n\r\n<b>Use Case: Submitting a CSR containing the public key to be certified.</b>\r\n\r\n<p>When the keys and certificate are intended to be used for authentication or signing alone, then the key pair will most commonly be generated at the client. Generating the key pair at the client provides a stronger binding between the certificate and the certificate owner. For example, a network device will generate a key pair and certificate request before becoming operational. For another example, a Web server that requires a certificate for its TLS endpoint will generate its own key pair and certificate request.</p>\r\n\r\n<p>The sequence of events is typically as follows:</p>\r\n\r\n<ol>\r\n<li>The device or software requiring the certificate generates a key pair and exports the public key as a PKCS #10 certificate request (CSR). The CSR also contains naming information coming from the device, such as DNS names and possibly email addresses.</li>\r\n<li>The CSR is submitted through the API, and is processed by the Certification Authority (CA). The CA issues a certificate for the device. The naming information is incorporated into the certificate by the CA as required.</li>\r\n<li>The certificate is imported back into the device or software, and the device becomes operational.</li>\r\n</ol>\r\n\r\n<p>During the above process, the private key never leaves the device. This enhances nonrepudiation.</p>\r\n\r\n<p>Step 2 above can be accomplished over the CA Gateway API with the following sequence of API calls:</p>\r\n\r\n<ol>\r\n<li>Obtain a list of available CAs (GET /v1/certificate-authorities).</li>\r\n<li>After identifying the required CA, get the CA details including the CA certificate chain (GET /v1/certificate-authorities/{caId}).</li>\r\n<li>Obtain a list of certificate profiles available at the CA (GET /v1/certificate-authorities/{caId}/profiles).</li>\r\n<li>Obtain the details of the certificate profiles (GET /v1/certificate-authorities/{caId}/profiles/{profileId}). Certificate profiles contain information about the certificate to be issued, such as:\r\n<ul>\r\n<li>the intended usage</li>\r\n<li>algorithms</li>\r\n<li>the protocols that can be used to obtain the certificate (API only in this release)</li>\r\n<li>the naming information that must be supplied when requesting a certificate using this profile</li>\r\n</ul></li>\r\n<li>Submit the CSR referencing the chosen profile, and receive the issued certificate in the response (POST /v1/certificate-authorities/{caId}/enrollments). Supply the required naming information.</li>\r\n</ol>\r\n \r\n<p>In the current release, all certificates will be issued synchronously.</p>\r\n \r\n<b>Use Case: Requesting S/MIME certificate in PKCS #12 format for email encryption</b>\r\n\r\n<p>An S/MIME certificate will typically be dual-usage so it can be used for both email signing/verification and encryption/decryption. For business continuity reasons, the Certificate Profile for an S/MIME certificate will specify that the private key will be backed up by the CA. Backing up the private key allows subsequent recovery of the private key in case it is ever lost.</p>\r\n\r\n<p>The sequence of events is typically as follows:</p>\r\n\r\n<ol>\r\n<li>A PKCS #12-formatted certificate and private key is requested from the CA through the API.</li>\r\n<li>The CA generates the key pair and backs up the private key.</li>\r\n<li>The PKCS #12 is returned to the client. The private key is protected with a passcode that was supplied by the client.</li>\r\n<li>The PKCS #12 is installed at the point of use, such as a mobile device, email client, Web browser, and so on.</li>\r\n</ol>\r\n\r\n<p>The steps above can be accomplished over the CA Gateway API in the following sequence of API calls:</p>\r\n\r\n<ol>\r\n<li>Obtain a list of available CAs (GET /v1/certificate-authorities).</li>\r\n<li>After identifying the required CA, get the CA details including the CA certificate chain (GET /v1/certificate-authorities/{caId}).</li>\r\n<li>Obtain a list of certificate profiles available at the CA (GET /v1/certificate-authorities/{caId}/profiles).</li>\r\n<li>Obtain the details of the certificate profiles (GET /v1/certificate-authorities/{caId}/profiles/{profileId}). Certificate profiles contain information about the certificate to be issued, such as:\r\n<ul>\r\n<li>the intended usage</li>\r\n<li>algorithms</li>\r\n<li>the protocols that can be used to obtain the certificate (API only in this release)</li>\r\n<li>the naming information that must be supplied when requesting a certificate using this profile</li>\r\n</ul></li>\r\n<li>Submit the request for a PKCS #12 referencing the chosen profile, and receive the issued certificate and key pair in the response (POST /v1/certificate-authorities/{caId}/enrollments). Supply the required naming information.</li>\r\n</ol>\r\n\r\n<p>In the current release, all certificates will be issued synchronously.</p>\r\n ",
"version": "API version 1.4",
"title": "CA Gateway"
},
"tags": [
{
"name": "general",
"description": "General CA Gateway operations."
},
{
"name": "certificate-authority",
"description": "Certification Authority operations."
},
{
"name": "enrollment",
"description": "Enrollment operations."
},
{
"name": "certificate",
"description": "Certificate operations."
},
{
"name": "certificate-events",
"description": "Certificate event operations."
},
{
"name": "subject",
"description": "Subject operations."
},
{
"name": "recovery",
"description": "Recovery operations."
}
],
"paths": {
"/v1": {
"get": {
"tags": [
"general"
],
"summary": "General information about the CA Gateway.",
"description": "<p>Returns general information about this installation of the CA Gateway. You can use this query to ping the gateway or get the number of available CAs. </p>",
"operationId": "cagwInfo",
"parameters": [
{
"name": "correlationId",
"in": "query",
"description": "A free-form identifier that will be logged with this query if any logging occurs.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InfoResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/v1/certificate-authorities": {
"get": {
"tags": [
"certificate-authority"
],
"summary": "A list of available CAs.",
"description": "<h3>Overview</h3>\r\n\r\n<p>Lists the CAs available through this gateway. The list will include only the CAs that the API user has permissions to use.</p>",
"operationId": "caList",
"parameters": [
{
"name": "$fields",
"in": "query",
"description": "<p>The $fields parameter allows you to specify which fields to return.</p>\r\n\r\n<p>Currently, only the following extra fields can be requested:</p>\r\n\r\n<ul>\r\n<li>caList.certificate - returns the CA certificate field for each CA</li>\r\n<li>caList.certificate.certificateData - returns the certificate data field of the CA certificate for each CA</li>\r\n<li>caList.chain - returns the CA certificate chain (excluding the CA certificate itself) for each CA</li>\r\n<li>caList.chain.certificateData - returns the certificate data field of each certificate in the chain for each CA</li>\r\n</ul>\r\n\r\n<p>None of these fields are returned by default. All other fields are returned by default.</p>",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "correlationId",
"in": "query",
"description": "A free-form identifier that will be logged with this query if any logging occurs.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CAListResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/v1/certificate-authorities/{caId}": {
"get": {
"tags": [
"certificate-authority"
],
"summary": "A single CA.",
"description": "<h2>Overview</h2>\r\n\r\n<p>Detailed information about a CA can be requested, such as:</p>\r\n\r\n<ul>\r\n\t<li>CA unique ID</li>\r\n\t<li>CA name</li>\r\n\t<li>CA status</li>\r\n\t<li>Properties such as:\r\n\t\t<ul style=\"list-style:disc\">\r\n\t\t\t<li>Issuer DN</li>\r\n\t\t\t<li>CA connector name</li>\r\n\t\t\t<li>CA type, such as Entrust Authority Security Manager</li>\r\n\t\t</ul>\r\n\t</li>\r\n</ul>",
"operationId": "ca",
"parameters": [
{
"name": "caId",
"in": "path",
"description": "ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.",
"required": true,
"example": "CA-1001",
"schema": {
"type": "string"
}
},
{
"name": "$fields",
"in": "query",
"description": "<p>The $fields parameter allows you to specify which fields to return.</p>\r\n\r\n<p>Currently, only the following extra fields can be requested:</p>\r\n\r\n<ul>\r\n<li>ca.certificate - returns the CA certificate field</li>\r\n<li>ca.certificate.certificateData - returns the certificate data field of the CA certificate</li>\r\n<li>ca.chain - returns the CA certificate chain (excluding the CA certificate itself)</li>\r\n<li>ca.chain.certificateData - returns the certificate data field of each certificate in the chain</li>\r\n</ul>\r\n\r\n<p>None of these fields are returned by default. All other fields are returned by default.</p>",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "correlationId",
"in": "query",
"description": "A free-form identifier that will be logged with this query if any logging occurs.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CAResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/v1/certificate-authorities/{caId}/capabilities": {
"get": {
"tags": [
"certificate-authority"
],
"summary": "The capabilities of the CA.",
"description": "<h3>Overview</h3>\r\n<p>Returns a list of capabilities that a CA supports. Capabilities determine which API calls, parameter values, and features that a particular CA supports.</p>\r\n<p>The capabilities will be grouped into different categories. The full name of a capability shall be the category name, a dot, and the capability name.</p>\r\n",
"operationId": "caCapabilities",
"parameters": [
{
"name": "caId",
"in": "path",
"description": "ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.",
"required": true,
"example": "CA-1001",
"schema": {
"type": "string"
}
},
{
"name": "correlationId",
"in": "query",
"description": "A free-form identifier that will be logged with this query if any logging occurs.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CapabilitiesResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/v1/certificate-authorities/{caId}/capabilities/{name}": {
"get": {
"tags": [
"certificate-authority"
],
"summary": "A capability.",
"description": "<h3>Overview</h3>\n<p>Gets a specified capability by full capability name. The full capability name consists of the category name, a dot, and the capability name. For example, certificates.SearchBySerial</p>\n",
"operationId": "caCapability",
"parameters": [
{
"name": "caId",
"in": "path",
"description": "ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.",
"required": true,
"example": "CA-1001",
"schema": {
"type": "string"
}
},
{
"name": "name",
"in": "path",
"description": "Name of a capability.",
"required": true,
"example": "EnrollmentByCSR",
"schema": {
"type": "string"
}
},
{
"name": "correlationId",
"in": "query",
"description": "A free-form identifier that will be logged with this query if any logging occurs.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CapabilityResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/v1/certificate-authorities/{caId}/profiles": {
"get": {
"tags": [
"certificate-authority"
],
"summary": "Certificate profiles for this CA.",
"description": "<h3>Overview</h3>\r\n<p>A Certificate Profile describes a particular type of certificate intended for a particular purpose. For example, a device authentication certificate profile defines a certificate for authenticating devices over a network. For another example, an S/MIME email encryption certificate profile defines a certificate for encrypting email messages. Each certificate request is associated with one certificate profile, and the certificate returned will reflect the purpose defined by the certificate profile. Each Certificate Profile contains information that must be provided by the client in the certificate request, such as naming information. Each Certificate Profile also specifies information used to generate the certificate, such as algorithms, key lengths, policy, and so on. Each Certificate Profile has a unique identifying name within the API.</p>\r\n",
"operationId": "certificateProfiles",
"parameters": [
{
"name": "caId",
"in": "path",
"description": "ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.",
"required": true,
"example": "CA-1001",
"schema": {
"type": "string"
}
},
{
"name": "correlationId",
"in": "query",
"description": "A free-form identifier that will be logged with this query if any logging occurs.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfilesResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/v1/certificate-authorities/{caId}/profiles/{profileId}": {
"get": {
"tags": [
"certificate-authority"
],
"summary": "A Certificate Profile.",
"description": "<h3>Overview</h3>\r\n\r\n<p>A Certificate Profile describes a particular type of certificate intended for a particular purpose. For example, a device authentication certificate profile defines a certificate for authenticating devices over a network. For another example, an S/MIME email encryption certificate profile defines a certificate for encrypting email messages. Each certificate request is associated with one certificate profile, and the certificate returned will reflect the purpose defined by the certificate profile. Each Certificate Profile can contain information that must be provided by the client in the certificate request, such as naming information. Each Certificate Profile also specifies information used to generate the certificate, such as algorithms, key lengths and so on. Also included may be CA policy information such as whether the private key will be backed up and whether the key pair must be generated by the client or by the CA. Such policy information can be used by the client to avoid enrolment errors. Each Certificate Profile has a unique identifying name within the API.</p>\r\n",
"operationId": "certificateProfile",
"parameters": [
{
"name": "caId",
"in": "path",
"description": "ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.",
"required": true,
"example": "CA-1001",
"schema": {
"type": "string"
}
},
{
"name": "profileId",
"in": "path",
"description": "ID of the profile.",
"required": true,
"example": "11111111-2222-3333-4444-555555555555",
"schema": {
"type": "string"
}
},
{
"name": "correlationId",
"in": "query",
"description": "A free-form identifier that will be logged with this query if any logging occurs.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/v1/certificate-authorities/{caId}/status": {
"get": {
"tags": [
"certificate-authority"
],
"summary": "The status of this CA.",
"description": "<h3>Overview</h3>\r\n<p>Returns whether the CA is up or down.</p>",
"operationId": "status",
"parameters": [
{
"name": "caId",
"in": "path",
"description": "ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.",
"required": true,
"example": "CA-1001",
"schema": {
"type": "string"
}
},
{
"name": "correlationId",
"in": "query",
"description": "A free-form identifier that will be logged with this query if any logging occurs.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CAStatusResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/v1/certificate-authorities/{caId}/enrollments": {
"post": {
"tags": [
"enrollment"
],
"summary": "Request a certificate or credential.",
"description": "<h3>Overview</h3>\r\n\r\n<p>The following enrollment use cases are supported:</p>\r\n\r\n<ul> \r\n<li>For client generated keys, the API supports Certificate Signing Request (CSR) submission in PKCS#10 format, either Base64 or PEM encoded. The CSR must be supplied to this API method along with the required naming information as specified in the Certificate Profile. Specific extensions may also be requested in the CSR body. These extensions may or may not be honored according to the policy enforced by the CA Gateway and underlying CA (see Roles below).</li>\r\n<li>For server-generated, backed-up private keys, the API supports PKCS #12 retrieval. No CSR is required, and the keys will be generated by the CA and returned in the PKCS #12. The client must supply a passcode that will be used to protect the returned PKCS #12.</li>\r\n</ul>\r\n\r\n<p>Certificate Subject DN information will be used from the following locations in the specified order subject to CA capabilities and whether provided in the request:</p>\r\n<ul>\r\n<li>optionalCertificateRequestDetails/subjectDn</li>\r\n<li>subjectVariables</li>\r\n<li>Subject DN field in a supplied CSR</li>\r\n</ul>\r\n</p>\r\n\r\n<p>In all enrollment use cases, Subject Alternative Names may be supplied.</p>\r\n\r\n<p>Note that clients who are acting under a Policy Constrained Role are <b>not</b> able to override values for the following:</p>\r\n<ul>\r\n<li>optionalCertificateRequestDetails/extensions (default is determined by CA policy)</li>\r\n<li>optionalCertificateRequestDetails/validityPeriod (default is determined by CA policy)</li>\r\n<li>optionalCertificateRequestDetails/privateKeyUsagePercentage (default is determined by CA policy)</li>\r\n<li>optionalCertificateRequestDetails/encodedPublicKey (public key can be supplied in CSR only)</li>\r\n<li>optionalCertificateRequestDetails/performPOP (default is true, a proof-of-possession check will always be performed)</li>\r\n</ul>\r\n",
"operationId": "certificatesEnroll",
"parameters": [
{
"name": "caId",
"in": "path",
"description": "ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.",
"required": true,
"example": "CA-1001",
"schema": {
"type": "string"
}
},
{
"name": "correlationId",
"in": "query",
"description": "A free-form identifier that will be logged with this query if any logging occurs.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful enrollment.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrollmentResponse"
}
}
}
},
"201": {
"description": "Enrollment accepted.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrollmentResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrollmentRequest"
}
}
},
"description": "Enrollment request."
}
}
},
"/v1/certificate-authorities/{caId}/recoveries": {
"post": {
"tags": [
"recovery"
],
"summary": "Recover a certificate and key.",
"description": "<h3>Overview</h3>\r\n\r\n<p>The CA keeps a secure copy of the private key for certificate profiles that identify the key as being backed up. The CA typically keeps a secure copy of the private key for encryption keys and certificates such as dual-usage S/MIME certificates. For these keys and certificates, losing the private key would result in losing the business data that was protected with it, such as secure email content. After losing a private key, it is possible to engage in a recovery process to recover the key and certificate. The recovery operation requires the client to supply the Subject DN and optionally the certificate profile name. If no certificate profile is referenced, then all keys and certificate types belonging to the subject will be recovered. The recovered keys and certificates are returned to the client in a PKCS #12-formatted response. A passcode must be supplied to the API. The passcode will be used to protect the private keys inside the PKCS #12 response.</p>\r\n",
"operationId": "certificateRecover",
"parameters": [
{
"name": "caId",
"in": "path",
"description": "ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.",
"required": true,
"example": "CA-1001",
"schema": {
"type": "string"
}
},
{
"name": "correlationId",
"in": "query",
"description": "A free-form identifier that will be logged with this query if any logging occurs.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful recovery.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryResponse"
}
}
}
},
"201": {
"description": "Recovery request accepted.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoveryRequest"
}
}
},
"description": "Recovery request."
}
}
},
"/v1/certificate-authorities/{caId}/certificate-events": {
"get": {
"tags": [
"certificate-events"
],
"summary": "A list of certificates events.",
"description": "Returns a paged set of events related to changes in certificate state",
"operationId": "certificate-events",
"parameters": [
{
"name": "caId",
"in": "path",
"description": "ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.",
"required": true,
"example": "CA-1001",
"schema": {
"type": "string"
}
},
{
"name": "preferredPageSize",
"in": "query",
"description": "The preferred number of certificate event records to return. If nextPageIndex is provided this value is ignored. Note that the actual number returned may not be equal to this and may even be zero, even if there are still more pages available.",
"required": false,
"example": "1000",
"schema": {
"type": "integer"
}
},
{
"name": "startDate",
"in": "query",
"description": "The starting point for the event search in ISO 8601 Datetime format. If nextPageIndex is provided this value is ignored.",
"required": false,
"example": "2019-10-31T00:00:00+00:00",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "nextPageIndex",
"in": "query",
"description": "An opaque index to include in the call for the next page. This was returned in the call for the previous page.",
"required": false,
"example": "opaque data",
"schema": {
"type": "string"
}
},
{
"name": "correlationId",
"in": "query",
"description": "A free-form identifier that will be logged with this query if any logging occurs.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CertificateEventsResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/v1/certificate-authorities/{caId}/subjects": {},
"/v1/certificate-authorities/{caId}/profiles/{profileId}/subjects": {
"post": {
"tags": [
"subject"
],
"summary": "Request a subject name.",
"description": "<h3>Overview</h3>\r\n<p>Constructs a subject DN based on the supplied request parameters. This operation is idempotent.</p>\r\n<p>The DN will be constructed based on the supplied name-value pairs in the order that they are received.</p>\r\n",
"operationId": "subjectRequest",
"parameters": [
{
"name": "caId",
"in": "path",
"description": "ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.",
"required": true,
"example": "CA-1001",
"schema": {
"type": "string"
}
},
{
"name": "profileId",
"in": "path",
"description": "The identifier of the profile used to generate the subject.",
"required": true,
"example": "CA-PROF-1001",
"schema": {
"type": "string"
}
},
{
"name": "correlationId",
"in": "query",
"description": "A free-form identifier that will be logged with this query if any logging occurs.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubjectResponse"
}
},
"SubjectResponse": {
"examples": {
"response": {
"value": {
"type": "SubjectResponse",
"subject": {
"dn": "dn=User,ou=CA01,o=Example,c=US"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubjectRequest"
}
}
},
"description": "Subject request."
}
}
},
"/v1/certificate-authorities/{caId}/subjects/{dn}": {
"get": {
"tags": [
"subject"
],
"summary": "Look up subject by DN.",
"description": "<h2>Overview</h2>\n\n<p>Certificates can be looked up by Subject DN. This operation is useful when you know the Subject DN of the certificate that you want to perform an action on, and you need the serial number to perform that action.</p>\n\n<h2>Response</h2>\n\n<p>The response contains a subject. Each subject has the DN, a list of serial numbers, and optionally a list of certificates.</p>\n",
"operationId": "subject",
"parameters": [
{
"name": "caId",
"in": "path",
"description": "ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.",
"required": true,
"example": "CA-1001",
"schema": {
"type": "string"
}
},
{
"name": "dn",
"in": "path",
"description": "DN of the subject.",
"required": true,
"example": "cn=testuser,ou=CA01,o=Example,c=US",
"schema": {
"type": "string",
"format": "string"
}
},
{
"name": "$fields",
"in": "query",
"description": "<p>The $fields parameter allows you to specify which fields to return.</p>\n\n<p>Currently, the subject in the subject response can contain the following fields:</p>\n<ul>\n<li>subject.dn. This field is required.</li>\n<li>subject.serialNumbers. This field is included by default.</li>\n<li>subject.certificates. This field is excluded by default.</li>\n</ul>\n\n<p>Currently, the only valid options for this field are:</p>\n<ul>\n<li>-subject.serialNumbers - To exclude the serialNumbers field.</li>\n<li>subject.certificates - To include the certificates field.</li>\n</ul>\n<p>All other values will be ignored. By default, the certificates in the certificates field will include all details.</p>",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "correlationId",
"in": "query",
"description": "A free-form identifier that will be logged with this query if any logging occurs.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubjectResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/v1/certificate-authorities/{caId}/subjects/{dn}/actions": {
"post": {
"tags": [
"subject"
],
"summary": "Perform action by DN.",
"description": "<h3>Overview</h3>\r\n<p>After certificates have been issued, it is possible to publicly change their trust status by making revocation, hold, or unhold requests to the API. These requests will cause the CA to alter its published revocation list. The CA periodically signs its revocation list and makes it available to relying parties. Additionally, the user entry itself can be deactivated and the certificates can be put on hold or revoked. Certificates requiring a status change are uniquely identified by the CA ID and the subject DN, both of which are supplied as path parameters to <code>POST /v1/certificate-authorities/{caId}/subjects/{dn}/actions</code>.</p>\r\n<p>Performing actions by DN will potentially affect the state of multiple certificates. Any failures or warnings associated with individual certificate state changes will not result in the whole operation failing. The caller should inspect the returned message/details array where any problems associated with individual certificates will be reported. For example if the CA has issued three certificates for the same DN and two are on hold but one is valid, then an attempt to unhold these certificates by DN will result in a COMPLETED status with one warning contained in the message/details section of the ActionResponse.</p>\r\n<p><b>Note</b>: If a DN change is in progress but has not yet been completed by the user, the user and certificate information have not been fully migrated over from the previous DN to the new DN. If a DN change is in progress, the REST client may provide the new DN in the request, and the requested action will be applied to the previous DN.</p>\r\n\r\n<h3>Body</h3>\r\n<p>The POST body is one of: </p>\r\n<ul>\r\n<li>RevokeAction</li>\r\n<li>HoldAction</li>\r\n<li>UnholdAction</li>\r\n<li>DeactivateAction</li>\r\n<li>ReactivateAction</li>\r\n</ul>",
"operationId": "subjectActions",
"parameters": [
{
"name": "caId",
"in": "path",
"description": "ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.",
"required": true,
"example": "CA-1001",
"schema": {
"type": "string"
}
},
{
"name": "dn",
"in": "path",
"description": "DN of the subject.",
"required": true,
"example": "cn=testuser,ou=CA01,o=Example,c=US",
"schema": {
"type": "string",
"format": "string"
}
},
{
"name": "correlationId",
"in": "query",
"description": "A free-form identifier that will be logged with this query if any logging occurs.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActionResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActionRequest"
}
}
},
"description": "Action request."
}
}
},
"/v1/certificate-authorities/{caId}/certificates/{serial}": {
"get": {
"tags": [
"certificate"
],
"summary": "Look up certificate by serial number.",
"description": "<h3>Overview</h3>\r\n\r\n<p>Certificates can be looked up by their serial number. The serial number must be in hexadecimal format.</p> \r\n",
"operationId": "certificate",
"parameters": [
{
"name": "caId",
"in": "path",
"description": "ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.",
"required": true,
"example": "CA-1001",
"schema": {
"type": "string"
}
},
{
"name": "serial",
"in": "path",
"description": "The certificate serial number of the certificate, in hexadecimal format. A certificate issued to a known subject DN can be queried using the <code>GET /v1/certificate-authorities/{caId}/subjects/{dn}</code> API.",
"required": true,
"example": "00112233",
"schema": {
"type": "string",
"format": "string"
}
},
{
"name": "$fields",
"in": "query",
"description": "<p>The $fields parameter allows you to specify which fields to return.</p>\r\n\r\n<p>Currently, only the following extra fields can be requested:</p>\r\n\r\n<ul>\r\n<li>chain - returns the CA certificate chain starting with the issuing CA and ending in the root CA.</li>\r\n</ul>\r\n\r\n<p>None of these fields are returned by default. All other fields are returned by default.</p>",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "correlationId",
"in": "query",
"description": "A free-form identifier that will be logged with this query if any logging occurs.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CertificateResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/v1/certificate-authorities/{caId}/certificates/{serial}/actions": {
"post": {
"tags": [
"certificate"
],
"summary": "Request an action on a certificate.",
"description": "<h3>Overview</h3>\r\n\r\n<p>After certificates have been issued, it is possible to publicly change their trust status by making revocation, hold, and unhold requests to the API. These requests will cause the CA to alter its published revocation list, which it periodically signs and makes available to relying parties. Certificates requiring a status change are uniquely identified by the CA ID and the serial number, both of which are supplied as path parameters to the POST /v1/certificate-authorities/{caId}/certificates/{serial}/actions.</p>\r\n\r\n<p>To list the supported CA-specific certificate actions, run the GET /v1/certificate-authorities/{caId}/capabilities/{name} call with name set to certificate.CertificateAction. Parameters for the CA-specific actions can be sent as properties.</p>\r\n\r\n<h3>Body</h3>\r\n\r\n<p>The POST body is one of: RevokeAction, HoldAction, UnholdAction or any supported CA-specific action.</p>\r\n",
"operationId": "certActionRequest",
"parameters": [
{
"name": "caId",
"in": "path",
"description": "ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.",
"required": true,
"example": "CA-1001",
"schema": {
"type": "string"
}
},
{
"name": "serial",
"in": "path",
"description": "The certificate serial number of the certificate, in hexadecimal format. A certificate issued to a known subject DN can be queried using the <code>GET /v1/certificate-authorities/{caId}/subjects/{dn}</code> API.",
"required": true,
"example": "00112233",
"schema": {
"type": "string",
"format": "string"
}
},
{
"name": "correlationId",
"in": "query",
"description": "A free-form identifier that will be logged with this query if any logging occurs.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Action complete.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActionResponse"
}
}
}
},
"202": {
"description": "Action accepted.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActionResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActionRequest"
}
}
}
}
}
}
},
"components": {
"responses": {
"NotFound": {
"description": "The specified resource was not found.",
"headers": {
"X-API-Version": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"Unauthorized": {
"description": "Unauthorized.",
"headers": {
"X-API-Version": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"InternalError": {
"description": "An internal error occurred on the gateway.",
"headers": {
"X-API-Version": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"NotImplemented": {
"description": "Operation is not implemented in this gateway.",
"headers": {
"X-API-Version": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"BadRequest": {
"description": "Something was wrong with the request.",
"headers": {
"X-API-Version": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"schemas": {
"BaseResponse": {
"type": "object",
"x-extendedDiscriminator": {
"propertyName": "type"
},
"properties": {
"type": {
"description": "Indicates the type of object response.",
"type": "string"
},
"message": {
"$ref": "#/components/schemas/ResponseMessage"
}
},
"required": [
"type"
]
},
"ListResponse": {
"allOf": [
{
"$ref": "#/components/schemas/BaseResponse"
},
{
"type": "object",
"properties": {
"metadata": {
"$ref": "#/components/schemas/ListMetadata"
}
}
}
]
},
"ListMetadata": {
"type": "object",
"properties": {
"currentCount": {
"type": "integer"
},
"totalCount": {
"type": "integer"
},
"currentOffset": {
"type": "integer"
},
"currentLimit": {
"type": "integer"
}
}
},
"InfoResponse": {
"allOf": [
{
"$ref": "#/components/schemas/BaseResponse"
},
{
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "InfoResponse"
},
"information": {
"$ref": "#/components/schemas/Information"
}
},
"required": [
"profiles"
]
}
]
},
"Information": {
"type": "object",
"description": "Holds general information about the gateway.",
"properties": {
"version": {
"type": "string",
"description": "The version of the CA Gateway."
},
"product": {
"type": "string",
"description": "The product name of this CA Gateway implementation."
},
"specificationVersion": {
"type": "string",
"description": "The version of the CA Gateway API specification supported by this gateway."
},
"configuredCACount": {
"type": "integer",
"description": "The number of CAs currently configured in this gateway."
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the server at the time of the request."
}
}
},
"CA": {
"type": "object",
"properties": {
"id": {
"description": "The CA's globally unique ID.",
"type": "string"
},
"name": {
"type": "string",
"description": "A short name for the CA."
},
"description": {
"type": "string",
"description": "A description of the CA."
},
"status": {
"type": "string",
"description": "The status of the CA"
},
"properties": {
"type": "object",
"description": "A list of properties for this CA.",
"additionalProperties": {
"type": "string"
}
},
"certificate": {
"$ref": "#/components/schemas/Certificate"
},
"chain": {
"type": "array",
"description": "The certificate chain for the CA.",
"items": {
"$ref": "#/components/schemas/Certificate"
}
}
},
"required": [
"id",
"name"
]
},
"CAResponse": {
"allOf": [
{
"$ref": "#/components/schemas/BaseResponse"
},
{
"description": "CA response.",
"type": "object",
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "CAResponse"
},
"ca": {
"$ref": "#/components/schemas/CA"
}
},
"required": [
"ca"
]
}
]
},
"CAListResponse": {
"allOf": [
{
"$ref": "#/components/schemas/ListResponse"
},
{
"description": "A response containing a list of CAs available through this CA Gateway that the API user has permissions to use.",
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "CAListResponse"
},
"caList": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CA"
}
}
},
"required": [
"caList"
]
}
]
},
"ProfilesResponse": {
"allOf": [
{
"$ref": "#/components/schemas/ListResponse"
},
{
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "ProfilesResponse"
},
"profiles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Profile"
}
}
},
"required": [
"profiles"
]
}
]
},
"ProfileResponse": {
"allOf": [
{
"$ref": "#/components/schemas/BaseResponse"
},
{
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "ProfileResponse"
},
"profile": {
"$ref": "#/components/schemas/Profile"
}
},
"required": [
"profile"
]
}
]
},
"Profile": {
"description": "Describes a certificate profile configuration.",
"type": "object",
"properties": {
"name": {
"type": "string"
},
"id": {
"description": "A unique identifier for this profile.",
"type": "string"
},
"protocols": {
"type": "array",
"description": "The array of enrollment protocols to which this profile applied. Currently this protocol will be the API only, but in the future may encompass other enrollment protocols such as SCEP, EST, CMPv2, and so on.",
"items": {
"type": "string"
}
},
"subjectVariableRequirements": {
"type": "array",
"description": "The list of naming variables that must be filled in and returned by the client in any enrollment request that references this profile. The values of the supplied variables will be used to form the Subject DN of the issued certificate.",
"items": {
"$ref": "#/components/schemas/PropertyRequirement"
}
},
"subjectAltNameRequirements": {
"type": "array",
"description": "The list of Subject Alternative Name values that must be be filled in by the client. Note that this list is only the mandatory Subject Alternative Names and it may be empty. The client is entitled to supply Subject Alternative Names that are not on this list which may be included in the issued certificate. Client-supplied Subject Alternative Names are subject to CA policy.",
"items": {
"$ref": "#/components/schemas/SubjectAltNameRequirement"
}
},
"requestedProperties": {
"description": "A list of any additional properties that can be filled in by the client during an enrollment request. The list may be empty. These properties are not added to the certificate or credential, but may have some meaning to the CA behind the CA Gateway. Some properties may be required by the CA for enrollment.",
"type": "array",
"items": {
"$ref": "#/components/schemas/PropertyRequirement"
}
},
"properties": {
"type": "object",
"description": "<p>Additional properties that may have specific meaning to the CA such as certificate policy information.</p>\r\n\r\n<p>Example certificate policy properties:</p>\r\n\r\n<ul>\r\n<li>key_usage - <q>encryption</q>, <q>verification</q> or <q>both</q> where <q>both</q> indicates a dual usage type certificate.</li>\r\n<li>key_type - The public key algorithm. Examples include: RSA-1024 RSA-2048 RSA-3072 RSA-4096 RSA-6144 DSA-1024 ECDSA-192 EC-P-192 EC-P-224 EC-P-256 EC-P-384 EC-P-521 EC-brainpoolP160r1 EC-brainpoolP160t1 EC-brainpoolP192r1 EC-brainpoolP192t1 EC-brainpoolP224r1 EC-brainpoolP224t1 EC-brainpoolP256r1 EC-brainpoolP256t1 EC-brainpoolP320r1 EC-brainpoolP320t1 EC-brainpoolP384r1 EC-brainpoolP384t1 EC-brainpoolP512r1 EC-brainpoolP512t1 EC-ansix9p160k1 EC-ansix9p160r1 EC-ansix9p160r2 EC-ansix9p192k1 EC-ansix9p192r1 EC-ansix9p224k1 EC-ansix9p224r1 EC-ansix9p256k1 EC-ansix9p256r1 EC-ansix9p384r1 EC-ansix9p521r1.</li>\r\n<li>key_backup - <q>true</q> if the CA policy determines that the private key will be backed up for potential subsequent recovery.</li>\r\n<li>key_client_generated - <q>true</q> if the key pair should be generated by the client and therefore supplied in the enrollment request. If <q>false</q> then no public key should be supplied in the enrollment request.</li>\r\n</ul>",
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"name",
"protocols",
"subjectVariableRequirements",
"properties"
]
},
"CertificateEventsResponse": {
"allOf": [
{
"$ref": "#/components/schemas/ListResponse"
},
{
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "CertificateEventsResponse"
},
"morePages": {
"type": "boolean",
"description": "Indicates whether more pages are currently available."
},
"nextPageIndex": {
"type": "string",
"description": "An opaque index to include in the call for the next page."
},
"events": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CertificateEvent"
}
}
},
"required": [
"events"
]
}
]
},
"CertificateEvent": {
"description": "A certificate state change event.",
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "The action associated with this user certificate status event",
"enum": [
"issued",
"hold",
"unhold",
"revoked",
"unknown",
"ready",
"active",
"reissued",
"renewed",
"expired",
"deactivated"
]
},
"event": {
"type": "integer",
"description": "An integer representing the type of event triggered"
},
"eventDate": {
"type": "string",
"format": "date-time",
"description": "The date at which the event associated with this user certificate status entry occurred"
},
"certificate": {
"type": "string",
"format": "base64",
"description": "The certificate associated with this user certificate status event"
},
"serialNumber": {
"type": "string",
"description": "The serial number in hexadecimal format of the certificate associated with this user certificate status event."
},
"detail": {
"type": "string",
"description": "Optional detail associated with this user certificate status event"
},
"reason": {
"$ref": "#/components/schemas/RevocationReason"
}
},
"required": [
"action",
"event",
"eventDate",
"serialNumber"
]
},
"PropertyRequirement": {
"description": "An entry in the subject DN, and whether it is required or not.",
"type": "object",
"properties": {
"name": {
"description": "Name of the requirement. This is the name used to specify this property when enrolling with the CA.",
"type": "string"
},
"description": {
"type": "string"
},
"required": {
"type": "boolean"
}
},
"required": [
"name",
"required"
]
},
"SubjectAltNameRequirement": {
"description": "A SubjectAltName entry type, and whether it is required or not.",
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/SubjectAltNameType"
},
"required": {
"type": "boolean"
}
},
"required": [
"nameType",
"required"
]
},
"Protection": {
"description": "Describes the means of protecting a payload, such as a PKCS #12 file. The following types of protection are supported: <code>PasswordProtection</code> and <code>CertificateProtection</code>. This class should not be used directly, but rather one of its subclasses. The subclass in use is identified by the <code>type</code> field.",
"type": "object",
"discriminator": {
"propertyName": "type"
},
"properties": {
"type": {
"type": "string",
"description": "Must be the name of a subclass of Protection. The subclasses are: PasswordProtection and CertificateProtection. "
}
},
"required": [
"type"
],
"example": {
"type": "PasswordProtection",
"password": "S3cret"
}
},
"PasswordProtection": {
"allOf": [
{
"$ref": "#/components/schemas/Protection"
},
{
"description": "Protect the payload with a password.",
"type": "object",
"properties": {
"password": {
"type": "string",
"format": "password"
}
},
"required": [
"password"
]
}
]
},
"CertificateProtection": {
"allOf": [
{
"$ref": "#/components/schemas/Protection"
},
{
"description": "Protect the payload with a certificate.",
"type": "object",
"properties": {
"certificate": {
"type": "string",
"format": "base64"
}
},
"required": [
"certificate"
]
}
]
},
"SubjectVariable": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"type",
"value"
]
},
"EnrollmentRequest": {
"description": "An enrollment request for a certificate.",
"type": "object",
"properties": {
"profileId": {
"description": "<p>The unique Certificate Profile name covering the required certificate type. A list of available certificate profiles can be obtained through <code>GET /v1/certificate-authorities/{caId}/profiles</code>, and details about the Certificate Profile can then be obtained through <code>GET /v1/certificate-authorities/{caId}/profiles/{profileId}</code>.</p> ",
"type": "string"
},
"requiredFormat": {
"$ref": "#/components/schemas/CertificateFormat"
},
"subjectVariables": {
"description": "<p>A list of subject variable name-value pairs. The Subject DN is constructed from the subject variables according to the builder configured in the Certificate Profile.</p>\n<p>The Certificate Profile obtained through <code>GET /v1/certificate-authorities/{caId}/profiles/{profileId}</code> will specify the list of subject variables that must be populated by the client when submitting the request. The values are then used by the CA to form the full Subject DN that will go into the issued certificate.</p>\n<p>Subject variable types are case sensitive and should match the case in the Certificate Profile.</p>\n<p>For example:</p> \n<pre>\n\"subjectVariables\": [\n {\"type\":\"cn\", \"value\":\"Test User\"},\n {\"type\":\"ou\", \"value\":\"myorgunit\"},\n {\"type\":\"o\", \"value\":\"myorg\"},\n {\"type\":\"c\", \"value\":\"US\"}\n]\n\n</pre>\n",
"type": "array",
"items": {
"$ref": "#/components/schemas/SubjectVariable"
}
},
"subjectAltNames": {
"description": "<p>Optional Subject Alternative Names can be supplied. These supplied Subject Alternative Names are in addition to any included in the CSR.</p>\r\n<p>For example, an S/MIME email certificate request will typically include an \"rfc822Name\" email address, whereas a network device or web server authentication certificate used for TLS would contain \"dNSName\" or \"iPAddress\". TLS handshake rules require that a server certificate must contain a \"dNSName\" or \"iPAddress\" that matches the URL used by the client.</p>\r\n<p>The following Subject Alternative Name types require a simple string value to be supplied as the \"value\" field:\r\n<ul> \r\n<li>rfc822Name, e.g. type: \"rfc822Name\", value: \"john.doe@example.com\"</li>\r\n<li>dNSName, e.g. type: \"dNSName\", value: \"server.example.com\"</li>\r\n<li>directoryName, e.g. type: \"directoryName\", value: \"cn=john doe,o=example inc,c=us\"</li>\r\n<li>uniformResourceIdentifier, e.g. type: \"uniformResourceIdentifier\", value: \"http://example.com/\"</li>\r\n<li>iPAddress, e.g. type: \"iPAddress\", value: \"192.168.1.1\"</li>\r\n<li>registeredID, e.g. type: \"registeredID\", value: \"1.2.3.4.5.6.7.8\"</li>\r\n</ul> \r\n<p>Requests for the above six types should include both \"type\" and \"value\" string fields.</p>\r\n<p>The \"otherName\" type consists of an unbounded number of possible subtypes which often cannot be represented as simple strings. When requesting a Subject Alternative Name of the otherName type supply the Base64/DER encoded GeneralName structure for the Subject Alternative Name in the \"der\" field. The string \"value\" field should be omitted.</p>\r\n<ul> \r\n<li>otherName, e.g. type: \"registeredID\", der: \"oBgGCCsGAQUFBwgDoAwwCgwIMTIzNDU2Nzg=\"</li>\r\n</ul>\r\n<p>The above \"der\" represents the following GeneralName ASN.1 structure which in turn is of the permanentIdentifier otherName type:</p>\r\n<p>&nbsp;[0] (2 elem)<br>\r\n&nbsp;&nbsp;OBJECT IDENTIFIER 1.3.6.1.5.5.7.8.3<br>\r\n&nbsp;&nbsp;&nbsp;[0] (1 elem)<br>\r\n&nbsp;&nbsp;&nbsp;&nbsp;SEQUENCE (1 elem)<br>\r\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;UTF8String 12345678<br>\r\n</p>\r\n<p>The Subject Alternative Name types \"ediPartyName\" and \"x400Address\" are not supported by this version of the CA Gateway.</p>\r\n<p>The CA may or may not allow certain Subject Alternative Names with the Certificate Profile being used.</p>\r\n",
"type": "array",
"items": {
"$ref": "#/components/schemas/SubjectAltName"
}
},
"previousSubjectDn": {
"description": "The previous subject DN. Triggers a DN change operation as part of the enrollment request, meaning any key and certificate history will be transferred.",
"type": "string"
},
"properties": {
"description": "A list of additional non-certificate properties. These properties may have been requested by the CA. Some properties may be required by the CA. The client can send additional properties that have not been requested, but there is no guarantee that they will have any effect.",
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"csr": {
"description": "<p>Optional Certificate Signing Request (CSR) in PKCS #10 format. If the certificate profile indicates that client key generation is required, then the CSR should be supplied. Typically, the CSR will be generated by the device, end entity, or software requiring the certificate. The CSR should contain the public key being certified. Extension requests are optional, and may or may not be processed according to the CA's policy. The Subject DN inside the CSR will be ignored. The certificate Subject DN will be formed using the supplied values for the subjectVariables (see below).</p>",
"type": "string",
"format": "base64"
},
"includeCa": {
"description": "A Boolean indication of whether to include CA certificates in a PKCS #12 response. This is applicable only when requiredFormat is PKCS12.",
"type": "boolean",
"default": true
},
"optionalCertificateRequestDetails": {
"$ref": "#/components/schemas/CertificateRequestDetails"
}
},
"required": [
"profileId",
"requiredFormat"
]
},
"CertExtension": {
"type": "object",
"properties": {
"oid": {
"type": "string",
"description": "The extension's OID in dotted decimal form."
},
"critical": {
"type": "boolean",
"default": false
},
"value": {
"type": "string",
"format": "base64",
"description": "The extension itself in ASN.1 DER format, encoded in Base64."
}
}
},
"SubjectAltName": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/SubjectAltNameType"
},
"value": {
"description": "The name portion of the Subject Alternative Name.",
"type": "string"
},
"der": {
"description": "A Base64-encoded Subject Alternative Name DER.",
"type": "string",
"format": "base64"
}
}
},
"SubjectAltNameType": {
"description": "The type of Subject Alternative Name.",
"type": "string",
"enum": [
"otherName",
"rfc822Name",
"dNSName",
"x400Address",
"directoryName",
"ediPartyName",
"uniformResourceIdentifier",
"iPAddress",
"registeredID"
]
},
"CertificateRequestDetails": {
"description": "Optional certificate request details section.",
"type": "object",
"properties": {
"subjectDn": {
"description": "The complete subject DN as a string.",
"type": "string"
},
"extensions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CertExtension"
}
},
"validityPeriod": {
"description": "The certificate validity period. An ISO 8601 date-time interval or duration indicating the \"not before\" and/or \"not after\" dates of the certificate.\r\n<br>\r\nExamples:\r\n<ul>\r\n <li>\r\n Specify the start date and expiry date:\r\n <br>\r\n \"2018-07-06T13:00Z/2019-07-06T13:00:00Z\"\r\n </li>\r\n <li>\r\n Specify the start date and a duration. Start on July 7, 2018 13:00Z with a lifetime of 1 year and 3 months:\r\n <br>\r\n \"2018-07-06T13:00Z/P1Y3M0DT0H0M\"\r\n </li>\r\n <li>\r\n Specify the expiry date and a duration. Expire on December 31, 2018 with a lifetime of 3 months (the start date will be automatically calculated):\r\n <br>\r\n \"P0Y3M0DT0H0M/2018-12-31T00:00Z\"\r\n <br>\r\n </li>\r\n <li>\r\n Specify a duration only. A lifetime of 1 year, 3 months, 10 days, 0 hours and 0 minutes. The start date will always be the current date:\r\n <br>\r\n \"P1Y3M10DT0H0M\"\r\n </li>\r\n</ul>\r\n",
"type": "string",
"format": "string"
},
"privateKeyUsagePercentage": {
"description": "The percentage of the certificate lifetime to use for the private key usage period. (Supported for X.509-formatted requests only.)",
"type": "integer",
"minimum": 1,
"maximum": 100
},
"encodedPublicKey": {
"description": "A Base64-encoded public key to be used. If supplied, then any CSR accompanying the request will be ignored.",
"type": "string",
"format": "base64"
},
"encodedPrivateKey": {
"description": "A Base64-encoded PKCS #8 private key to be used. If supplied, then any CSR accompanying the request will be ignored.",
"type": "string",
"format": "base64"
},
"forceIssuance": {
"description": "Allow the certificate to be issued even if the user is currently deactivated. Setting this option will reactivate the user and allow the certificate to be issued. This option is the equivalent of performing a Reactivate and then an enrollment.",
"type": "boolean",
"default": false
},
"useSANFromCSR": {
"description": "If true, any Subject Alternative Names contained within the submitted CSR will be used. If false, any Subject Alternative Names contained within the submitted CSR will be ignored.",
"type": "boolean",
"default": true
},
"performPOP": {
"description": "If true, a Proof-Of-Possession check will be performed on the key within the CSR.",
"type": "boolean",
"default": true
}
}
},
"CertificateFormat": {
"description": "Information about the requested format of a certificate.",
"type": "object",
"properties": {
"format": {
"description": "The certificate format. Values: PKCS12, X509 or PEM. For X509 and PEM a CSR or external public key must be supplied. For PKCS12 the keys will be generted by the CA and returned in the response.",
"type": "string"
},
"protection": {
"$ref": "#/components/schemas/Protection"
}
},
"required": [
"format"
]
},
"Action": {
"description": "An action to be performed. This class should not be used directly, but rather one of its subclasses. To specify an action, use the appropriate subclass of this class: RevokeAction, HoldAction, UnholdAction, ReactivateAction, or DeactivateAction. The type of action is specified by setting one of those names in the \\\"type\\\" field.",
"type": "object",
"discriminator": {
"propertyName": "type"
},
"example": {
"type": "RevokeAction",
"reason": "affiliationChanged",
"comment": "A comment",
"issueCrl": "true",
"properties": {
"additionalProp1": "property value 1",
"additionalProp2": "property value 2",
"additionalProp3": "property value 3"
}
},
"properties": {
"type": {
"description": "Denotes the type of action. Must be the name of a subclass of Action. Names include: RevokeAction, HoldAction, UnholdAction, ReactivateAction, and DeactivateAction.",
"type": "string"
},
"id": {
"description": "ID for the action request. This ID is generated by the server and returned in the response. If the client populates this field for a request, it is ignored.",
"type": "string"
},
"properties": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"comment": {
"description": "An optional comment to go with the action. This comment may or may not be used by the CA for things like auditing and logging.",
"type": "string"
},
"status": {
"$ref": "#/components/schemas/ActionStatus"
},
"succeedIfAlreadyInRequestedState": {
"type": "boolean",
"description": "If the target entity (that is, the certificate or user) is already in the requested state, then this option controls whether to return a success or a failure. The default is true."
},
"issueCrl": {
"type": "boolean",
"description": "Indicates whether to publish certificate revocation list."
}
},
"required": [
"type"
]
},
"RevokeAction": {
"allOf": [
{
"$ref": "#/components/schemas/Action"
},
{
"description": "An action to revoke one or more certificates.",
"example": {
"type": "RevokeAction",
"reason": "affiliationChanged",
"comment": "A comment",
"properties": {
"additionalProp1": "property value 1",
"additionalProp2": "property value 2",
"additionalProp3": "property value 3"
}
},
"properties": {
"reason": {
"$ref": "#/components/schemas/RevocationReason"
},
"comment": {
"type": "string",
"description": "An optional comment on the revocation. The comment is not included in the CRL and so is not public, but it is available in certain administration interfaces of the CA."
},
"compromiseDate": {
"type": "string",
"format": "date-time"
}
},
"required": [
"reason"
]
}
]
},
"HoldAction": {
"allOf": [
{
"$ref": "#/components/schemas/Action"
},
{
"description": "An action to hold one or more certificates.",
"example": {
"type": "HoldAction",
"comment": "A comment",
"properties": {
"additionalProp1": "property value 1",
"additionalProp2": "property value 2",
"additionalProp3": "property value 3"
}
}
}
]
},
"UnholdAction": {
"allOf": [
{
"$ref": "#/components/schemas/Action"
},
{
"description": "An action to unhold one or more certificates.",
"example": {
"type": "UnholdAction",
"comment": "A comment",
"properties": {
"additionalProp1": "property value 1",
"additionalProp2": "property value 2",
"additionalProp3": "property value 3"
}
}
}
]
},
"RenewAction": {
"allOf": [
{
"$ref": "#/components/schemas/Action"
},
{
"description": "An action to renew one or more certificates.",
"example": {
"type": "RenewAction",
"comment": "A comment",
"properties": {
"additionalProp1": "property value 1",
"additionalProp2": "property value 2",
"additionalProp3": "property value 3"
}
}
}
]
},
"ReissueAction": {
"allOf": [
{
"$ref": "#/components/schemas/Action"
},
{
"description": "An action to renew one or more certificates.",
"example": {
"type": "ReissueAction",
"comment": "A comment",
"properties": {
"additionalProp1": "property value 1",
"additionalProp2": "property value 2",
"additionalProp3": "property value 3"
}
}
}
]
},
"DeactivateAction": {
"allOf": [
{
"$ref": "#/components/schemas/Action"
},
{
"description": "An action to deactivate a user. The user will no longer be able to receive new certificates. Optionally, existing certificates can be permanently revoked or put on hold.",
"example": {
"type": "DeactivateAction",
"certificateAction": "onHold",
"comment": "A comment",
"properties": {
"additionalProp1": "property value 1",
"additionalProp2": "property value 2",
"additionalProp3": "property value 3"
}
},
"properties": {
"certificateAction": {
"$ref": "#/components/schemas/CertificateActionOnDeactivate"
},
"comment": {
"type": "string",
"description": "An optional comment for when a certificate action is optionally specified. The comment is not included in the CRL and so is not public, but it is available in certain administration interfaces of the CA."
}
}
}
]
},
"ReactivateAction": {
"allOf": [
{
"$ref": "#/components/schemas/Action"
},
{
"description": "An action to reactivate a user.",
"example": {
"type": "ReactivateAction",
"properties": {
"additionalProp1": "property value 1",
"additionalProp2": "property value 2",
"additionalProp3": "property value 3"
}
},
"properties": {
"certificateAction": {
"$ref": "#/components/schemas/CertificateActionOnReactivate"
}
}
}
]
},
"ActionRequest": {
"description": "A request for an action to be performed.",
"type": "object",
"properties": {
"action": {
"$ref": "#/components/schemas/Action"
}
},
"required": [
"action"
]
},
"Subject": {
"type": "object",
"properties": {
"dn": {
"description": "The subject DN.",
"type": "string"
},
"serialNumbers": {
"description": "A list of serial numbers belonging to this subject",
"type": "array",
"items": {
"type": "string"
}
},
"certificates": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Certificate"
}
}
},
"required": [
"dn"
]
},
"SubjectRequest": {
"description": "A request for a subject name.",
"type": "object",
"example": {
"profileId": "cacacc73-31a7-4eed-bc30-3eae3554302f",
"subjectVariables": {
"dn": "User",
"ou": "CA01",
"o": "Example",
"c": "US"
}
},
"properties": {
"subjectVariables": {
"description": "<p>A list of subject variable name-value pairs. The Subject DN is constructed from the subject variables according to the builder configured in the Certificate Profile.</p>\n<p>The Certificate Profile obtained through <code>GET /v1/certificate-authorities/{caId}/profiles/{profileId}</code> will specify the list of subject variables that must be populated by the client when submitting the request. The values are then used by the CA to form the full Subject DN that will go into the issued certificate.</p>\n<p>Subject variable types are case sensitive and should match the case in the Certificate Profile.</p>\n<p>For example:</p> \n<pre>\n\"subjectVariables\": [\n {\"type\":\"cn\", \"value\":\"Test User\"},\n {\"type\":\"ou\", \"value\":\"myorgunit\"},\n {\"type\":\"o\", \"value\":\"myorg\"},\n {\"type\":\"c\", \"value\":\"US\"}\n]\n\n</pre>\n",
"type": "array",
"items": {
"$ref": "#/components/schemas/SubjectVariable"
}
},
"csr": {
"description": "An optional PEM-encoded CSR for the subject request.",
"type": "string",
"format": "base64"
},
"metadata": {
"description": "Metadata to associate with the individual request.",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"profileId"
]
},
"SubjectResponse": {
"description": "Response to a subject query.",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponse"
},
{
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "SubjectResponse"
},
"subject": {
"$ref": "#/components/schemas/Subject"
}
},
"required": [
"subject"
]
}
]
},
"SubjectsResponse": {
"description": "Response to a subject's query.",
"allOf": [
{
"$ref": "#/components/schemas/ListResponse"
},
{
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "SubjectsResponse"
},
"subjects": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Subject"
}
}
}
}
]
},
"RevocationReason": {
"type": "string",
"enum": [
"unspecified",
"keyCompromise",
"affiliationChanged",
"superseded",
"cessationOfOperation",
"certificateHold"
]
},
"CertificateActionOnDeactivate": {
"type": "string",
"enum": [
"onHold",
"revoke"
]
},
"CertificateActionOnReactivate": {
"type": "string",
"enum": [
"cancelOnHold"
]
},
"ActionResponse": {
"description": "Response to an action operation. Contains the action.",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponse"
},
{
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "ActionResponse"
},
"action": {
"$ref": "#/components/schemas/Action"
}
},
"required": [
"action"
]
}
]
},
"ActionsResponse": {
"description": "A list of actions and their status.",
"allOf": [
{
"$ref": "#/components/schemas/ListResponse"
},
{
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "ActionsResponse"
},
"actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Action"
}
}
},
"required": [
"actions"
]
}
]
},
"Enrollment": {
"description": "An enrollment.",
"properties": {
"id": {
"description": "A unique identifier for the enrollment request.",
"type": "string"
},
"status": {
"$ref": "#/components/schemas/Status"
},
"body": {
"description": "The response object from the request, typically a certificate or PKCS #12. Encoded in Base64 format.",
"type": "string",
"format": "base64"
},
"properties": {
"type": "object",
"description": "Additional properties that may be returned such as a reference to the certificate or keys",
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"status",
"enrollmentId"
]
},
"EnrollmentResponse": {
"description": "Response to an enrollment request.",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponse"
},
{
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "EnrollmentResponse"
},
"enrollment": {
"$ref": "#/components/schemas/Enrollment"
}
}
}
]
},
"EnrollmentsResponse": {
"description": "Response to an enrollments request.",
"allOf": [
{
"$ref": "#/components/schemas/ListResponse"
},
{
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "EnrollmentsResponse"
},
"enrollments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Enrollment"
}
}
}
}
]
},
"ActionStatus": {
"type": "string",
"description": "<p>The status of an action request. If the status is ACCEPTED, then the action is still pending. If the status is REJECTED, there should be a reason for the rejection in the response's message.</p><p>This field is returned by the server. If the client supplies this field in a request, it will be ignored.</p>",
"enum": [
"ACCEPTED",
"REJECTED",
"COMPLETED"
]
},
"RecoveryRequest": {
"type": "object",
"description": "A request for certificate and key recovery.",
"properties": {
"subjectDn": {
"description": "The subject's DN.",
"type": "string"
},
"recoverAll": {
"description": "<p>If <code>true</code>, then all keys and certificate matching the other criteria will be recovered, including the full key history. The full key history is important for decrypting historical data such as old email messages.</p>\r\n\r\n<p>If <code>false</code>, then only the most recent keys and certificates of each type matching the criteria will be recovered.</p>\r\n\r\n<p>If unspecified, the default is false.</p>",
"type": "boolean"
},
"protection": {
"$ref": "#/components/schemas/Protection"
},
"properties": {
"type": "object",
"description": "Additional properties that may or may not have an effect depending on the CA and its capabilities.",
"additionalProperties": {
"type": "string"
}
},
"profileId": {
"description": "This optional parameter is used to constrain the recover operation to one specified Certificate Profile if the Subject has been issued with certificates from multiple Certificate Profiles.",
"type": "string"
},
"includeCa": {
"description": "A Boolean indication of whether to include CA certificates in the response.",
"type": "boolean",
"default": true
}
},
"required": [
"subjectDn",
"profileId"
]
},
"Recovery": {
"properties": {
"id": {
"description": "A unique identifier for the recovery request. This identifier is returned by the server. If the identifier is supplied with a request, then the identifier is ignored.",
"type": "string"
},
"status": {
"$ref": "#/components/schemas/Status"
},
"body": {
"description": "The response object from the request. The response opject is a PKCS #12 file, encoded in Base64 format.",
"type": "string",
"format": "base64"
},
"properties": {
"type": "object",
"description": "Additional properties that may be returned such as a reference to the certificate or keys",
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"status",
"id"
]
},
"RecoveryResponse": {
"description": "Response to a recovery request.",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponse"
},
{
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "RecoveryResponse"
},
"recovery": {
"$ref": "#/components/schemas/Recovery"
}
},
"required": [
"recovery"
]
}
]
},
"RecoveriesResponse": {
"description": "Response to a recoveries request.",
"allOf": [
{
"$ref": "#/components/schemas/ListResponse"
},
{
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "RecoveriesResponse"
},
"recoveries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Recovery"
}
}
}
}
]
},
"Status": {
"description": "<p>The status of the enrollment request.</p>\r\n<ul>\r\n<li>ACCEPTED - The request was accepted and the response includes the requested certificate.</li>\r\n<li>PENDING - The request was accepted but it could not be processed at this time.</li>\r\n<li>REJECTED - The request was rejected.</li>\r\n</ul>",
"type": "string",
"enum": [
"REJECTED",
"ACCEPTED",
"PENDING"
]
},
"Certificate": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"normal",
"held",
"revoked"
]
},
"versionNumber": {
"type": "string"
},
"serialNumber": {
"type": "string"
},
"signatureAlgID": {
"type": "string"
},
"issuerName": {
"type": "string"
},
"validityPeriod": {
"description": "A certificate validity period.",
"type": "string",
"format": "ISO-8601 interval"
},
"subjectName": {
"type": "string"
},
"rfc2253EncodedSubjectName": {
"description": "The RFC 2253 encoding of the subject name, where any attribute values that contain characters which require escaping are enclosed in quotation marks (without any escaping).",
"type": "string"
},
"rfc2253EscapedSubjectName": {
"description": "The RFC 2253 version of the subject name, where attribute values are escaped (using &bsol;), as per the RFC.",
"type": "string"
},
"subjectPublicKeyInfo": {
"$ref": "#/components/schemas/SubjectPublicKeyInfo"
},
"issuerUniqueIdentifier": {
"type": "string"
},
"subjectUniqueIdentifier": {
"type": "string"
},
"certificateSignatureAlg": {
"type": "string"
},
"revocationInfo": {
"$ref": "#/components/schemas/RevocationInfo"
},
"certificateData": {
"description": "The actual certificate in Base64 format. The certificate is included only if it is requested.",
"type": "string",
"format": "base64"
}
},
"required": [
"status",
"versionNumber",
"serialNumber",
"signatureAlgId",
"issuerName",
"validityPeriod",
"subjectName",
"subjectPublicKeyInfo",
"certificateSignatureAlg"
]
},
"RevocationInfo": {
"type": "object",
"properties": {
"comment": {
"type": "string"
},
"compromiseDate": {
"type": "string",
"format": "date-time"
},
"revocationDate": {
"type": "string",
"format": "date-time"
},
"reason": {
"$ref": "#/components/schemas/RevocationReason"
}
}
},
"SubjectPublicKeyInfo": {
"type": "object",
"properties": {
"publicKeyAlg": {
"type": "string"
},
"subjectPublicKey": {
"type": "string",
"format": "base64"
}
}
},
"CertificateResponse": {
"allOf": [
{
"$ref": "#/components/schemas/BaseResponse"
},
{
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "CertificateResponse"
},
"certificate": {
"$ref": "#/components/schemas/Certificate"
},
"chain": {
"description": "Optional certificate chain excluding the requested certificate. The certificate chain is included only if it is requested.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Certificate"
}
}
},
"required": [
"certificate"
]
}
]
},
"CertificatesResponse": {
"allOf": [
{
"$ref": "#/components/schemas/ListResponse"
},
{
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "CertificatesResponse"
},
"certificates": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Certificate"
}
}
},
"required": [
"certificates"
]
}
]
},
"Capability": {
"description": "Represents information for a CA. You will not receive this class directly. Instead, you will receive one of the subclasses of this class - BooleanCapability, ListCapability, or MapCapability - depending on how the capability is expressed. The \\\"type\\\" field will indicate which type to parse.",
"discriminator": {
"propertyName": "type"
},
"properties": {
"type": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"endpoint": {
"type": "string"
},
"field": {
"type": "string"
}
},
"required": [
"type",
"name"
],
"example": {
"type": "BooleanCapability",
"name": "Key Backup",
"value": true
}
},
"BooleanCapability": {
"allOf": [
{
"$ref": "#/components/schemas/Capability"
},
{
"description": "A capability that is either true or false.",
"properties": {
"value": {
"description": "The Boolean value of this capability.",
"type": "boolean"
}
},
"required": [
"value"
]
}
]
},
"ListCapability": {
"allOf": [
{
"$ref": "#/components/schemas/Capability"
},
{
"description": "A capability that specifies a list of values.",
"properties": {
"list": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"list"
]
}
]
},
"MapCapabilities": {
"allOf": [
{
"$ref": "#/components/schemas/Capability"
},
{
"description": "A capability that is an arbitrary map of properties.",
"properties": {
"properties": {
"description": "The map of properties for this capability.",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"properties"
]
}
]
},
"CapabilitiesResponse": {
"allOf": [
{
"$ref": "#/components/schemas/ListResponse"
},
{
"description": "A capabilities response.",
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "CapabilitiesResponse"
},
"capabilities": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Capability"
}
}
}
},
"required": [
"capabilities"
]
}
]
},
"CapabilityResponse": {
"allOf": [
{
"$ref": "#/components/schemas/BaseResponse"
},
{
"description": "A single capability response.",
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "CapabilityResponse"
},
"capability": {
"$ref": "#/components/schemas/Capability"
}
},
"required": [
"capability"
]
}
]
},
"ErrorMessage": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"target": {
"type": "string"
},
"value": {
"type": "string"
},
"details": {
"description": "An optional list of errors that caused this failure.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
},
"additionalProperties": {
"type": "string"
},
"required": [
"code",
"message"
]
},
"ResponseMessage": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"target": {
"type": "string"
},
"value": {
"type": "string"
},
"details": {
"description": "Additional messages that relate to this message.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ResponseMessageDetail"
}
}
},
"additionalProperties": {
"type": "string"
},
"required": [
"message"
]
},
"ResponseMessageDetail": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"target": {
"type": "string"
},
"value": {
"type": "string"
}
},
"additionalProperties": {
"type": "string"
}
},
"CAStatusResponse": {
"description": "The status of a CA.",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponse"
},
{
"properties": {
"status": {
"type": "string"
},
"serviceStatus": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
]
},
"ErrorResponse": {
"allOf": [
{
"$ref": "#/components/schemas/BaseResponse"
},
{
"properties": {
"type": {
"x-code-exclude": true,
"type": "string",
"default": "ErrorResponse"
},
"caMessage": {
"description": "An optional error message from the CA behind the gateway.",
"type": "string"
},
"error": {
"$ref": "#/components/schemas/ErrorMessage"
}
},
"required": [
"code",
"message"
]
}
]
}
}
}
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment