Script API

Last updated
Save as PDF

Using the Script API

The EgoSecure Full Disk Encryption public APIs are in dynamic linked libraries (DDL) and are part of an EgoSecure Full Disk Encryption installation. Two DLLs contain the entry points of all public script API’s:

FDEScriptapi.dll: This API configures FDE settings for FDE installations.
PBAScriptapi.dll: This API configures PBA settings for FDE installations.

List of public script API functions

Header File	Method description
PBAScriptAPI.h	CreatePBAScript (LPPBADATA pdata, char pszScriptPath, BOOL fEncrypted)* Create a PBA script according to pdata, and save it to pszScriptPath. fEncrypted specifies whether the script should be encrypted. Only encrypted scripts may be executed by the following API.
CreatePBAScriptEx(LPPBADATA pdata, ULONG nDataSize, char pszScriptPath, BOOL fEncrypted)* - recommended This method extends the functionality of a previous method. The argument nDataSize specifies the size of the pdata buffer. This method is a recommended one.
ProcessPBAScript (LPSCRIPTEXECDATA pExecData, LPSTR szScriptPath) Execute an encrypted PBA script located at szScriptPath, and store the result in pExecData.
GetPBAScriptResult (LPSCRIPTEXECDATA sData) Retrieve the execution result of the last PBA script, and store the result in sData. This includes PBA scripts executed by EgoSecure.
ConvertHDKey (char pszHDKey, int iHDKeySize, LPSTR pszID, int iIDsize, LPSTR pszHDFilePath, LPSTR pszPassword)* Decrypts and converts a given Helpdesk file into a string, which can be used to add a Helpdesk key with the USERDATA struct. The string is a still in an encrypted format.
int Generate SPW (const char szAdminPwd, char SPW, DWORD spwBuffSize) Generates an encrypted password string (SPW) for a password being passed (szAdminPwd). Result will be stored in SPW buffer, buffer size must be passed as spwBuffSize argument.
FDEScriptAPI.h	CreateFDEScript (LPFDEDATA pdata, char pszScriptPath, BOOL fEncrypted)* Create a FDE script according to pdata, and save it to pszScriptPath. fEncrypted specifies whether the script should be encrypted. Only encrypted scripts may be executed by the following API.
CreateFDEScriptEx(LPFDEDATA pdata, ULONG nFdeDataStructSize, char pszScriptPath, BOOL fEncrypted)* - recommended This method extends the functionality of a previous method. The argument nFdeDataStructSize specifies the size of the pdata buffer.
ProcessFDEScript (LPFDESCRIPTEXECDATA pExecData, LPSTR szScriptPath) Execute an encrypted FDE script located at szScriptPath, and store the result in pExecData. For a script that initializes FDE or un-install FDE, this method will cause the computer to re-start after execution.
ProcessFDEScriptEx (LPFDESCRIPTEXECDATA pExecData, LPSTR szScript, BOOL fRestart) - recommended This method extends the functionality of previous method. If the last argument fRestart is set to false, the computer will not be re-started after an un-install FDE script is executed.
GetFDEScriptResult (LPFDESCRIPTEXECDATA sData) Retrieve the execution result of the last FDE script, and store the result in sData. This includes FDE scripts executed by EgoSecure.

Header File

Method description

PBAScriptAPI.h

CreatePBAScript (LPPBADATA pdata, char *pszScriptPath, BOOL fEncrypted)

Create a PBA script according to pdata, and save it to pszScriptPath. fEncrypted specifies whether the script should be encrypted. Only encrypted scripts may be executed by the following API.

CreatePBAScriptEx(LPPBADATA pdata, ULONG nDataSize, char *pszScriptPath, BOOL fEncrypted) - recommended

This method extends the functionality of a previous method. The argument nDataSize specifies the size of the pdata buffer.
This method is a recommended one.

ProcessPBAScript (LPSCRIPTEXECDATA pExecData, LPSTR szScriptPath)

Execute an encrypted PBA script located at szScriptPath, and store the result in pExecData.

GetPBAScriptResult (LPSCRIPTEXECDATA sData)

Retrieve the execution result of the last PBA script, and store the result in sData. This includes PBA scripts executed by EgoSecure.

ConvertHDKey (char *pszHDKey, int iHDKeySize, LPSTR pszID, int iIDsize, LPSTR pszHDFilePath, LPSTR pszPassword)

Decrypts and converts a given Helpdesk file into a string, which can be used to add a Helpdesk key with the USERDATA struct. The string is a still in an encrypted format.

int Generate SPW (const char* szAdminPwd, char *SPW, DWORD spwBuffSize)

Generates an encrypted password string (SPW) for a password being passed (szAdminPwd). Result will be stored in SPW buffer, buffer size must be passed as spwBuffSize argument.

FDEScriptAPI.h

CreateFDEScript (LPFDEDATA pdata, char *pszScriptPath, BOOL fEncrypted)

Create a FDE script according to pdata, and save it to pszScriptPath. fEncrypted specifies whether the script should be encrypted. Only encrypted scripts may be executed by the following API.

CreateFDEScriptEx(LPFDEDATA pdata, ULONG nFdeDataStructSize, char *pszScriptPath, BOOL fEncrypted) - recommended

This method extends the functionality of a previous method. The argument nFdeDataStructSize specifies the size of the pdata buffer.

ProcessFDEScript (LPFDESCRIPTEXECDATA pExecData, LPSTR szScriptPath)

Execute an encrypted FDE script located at szScriptPath, and store the result in pExecData. For a script that initializes FDE or un-install FDE, this method will cause the computer to re-start after execution.

ProcessFDEScriptEx (LPFDESCRIPTEXECDATA pExecData, LPSTR szScript, BOOL fRestart) - recommended

This method extends the functionality of previous method. If the last argument fRestart is set to false, the computer will not be re-started after an un-install FDE script is executed.

GetFDEScriptResult (LPFDESCRIPTEXECDATA sData)

Retrieve the execution result of the last FDE script, and store the result in sData. This includes FDE scripts executed by EgoSecure.

List of data structures

Name	Defined in	Description	Sub data structure*
LPPBADATA	PBAData.h	struct that contains PBA configuration information	SCRIPTCONFDATA KEKDATA LOCKDATA LPUSERDATA PREBOOTDATA ERIDATA SNBDATA SELFINITDATA SSODATA ERI_SETTINGS LOGDATA PBA_SCREEN_DATA (compatible only with CreatePBAScriptEx method)
LPSCRIPTEXECDATA	PBAScriptAPI.h	struct that contains the execution result of PBA script.
LPFDEDATA	FDEData.h	struct that contains FDE configuration information	SCRIPTCONFDATA REPARTDATA BOOTDATA ERIDATA LPENCDATA UNINSTDATA ERI_SETTINGS LOGDATA FDESMARTDATA (compatible only with CreateFDEScriptEx method)
LPFDESCRIPTEXECDATA	FDEScriptAPI.h	struct that contains the execution result of FDE script.
SCRIPTCONFDATA	SNBData.h	struct that contains information about how a script should be executed. For example, whether the script is a initialization or configuration script, or whether a warning window should be displayed if error occurs
KEKDATA	PBALLAL.h	struct that contains information about KEK configuration.	LPLabelEntry LPKeyUsageEntry
LOCKDATA	PBALLAL.h	struct that contains information about PBA locking configuration.
LPUSERDATA	PBALLAL.h	struct that contains information about PBA entry list.
PREBOOTDATA	PBALLAL.h	struct that contains information about general PBA configuration.	LPIProviderEntry
ERIDATA	SNBData.h	struct that contains ERI generation paramters
SNBDATA	SNBData.h	struct that contains parameters for changing FDE Admin Password
SELFINITDATA	PBAData.h	struct that contains user and smart card capturing settings
SSODATA	PBAData.h	struct that contains single sign-on settings
PDA_SCREEN_DATA (compatible only with CreatePBAScriptEx method)	PBAData.h	struct that contains information about screen resolution in PBA
ERI_SETTINGS	SNBData.h	struct that contains password length restriction for ERI
LOGDATA**	SNBData.h	struct that contains configuration settings for different log files
REPARTDATA	FDEData.h	struct that contains partition resizing information.
BOOTDATA	FDEData.h	struct that contains information required to change FDE Admin Password
LPENCDATA	FDEData.h	struct that contains disk partition encryption information. If more than one partition needs to be encrypted, a list of this struct is required
UNINSTDATA	FDEData.h	struct that contains de-initialization and uninstall settings for FDE
FDESMARTDATA (compatible only with CreateFDEScriptEx method)	FDEData.h	struct that contains settings for encrypting disk encryption key and hiding FDE tray	FDEDEKPROTECTIONSETTINGS FDETRAYSETTINGS

*This column does not contain all the members of a struct. Instead, it focuses on structs defined by EgoSecure. Later rows describe where these structs are defined.

**MAX_PATH is defined in win32defs.h, a generic header available with Windows IDE installation.

Code samples for Script API

This section contains a simple code sample that shows how to change the FDE administration password via FDE and PBA scripts respectively. Only FDE-related errors are checked in the example.

PBA script sample

Step	Description
Assign settings	Declare struct to hold PBA configuration information: PBADATA pbaData; memset(&pbadata,0,sizeof(pbaData)); Assign the current password of FDE administrator so that the script may be authenticated: strcpy(pbaData.scriptConf.szAdminPwd,"oldpassword"); Assign the new password to corresponding struct: pbaData.snbData.fAdminPW=TRUE; strcpy(pbaData.snbData.szNewAdminPwd,"newpassword");
Load DLL	Use Windows generic library to load the DLL: HINSTANCE hLib = LoadLibrary(L"PBAScriptAPI.dll");
Create PBA script	Obtain a pointer to the script creation method: fp_CreatePBAScript = (ft_CreatePBAScript) GetProcAddress(hLib, "CreatePBAScript"); Create an encrypted script for execution: nRc = fp_CreatePBAScript(&pdata,pszScriptPath,TRUE); Create a plain script for viewing: nRc = fp_CreatePBAScript (&pdata,pszScriptPath,FALSE);
Execute PBA script	Declare the struct to hold the execution result: LPSCRIPTEXECDATA pExecData; memset(&pExecData,0,sizeof(pExecData)); Obtain a pointer to the script execution method: fp_ProcessPBAScript = (ft_ProcessPBAScript) GetProcAddress(hLib, "ProcessPBAScript"); Execute the script: nRc = ft_ProcessPBAScript(&pExecData,szScriptPath);

FDE script sample

Step	Description
Assign settings	Declare struct to hold FDE configuration information: PBADATA fdeData; memset(&fdeData,0,sizeof(pbaData)); Assign the current password of FDE administrator so that the script may be authenticated: strcpy(fdeData.scriptConf.szAdminPwd,"oldpassword"); Set the script to be a configuration script (optional): fdeData.scriptConf.fConfigScript = TRUE; Assign the new password to corresponding struct: fdeData.bootData.fBootOptions=TRUE; strcpy(pbaData.snbData.szNewAdminPwd,"newpassword");
Load DLL	Use Windows generic library to load the DLL: HINSTANCE hLib = LoadLibrary(L"FDEScriptAPI.dll");
Create FDE script	Obtain a pointer to the script creation method: fp_CreateFDEScript = (ft_CreateFDEScript) GetProcAddress(hLib, "CreateFDEScript"); Create an encrypted script for execution: nRc = fp_CreateFDEScript(&pdata,pszScriptPath,TRUE); Create a plain script for viewing: nRc = fp_CreateFDEScript (&pdata,pszScriptPath,FALSE);
Execute FDE script	Declare the struct to hold the execution result: LPFDESCRIPTEXECDATA pExecData; Memset(&pExecData,0,sizeof(pExecData)); Obtain a pointer to the script execution method: fp_ProcessFDEScript = (ft_ProcessFDEScript) GetProcAddress(hLib, "ProcessFDEScript"); Execute the script: nRc = ft_ProcessFDEScript(&pExecData,szScriptPath);