DPAPI Module

Properties   Methods   Events   Config Settings   Errors  

The DPAPI module allows you to protect and unprotect data.

Syntax

IPWorksEncrypt.Dpapi

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)

//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)

//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)

//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)

//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 module with short descriptions. Click on the links for further details.

Method List

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

Event List

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

Config Settings

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

DataDescription Property (DPAPI Module)

The description of data.

Syntax

• Swift
• Objective-C

public var dataDescription: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=dataDescription,setter=setDataDescription:) NSString* dataDescription;

- (NSString*)dataDescription;
- (void)setDataDescription :(NSString*)newDataDescription;

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.

InputFile Property (DPAPI Module)

The file to process.

Syntax

• Swift
• Objective-C

public var inputFile: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=inputFile,setter=setInputFile:) NSString* inputFile;

- (NSString*)inputFile;
- (void)setInputFile :(NSString*)newInputFile;

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.

InputMessage Property (DPAPI Module)

The message to process.

Syntax

• Swift
• Objective-C

public var inputMessage: String {
  get {...}
  set {...}
}

public var inputMessageB: Data {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=inputMessage,setter=setInputMessage:) NSString* inputMessage;

- (NSString*)inputMessage;
- (void)setInputMessage :(NSString*)newInputMessage;

@property (nonatomic,readwrite,assign,getter=inputMessageB,setter=setInputMessageB:) NSData* inputMessageB;

- (NSData*)inputMessageB;
- (void)setInputMessageB :(NSData*)newInputMessage;

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.

OutputFile Property (DPAPI Module)

The output file when encrypting or decrypting.

Syntax

• Swift
• Objective-C

public var outputFile: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=outputFile,setter=setOutputFile:) NSString* outputFile;

- (NSString*)outputFile;
- (void)setOutputFile :(NSString*)newOutputFile;

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.

OutputMessage Property (DPAPI Module)

The output message after processing.

Syntax

• Swift
• Objective-C

public var outputMessage: String {
  get {...}
}

public var outputMessageB: Data {
  get {...}
}

@property (nonatomic,readonly,assign,getter=outputMessage) NSString* outputMessage;

- (NSString*)outputMessage;

@property (nonatomic,readonly,assign,getter=outputMessageB) NSData* outputMessageB;

- (NSData*)outputMessageB;

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.

Overwrite Property (DPAPI Module)

Indicates whether or not the module should overwrite files.

Syntax

• Swift
• Objective-C

public var overwrite: Bool {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=overwrite,setter=setOverwrite:) BOOL overwrite;

- (BOOL)overwrite;
- (void)setOverwrite :(BOOL)newOverwrite;

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.

Password Property (DPAPI Module)

An optional password to further protect data.

Syntax

• Swift
• Objective-C

public var password: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=password,setter=setPassword:) NSString* password;

- (NSString*)password;
- (void)setPassword :(NSString*)newPassword;

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.

PromptTitle Property (DPAPI Module)

The title of the prompt window.

Syntax

• Swift
• Objective-C

public var promptTitle: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=promptTitle,setter=setPromptTitle:) NSString* promptTitle;

- (NSString*)promptTitle;
- (void)setPromptTitle :(NSString*)newPromptTitle;

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.

PromptUser Property (DPAPI Module)

Whether to display a prompt.

Syntax

• Swift
• Objective-C

public var promptUser: Bool {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=promptUser,setter=setPromptUser:) BOOL promptUser;

- (BOOL)promptUser;
- (void)setPromptUser :(BOOL)newPromptUser;

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 .

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

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

ProtectionDescriptor Property (DPAPI Module)

The CNG protection descriptor.

Syntax

• Swift
• Objective-C

public var protectionDescriptor: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=protectionDescriptor,setter=setProtectionDescriptor:) NSString* protectionDescriptor;

- (NSString*)protectionDescriptor;
- (void)setProtectionDescriptor :(NSString*)newProtectionDescriptor;

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

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.

UseCNG Property (DPAPI Module)

Whether to use CNG DPAPI.

Syntax

• Swift
• Objective-C

public var useCNG: Bool {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=useCNG,setter=setUseCNG:) BOOL useCNG;

- (BOOL)useCNG;
- (void)setUseCNG :(BOOL)newUseCNG;

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.

UseHex Property (DPAPI Module)

Whether input or output is hex encoded.

Syntax

• Swift
• Objective-C

public var useHex: Bool {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=useHex,setter=setUseHex:) BOOL useHex;

- (BOOL)useHex;
- (void)setUseHex :(BOOL)newUseHex;

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.

Config Method (DPAPI Module)

Sets or retrieves a configuration setting.

Syntax

• Swift
• Objective-C

public func config(configurationString: String) throws -> String

- (NSString*)config:(NSString*)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 (DPAPI Module)

Protects the data.

Syntax

• Swift
• Objective-C

public func protect() throws -> Void

- (void)protect;

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)

//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)

//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 (DPAPI Module)

Resets the component.

Syntax

• Swift
• Objective-C

public func reset() throws -> Void

- (void)reset;

Remarks

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

Unprotect Method (DPAPI Module)

Unprotects the data.

Syntax

• Swift
• Objective-C

public func unprotect() throws -> Void

- (void)unprotect;

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)

//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)

//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 (DPAPI Module)

Fired when information is available about errors during data delivery.

Syntax

• Swift
• Objective-C

func onError(errorCode: Int32, description: String)

- (void)onError:(int)errorCode :(NSString*)description;

Remarks

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

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 (DPAPI Module)

Fired as progress is made.

Syntax

• Swift
• Objective-C

func onProgress(bytesProcessed: Int64, percentProcessed: Int32)

- (void)onProgress:(long long)bytesProcessed :(int)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 Module)

DPAPI Config Settings

Base Config Settings

Trappable Errors (DPAPI Module)

DPAPI Errors