Documentation Powered by ReDoc

CA Gateway (API version 1.8)

Download OpenAPI specification:Download

API Overview

The 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:

  • query available Certification Authorities (CAs)
  • query CA artifacts, such as CA certificate chains and revocation lists (CRLs)
  • query available Certificate Profiles for each CA
  • submit Enrollment Requests for certificates with client-generated or server-generated key pairs (which may or may not be backed up for subsequent recovery)
  • submit Recovery Requests for keys that have been stored by the CA
  • submit Certificate Management Requests for revoking certificates, putting certificates on hold, or taking certificates off hold (resulting in an updated CRL)

Definitions

The following terms are used throughout the documentation and the API.

Issuing Certification Authority: The CA that signs certificates and revocation lists. Each CA has a unique identifying name within the API.

Root Certification Authority: 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.

Certificate Revocation List (CRL): 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.

Certificate Profile: 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.

Subject Distinguished Name: 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".

Issuer Distinguished Name: The name in certificates that identifies the issuing CA. For example, "ou=Issuing CA, o=Example, c=US".

Subject Alternative Name: 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.

Certificate Request (PKCS #10 CSR): 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.

Common formats in the API

CA Identifier

CA Identifiers used in the URI of a request must be encoded in UTF8 and percent encoded.

Distinguished Names (DNs)

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:

  • If the DN is in the request path: cn="LastName, FirstName",ou=YourDepartment,o=YourCorp,c=US
  • If the DN is in the request body: "subjectDn": "cn=\"LastName, FirstName\",ou=mkusers,o=acmeone,c=ca"

The following characters are supported in a Subject Distinguished Name by the CA Gateway but must be RFC2253 encoded:

  • quotation marks (")
  • backslash (\\)
  • forward slash (/)
  • number sign (#)
  • percent (%)
  • question mark (?)
  • semicolon (;)

Dates and Times

  • All dates in the CA Gateway API must be in ISO 8601 format.
  • Durations shall conform to the duration section of ISO 8601.
  • Intervals shall conform to the interval section of ISO 8601.

Certificate Serial Number

When a certificate's serial number is used in an URI, the serial number must:

  • be in hexadecimal format
  • use only lowercase letters
  • contain no colons or other separators
  • be between 2 and 40 digits in length

Common Use Cases

Use Case: Submitting a CSR containing the public key to be certified.

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.

The sequence of events is typically as follows:

  1. 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.
  2. 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.
  3. The certificate is imported back into the device or software, and the device becomes operational.

During the above process, the private key never leaves the device. This enhances nonrepudiation.

Step 2 above can be accomplished over the CA Gateway API with the following sequence of API calls:

  1. Obtain a list of available CAs (GET /v1/certificate-authorities).
  2. After identifying the required CA, get the CA details including the CA certificate chain (GET /v1/certificate-authorities/{caId}).
  3. Obtain a list of certificate profiles available at the CA (GET /v1/certificate-authorities/{caId}/profiles).
  4. 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:
    • the intended usage
    • algorithms
    • the protocols that can be used to obtain the certificate (API only in this release)
    • the naming information that must be supplied when requesting a certificate using this profile
  5. 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.

In the current release, all certificates will be issued synchronously.

Use Case: Requesting S/MIME certificate in PKCS #12 format for email encryption

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.

The sequence of events is typically as follows:

  1. A PKCS #12-formatted certificate and private key is requested from the CA through the API.
  2. The CA generates the key pair and backs up the private key.
  3. The PKCS #12 is returned to the client. The private key is protected with a passcode that was supplied by the client.
  4. The PKCS #12 is installed at the point of use, such as a mobile device, email client, Web browser, and so on.

The steps above can be accomplished over the CA Gateway API in the following sequence of API calls:

  1. Obtain a list of available CAs (GET /v1/certificate-authorities).
  2. After identifying the required CA, get the CA details including the CA certificate chain (GET /v1/certificate-authorities/{caId}).
  3. Obtain a list of certificate profiles available at the CA (GET /v1/certificate-authorities/{caId}/profiles).
  4. 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:
    • the intended usage
    • algorithms
    • the protocols that can be used to obtain the certificate (API only in this release)
    • the naming information that must be supplied when requesting a certificate using this profile
  5. 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.

In the current release, all certificates will be issued synchronously.

General

General CA Gateway operations.

General information about the CA Gateway.

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.

query Parameters
correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1
/v1

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "InfoResponse",
  • "message":
    {
    },
  • "information":
    {
    }
}

CertificateAuthority

Certification Authority operations.

A list of available CAs.

Overview

Lists the CAs available through this gateway. The list will include only the CAs that the API user has permissions to use.

query Parameters
$fields
string

The $fields parameter allows you to specify which fields to return.

Currently, only the following extra fields can be requested:

  • caList.certificate - returns the CA certificate field for each CA
  • caList.certificate.certificateData - returns the certificate data field of the CA certificate for each CA
  • caList.chain - returns the CA certificate chain (excluding the CA certificate itself) for each CA
  • caList.chain.certificateData - returns the certificate data field of each certificate in the chain for each CA

None of these fields are returned by default. All other fields are returned by default.

correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities
/v1/certificate-authorities

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "CAListResponse",
  • "message":
    {
    },
  • "metadata":
    {
    },
  • "caList":
    [
    ]
}

A single CA.

Overview

Detailed information about a CA can be requested, such as:

  • CA unique ID
  • CA name
  • CA status
  • Properties such as:
    • Issuer DN
    • CA connector name
    • CA type, such as Entrust Authority Security Manager
path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

query Parameters
$fields
string

The $fields parameter allows you to specify which fields to return.

Currently, only the following extra fields can be requested:

  • ca.certificate - returns the CA certificate field
  • ca.certificate.certificateData - returns the certificate data field of the CA certificate
  • ca.chain - returns the CA certificate chain (excluding the CA certificate itself)
  • ca.chain.certificateData - returns the certificate data field of each certificate in the chain
  • ca.licenseInfo - returns license info for online CAs.

None of these fields are returned by default. All other fields are returned by default.

correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}
/v1/certificate-authorities/{caId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "CAResponse",
  • "message":
    {
    },
  • "ca":
    {
    }
}

The capabilities of the CA.

Overview

Returns a list of capabilities that a CA supports. Capabilities determine which API calls, parameter values, and features that a particular CA supports.

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.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

query Parameters
correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/capabilities
/v1/certificate-authorities/{caId}/capabilities

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "CapabilitiesResponse",
  • "message":
    {
    },
  • "metadata":
    {
    },
  • "capabilities":
    {
    }
}

A capability.

Overview

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

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

name
required
string
Example: EnrollmentByCSR

Name of a capability.

query Parameters
correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/capabilities/{name}
/v1/certificate-authorities/{caId}/capabilities/{name}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "CapabilityResponse",
  • "message":
    {
    },
  • "capability":
    {
    }
}

Certificate profiles for this CA.

Overview

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.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

query Parameters
correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/profiles
/v1/certificate-authorities/{caId}/profiles

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "ProfilesResponse",
  • "message":
    {
    },
  • "metadata":
    {
    },
  • "profiles":
    [
    ]
}

A Certificate Profile.

Overview

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.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

profileId
required
string
Example: 11111111-2222-3333-4444-555555555555

ID of the profile.

query Parameters
correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/profiles/{profileId}
/v1/certificate-authorities/{caId}/profiles/{profileId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "ProfileResponse",
  • "message":
    {
    },
  • "profile":
    {
    }
}

The status of this CA.

Overview

Returns whether the CA is up or down.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

query Parameters
correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/status
/v1/certificate-authorities/{caId}/status

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "string",
  • "message":
    {
    },
  • "status": "string",
  • "serviceStatus":
    {
    }
}

Enrollment

Enrollment operations.

A list of enrollments.

Note: This API is not implemented yet. It's designed for future use.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

query Parameters
$fields
string

Comma-separated list of fields to include in the response.

$offset
string

Used for pagination.

$limit
string

Used for pagination.

$filter
string

Used for filtering.

correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/enrollments
/v1/certificate-authorities/{caId}/enrollments

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "EnrollmentsResponse",
  • "message":
    {
    },
  • "metadata":
    {
    },
  • "enrollments":
    [
    ]
}

Request a certificate or credential.

Overview

The following enrollment use cases are supported:

  • 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).
  • 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.

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:

  • optionalCertificateRequestDetails/subjectDn
  • subjectVariables
  • Subject DN field in a supplied CSR

In all enrollment use cases, Subject Alternative Names may be supplied.

Note that clients who are acting under a Policy Constrained Role are not able to override values for the following:

  • optionalCertificateRequestDetails/extensions (default is determined by CA policy)
  • optionalCertificateRequestDetails/validityPeriod (default is determined by CA policy)
  • optionalCertificateRequestDetails/privateKeyUsagePercentage (default is determined by CA policy)
  • optionalCertificateRequestDetails/encodedPublicKey (public key can be supplied in CSR only)
  • optionalCertificateRequestDetails/performPOP (default is true, a proof-of-possession check will always be performed)

Note: To achieve a successful enrollement request, the body should at least have the three required fields: "profileId", "CSR" and "requiredFormat".

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

query Parameters
correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Request Body schema: application/json

Enrollment request.

profileId
required
string

The unique Certificate Profile name covering the required certificate type. A list of available certificate profiles can be obtained through GET /v1/certificate-authorities/{caId}/profiles, and details about the Certificate Profile can then be obtained through GET /v1/certificate-authorities/{caId}/profiles/{profileId}.

requiredFormat
required
object (CertificateFormat)

Information about the requested format of a certificate.

subjectVariables
Array of objects (SubjectVariable)

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.

The Certificate Profile obtained through GET /v1/certificate-authorities/{caId}/profiles/{profileId} 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.

Subject variable types are case sensitive and should match the case in the Certificate Profile.

For example:

"subjectVariables": [
  {"type":"cn", "value":"Test User"},
  {"type":"ou", "value":"myorgunit"},
  {"type":"o", "value":"myorg"},
  {"type":"c", "value":"US"}
]

subjectAltNames
Array of objects (SubjectAltName)

Optional Subject Alternative Names can be supplied. These supplied Subject Alternative Names are in addition to any included in the CSR.

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.

The following Subject Alternative Name types require a simple string value to be supplied as the "value" field:

  • rfc822Name, e.g. type: "rfc822Name", value: "john.doe@example.com"
  • dNSName, e.g. type: "dNSName", value: "server.example.com"
  • directoryName, e.g. type: "directoryName", value: "cn=john doe,o=example inc,c=us"
  • uniformResourceIdentifier, e.g. type: "uniformResourceIdentifier", value: "http://example.com/"
  • iPAddress, e.g. type: "iPAddress", value: "192.168.1.1"
  • registeredID, e.g. type: "registeredID", value: "1.2.3.4.5.6.7.8"

Requests for the above six types should include both "type" and "value" string fields.

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.

  • otherName, e.g. type: "registeredID", der: "oBgGCCsGAQUFBwgDoAwwCgwIMTIzNDU2Nzg="

The above "der" represents the following GeneralName ASN.1 structure which in turn is of the permanentIdentifier otherName type:

 [0] (2 elem)
  OBJECT IDENTIFIER 1.3.6.1.5.5.7.8.3
   [0] (1 elem)
    SEQUENCE (1 elem)
     UTF8String 12345678

The Subject Alternative Name types "ediPartyName" and "x400Address" are not supported by this version of the CA Gateway.

The CA may or may not allow certain Subject Alternative Names with the Certificate Profile being used.

previousSubjectDn
string

The previous subject DN. Triggers a DN change operation as part of the enrollment request, meaning any key and certificate history will be transferred.

properties
object

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.

csr
required
string <base64>

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).

includeCa
boolean

A Boolean indication of whether to include CA certificates in the enrollment response. Note that the default for this flag for PKCS12 responses is true, whereas the default for other responses is false. The chain will be returned in the most appropriate way for the requested response format. For PKCS12 formatted responses the chain will be included inside the returned PKCS12. For PEM formatted responses the chain will be included in the body with issued certificate separated by the PEM headers/footers. For X509 formatted responses the chain will be included as a separate chain array in the response.

optionalCertificateRequestDetails
object (CertificateRequestDetails)

Optional certificate request details section.

Responses

200

Successful enrollment.

201

Enrollment accepted.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

post/v1/certificate-authorities/{caId}/enrollments
/v1/certificate-authorities/{caId}/enrollments

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "profileId": "string",
  • "requiredFormat":
    {
    },
  • "subjectVariables":
    [
    ],
  • "subjectAltNames":
    [
    ],
  • "previousSubjectDn": "string",
  • "properties":
    {
    },
  • "csr": "string",
  • "includeCa": true,
  • "optionalCertificateRequestDetails":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "EnrollmentResponse",
  • "message":
    {
    },
  • "enrollment":
    {
    }
}

An enrollment request.

Note: This API is not implemented yet. It's designed for future use.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

enrollmentId
required
string <string>
Example: 11111111-2222-3333-4444-555555555555

ID of the enrollment request.

query Parameters
$fields
string

Comma-separated list of fields to include in the response.

correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/enrollments/{enrollmentId}
/v1/certificate-authorities/{caId}/enrollments/{enrollmentId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "EnrollmentResponse",
  • "message":
    {
    },
  • "enrollment":
    {
    }
}

Modify an enrollment request.

Modifies an enrollment request. This operation can be used to approve or deny a request, or perform other permitted alterations.
Note: This API is not implemented yet. It's designed for future use.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

enrollmentId
required
string <string>
Example: 11111111-2222-3333-4444-555555555555

ID of the enrollment request.

query Parameters
$fields
string

Comma-separated list of fields to include in the response.

correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

Successful recovery.

201

Recovery request accepted.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

patch/v1/certificate-authorities/{caId}/enrollments/{enrollmentId}
/v1/certificate-authorities/{caId}/enrollments/{enrollmentId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "RecoveryResponse",
  • "message":
    {
    },
  • "recovery":
    {
    }
}

Certificate

Certificate operations.

Look up certificate by serial number.

Overview

Certificates can be looked up by their serial number. The serial number must be in hexadecimal format.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

serial
required
string <string>
Example: 00112233

The certificate serial number of the certificate, in hexadecimal format. A certificate issued to a known subject DN can be queried using the GET /v1/certificate-authorities/{caId}/subjects/{dn} API.

query Parameters
$fields
string

The $fields parameter allows you to specify which fields to return.

Currently, only the following extra fields can be requested:

  • chain - returns the CA certificate chain starting with the issuing CA and ending in the root CA.

None of these fields are returned by default. All other fields are returned by default.

correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/certificates/{serial}
/v1/certificate-authorities/{caId}/certificates/{serial}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "CertificateResponse",
  • "message":
    {
    },
  • "certificate":
    {
    },
  • "chain":
    [
    ]
}

Action requests for a certificate.

Note: This API is not implemented yet. It's designed for future use.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

serial
required
string <string>
Example: 00112233

The certificate serial number of the certificate, in hexadecimal format. A certificate issued to a known subject DN can be queried using the GET /v1/certificate-authorities/{caId}/subjects/{dn} API.

query Parameters
$fields
string

Comma-separated list of fields to include in the response.

$offset
string

Used for pagination.

$limit
string

Used for pagination.

$filter
string

Used for filtering.

correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/certificates/{serial}/actions
/v1/certificate-authorities/{caId}/certificates/{serial}/actions

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "ActionsResponse",
  • "message":
    {
    },
  • "metadata":
    {
    },
  • "actions":
    [
    ]
}

Request an action on a certificate.

Overview

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.

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.

Body

The POST body is one of:

  • RevokeAction: An action to revoke one or more certificates. The reason field is required.
  • HoldAction: An action to hold one or more certificates.
  • UnholdAction: An action to unhold one or more certificates.

    • or any supported CA-specific action.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

serial
required
string <string>
Example: 00112233

The certificate serial number of the certificate, in hexadecimal format. A certificate issued to a known subject DN can be queried using the GET /v1/certificate-authorities/{caId}/subjects/{dn} API.

query Parameters
correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Request Body schema: application/json
action
required
object (Action)

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. The applicable subclasses are specified in the Body section above. The type of action is specified by setting one of those names in the "type" field.

Responses

200

Action complete.

202

Action accepted.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

post/v1/certificate-authorities/{caId}/certificates/{serial}/actions
/v1/certificate-authorities/{caId}/certificates/{serial}/actions

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "action":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "ActionResponse",
  • "message":
    {
    },
  • "action":
    {
    }
}

A certificate action request.

Note: This API is not implemented yet. It's designed for future use.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

serial
required
string <string>
Example: 00112233

The certificate serial number of the certificate, in hexadecimal format. A certificate issued to a known subject DN can be queried using the GET /v1/certificate-authorities/{caId}/subjects/{dn} API.

actionId
required
string <string>
Example: 11111111-2222-3333-4444-555555555555

ID of the action.

query Parameters
$fields
string

Comma-separated list of fields to include in the response.

correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/certificates/{serial}/actions/{actionId}
/v1/certificate-authorities/{caId}/certificates/{serial}/actions/{actionId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "ActionResponse",
  • "message":
    {
    },
  • "action":
    {
    }
}

CertificateEvents

Certificate event operations.

A list of certificates events.

Overview

The certificate-events API returns paged sets of events related to changes in certificate state. This feature of CA Gateway is intended to support the maintenance of an external inventory/database of certificates and corresponding state. The following state changes result in an event:

  • Issuance of a new certificate
  • Revocation of an existing certificate
  • Placing on hold (suspension) of an existing certificate
  • Taking off hold (unsuspension) of an existing certificate

Note that the returned events are those known to the CA and will include visible events that have been triggered out-of-band to CA Gateway via other enrollment mechanisms for example.

Clients of the certificate-events API should implement the following algorithm. This describes one round of fetching events after which the client can pause for a period before executing the next round during which new events are created at the CA.:

  • The first time calling into the certificate-events API provide the desired startDate and a preferredPageSize.
  • Subsequent times provide the value of nextPageIndex that was returned by the previous call.
  • Keep iterating until morePages returns false. Keep in mind that some pages might come back empty even when morePages is true!
  • Once morePages returns false nextPageIndex can be persisted for the next round. This will allow the returned events to commence from where was left off previously.

As the name of the parameter suggests preferredPageSize is just that, i.e. a preference of the client. CA Gateway makes no guarantee that the preference will be honored precisely. The certificate-events API may return less than that amount, more than that amount or indeed no events at all, even when morePages is true. These semantics are deliberate and allow the various CA types supported by CA Gateway leeway in how they filter and organise events internally.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

query Parameters
preferredPageSize
integer
Example: preferredPageSize=1000

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.

startDate
string <date-time>
Example: startDate=2019-10-31T00:00:00+00:00

The starting point for the event search in ISO 8601 Datetime format (e.g. 2019-10-31T00:00:00+00:00). If nextPageIndex is provided this value is ignored.

nextPageIndex
string
Example: nextPageIndex=opaque data

An opaque index to include in the call for the next page. This was returned in the call for the previous page.

correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/certificate-events
/v1/certificate-authorities/{caId}/certificate-events

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "CertificateEventsResponse",
  • "message":
    {
    },
  • "metadata":
    {
    },
  • "morePages": true,
  • "nextPageIndex": "string",
  • "events":
    [
    ]
}

CaEvents

CA event operations.

A list of CA events.

Overview

The ca-events API returns paged sets of events related to changes on the Certificate Authority (CA). This feature of CA Gateway is intended to support the monitoring, maintenance and synchronization of external in response to changes on the CA. Different CAs support different events. Some of the following state changes may result in an event:

  • Creation of a CA user
  • Deletion of a CA user

Note that the returned events are those known to the CA and will include visible events that have been triggered out-of-band to CA Gateway via other enrollment mechanisms for example.

Clients of the ca-events API should implement the following algorithm. This describes one round of fetching events after which the client can pause for a period before executing the next round during which new events are created at the CA.:

  • The first time calling into the ca-events API provide the desired startDate and a preferredPageSize.
  • Subsequent times provide the value of nextPageIndex that was returned by the previous call.
  • Keep iterating until morePages returns false. Keep in mind that some pages might come back empty even when morePages is true!
  • Once morePages returns false nextPageIndex can be persisted for the next round. This will allow the returned events to commence from where was left off previously.

As the name of the parameter suggests preferredPageSize is just that, i.e. a preference of the client. CA Gateway makes no guarantee that the preference will be honored precisely. The ca-events API may return less than that amount, more than that amount or indeed no events at all, even when morePages is true. These semantics are deliberate and allow the various CA types supported by CA Gateway leeway in how they filter and organise events internally.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

query Parameters
preferredPageSize
integer
Example: preferredPageSize=1000

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.

startDate
string <date-time>
Example: startDate=2019-10-31T00:00:00+00:00

The starting point for the event search in ISO 8601 Datetime format (e.g. 2019-10-31T00:00:00+00:00). If nextPageIndex is provided this value is ignored.

nextPageIndex
string
Example: nextPageIndex=opaque data

An opaque index to include in the call for the next page. This was returned in the call for the previous page.

correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/ca-events
/v1/certificate-authorities/{caId}/ca-events

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "CAEventsResponse",
  • "message":
    {
    },
  • "metadata":
    {
    },
  • "morePages": true,
  • "nextPageIndex": "string",
  • "events":
    [
    ]
}

Subject

Subject operations.

List of certificate subjects.

Note: This API is not implemented yet. It's designed for future use.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA.

query Parameters
$fields
string

Comma-separated list of fields to include in the response.

$offset
string

Used for pagination.

$limit
string

Used for pagination.

$filter
string

Used for filtering.

correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/subjects
/v1/certificate-authorities/{caId}/subjects

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "SubjectsResponse",
  • "message":
    {
    },
  • "metadata":
    {
    },
  • "subjects":
    [
    ]
}

Request a subject name.

Overview

Constructs a subject DN based on the supplied request parameters. This operation is idempotent.

The DN will be constructed based on the supplied name-value pairs in the order that they are received.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

profileId
required
string
Example: CA-PROF-1001

The identifier of the profile used to generate the subject.

query Parameters
correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Request Body schema: application/json

Subject request.

subjectVariables
Array of objects (SubjectVariable)

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.

The Certificate Profile obtained through GET /v1/certificate-authorities/{caId}/profiles/{profileId} 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.

Subject variable types are case sensitive and should match the case in the Certificate Profile.

For example:

"subjectVariables": [
  {"type":"cn", "value":"Test User"},
  {"type":"ou", "value":"myorgunit"},
  {"type":"o", "value":"myorg"},
  {"type":"c", "value":"US"}
]

csr
string <base64>

An optional PEM-encoded CSR for the subject request.

metadata
object

Metadata to associate with the individual request.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

post/v1/certificate-authorities/{caId}/profiles/{profileId}/subjects
/v1/certificate-authorities/{caId}/profiles/{profileId}/subjects

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "profileId": "cacacc73-31a7-4eed-bc30-3eae3554302f",
  • "subjectVariables":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "SubjectResponse",
  • "message":
    {
    },
  • "subject":
    {
    }
}

Look up subject by DN.

Overview

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.

Response

The response contains a subject. Each subject has the DN, a list of serial numbers, and optionally a list of certificates.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

dn
required
string <string>
Example: cn=testuser,ou=CA01,o=Example,c=US

DN of the subject.

query Parameters
$fields
string

The $fields parameter allows you to specify which fields to return.

Currently, the subject in the subject response can contain the following fields:

  • subject.dn. This field is required.
  • subject.serialNumbers. This field is included by default.
  • subject.certificates. This field is excluded by default.

Currently, the only valid options for this field are:

  • -subject.serialNumbers - To exclude the serialNumbers field.
  • subject.certificates - To include the certificates field.

All other values will be ignored. By default, the certificates in the certificates field will include all details.

correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/subjects/{dn}
/v1/certificate-authorities/{caId}/subjects/{dn}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "SubjectResponse",
  • "message":
    {
    },
  • "subject":
    {
    }
}

Perform action by DN.

Overview

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 POST /v1/certificate-authorities/{caId}/subjects/{dn}/actions.

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.

Note: 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.

Body

The POST body is one of:

  • RevokeAction: An action to revoke one or more certificates. The reason field is required.
  • HoldAction: An action to hold one or more certificates.
  • UnholdAction: An action to unhold one or more certificates.
  • DeactivateAction : 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.
    DeactivateAction does not revoke certificates and the user can be returned to the original state by performing the ReactivateAction.
  • ReactivateAction: An action to reactivate a user.

Note: Not all actions are applicable to all CAs.
Find out the applicable actions by invoking the GET /cagw/v1/certificate-authorities/{caId}/capabilities/{name} resource on a CA supplying {name} as "subjects.SubjectDNAction".

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

dn
required
string <string>
Example: cn=testuser,ou=CA01,o=Example,c=US

DN of the subject.

query Parameters
correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Request Body schema: application/json

Action request.

action
required
object (Action)

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. The applicable subclasses are specified in the Body section above. The type of action is specified by setting one of those names in the "type" field.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

post/v1/certificate-authorities/{caId}/subjects/{dn}/actions
/v1/certificate-authorities/{caId}/subjects/{dn}/actions

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "action":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "ActionResponse",
  • "message":
    {
    },
  • "action":
    {
    }
}

Recovery

Recovery operations.

A list of certificate recoveries.

Note: This API is not implemented yet. It's designed for future use.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

query Parameters
$fields
string

Comma-separated list of fields to include in the response.

$offset
string

Used for pagination.

$limit
string

Used for pagination.

$filter
string

Used for filtering.

correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/recoveries
/v1/certificate-authorities/{caId}/recoveries

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "RecoveriesResponse",
  • "message":
    {
    },
  • "metadata":
    {
    },
  • "recoveries":
    [
    ]
}

Recover a certificate and key.

Overview

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.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

query Parameters
correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Request Body schema: application/json

Recovery request.

subjectDn
required
string

The subject's DN.

recoverAll
boolean

If true, 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.

If false, then only the most recent keys and certificates of each type matching the criteria will be recovered.

If unspecified, the default is false.

protection
object (Protection)

Describes the means of protecting a payload, such as a PKCS #12 file. The following types of protection are supported: PasswordProtection and CertificateProtection. This class should not be used directly, but rather one of its subclasses. The subclass in use is identified by the type field.

properties
object

Additional properties that may or may not have an effect depending on the CA and its capabilities.

profileId
string

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.

includeCa
boolean
Default: true

A Boolean indication of whether to include CA certificates in the response.

Responses

200

Successful recovery.

201

Recovery request accepted.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

post/v1/certificate-authorities/{caId}/recoveries
/v1/certificate-authorities/{caId}/recoveries

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "subjectDn": "string",
  • "recoverAll": true,
  • "protection":
    {
    },
  • "properties":
    {
    },
  • "profileId": "string",
  • "includeCa": true
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "RecoveryResponse",
  • "message":
    {
    },
  • "recovery":
    {
    }
}

An enrollment request.

Note: This API is not implemented yet. It's designed for future use.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

recoveryId
required
string <string>
Example: 11111111-2222-3333-4444-555555555555

ID of the enrollment request.

query Parameters
correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/recoveries/{recoveryId}
/v1/certificate-authorities/{caId}/recoveries/{recoveryId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "RecoveryResponse",
  • "message":
    {
    },
  • "recovery":
    {
    }
}

Domain

Domain operations.

A list of all domains.

Overview

Lists the domains available for the CA through this gateway. This resource is only applicable to publicly trusted CAs. $offset and $limit can be used for paging of the results if the targetted CA is capable of paging. Similarly the $filter field can be used to send CA specific search constraints to the CAs - query the CAs "domains.Filter" capability to see what constraints are possible for the CA.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

query Parameters
$fields
string

Comma-separated list of fields to include in the response.

correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/domains
/v1/certificate-authorities/{caId}/domains

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "DomainsResponse",
  • "message":
    {
    },
  • "metadata":
    {
    },
  • "domains":
    [
    ]
}

Add a new domain.

Overview

Adds a new domain to the CA. For commercial publicly trusted CA services adding a domain is typically a billable entitlement.

Supply the following information:

  • name: The domain name, for example mydomain.com
  • verificationMethod: The verification methods are specified by the CAB forum documentation. Examples include email, webServer, dns and manual.
  • emailVerificationInfo: (Only applicable if verification method is email) The email addresses that should receive the domain verification email. If absent when verificationMethod=email the CA might use an email address from WHOIS for verification purposes.
path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

query Parameters
correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Request Body schema: application/json

Domain add request.

name
required
string

The domain name.

verificationMethod
string

For example email, webServer or dns. This is optional and non-binding as the CA may not let the client decide anyway.

emailVerificationInfo
object (VerificationInfoEmail)
properties
object

Additional properties that may or may not have an effect depending on the CA and its capabilities.

Responses

200

Successful enrollment.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

post/v1/certificate-authorities/{caId}/domains
/v1/certificate-authorities/{caId}/domains

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "string",
  • "verificationMethod": "string",
  • "emailVerificationInfo":
    {
    },
  • "properties":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "DomainResponse",
  • "message":
    {
    },
  • "domain":
    {
    }
}

Retrieves information about a single registered domain.

Information held at the CA about the domain, including domain verification information.

path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

domain
required
string
Example: entrust.com

Domain name

query Parameters
$fields
string

The $fields parameter allows you to specify which fields to return.

Currently, only the following extra fields can be requested:

  • domainGet.verificationInfo: domain verification info such as DNS email addresses, web server or DNS authentication tokens

None of these fields are returned by default. All other fields are returned by default.

correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Responses

200

OK.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

get/v1/certificate-authorities/{caId}/domains/{domain}
/v1/certificate-authorities/{caId}/domains/{domain}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "DomainResponse",
  • "message":
    {
    },
  • "domain":
    {
    }
}

Request an action on a domain.

Overview

After a domain has been added the actions resource can be used to perform actions on that domain. The list of possible actions is defined by the CA's capabilities.

To list the supported CA-specific domain actions, run the GET /v1/certificate-authorities/{caId}/capabilities/domain.DomainAction.

Currently only ReverifyDomainAction is supported.

Supply the following information:

  • type: The type of the action being performed. For example ReverifyDomainAction
  • verificationMethod: (ReverifyDomainAction only) The available verification methods is dependent on the CA. Examples include email, webServer and dns.
  • emailVerificationInfo: Applicable for ReverifyDomainAction only and if verification method is email. If absent when verificationMethod=email the CA might use an email address from WHOIS for verification purposes.
path Parameters
caId
required
string
Example: CA-1001

ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities.

domain
required
string <string>
Example: entrust.com

The domain name

query Parameters
correlationId
string

A free-form identifier that will be logged with this query if any logging occurs.

Request Body schema: application/json
action
required
object (DomainAction)

A domain 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: ReverifyDomainAction. The type of action is specified by setting one of those names in the "type" field.

Responses

200

Action complete.

202

Action accepted.

400

Something was wrong with the request.

403

Unauthorized.

404

The specified resource was not found.

500

An internal error occurred on the gateway.

501

Operation is not implemented in this gateway.

post/v1/certificate-authorities/{caId}/domains/{domain}/actions
/v1/certificate-authorities/{caId}/domains/{domain}/actions

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "action":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "DomainResponse",
  • "message":
    {
    },
  • "domain":
    {
    }
}

ErrorCodes

A List of error codes that can be produced by CAGW:

  • CAGW_4000: The specified resource was not found.
  • CAGW_4001: Could not parse CSR.
  • CAGW_4002: Could not build a valid subject name.
  • CAGW_4003: Could not find cert type configured for profile.
  • CAGW_4004: Could not find cert definition configured for profile.
  • CAGW_4005: Could not find user type configured for profile.
  • CAGW_4006: Invalid subject DN name.
  • CAGW_4007: Invalid CSR.
  • CAGW_4008: Invalid format requested.
  • CAGW_4009: Invalid protection.
  • CAGW_4010: Invalid private key.
  • CAGW_4011: Invalid JSON body.
  • CAGW_4012: Invalid HTTP request message.
  • CAGW_4013: Invalid HTTP request method.
  • CAGW_4014: Invalid profile identifier.
  • CAGW_4015: Distinguished Name not found.
  • CAGW_4016: Could not find certificate with serial number.
  • CAGW_4017: Could not find certificate with DN.
  • CAGW_4018: CA with specified name not found.
  • CAGW_4019: The certificate owner's account is in a deactivated state.
  • CAGW_4020: Unable to manage certificate.
  • CAGW_4021: There are no configured profiles for this CA.
  • CAGW_4022: A PasswordProtection object must be supplied if the requested type is PKCS12
  • CAGW_4023: An invalid action type was received.
  • CAGW_4024: Could not get the capabilities of the CA.
  • CAGW_4025: Could not get the capability.
  • CAGW_4026: Invalid certificate validity period.
  • CAGW_4027: Access Denied.
  • CAGW_4028: An enrollment request must have either a subjectVariables or subjectDn entry.
  • CAGW_4029: Both subjectVariables and subjectDn are present. Only one may be present in an enrollment request.
  • CAGW_4030: Unable to manage user.
  • CAGW_4031: 'includeCa' is only applicable for required format PKCS12.
  • CAGW_4032: Repeated subject variable given to the template subject builder. Variable names cannot be repeated when using the template subject builder.
  • CAGW_4033: Subject variable missing.
  • CAGW_4034: Missing profile identifier.
  • CAGW_4035: Invalid or missing revocation reason.
  • CAGW_4036: Invalid expression for $filter parameter.
  • CAGW_4037: Request body is empty.
  • CAGW_4038: Invalid private key usage percentage.
  • CAGW_4039: Missing value property of subject variable pair.
  • CAGW_4040: Invalid Subject Alternative Name type supplied.
  • CAGW_4041: Missing 'requiredFormat' object in enrollment.
  • CAGW_4042: Invalid request parameters.
  • CAGW_4043: Error in the configuration of one or more managed CA.
  • CAGW_4044: Missing enrollment tracking in request properties.
  • CAGW_4045: Invalid CA capability.
  • CAGW_4046: No permission to send HTTP headers.
  • CAGW_4047: Bad connector filter configuration.
  • CAGW_4048: Issuance denied.
  • CAGW_4049: Certificate Transparency error.
  • CAGW_4500: Unable to create directory entry.
  • CAGW_4501: Unsupported operation.
  • CAGW_4502: No certificate serial numbers were supplied for the certificate management operation.
  • CAGW_4503: No certificate management action supplied.
  • CAGW_4504: Invalid request, missing parameters.
  • CAGW_4505: No PKCS#12 passcode supplied.
  • CAGW_4506: Failed to validate proof of possession of private key.
  • CAGW_4507: No public key found in request.
  • CAGW_4508: Failed to parse PKCS#10 Certificate Request (CSR).
  • CAGW_4509: CSR required for proof of possession of private key.
  • CAGW_4510: Only one certificate request per message is permitted.
  • CAGW_4511: Unable to parse external Subject Alternative Name General Names structure.
  • CAGW_4512: Unable to parse external X.509 extensions structure.
  • CAGW_4513: The certificate owner's account is in a state that does not permit any operations.
  • CAGW_4514: A change DN operation has been requested, however the previous Subject DN supplied does not exist.
  • CAGW_4515: Invalid request format.
  • CAGW_4516: Warning that the certificate is already in the requested state.
  • CAGW_4517: Warning that the certificate serial number does not reference any of the certificates belonging to this subject.
  • CAGW_4518: Invalid Subject DN. The requested Subject DN is not compatible with the issuing CA.
  • CAGW_4519: No response format supplied.
  • CAGW_4520: Invalid public key in request.
  • CAGW_4521: Warning that the user is already in the requested state.
  • CAGW_4522: Unable to recover the requested keys/certificates.
  • CAGW_4523: The requested certificate definition does not match the certificate's original definition.
  • CAGW_4524: Unable to build PKCS#12.
  • CAGW_4525: Public key provided in request but policy is configured for server side key generation.
  • CAGW_4526: Invalid response format supplied.
  • CAGW_4527: The user does not have any certificates to unsuspend.
  • CAGW_4528: Failed to parse X.509 Certificate.
  • CAGW_4529: Private key provided but policy is not configured for key backup.
  • CAGW_4530: An enrollment request must have either a CSR or public and private key pair if the requested format is X509.
  • CAGW_4531: If public key is provided, private key must be provided too.
  • CAGW_4532: An enrollment request must have either a subjectVariables or subjectDn entry if the requested format is PKCS12
  • CAGW_4533: Either subjectVariables, subjectDn or CSR is required if the requested format is X509.
  • CAGW_4534: The certificate template indicates that key archival is required, but a private key was not provided.
  • CAGW_4535: No public key was supplied either inside a CSR or externally.
  • CAGW_4536: If 'publish certificate in Active Directory' is enabled, user must exist in Active Directory.
  • CAGW_4537: No certificates found for the subject DN.
  • CAGW_4538: There does not exist a user in SM Cloud CA for this Client.
  • CAGW_4539: Invalid Client Certificate. The Subject must have the RDN of type 'SERIALNUMBER'.
  • CAGW_4540: This PKIaaS CA connector is configured to use an http header but header not found or invalid.
  • CAGW_4541: Invalid Client Certificate.The client does not have the required role permission.
  • CAGW_4542: Received invalid or null RequestAttributes Object.
  • CAGW_4543: Invalid Client. The IdP for this client not found.
  • CAGW_4544: Product license violation.
  • CAGW_4545: Product license expired or not yet valid.