PowerShell script reference for Adaptable Application

This section documents all available PowerShell functions for use with the Adaptable Application driver. PowerShell scripts are stored in the \Venafi\Scripts\AdaptableApp folder.

The input parameters and response format for each function is predefined. All functions receive a set of general parameters, whereas those parameters that are specific to the function are only passed to it. All of the standard provisioning functions must be present in your script, but the Remote Generation functions are optional and their absence is used to indicate a lack of support for "Generate Key/CSR on Application=Yes".

DID YOU KNOW? To prevent vulnerabilities, the PowerShell scripts are stored on the Trust Protection Platform server. While it might have been more convenient to allow downloading the script, storing the scripts on the Trust Protection Platform server prevents potentially harmful scripts from affecting the server. Only privileged users on your Trust Protection Platform server can access scripts.

You must ensure the same version of all your Adaptable Application scripts are on all servers in the cluster that have the WebConsole component installed. For this reason, it is wise to include a script version number in the file name, so you can easily check to see that the same version of the script is installed on all servers in the cluster.

NOTE To work effectively with any Venafi adaptable solution, you must have some working knowledge of PowerShell scripting, or you must have equivalent experience with a scripting language similar to PowerShell.

Data is passed to the functions using hash tables (key-value pairs). Using hash tables enables the addition of new functions in future releases. For more information, see About hash tables for Adaptable Application

The following diagram shows which PowerShell functions are invoked at which stage in the certificate lifecycle:

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

BEST PRACTICE When customizing (or creating a new) PowerShell script, keep the following security best practices in mind:

Avoid hard-coding credentials into your PowerShell scripts.
Only include code in functions that relate to the task they are designated to perform.
Scripts should not do anything that could alter the integrity or availability of the local Windows system (the system hosting Trust Protection Platform).

About debug logging

When a user has requested debug logging by checking Enable Debug Logging for Adaptable Application, the driver sets a global variable called $DEBUG_FILE whenever it executes a PowerShell function. So your PowerShell script should reference the value of the $DEBUG_FILE variable to decide whether or not to log information for troubleshooting purposes. The value the driver assigns to the $DEBUG_FILE variable is a recommended file path name on the Trust Protection Platform server for use when logging events to a file. The file name is designed to be unique to the instance of the Adaptable component so as to avoid conflicts when multiple scripts are running at the same time and writing to the log file. If the recommended file name is used, the resulting log file appears in the <Venafi Home>\Logs directory by default (e.g. C:\Program Files\Venafi\Logs).

For information about where Enable Debug Logging is configured for Adaptable Application, see Configuring an Adaptable Application object, or if you're using Adaptable Application with Onboard Discovery, see Creating a new Onboard Discovery job.

General hash table variables
Variable Name	Data Type	Description
AssetName	String	The name used to uniquely identify the certificate that is provisioned to the device. Value is initially automatically generated using the following naming convention: <Common Name>_<ValidTo as yyMMMdd>_<Last 4 of Serial> for centrally generated CSRs <Common Name>_RGEN_<Current Date/Time as yyMMdd-HHmmss> for remotely generated CSRs AssetName can be overridden by several PowerShell functions if it is necessary for a particular device to use a different naming convention (e.g. to deal with string length or special character limitations).
AppObjectDN	String	Contains the Trust Protection Platform distinguished name (DN) of the calling application object.
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
HostAddress	String	Contains the hostname or IP address specified by the device object.
TcpPort	Integer	A value containing the TCP port specified by the application object.
UserName	String	The user name portion of the user name or private key credential assigned to the device or application object. Used for authenticating with the device.
UserPass	String	The password portion of the user name credential assigned to the device or application object. Used for authenticating with the device.
UserPrivKey	String	The privacy-enhanced electronic mail (PEM)-formatted RSA private key portion of the private key credential assigned to the device or application object. Used for authenticating with the device via SSH.
VarBool1	Boolean	The value of the Yes/No (true/false) user-defined field as defined by the header at the top of the PowerShell script.
VarBool2	Boolean	The value of the Yes/No (true/false) user-defined field as defined by the header at the top of the PowerShell script.
VarPass	String	Contains the value of the password field as defined by the header at the top of the PowerShell script.
VarText1	String	The text contained in the user-defined field as defined by the header at the top of the PowerShell script.
VarText2	String	The text contained in the user-defined field as defined by the header at the top of the PowerShell script.
VarText3	String	The text contained in the user-defined field as defined by the header at the top of the PowerShell script.
VarText4	String	The text contained in the user-defined field as defined by the header at the top of the PowerShell script.
VarText5	String	The text contained in the user-defined field as defined by the header at the top of the PowerShell script.