DPAPI Class

Properties   Methods   Events   Config Settings   Errors  

The DPAPI class allows you to protect and unprotect data.

Class Name

IPWorksEncrypt_DPAPI

Procedural Interface

 ipworksencrypt_dpapi_open();
 ipworksencrypt_dpapi_close($res);
 ipworksencrypt_dpapi_register_callback($res, $id, $function);
 ipworksencrypt_dpapi_get_last_error($res);
 ipworksencrypt_dpapi_get_last_error_code($res);
 ipworksencrypt_dpapi_set($res, $id, $index, $value);
 ipworksencrypt_dpapi_get($res, $id, $index);
 ipworksencrypt_dpapi_do_config($res, $configurationstring);
 ipworksencrypt_dpapi_do_protect($res);
 ipworksencrypt_dpapi_do_reset($res);
 ipworksencrypt_dpapi_do_unprotect($res);

Remarks

The class supports the classic Microsoft Windows Data Protection API (DPAPI) or CNG DPAPI implementation. The use of UseCNG determines which implementation is used.

The classic DPAPI functionality protects data on a single system. The CNG DPAPI is designed with modern use cases involved. In many cases, especially with cloud computing, protection and unprotection may be done on different systems. With this in mind the Microsoft CNG DPAPI allows encrypting to a set of principals that can be used to unprotect the data on other systems after authenticating.

Protecting Data

Protect protects the specified data.

The class supports protecting data using either the classic DPAPI or CNG DPAPI implementation. The use of UseCNG determines which implementation is used. The list of applicable properties differs depending on whether CNG DPAPI is being used.

When using classic DPAPI (UseCNG is False), the following optional properties are applicable:

• DataDescription
• Password
• PromptTitle
• PromptUser

When using CNG DPAPI (UseCNG is True), the following properties are applicable:

• ProtectionDescriptor (required)
• EscapeDescriptor
• UseStreamMode

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• InputFile
• InputMessage

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• OutputFile
• OutputMessage: The output data is written to this property if no other destination is specified.

Code Example (Classic DPAPI - UseCNG is False)

 
 Copy
//Protect
Dpapi dpapi = new Dpapi();
dpapi.InputMessage = "test";
dpapi.Protect();
byte[] protectedData = dpapi.OutputMessageB;

//Unprotect
dpapi = new Dpapi();
dpapi.InputMessageB = protectedData;
dpapi.Unprotect();
Console.WriteLine(dpapi.OutputMessage); //outputs "test"

Code Example (CNG DPAPI - UseCNG is True)

 
 Copy
//Protect
Dpapi dpapi = new Dpapi();
dpapi.UseCNG = true;
dpapi.ProtectionDescriptor = "LOCAL=user";
dpapi.InputMessage = "test";
dpapi.Protect();
byte[] protectedData = dpapi.OutputMessageB;

//Unprotect
dpapi = new Dpapi();
dpapi.UseCNG = true;
dpapi.InputMessageB = protectedData;
dpapi.Unprotect();
Console.WriteLine(dpapi.OutputMessage); //outputs "test"

Unprotecting Data

Unprotect unprotects the specified data.

The class supports unprotecting data using either the classic DPAPI or CNG DPAPI implementation. The use of UseCNG determines which implementation is used. The list of applicable properties differs depending on whether CNG DPAPI is being used.

When using classic DPAPI (UseCNG is False), the following optional properties are applicable:

• DataDescription (populated after completion)
• Password

When using CNG DPAPI (UseCNG is True), the following properties are applicable:

• ProtectionDescriptor (populated after completion)
• UseStreamMode

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• InputFile
• InputMessage

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• OutputFile
• OutputMessage: The output data is written to this property if no other destination is specified.

Code Example (Classic DPAPI - UseCNG is False)

 
 Copy
//Protect
Dpapi dpapi = new Dpapi();
dpapi.InputMessage = "test";
dpapi.Protect();
byte[] protectedData = dpapi.OutputMessageB;

//Unprotect
dpapi = new Dpapi();
dpapi.InputMessageB = protectedData;
dpapi.Unprotect();
Console.WriteLine(dpapi.OutputMessage); //outputs "test"

Code Example (CNG DPAPI - UseCNG is True)

 
 Copy
//Protect
Dpapi dpapi = new Dpapi();
dpapi.UseCNG = true;
dpapi.ProtectionDescriptor = "LOCAL=user";
dpapi.InputMessage = "test";
dpapi.Protect();
byte[] protectedData = dpapi.OutputMessageB;

//Unprotect
dpapi = new Dpapi();
dpapi.UseCNG = true;
dpapi.InputMessageB = protectedData;
dpapi.Unprotect();
Console.WriteLine(dpapi.OutputMessage); //outputs "test"

Property List

---

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

DataDescription Property (IPWorksEncrypt_DPAPI Class)

The description of data.

Object Oriented Interface

public function getDataDescription();


public function setDataDescription($value);

Procedural Interface

ipworksencrypt_dpapi_get($res, 1 );


ipworksencrypt_dpapi_set($res, 1, $value );

Default Value

''

Remarks

This property specifies an optional description of the protected data.

This may be set before calling Protect. This property will be populated when calling Unprotect.

This setting is not applicable when UseCNG is set to True.

Data Type

String

InputFile Property (IPWorksEncrypt_DPAPI Class)

The file to process.

Object Oriented Interface

public function getInputFile();


public function setInputFile($value);

Procedural Interface

ipworksencrypt_dpapi_get($res, 2 );


ipworksencrypt_dpapi_set($res, 2, $value );

Default Value

''

Remarks

This property specifies the file to be processed. Set this property to the full or relative path to the file which will be processed.

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• InputFile
• InputMessage

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• OutputFile
• OutputMessage: The output data is written to this property if no other destination is specified.

Data Type

String

InputMessage Property (IPWorksEncrypt_DPAPI Class)

The message to process.

Object Oriented Interface

public function getInputMessage();


public function setInputMessage($value);

Procedural Interface

ipworksencrypt_dpapi_get($res, 3 );


ipworksencrypt_dpapi_set($res, 3, $value );

Default Value

''

Remarks

This property specifies the message to be processed.

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• InputFile
• InputMessage

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• OutputFile
• OutputMessage: The output data is written to this property if no other destination is specified.

Data Type

Binary String

OutputFile Property (IPWorksEncrypt_DPAPI Class)

The output file when encrypting or decrypting.

Object Oriented Interface

public function getOutputFile();


public function setOutputFile($value);

Procedural Interface

ipworksencrypt_dpapi_get($res, 4 );


ipworksencrypt_dpapi_set($res, 4, $value );

Default Value

''

Remarks

This property specifies the file to which the output will be written when Encrypt or Decrypt is called. This may be set to an absolute or relative path.

This property is only applicable to Encrypt and Decrypt.

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• InputFile
• InputMessage

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• OutputFile
• OutputMessage: The output data is written to this property if no other destination is specified.

Data Type

String

OutputMessage Property (IPWorksEncrypt_DPAPI Class)

The output message after processing.

Object Oriented Interface

public function getOutputMessage();

Procedural Interface

ipworksencrypt_dpapi_get($res, 5 );

Default Value

''

Remarks

This property will be populated with the output from the operation if OutputFile is not set.

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• InputFile
• InputMessage

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• OutputFile
• OutputMessage: The output data is written to this property if no other destination is specified.

This property is read-only and not available at design time.

Data Type

Binary String

Overwrite Property (IPWorksEncrypt_DPAPI Class)

Indicates whether or not the class should overwrite files.

Object Oriented Interface

public function getOverwrite();


public function setOverwrite($value);

Procedural Interface

ipworksencrypt_dpapi_get($res, 6 );


ipworksencrypt_dpapi_set($res, 6, $value );

Default Value

false

Remarks

This property indicates whether or not the class will overwrite OutputFile. If Overwrite is False, an error will be thrown whenever OutputFile exists before an operation. The default value is False.

Data Type

Boolean

Password Property (IPWorksEncrypt_DPAPI Class)

An optional password to further protect data.

Object Oriented Interface

public function getPassword();


public function setPassword($value);

Procedural Interface

ipworksencrypt_dpapi_get($res, 7 );


ipworksencrypt_dpapi_set($res, 7, $value );

Default Value

''

Remarks

This property may be set to a password to protect the data further.

When protecting data without specifying a password any application running under the same user account can unprotect the data. By specifying a password another piece of information is required to unprotect the data.

This may be set before calling Protect. If a password was specified when protecting data it must be set before calling Unprotect.

This setting is not applicable when UseCNG is set to True.

Data Type

String

PromptTitle Property (IPWorksEncrypt_DPAPI Class)

The title of the prompt window.

Object Oriented Interface

public function getPromptTitle();


public function setPromptTitle($value);

Procedural Interface

ipworksencrypt_dpapi_get($res, 8 );


ipworksencrypt_dpapi_set($res, 8, $value );

Default Value

''

Remarks

This property specifies the title of the prompt dialog if PromptUser is True. The default value is empty string.

This setting is not applicable when UseCNG is set to True.

Data Type

String

PromptUser Property (IPWorksEncrypt_DPAPI Class)

Whether to display a prompt.

Object Oriented Interface

public function getPromptUser();


public function setPromptUser($value);

Procedural Interface

ipworksencrypt_dpapi_get($res, 9 );


ipworksencrypt_dpapi_set($res, 9, $value );

Default Value

false

Remarks

This property specifies whether a prompt is displayed when calling Protect. This dialog is created by the system and informs the user of the request action. The user may accept or cancel the request. If the user cancels the request the Protect method fails with an error.

When True the PromptTitle may be set to customize the window title.

This setting is not applicable when UseCNG is set to True. ;

Data Type

Boolean

ProtectionDescriptor Property (IPWorksEncrypt_DPAPI Class)

The CNG protection descriptor.

Object Oriented Interface

public function getProtectionDescriptor();


public function setProtectionDescriptor($value);

Procedural Interface

ipworksencrypt_dpapi_get($res, 10 );


ipworksencrypt_dpapi_set($res, 10, $value );

Default Value

''

Remarks

This property specifies the protection descriptor rule string. The protection descriptor is used by the system to decide which entities can unprotect the data at a later time. This property must be specified before calling Protect. This property is populated after calling Unprotect.

Protection descriptors can be defined for the following types of authorization:

• A local user or machine
• An account or group in an Active Directory forest
• A set of web credentials
• A certificate in the user's certificate store

A local user or machine may be used for machines that are or are not on a domain. For instance:

• LOCAL=user
• LOCAL=machine

The use of SID and SDDL requires that the machine be part of a domain. For instance:

• SID=S-1-5-21-4392301 AND SID=S-1-5-21-3101812
• SDDL=O:S-1-5-5-0-290724G:SYD:(A;;CCDC;;;S-1-5-5-0-290724)(A;;DC;;;WD)

Certificates may also be used as a descriptor. To decrypt, the certificate with corresponding private key must be present in the user's certificate store. The public certificate can be specified as the SHA1 thumbprint (hash) of the certificate, or the base64 encoded certificate itself. For instance:

• CERTIFICATE=HashID:28ac375635b82ca3e20a1c9422145bc93965dae7
• CERTIFICATE=CertBlob:MIIC7TCCAdWgAw...pgpVgYpppr

Note: The base64 certificate data should not include any headers, footers, or whitespace.

The use of AND and OR operators are accepted in order to encrypt data for multiple parties or establish multiple conditions for decryption.

For more details about protection descriptors and accepted formats please refer to the Microsoft Documentation for Protection Descriptors

This setting is only applicable when UseCNG is set to True.

Data Type

String

UseCNG Property (IPWorksEncrypt_DPAPI Class)

Whether to use CNG DPAPI.

Object Oriented Interface

public function getUseCNG();


public function setUseCNG($value);

Procedural Interface

ipworksencrypt_dpapi_get($res, 11 );


ipworksencrypt_dpapi_set($res, 11, $value );

Default Value

false

Remarks

The class supports protecting data using either the classic DPAPI or CNG DPAPI implementation. When set to True the CNG DPAPI implementation is sued. When set to False (default) the classic DPAPI implementation is used.

Data Type

Boolean

UseHex Property (IPWorksEncrypt_DPAPI Class)

Whether input or output is hex encoded.

Object Oriented Interface

public function getUseHex();


public function setUseHex($value);

Procedural Interface

ipworksencrypt_dpapi_get($res, 12 );


ipworksencrypt_dpapi_set($res, 12, $value );

Default Value

false

Remarks

This property specifies whether the encrypted data is hex encoded.

If set to True, when Protect is called the class will perform the encryption as normal and then hex encode the output. OutputMessage or OutputFile will hold hex encoded data.

If set to True, when Unprotect is called the class will expect InputMessage or InputFile to hold hex encoded data. The class will then hex decode the data and perform decryption as normal.

Data Type

Boolean

Config Method (IPWorksEncrypt_DPAPI Class)

Sets or retrieves a configuration setting.

Object Oriented Interface

public function doConfig($configurationstring);

Procedural Interface

ipworksencrypt_dpapi_do_config($res, $configurationstring);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Protect Method (IPWorksEncrypt_DPAPI Class)

Protects the data.

Object Oriented Interface

public function doProtect();

Procedural Interface

ipworksencrypt_dpapi_do_protect($res);

Remarks

Protect protects the specified data.

The class supports protecting data using either the classic DPAPI or CNG DPAPI implementation. The use of UseCNG determines which implementation is used. The list of applicable properties differs depending on whether CNG DPAPI is being used.

When using classic DPAPI (UseCNG is False), the following optional properties are applicable:

• DataDescription
• Password
• PromptTitle
• PromptUser

When using CNG DPAPI (UseCNG is True), the following properties are applicable:

• ProtectionDescriptor (required)
• EscapeDescriptor
• UseStreamMode

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• InputFile
• InputMessage

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• OutputFile
• OutputMessage: The output data is written to this property if no other destination is specified.

Code Example (Classic DPAPI - UseCNG is False)

 
 Copy
//Protect
Dpapi dpapi = new Dpapi();
dpapi.InputMessage = "test";
dpapi.Protect();
byte[] protectedData = dpapi.OutputMessageB;

//Unprotect
dpapi = new Dpapi();
dpapi.InputMessageB = protectedData;
dpapi.Unprotect();
Console.WriteLine(dpapi.OutputMessage); //outputs "test"

Code Example (CNG DPAPI - UseCNG is True)

 
 Copy
//Protect
Dpapi dpapi = new Dpapi();
dpapi.UseCNG = true;
dpapi.ProtectionDescriptor = "LOCAL=user";
dpapi.InputMessage = "test";
dpapi.Protect();
byte[] protectedData = dpapi.OutputMessageB;

//Unprotect
dpapi = new Dpapi();
dpapi.UseCNG = true;
dpapi.InputMessageB = protectedData;
dpapi.Unprotect();
Console.WriteLine(dpapi.OutputMessage); //outputs "test"

Reset Method (IPWorksEncrypt_DPAPI Class)

Resets the class.

Object Oriented Interface

public function doReset();

Procedural Interface

ipworksencrypt_dpapi_do_reset($res);

Remarks

When called, the class will reset all of its properties to their default values.

Unprotect Method (IPWorksEncrypt_DPAPI Class)

Unprotects the data.

Object Oriented Interface

public function doUnprotect();

Procedural Interface

ipworksencrypt_dpapi_do_unprotect($res);

Remarks

Unprotect unprotects the specified data.

The class supports unprotecting data using either the classic DPAPI or CNG DPAPI implementation. The use of UseCNG determines which implementation is used. The list of applicable properties differs depending on whether CNG DPAPI is being used.

When using classic DPAPI (UseCNG is False), the following optional properties are applicable:

• DataDescription (populated after completion)
• Password

When using CNG DPAPI (UseCNG is True), the following properties are applicable:

• ProtectionDescriptor (populated after completion)
• UseStreamMode

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• InputFile
• InputMessage

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• OutputFile
• OutputMessage: The output data is written to this property if no other destination is specified.

Code Example (Classic DPAPI - UseCNG is False)

 
 Copy
//Protect
Dpapi dpapi = new Dpapi();
dpapi.InputMessage = "test";
dpapi.Protect();
byte[] protectedData = dpapi.OutputMessageB;

//Unprotect
dpapi = new Dpapi();
dpapi.InputMessageB = protectedData;
dpapi.Unprotect();
Console.WriteLine(dpapi.OutputMessage); //outputs "test"

Code Example (CNG DPAPI - UseCNG is True)

 
 Copy
//Protect
Dpapi dpapi = new Dpapi();
dpapi.UseCNG = true;
dpapi.ProtectionDescriptor = "LOCAL=user";
dpapi.InputMessage = "test";
dpapi.Protect();
byte[] protectedData = dpapi.OutputMessageB;

//Unprotect
dpapi = new Dpapi();
dpapi.UseCNG = true;
dpapi.InputMessageB = protectedData;
dpapi.Unprotect();
Console.WriteLine(dpapi.OutputMessage); //outputs "test"

Error Event (IPWorksEncrypt_DPAPI Class)

Fired when information is available about errors during data delivery.

Object Oriented Interface

public function fireError($param);

Procedural Interface

ipworksencrypt_dpapi_register_callback($res, 1, array($this, 'fireError'));

Parameter List

 'errorcode'
 'description'

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Progress Event (IPWorksEncrypt_DPAPI Class)

Fired as progress is made.

Object Oriented Interface

public function fireProgress($param);

Procedural Interface

ipworksencrypt_dpapi_register_callback($res, 2, array($this, 'fireProgress'));

Parameter List

 'bytesprocessed'
 'percentprocessed'

Remarks

This event is fired automatically as data is processed by the class.

The PercentProcessed parameter indicates the current status of the operation.

The BytesProcessed parameter holds the total number of bytes processed so far.

Config Settings (DPAPI Class)

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

DPAPI Config Settings

Base Config Settings

Trappable Errors (DPAPI Class)

DPAPI Errors

	104   Cannot read or write file.
	109   Cannot protect data.
	110   Cannot unprotect data
	111   OutputFile already exists and Overwrite is False.
	304   Cannot write file.
	305   Cannot read file.
	306   Cannot create file.