OSDP Class

Properties   Methods   Events   Config Settings   Errors  

The OSDP (Operating System Data Protection) class allows you to protect and unprotect data.

Syntax

class ipworksencrypt.OSDP

Remarks

On Windows, the class supports the classic Microsoft Windows Data Protection API (DPAPI) or CNG DPAPI implementation. The use of use_cng determines which implementation is used. Support for macOS is also available via the macOS keychain.

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. On macOS, a key is saved in the Keychain which is used to protect and uprotect data.

Protecting Data

protect protects the specified data.

On Windows, the class supports the classic Microsoft Windows Data Protection API (DPAPI) or CNG DPAPI implementation. The use of use_cng determines which implementation is used. Support for macOS is also available via the macOS keychain.

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

• data_description
• password
• prompt_title
• prompt_user

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

• protection_descriptor (required)
• EscapeDescriptor
• UseStreamMode

On macOS, the following settings are applicable:

• UseSystemKeychain
• KeychainServiceName

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:

• input_file
• input_message

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

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

Code Example (Classic DPAPI - use_cng is False)

//Protect OSDP osdp = new OSDP(); osdp.InputMessage = "test"; osdp.Protect(); byte[] protectedData = osdp.OutputMessageB; //Unprotect osdp = new OSDP(); osdp.InputMessageB = protectedData; osdp.Unprotect(); Console.WriteLine(osdp.OutputMessage); //outputs "test"

Code Example (CNG DPAPI - use_cng is True)

//Protect OSDP osdp = new OSDP(); osdp.UseCNG = true; osdp.ProtectionDescriptor = "LOCAL=user"; osdp.InputMessage = "test"; osdp.Protect(); byte[] protectedData = osdp.OutputMessageB; //Unprotect osdp = new OSDP(); osdp.UseCNG = true; osdp.InputMessageB = protectedData; osdp.Unprotect(); Console.WriteLine(osdp.OutputMessage); //outputs "test"

Code Example (macOS)

//Protect OSDP osdp = new OSDP(); osdp.Config("UseSystemKeychain=false"); osdp.Config("KeychainServiceName=nsoftware OSDP User Key"); osdp.InputMessage = "test"; osdp.Protect(); byte[] protectedData = osdp.OutputMessageB; //Unprotect osdp = new OSDP(); osdp.Config("UseSystemKeychain=false"); osdp.Config("KeychainServiceName=nsoftware OSDP User Key"); osdp.InputMessageB = protectedData; osdp.Unprotect(); Console.WriteLine(osdp.OutputMessage); //outputs "test"

Unprotecting Data

unprotect unprotects the specified data.

On Windows, the class supports the classic Microsoft Windows Data Protection API (DPAPI) or CNG DPAPI implementation. The use of use_cng determines which implementation is used. Support for macOS is also available via the macOS keychain.

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

• data_description (populated after completion)
• password

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

• protection_descriptor (populated after completion)
• UseStreamMode

On macOS, the following settings are applicable:

• UseSystemKeychain
• KeychainServiceName

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:

• input_file
• input_message

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

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

Code Example (Classic DPAPI - use_cng is False)

//Protect OSDP osdp = new OSDP(); osdp.InputMessage = "test"; osdp.Protect(); byte[] protectedData = osdp.OutputMessageB; //Unprotect osdp = new OSDP(); osdp.InputMessageB = protectedData; osdp.Unprotect(); Console.WriteLine(osdp.OutputMessage); //outputs "test"

Code Example (CNG DPAPI - use_cng is True)

//Protect OSDP osdp = new OSDP(); osdp.UseCNG = true; osdp.ProtectionDescriptor = "LOCAL=user"; osdp.InputMessage = "test"; osdp.Protect(); byte[] protectedData = osdp.OutputMessageB; //Unprotect osdp = new OSDP(); osdp.UseCNG = true; osdp.InputMessageB = protectedData; osdp.Unprotect(); Console.WriteLine(osdp.OutputMessage); //outputs "test"

Code Example (macOS)

//Protect OSDP osdp = new OSDP(); osdp.Config("UseSystemKeychain=false"); osdp.Config("KeychainServiceName=nsoftware OSDP User Key"); osdp.InputMessage = "test"; osdp.Protect(); byte[] protectedData = osdp.OutputMessageB; //Unprotect osdp = new OSDP(); osdp.Config("UseSystemKeychain=false"); osdp.Config("KeychainServiceName=nsoftware OSDP User Key"); osdp.InputMessageB = protectedData; osdp.Unprotect(); Console.WriteLine(osdp.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.

data_description Property

The description of data.

Syntax

def get_data_description() -> str: ...
def set_data_description(value: str) -> None: ...

data_description = property(get_data_description, set_data_description)

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 use_cng is set to True.

This setting is not applicable on macOS.

input_file Property

The file to process.

Syntax

def get_input_file() -> str: ...
def set_input_file(value: str) -> None: ...

input_file = property(get_input_file, set_input_file)

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:

• input_file
• input_message

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

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

input_message Property

The message to process.

Syntax

def get_input_message() -> bytes: ...
def set_input_message(value: bytes) -> None: ...

input_message = property(get_input_message, set_input_message)

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:

• input_file
• input_message

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

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

output_file Property

The output file when encrypting or decrypting.

Syntax

def get_output_file() -> str: ...
def set_output_file(value: str) -> None: ...

output_file = property(get_output_file, set_output_file)

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:

• input_file
• input_message

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

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

output_message Property

The output message after processing.

Syntax

def get_output_message() -> bytes: ...

output_message = property(get_output_message, None)

Default Value

""

Remarks

This property will be populated with the output from the operation if output_file 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:

• input_file
• input_message

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

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

This property is read-only.

overwrite Property

Indicates whether or not the class should overwrite files.

Syntax

def get_overwrite() -> bool: ...
def set_overwrite(value: bool) -> None: ...

overwrite = property(get_overwrite, set_overwrite)

Default Value

FALSE

Remarks

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

password Property

An optional password to further protect data.

Syntax

def get_password() -> str: ...
def set_password(value: str) -> None: ...

password = property(get_password, set_password)

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 use_cng is set to True.

This setting is not applicable on macOS.

prompt_title Property

The title of the prompt window.

Syntax

def get_prompt_title() -> str: ...
def set_prompt_title(value: str) -> None: ...

prompt_title = property(get_prompt_title, set_prompt_title)

Default Value

""

Remarks

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

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

This setting is not applicable on macOS.

prompt_user Property

Whether to display a prompt.

Syntax

def get_prompt_user() -> bool: ...
def set_prompt_user(value: bool) -> None: ...

prompt_user = property(get_prompt_user, set_prompt_user)

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 prompt_title may be set to customize the window title.

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

This setting is not applicable on macOS. ;

protection_descriptor Property

The CNG protection descriptor.

Syntax

def get_protection_descriptor() -> str: ...
def set_protection_descriptor(value: str) -> None: ...

protection_descriptor = property(get_protection_descriptor, set_protection_descriptor)

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 use_cng is set to True.

This setting is not applicable on macOS.

use_cng Property

Whether to use CNG DPAPI.

Syntax

def get_use_cng() -> bool: ...
def set_use_cng(value: bool) -> None: ...

use_cng = property(get_use_cng, set_use_cng)

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.

This setting is not applicable on macOS.

use_hex Property

Whether input or output is hex encoded.

Syntax

def get_use_hex() -> bool: ...
def set_use_hex(value: bool) -> None: ...

use_hex = property(get_use_hex, set_use_hex)

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. output_message or output_file will hold hex encoded data.

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

config Method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

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

Protects the data.

Syntax

def protect() -> None: ...

Remarks

protect protects the specified data.

On Windows, the class supports the classic Microsoft Windows Data Protection API (DPAPI) or CNG DPAPI implementation. The use of use_cng determines which implementation is used. Support for macOS is also available via the macOS keychain.

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

• data_description
• password
• prompt_title
• prompt_user

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

• protection_descriptor (required)
• EscapeDescriptor
• UseStreamMode

On macOS, the following settings are applicable:

• UseSystemKeychain
• KeychainServiceName

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:

• input_file
• input_message

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

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

Code Example (Classic DPAPI - use_cng is False)

//Protect OSDP osdp = new OSDP(); osdp.InputMessage = "test"; osdp.Protect(); byte[] protectedData = osdp.OutputMessageB; //Unprotect osdp = new OSDP(); osdp.InputMessageB = protectedData; osdp.Unprotect(); Console.WriteLine(osdp.OutputMessage); //outputs "test"

Code Example (CNG DPAPI - use_cng is True)

//Protect OSDP osdp = new OSDP(); osdp.UseCNG = true; osdp.ProtectionDescriptor = "LOCAL=user"; osdp.InputMessage = "test"; osdp.Protect(); byte[] protectedData = osdp.OutputMessageB; //Unprotect osdp = new OSDP(); osdp.UseCNG = true; osdp.InputMessageB = protectedData; osdp.Unprotect(); Console.WriteLine(osdp.OutputMessage); //outputs "test"

Code Example (macOS)

//Protect OSDP osdp = new OSDP(); osdp.Config("UseSystemKeychain=false"); osdp.Config("KeychainServiceName=nsoftware OSDP User Key"); osdp.InputMessage = "test"; osdp.Protect(); byte[] protectedData = osdp.OutputMessageB; //Unprotect osdp = new OSDP(); osdp.Config("UseSystemKeychain=false"); osdp.Config("KeychainServiceName=nsoftware OSDP User Key"); osdp.InputMessageB = protectedData; osdp.Unprotect(); Console.WriteLine(osdp.OutputMessage); //outputs "test"

reset Method

Resets the class.

Syntax

def reset() -> None: ...

Remarks

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

unprotect Method

Unprotects the data.

Syntax

def unprotect() -> None: ...

Remarks

unprotect unprotects the specified data.

On Windows, the class supports the classic Microsoft Windows Data Protection API (DPAPI) or CNG DPAPI implementation. The use of use_cng determines which implementation is used. Support for macOS is also available via the macOS keychain.

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

• data_description (populated after completion)
• password

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

• protection_descriptor (populated after completion)
• UseStreamMode

On macOS, the following settings are applicable:

• UseSystemKeychain
• KeychainServiceName

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:

• input_file
• input_message

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

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

Code Example (Classic DPAPI - use_cng is False)

//Protect OSDP osdp = new OSDP(); osdp.InputMessage = "test"; osdp.Protect(); byte[] protectedData = osdp.OutputMessageB; //Unprotect osdp = new OSDP(); osdp.InputMessageB = protectedData; osdp.Unprotect(); Console.WriteLine(osdp.OutputMessage); //outputs "test"

Code Example (CNG DPAPI - use_cng is True)

//Protect OSDP osdp = new OSDP(); osdp.UseCNG = true; osdp.ProtectionDescriptor = "LOCAL=user"; osdp.InputMessage = "test"; osdp.Protect(); byte[] protectedData = osdp.OutputMessageB; //Unprotect osdp = new OSDP(); osdp.UseCNG = true; osdp.InputMessageB = protectedData; osdp.Unprotect(); Console.WriteLine(osdp.OutputMessage); //outputs "test"

Code Example (macOS)

//Protect OSDP osdp = new OSDP(); osdp.Config("UseSystemKeychain=false"); osdp.Config("KeychainServiceName=nsoftware OSDP User Key"); osdp.InputMessage = "test"; osdp.Protect(); byte[] protectedData = osdp.OutputMessageB; //Unprotect osdp = new OSDP(); osdp.Config("UseSystemKeychain=false"); osdp.Config("KeychainServiceName=nsoftware OSDP User Key"); osdp.InputMessageB = protectedData; osdp.Unprotect(); Console.WriteLine(osdp.OutputMessage); //outputs "test"

on_error Event

Fired when information is available about errors during data delivery.

Syntax

class OSDPErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class OSDP:
@property
def on_error() -> Callable[[OSDPErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[OSDPErrorEventParams], None]) -> None: ...

Remarks

The on_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.

on_progress Event

Fired as progress is made.

Syntax

class OSDPProgressEventParams(object):
  @property
  def bytes_processed() -> int: ...

  @property
  def percent_processed() -> int: ...

# In class OSDP:
@property
def on_progress() -> Callable[[OSDPProgressEventParams], None]: ...
@on_progress.setter
def on_progress(event_hook: Callable[[OSDPProgressEventParams], None]) -> None: ...

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.

OSDP Config Settings

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.

OSDP Config Settings

Base Config Settings

OSDP Errors

OSDP Errors