Retrieve-Certificate function

Implementing logic for the Retrieve-Certificate function is required unless the Submit-CsrAsNew, Submit-CsrAsRenewal, and Submit-CsrAsReplacement functions are all written to return the certificate issued by the CA. 

When implemented, this function must attempt to retrieve a certificate from the CA.  It is called at Processing Stage 700 and could return a Pending status to indicate that the driver should retry the operation again later. When the certificate issued by the CA is available, the function must return a status of Issued and include the certificate in the same response.

NOTE  The Retrieve-Certificate function is not called when the Submit-CsrAsNew, Submit-CsrAsRenewal, or Submit-CsrAsReplacement functions return a certificate in the Pkcs7 or Pkcs12 parameters. Also, this function must return Pkcs7 or Pkcs12 unless they were returned by the Submit function.

Refer to the Returns table below.

Specific hash table variables

Variable Name

Data Type

Description

CertId

String

Text that uniquely identifies the certificate issued by the CA.
General hash table variables

Variable Name

Data Type

Description

AuxPass

String

The password portion of the Secondary Credential when a user name or a password credential is assigned, or the PKCS#12 password when a certificate credential is assigned

AuxPfxData

Byte Array

A PKCS#12 byte array that contains a client certificate and private key when a certificate credential is assigned as the Secondary Credential

AuxUser

String

The user name portion of the Secondary Credential when a user name credential is assigned

CertObjDN

String

Venafi distinguished name (DN) of the certificate object in the policy tree

CustomFields

Hashtable

Hash table keys are Custom Field labels and the values are strings (single-valued) or string arrays (multi-valued).

OAuthAccessToken

String

OAuth token passed to the PowerShell script. Tokens are passed only after you've provided the required information in the WebSDK OAuth Token Configuration settings of the Adaptable object. See Configuring the Adaptable CA object.

How it works

When used, each time your script is called, Trust Protection Platform requests a new token automatically. Each new token is associated with both the specified user and with the referenced application ID. After the script finishes running, Trust Protection Platform revokes the token automatically. To get started, see Adaptable CA prerequisites.

PfxData

Byte Array

PKCS#12 keystore containing client certificate and private key for authenticating with the CA; this and the PfxPass are used together to instantiate an X509Certificate2 object for client certificate authentication.

PfxPass

SecureString

Password for access to the private key of the PfxData PKCS#12

UserName

String

User name for authenticating with the CA

UserPass

String

Password for authenticating with the CA

WebSdkUrl

String

String representing the fully-qualified domain name to the WebSDK of your Trust Protection Platform server. For information on where this variable data is set, see Trust Protection Platform server configuration.

Returns

Return

Data Type

Description

DiscardPrivateKeyAndCsr

Bool

A boolean that when $true tells the driver to discard stored assets that will not match the certificate being returned

EncryptPass

String

The password used to encrypt the private key or PKCS#12.

Pkcs7

Array

A collection that includes all of the CA certificates in the issuing chain.

Pkcs12

Array

A collection that includes the issued certificate, its private key, and (optionally) all of the CA certificates in the chain.

When PKCS#12 is returned, EncryptPass must also be returned and Pkcs7 and PrivKeyPem are ignored.

Also, if the PrivKeyPem data is a password-encrypted private key, EncryptPass must be returned.

PrivKeyPem

String

An OpenSSL or PKCS#8 private key in PEM format.

Result

String

Shows "Success" or "NotUsed" to indicate the non-error completion state.

Status

String

Shows "Pending" or "Issued" to indicate whether or not the certificate has been issued by the CA.

TransId

String

Text used by the CA to uniquely identify the certificate request submitted previously.

IMPORTANT  If Pkcs12 or PrivKeyPem are returned, DiscardPrivateKeyAndCsr is automatically set to $true and cannot be overridden.

For information about processing stages, see About certificate lifecycle management.