POST PKI/HashiCorp/CA

Defines the configuration for Trust Protection Platform to manage the intermediate CA certificate and optionally creates a role for a HashiCorp Vault PKI secrets engine.

Creates a device object and a HashiCorp Vault PKI application object. The application object specifies the name of the HashiCorp PKI secrets engine. Troubleshooting information is available on the Support and Log tabs. These two tabs are available only in the UI.
Remotely generates the key pair and CSR for the CA in the Vault.
Enrollment of the CSR requires an integration with a CA that supports issuance of sub CA certificates, for example, Microsoft ADCS. The subordinate CA certificate is also known as an intermediate certificate.
Once enrolled, the driver provisions the CA certificate to the vault enabling it to start issuing end-entity certificates.

Prerequisites

After you set up the HashiCorp vault, complete these tasks:

In HashiCorp, set up permissions. For more information, see HashiCorp Vault permission requirements.
In HashiCorp, enable the TLS option.
Create a Policy folder to hold the objects that will be created. Be sure to grant the API caller the required permissions. These permissions are required by the HashiCorp Vault PKI WebSDK methods.
Create a Password credential where the HashiCorp Vault token is the password. For help with creating credentials, see the Administration Guide.
Identify a CA template that is capable of issuing CA certificates. Example, the SubCA Template of a Microsoft CA.
Create credentials for the chosen CA template.
Create a CA template and test enrollment of a subordinate CA certificate.
(Optional) Create PKI roles by calling POST PKI/HashiCorp/Role. You can assign existing roles to HashiCorp Vault PKI applications at the time of creation or add them later.

After this API call runs, the policy folder shows the HashiCorp application object, role, and other information. For example:

HashiCorp application object

Requirements

Permissions: The caller must have theCreate permission to the FolderDn.
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

When adding query parameters, use the /? syntax. If you are not passing any parameters, make sure the URL ends with a trailing slash. Otherwise, some environments, such as cURL and PowerShell, return a HTTP 307 Temporary Redirect message.

Input parameters
Name	Description
Certificate	The attributes of the intermediate CA certificate for provisioning to the HashiCorp Vault PKI secrets engine: CommonName: The Common Name (CN) attribute of Subject Distinguished Name (DN). Organization: (Optional) The Organization (O) field for the certificate Subject DN. OrganizationalUnits: (Optional) An array of department or divisions within the organization (OU) that are responsible for maintaining the certificate. City: (Optional) The City or Locality (L) field for the certificate Subject DN. State: (Optional) The State (ST) field for the certificate Subject DN. Country: (Optional) The Country (C) field for the certificate Subject DN. An array of Subject Alternate Names (SANs) for the certificate. Skip this parameter if the policy already specifies SAN Types. For example, SubjectAltNames:[ {TypeName:DNS, Name:www.example.com}]. Name: The SAN friendly name that corresponds to TypeName. For example, if a TypeName is IP, in the Name specify a valid IP address. TypeName: One of the following HashiCorp SAN descriptions. DNS, RFC822, UPN, URI, IP.
CreateCertificateAuthority	The setting to determine how to generate the new CA certificate: true: Default. Generate a new CA certificate for the PkiPath in the Vault. false: Require the secrets engine to have an existing CA certificate before generating a new one.
CreatePKIRole	Works in conjunction with Roles. The setting to control role creation in the HashiCorp vault: true: If one or more Roles is missing in the PkiPath, create them. false: Default. Require that roles are already defined by the secrets engine.
CRLAddress	(Optional) The URL of the endpoint that provides a Certificate Revoke List (CRL) for the intermediate CA.
FolderDn	The distinguished name of the Policy folder.
Installation	Information about the HashiCorp vault: CredentialDn: The device credential is required when the device policy does not assign a Password credential in the FolderDN. Host: The HashiCorp Vault server name or IP address. Port: (Optional) The HashiCorp server port. The default is 443.
KeyAlgorithm	(Optional) Use in conjunction with KeyBitSize: RSA: Default. RSA key. EC: ECC (Elliptic Curve Cryptography) key.
KeyBitSize	(Optional) Use in conjunction with KeyAlgorithm: If KeyAlgorithm is RSA, specify 2048 or 4096 bits. Default 2048. If KeyAlgorithm is EC, specify 256, 384, or 521.
OCSPAddress	(Optional) The URL of the Online Certificate Status Protocol (OCSP) service that provides the revocation status of certificates by the intermediate CA.
PkiPath	The path name of the HashiCorp Vault where the PKI secrets engine is mounted. This value appears in Trust Protection Platform as the Application object name.
Roles	An array of role GUIDs that have the authority to create CSRs. To get the GUID, call POST Config/FindObjectsOfClass with these parameters: Class:Policy. ObjectDN: The parent folder to search. Recursive: 1. Pattern: The role name as the pattern. For example, Pattern:*role.

Returns

Response description
Name	Description
HTTP 400 on Error	Returns an error message for bad parameters, data, or syntax: [FolderDn] is not Policy. Can't find credential object. Can't find policy object. Certificate is required. Certificate with the Common Name [CommonName] already exists. Guid [Certificate object GUID] CommonName parameter is required. CredentialDn parameter is required. Failed to associate certificate and application. Failed to create application object. Failed to create certificate. You do not have Create permission. Failed to create device object. Host is required. Installation parameter is required. Invalid permissions. You do not have permission to create object. KeyBitSize is not valid. PKI already exists. Guid [application GUID]. Pki path can't be empty. Type of Credential should be Password.
HTTP 307	If the method is missing a slash (/) at the end of the URL or between the query parameters, this message appears: There is no operation listening for [Web SDK method], but there is an operation listening for [Web SDK method/], so you are being redirected there.
HTTP 200 on Success	For valid requests, this method returns a HTTP 200 message and the CreatePkiResponse object.

Example: Create the configuration for managing a Vault PKI secrets engine

Request for Example

POST https://test.venafi.example/vedsdk/PKI/HashiCorp/CA 
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "FolderDn":"\\VED\\Policy\\HashiCorp",
   "PkiPath":"pki-issuer",
   "CreateCertificateAuthority":"true",
   "Certificate":{
      "CommonName":"www.test.venafi.com",
      "Organization":"Venafi",
      "City":"SLC",
      "State":"UT",
      "Country":"US",
      "SubjectAltNames":[
         {
            "Name":"DNS",
            "TypeName":"gsk.venafi.example"
         }
      ],
      "KeyBitSize":"2048",
      "KeyAlgorithm":"RSA"
   },
   "Installation":{
      "Host":"192.168.1.150",
      "CredentialDn":"\\VED\\Policy\\HashiCorp\\MyHashiCorpToken",
      "Port":"8443"
   },
   "CreatePKIRole":"true",
   "Roles":[
      "{b94d2686-d12c-4206-8dbc-4a08ad01197a}"
   ]
}

Response for Example

HTTP/1.1 200 OK
{
   "CertificateDN":"\\VED\\Policy\\HashiCorp\\www.test.venafi.com",
   "CertificateGuid":"{809f3036-fd1f-4b03-9951-12e773a653e0}",
   "Error":null,
   "Guid":"{d790add4-d9e7-474a-a667-f397b1b2f12d}" 
}