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 spe