POST Certificates/Request

Enrolls or provisions a new certificate. If the certificate already exists, the current certificate archives to the History tab and the CA receives a new certificate request. Based on Policy tree settings, you can use a single Certificates/Request call to enroll or provision. The same request can also:

  • Create one or more devices that will use the same certificate.
  • Allow one or more applications that run on a device to use the same certificate.

  • Create a certificate for an elastic instance. After the instance terminates, a tool, such as an Instance Watcher, can automatically clean up the certificate (and associated objects). For more information, see Example 5: Provision a certificate for an EC2 instance.

  • Set Custom Field values on a Certificate object.

After a successful enrollment or provision, the certificate appears in the Policy folder. However, if the issuing CA overrode values in the CSR, for example Organization Unit (OU), some fields may be empty.

TIP  If you want an SSH certificate, call POST SSHCertificates/Request instead.

Prerequisites

In the UI, do these prerequisite tasks:

  • For enrollment and provisioning, set up the Certificate Authority template for communications with a Certificate Authority (CA).
  • For enrollment and provisioning, add a Policy folder to use as a PolicyDN. In the policy, set default values, such as the allowed SAN Types.
  • For provisioning, get the device credentials and configure an agent to install the certificate.

Requirements

  • Permissions:  The caller must have:
    • Create permission to either the PolicyDN or the system default location where the certificate will be created.
    • Private Key Read permission permission to the Certificate object .
  • Token scope:  Certificate:Manage

Headers

  • Content type: Content-Type:application/json.

  • Token: The bearer access token that you received. For example, Authorization:Bearer 4MyGeneratedBearerTknz==. For more information, see Passing a bearer token in your API calls.

Parameters

Either specify PKCS10 and the certificate that includes the public and private key pair, or specify certificate field values and allow Trust Protection Platform to create the key pair and CSR.

Input parameters

Name

Description

Format

(Optional) The certificate format:

  • Base64: Show the certificate in the traditional PEM format. The mime-type is application/x-pem-file.
  • Base64 (PKCS #8): Show the certificate in the PEM format and include the PKCS#8 encoded private key. The mime-type is application/x-pem-file.
  • DER: Show the raw certificate. Use IncludePrivateKey and set the password. The mime-type is application/x-x509-ca-cert.
  • JKS: Show the certificate in the Java Keystore (JKS) format. The mime-type is application/octet-stream.
  • PKCS #7: Show the certificate with optional chain in the PKCS#12 format. The mime-type is application/x-pkcs7-certificates.
  • PKCS #12: Show the certificate in the PKCS#12 format. Use IncludePrivateKey and set the password. The mime-type is application/x-pkcs12.

Password

If the IncludePrivateKey value is true, this value must be set.

Create a strong password by using a

  • minimum of 12 characters
  • combination of at least three of the following:
    • one or more lowercase letters
    • one or more uppercase letters
    • one or more numbers
    • one or more special characters

IncludePrivateKey

(Optional) When the Format is Base64 (PKCS #8), PKCS #12, or JKS, you can specify whether to return the private key:

  • false: No private key.
  • true: Default. Create a private key based on KeystorePassword.

IncludeChain

(Optional) When the Format is Base64, Base64, PKCS #7, PKCS #12, or JKS, you can include the parent or root chain in the return data.

  • true: Include the root chain. Use RootFirstOrder to set the order. The data appears after any private key information.
  • false: Omit the root chain.

FriendlyName

The label or alias to use for Base64, JKS, or PKCS #12 formats. Required for the JKS format.

RootFirstOrder

The order of the certificate chain of trust. Use when IncludeChain is true:

  • true: The root certificate first, followed by intermediate certificates, and finally the end entity certificate.
  • false: Default. The end entity first, followed by intermediate certificates, and finally the root certificate.

KeystorePassword

If the Format is JKS, you must set this value. Use the same requirements as required for Password.

Approvers

(Optional) An array of one or more identities for certificate workflow approvers. For more information, see How to specify Approvers and Contacts for Certificates/Request.

CADN

The Distinguished Name (DN) of the Certificate Authority Template.

CASpecificAttributes

(Optional) An array of name/value pairs providing any CA attributes to store with the Certificate object. During enrollment, the values submit to the CA. For more information, see X509 Certificate CA Specific Attributes.

CertificateType

(Optional) One of the following Certificate object types. Ignores any other value.

  • (CertificateType is absent): Default. X.509 Server Certificate.
  • Auto Set the Certificate object type automatically after enrollment. Depending on the certificate EKU, the Auto CertificateType automatically sets the Certificate object type after enrollment.
  • Code Signing: X.509 Code Signing Certificate.
  • Device: X.509 Device Certificate.
  • Server: X.509 Server Certificate.
  • User: X.509 User Certificate.

City

(Optional) The City field for the certificate Subject DN. Specify a value when requesting a centrally generated CSR.

Contacts

(Optional) An array of one or more identities for users or groups who receive notifications about events pertaining to the object. For more information, see How to specify Approvers and Contacts for Certificates/Request.

Country

(Optional) The Country field for the certificate Subject DN. Specify a value when requesting a centrally generated CSR.

CustomFields

Required when a predefined Custom Field is mandatory. Otherwise, optional. An array that sets Custom Field values on a Certificate object. Also updates hidden and read-only Custom Fields. For more information, see Example 3: Enroll a certificate and include Custom Field values.

  • Name: Case sensitive. A Custom Field that appears on a Certificate object. For more information, see Viewing custom fields.

    - AND -

  • Values: Case sensitive. An array of one or more values that match the Custom Field Type definition:

    • Date/Time with only calendar date: Use the YYYY-MM-DD format. For example, 2020-12-17.
    • Date/Time with only time of day: Use the HH:MM format. For example, 23:59.

    • Date/Time with both date and time: Specify a single value with a space separating date from time. For example, 2019-02-28 23:59.

      NOTE   Dates and times will interpret in the time zone of the VEDSDK server. Be sure to adjust the Values accordingly.

    • List: Follow the Field Type requirements. Single Select, allows only one value. Multi-Select allows more than one value. Either specify all Display Name or all Stored Value data; no mixing.

    • String: Pass a value that matches the Validation Regular Expression for this Custom Field.

    • Identity Selector: Specify an array of one or more identities, such as a group or individual approver. Use the PrefixedUniversal format that represents a valid identity. For example: AD+venqa:85e3ce9bec25b34780ebfd85a4d73451.

CreatedBy

(Optional) The person, entity, or caller of this request. The default is Web SDK. Avoid overriding the default unless the caller is a significant enterprise application that is tightly integrated with Trust Protection Platform, such as a custom web portal. To add details, use Origin instead. If you want both attributes to have the same value, set only CreatedBy.

Devices

The parameters for creating devices in the Policy tree. All specified devices will use the certificate that generates in this request:

  • Applications: (Optional) An array of one or more Application objects to allow software, which runs on ObjectName, to use the same certificate. For more information, see Certificates/Request Applications parameters for provisioning.

  • CloudInstanceID: Required for Amazon EC2 provisioning. The unique cloud instance ID.

  • CloudRegion: Required for Amazon EC2 provisioning. The geographic location where the cloud service instance resides. An instance in AWS can only exist in a single region.

  • CloudService: Required for Amazon EC2 provisioning. AWS: An Amazon E2C cloud service. Requires you to install and configure the Cloud Instance Monitoring feature.

  • ConcurrentConnectionLimit: (Optional) Maximum number of connections the device will accept from Trust Protection Platform.
  • Contacts: (Optional) An array of one or more identities who receive notifications for this device. For more information, see How to specify Approvers and Contacts for Certificates/Request.
  • CreatedBy: (Optional) The person or entity that is creating the device and any associated software applications for the device. Any value is accepted. Default is Web SDK.
  • CredentialDN: (Optional) The device credential.
  • Description: (Optional) The description for this device.
  • EnforceKnownHost: (Optional) For SSH keys. true: Enable known host key enforcement. false: Disable known host key enforcement.
  • Host: (Optional) The physical Fully Qualified Domain Name (FQDN) for the host or the IP address for a device.
  • ObjectName: (Optional) The device host name or IP address for the certificate object in Trust Protection Platform. If the value is missing, the object name is the Subject.
  • PolicyDN: Required. The folder DN for the new certificate.
  • Port: (Optional) The port number to communicate with the device.
  • SudoCredentialDN: (Optional) Use in conjunction with UseSudo. The DN that holds the password credential to be used if sudo is configured to prompt for a password when executing a command.
  • TempDirectory: (Optional) The host directory path to hold temporary files during provisioning. For example /tmp/. The folder should have the necessary write permissions.
  • TrustedFingerprint: (Optional) For Secure Shell (SSH) keys. The SSH server key fingerprint. If this value is set, and EnforceKnownHost is enabled, Trust Protection Platform will only successfully connect to the device if the hosts fingerprint matches this value.
  • UseSudo: (Optional) Use in conjunction with SudoCredentialDN. For cases where the device credentials require sudo privilege elevation to execute commands when installing the certificate on a Unix or Linux device: true: Execute commands using sudo when provisioning. false: Execute commands directly without using sudo.

DisableAutomaticRenewal

(Optional) The setting to control whether manual intervention is required for certificate renewal.

  • false: Default. Allow automatic certificate renewal.
  • true: Require manual intervention for certificate renewal.

EllipticCurve

(Optional) For Elliptic Curve Cryptography (ECC), use this parameter in conjunction with KeyAlgorithm. Specify the value that your Certificate Authority supports:

  • P256: Default. Use Elliptic Prime Curve 256 bit encryption.
  • P384: Use Elliptic Prime Curve 384 bit encryption.
  • P521: Use Elliptic Prime Curve 521 bit encryption. (not supported by all Certificate Authorities).
  • Any other value defaults to P256.

KeyAlgorithm

(Optional) The encryption algorithm for the public key:

  • RSA: Default. Rivest, Shamir, Adleman key (RSA). Use this parameter in conjunction with KeybitSize.
  • ECC: Elliptic Curve Cryptography (ECC). Use this parameter in conjunction with EllipticCurve.

KeyBitSize

(Optional) Use this parameter when KeyAlgorithm is RSA. The number of bits to allow for key generation. The default is 2048.

ManagementType

 (Optional) The level of management that Trust Protection Platform applies to the certificate:
  • Enrollment: Default. Issue a new certificate, renew certificate, or key generation request to a CA for enrollment. Do not automatically provision the certificate.
  • Monitoring: Allow Trust Protection Platform to monitor the certificate for expiration and renewal.
  • Provisioning: Issue a new certificate, renew a certificate, or send a key generation request to a CA for enrollment. Automatically install or provision the certificate.
  • Unassigned: Certificates are neither enrolled or monitored by Trust Protection Platform.

Origin

(Optional) Additional information, such as the name and version of the calling application, that describes the source of this enrollment, renewal, or provisioning request. The default is Web SDK. Works in conjunction with CreatedBy. If you want both attributes to have the same value, set only CreatedBy.

PolicyDN

Required. An existing Policy folder path that will hold information about the new certificate. If the value is missing, the folder name is the system default. If no system default is configured, the command will fail with a BadRequest error. For example, \\VED\\Policy\\Certificates.

ObjectName (CN)

Either the ObjectName or Subject parameter is required. Both parameters can appear in the same request when Subject is the friendly name for the Certificate object. If the value is missing, the ObjectName is the Subject DN.

Organization

(Optional) The Organization field for the certificate Subject DN. Specify a value when the CSR centrally generates.

OrganizationalUnit

(Optional) The department or division within the organization that is responsible for maintaining the certificate. When you are requesting a centrally generated CSR, specify the name that will appear on the certificate Subject DN.

PKCS10

(Optional) The PKCS#10 Certificate Signing Request (CSR). Omit escape characters such as \n or \r\n. If this value is provided, any Subject DN fields and the KeyBitSize in the request are ignored.

Reenable

(Optional) The action to control a previously disabled certificate:

  • false: Default. Do not renew a previously disabled certificate.
  • true: Clear the Disabled attribute, reenable, and then renew the certificate (in this request). Reuse the same CertificateDN, that is also known as a Certificate object.

SetWorkToDo

(Optional) The setting to control certificate processing:

  • false: Allow another API call to set the WorktoDo attribute or allow certificate processing to occur with nightly tasks.
  • true: Default. Set the WorktoDo attribute. Start the lifecycle processing as soon as Certificate Manager is able to do so.

SidExtensionIdentity

(Optional) The SID (AD Security Identifier) extension identity to resolve the SID from. If this parameter is provided, then SidExtensionValue is ignored. Should be in prefixed universal format.

SidExtensionValue

(Optional) The SID (AD Security Identifier) extension value. The value of the objectSid attribute for an AD user.

State

(Optional) The State field for the certificate Subject DN. Specify a value when requesting a centrally generated CSR.

Subject

The Common Name field for the certificate Subject (DN). Specify a value when requesting a centrally generated CSR.

SubjectAlternateNames

Skip this parameter if the policy already specifies SAN Types.

For each SAN, specify either Type or TypeName and a corresponding Name. Because some CA templates include SAN=CN (certificate name), use the UI to confirm the SAN in your API call appears in the SAN value of the certificate.

For example, SubjectAltNames:[ {"TypeName":"2", "Name":"www.example.com"}, {"TypeName":"7", "Name":"9.5.45.11"} ].

  • Type or TypeName: A number that represents the kind of SAN:
    • 0: OtherName. Specify a Uniform Resource Name (URN) or username.
    • 1: Email
    • 2: DNS
    • 6: URI
    • 7: IPAddress
  • Name: The SAN friendly name that corresponds to the Type or TypeName parameter. For example, if a TypeName is IPAddress, the Name value is a valid IP address.

WorkToDoTimeout

(Optional) The maximum wait time for the CA to issue or renew a certificate.

Overrides the Platforms tree setting for the Certificate API ToDo Timeout setting. The maximum number of seconds to wait for the ToDo operation to complete. The default is zero seconds with a maximum value of 120 seconds. For example:WorkToDoTimeout: 60. For more information, see Certificates API configuration.

Returns

Response description

Name

Description

HTTP 200

When WorkToDoTimeout is omitted or processing exceeded the time out, response is: 

  • CertificateDN: The Trust Protection Platform DN of the newly created certificate object, if it was successfully created.
  • Guid: A value that uniquely identifies the Certificate object.

HTTP 200 with WorkToDoTimeout

The response is: 

  • CertificateData: Only appears when the certificate creates before the WorkToDoTimeout. If certificate creation completes before a timeout is reached (either specified or global), the response includes the certificate.
  • CertificateDN: The Trust Protection Platform DN of the newly created certificate object, if it was successfully created.
  • Filename: Available for WorkToDoTimeout. The suggested filename for the certificate data (in case the caller wants to save the certificate data in a file).
  • Format: Available for WorkToDoTimeout. A reminder of the intended Format that is imbedded in the CertificateData.
    • Base64or Base64 (PKCS #8) : application/x-pem-file

      To decode, print, or cast Base64 data, use a library method or utility. Examples:

      Bash

      echo Q2VydGlmaWNhdGVEYXRh | base64 --decode -o bash.pfx

      OpenSSL

      echo Q2VydGlmaWNhdGVEYXRh | openssl enc -base64 -d -out OpenSSL.pfx

      Perl

      use MIME::Base64;

      print decode_base64("Q2VydGlmaWNhdGVEYXRh");

      PowerShell

      [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String("Q2VydGlmaWNhdGVEYXRh")) >> C:\myfolder.RS-SAMPLE\Desktop\PowerShell.pfx

      Python

      import base64

      base64.b64decode("Q2VydGlmaWNhdGVEYXRh")

      where Q2VydGlmaWNhdGVEYXRh is the CertificateData response value.

    • DER: application/x-x509-ca-cert
    • JKS: application/octet-stream
    • PKCS #7: application/x-pkcs7-certificates
    • PKCS #12: application/x-pkcs12
  • Guid: A value that uniquely identifies the Certificate object.

HTTP 202

The certificate request was valid however, processing has yet to complete. Upon completion, call POST Certificates/Retrieve to get the certificate.

  • CertificateDN: The Trust Protection Platform DN of the newly created certificate object, if it was successfully created.
  • Error: A message describing the status of certification creation.
  • Guid: A value that uniquely identifies the Certificate object.

HTTP 400

For invalid requests, the CSR fails to generate. Certificates/Request returns a HTTP 400 BadRequest and an Error: value. For more information, see Certificates/Request error messages.