XMLDecryptor Class

Properties   Methods   Events   Config Settings   Errors  

The XMLDecryptor class decrypts XML documents.

Syntax

class secureblackbox.XMLDecryptor

Remarks

XMlDecryptor decrypts XML documents encrypted with certificates or generic keys.

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.

decryption_key Property

The symmetric (session) key used to encrypt the data.

Syntax

def get_decryption_key() -> bytes: ...
def set_decryption_key(value: bytes) -> None: ...

decryption_key = property(get_decryption_key, set_decryption_key)

Remarks

Use this property to provide the encryption symmetric (session) key that will be used to encrypt a data.

It is required when the encrypt_key property is disabled. If the encrypt_key property is enabled, and no value is set, the component will generate a random session key (recommended).

encoding Property

Specifies XML encoding.

Syntax

def get_encoding() -> str: ...
def set_encoding(value: str) -> None: ...

encoding = property(get_encoding, set_encoding)

Default Value

""

Remarks

Use this property to specify the encoding to apply to the XML documents.

encrypted_data_type Property

Defines the type of data being encrypted.

Syntax

def get_encrypted_data_type() -> int: ...

encrypted_data_type = property(get_encrypted_data_type, None)

Possible Values

0   # Element
1   # Content
2   # External

Default Value

0

Remarks

This property defines what data type is about to be encrypted.

Supported values:

This property is read-only.

encryption_method Property

The encryption method used to encrypt the document.

Syntax

def get_encryption_method() -> str: ...

encryption_method = property(get_encryption_method, None)

Default Value

"AES256"

Remarks

This property contains the encryption algorithm used to encrypt the XML document.

Supported values:

If use_gcm property is enabled, then supported values are:

This property is read-only.

encrypt_key Property

Specifies if the encryption key is encrypted.

Syntax

def get_encrypt_key() -> bool: ...

encrypt_key = property(get_encrypt_key, None)

Default Value

TRUE

Remarks

Use this property to specify if encryption (session) key should be encrypted and also added to the encrypted data.

This property is read-only.

external_crypto_async_document_id Property

Specifies an optional document ID for SignAsyncBegin() and SignAsyncEnd() calls.

Syntax

def get_external_crypto_async_document_id() -> str: ...
def set_external_crypto_async_document_id(value: str) -> None: ...

external_crypto_async_document_id = property(get_external_crypto_async_document_id, set_external_crypto_async_document_id)

Default Value

""

Remarks

Specifies an optional document ID for SignAsyncBegin() and SignAsyncEnd() calls.

Use this property when working with multi-signature DCAuth requests and responses to uniquely identify documents signed within a larger batch. On the completion stage, this value helps the signing component identify the correct signature in the returned batch of responses.

If using batched requests, make sure to set this property to the same value on both the pre-signing (SignAsyncBegin) and completion (SignAsyncEnd) stages.

external_crypto_custom_params Property

Custom parameters to be passed to the signing service (uninterpreted).

Syntax

def get_external_crypto_custom_params() -> str: ...
def set_external_crypto_custom_params(value: str) -> None: ...

external_crypto_custom_params = property(get_external_crypto_custom_params, set_external_crypto_custom_params)

Default Value

""

Remarks

Custom parameters to be passed to the signing service (uninterpreted).

external_crypto_data Property

Additional data to be included in the async state and mirrored back by the requestor.

Syntax

def get_external_crypto_data() -> str: ...
def set_external_crypto_data(value: str) -> None: ...

external_crypto_data = property(get_external_crypto_data, set_external_crypto_data)

Default Value

""

Remarks

Additional data to be included in the async state and mirrored back by the requestor.

external_crypto_external_hash_calculation Property

Specifies whether the message hash is to be calculated at the external endpoint.

Syntax

def get_external_crypto_external_hash_calculation() -> bool: ...
def set_external_crypto_external_hash_calculation(value: bool) -> None: ...

external_crypto_external_hash_calculation = property(get_external_crypto_external_hash_calculation, set_external_crypto_external_hash_calculation)

Default Value

FALSE

Remarks

Specifies whether the message hash is to be calculated at the external endpoint. Please note that this mode is not supported by the DCAuth class.

If set to true, the class will pass a few kilobytes of to-be-signed data from the document to the OnExternalSign event. This only applies when SignExternal() is called.

external_crypto_hash_algorithm Property

Specifies the request's signature hash algorithm.

Syntax

def get_external_crypto_hash_algorithm() -> str: ...
def set_external_crypto_hash_algorithm(value: str) -> None: ...

external_crypto_hash_algorithm = property(get_external_crypto_hash_algorithm, set_external_crypto_hash_algorithm)

Default Value

"SHA256"

Remarks

Specifies the request's signature hash algorithm.

external_crypto_key_id Property

The ID of the pre-shared key used for DC request authentication.

Syntax

def get_external_crypto_key_id() -> str: ...
def set_external_crypto_key_id(value: str) -> None: ...

external_crypto_key_id = property(get_external_crypto_key_id, set_external_crypto_key_id)

Default Value

""

Remarks

The ID of the pre-shared key used for DC request authentication.

Asynchronous DCAuth-driven communication requires that parties authenticate each other with a secret pre-shared cryptographic key. This provides an extra protection layer for the protocol and diminishes the risk of the private key becoming abused by foreign parties. Use this property to provide the pre-shared key identifier, and use external_crypto_key_secret to pass the key itself.

The same KeyID/KeySecret pair should be used on the DCAuth side for the signing requests to be accepted.

Note: The KeyID/KeySecret scheme is very similar to the AuthKey scheme used in various Cloud service providers to authenticate users.

Example:

 
 Copy
  signer.ExternalCrypto.KeyID = "MainSigningKey";
  signer.ExternalCrypto.KeySecret = "abcdef0123456789";

external_crypto_key_secret Property

The pre-shared key used for DC request authentication.

Syntax

def get_external_crypto_key_secret() -> str: ...
def set_external_crypto_key_secret(value: str) -> None: ...

external_crypto_key_secret = property(get_external_crypto_key_secret, set_external_crypto_key_secret)

Default Value

""

Remarks

The pre-shared key used for DC request authentication. This key must be set and match the key used by the DCAuth counterpart for the scheme to work.

Read more about configuring authentication in the external_crypto_key_id topic.

external_crypto_method Property

Specifies the asynchronous signing method.

Syntax

def get_external_crypto_method() -> int: ...
def set_external_crypto_method(value: int) -> None: ...

external_crypto_method = property(get_external_crypto_method, set_external_crypto_method)

Possible Values

0   # PKCS1
1   # PKCS7

Default Value

0

Remarks

Specifies the asynchronous signing method. This is typically defined by the DC server capabilities and setup.

Available options:

external_crypto_mode Property

Specifies the external cryptography mode.

Syntax

def get_external_crypto_mode() -> int: ...
def set_external_crypto_mode(value: int) -> None: ...

external_crypto_mode = property(get_external_crypto_mode, set_external_crypto_mode)

Possible Values

0   # Default
1   # Disabled
2   # Generic
3   # DCAuth
4   # DCAuthJSON

Default Value

0

Remarks

Specifies the external cryptography mode.

Available options:

external_crypto_public_key_algorithm Property

Provide the public key algorithm here if the certificate is not available on the pre-signing stage.

Syntax

def get_external_crypto_public_key_algorithm() -> str: ...
def set_external_crypto_public_key_algorithm(value: str) -> None: ...

external_crypto_public_key_algorithm = property(get_external_crypto_public_key_algorithm, set_external_crypto_public_key_algorithm)

Default Value

""

Remarks

Provide the public key algorithm here if the certificate is not available on the pre-signing stage.

external_data Property

The data that should be encrypted.

Syntax

def get_external_data() -> bytes: ...
def set_external_data(value: bytes) -> None: ...

external_data = property(get_external_data, set_external_data)

Remarks

Use this property to provide the data that should be encrypted if encrypted_data_type property is set to cxedtExternal value.

fips_mode Property

Reserved.

Syntax

def get_fips_mode() -> bool: ...
def set_fips_mode(value: bool) -> None: ...

fips_mode = property(get_fips_mode, set_fips_mode)

Default Value

FALSE

Remarks

This property is reserved for future use.

input_bytes Property

Use this property to pass the input to class in byte array form.

Syntax

def get_input_bytes() -> bytes: ...
def set_input_bytes(value: bytes) -> None: ...

input_bytes = property(get_input_bytes, set_input_bytes)

Remarks

Assign a byte array containing the data to be processed to this property.

input_file Property

The XML file to be decrypted.

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

Provide the path to the XML document to be decrypted.

key_decryption_cert_bytes Property

Returns the raw certificate data in DER format.

Syntax

def get_key_decryption_cert_bytes() -> bytes: ...

key_decryption_cert_bytes = property(get_key_decryption_cert_bytes, None)

Remarks

Returns the raw certificate data in DER format.

This property is read-only.

key_decryption_cert_handle Property

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Syntax

def get_key_decryption_cert_handle() -> int: ...
def set_key_decryption_cert_handle(value: int) -> None: ...

key_decryption_cert_handle = property(get_key_decryption_cert_handle, set_key_decryption_cert_handle)

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation.

 
 Copy
  pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

key_decryption_key Property

The symmetric key used to decrypt a session key.

Syntax

def get_key_decryption_key() -> bytes: ...
def set_key_decryption_key(value: bytes) -> None: ...

key_decryption_key = property(get_key_decryption_key, set_key_decryption_key)

Remarks

Use this property to provide the decryption symmetric key that will be used to decrypt a session key. It is required when encrypt_key property is enabled and key_encryption_type set to cxetKeyWrap value.

key_encryption_type Property

Defines how the session key is encrypted.

Syntax

def get_key_encryption_type() -> int: ...

key_encryption_type = property(get_key_encryption_type, None)

Possible Values

0   # KeyTransport
1   # KeyWrap

Default Value

0

Remarks

This property defines how the session key is encrypted.

Supported values:

This property is read-only.

key_info_item_count Property

The number of records in the KeyInfoItem arrays.

Syntax

def get_key_info_item_count() -> int: ...

key_info_item_count = property(get_key_info_item_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• key_info_item_issuer_rdn
• key_info_item_serial_number
• key_info_item_subject_key_id
• key_info_item_subject_rdn

The array indices start at 0 and end at key_info_item_count - 1.

This property is read-only.

key_info_item_issuer_rdn Property

A list of Property=Value pairs that uniquely identify the certificate issuer.

Syntax

def get_key_info_item_issuer_rdn(key_info_item_index: int) -> str: ...

Default Value

""

Remarks

A list of Property=Value pairs that uniquely identify the certificate issuer.

Example: /C=US/O=Nationwide CA/CN=Web Certification Authority

The key_info_item_index parameter specifies the index of the item in the array. The size of the array is controlled by the key_info_item_count property.

This property is read-only.

key_info_item_serial_number Property

Returns the certificate's serial number.

Syntax

def get_key_info_item_serial_number(key_info_item_index: int) -> bytes: ...

Remarks

Returns the certificate's serial number.

The serial number is a binary string that uniquely identifies a certificate among others issued by the same CA. According to the X.509 standard, the (issuer, serial number) pair should be globally unique to facilitate chain building.

The key_info_item_index parameter specifies the index of the item in the array. The size of the array is controlled by the key_info_item_count property.

This property is read-only.

key_info_item_subject_key_id Property

Contains a unique identifier of the certificate's cryptographic key.

Syntax

def get_key_info_item_subject_key_id(key_info_item_index: int) -> bytes: ...

Remarks

Contains a unique identifier of the certificate's cryptographic key.

Subject Key Identifier is a certificate extension which allows a specific public key to be associated with a certificate holder. Typically, subject key identifiers of CA certificates are recorded as respective CA key identifiers in the subordinate certificates that they issue, which facilitates chain building.

The key_info_item_subject_key_id and key_info_item_ca_key_id properties of self-signed certificates typically contain identical values, as in that specific case, the issuer and the subject are the same entity.

The key_info_item_index parameter specifies the index of the item in the array. The size of the array is controlled by the key_info_item_count property.

This property is read-only.

key_info_item_subject_rdn Property

A list of Property=Value pairs that uniquely identify the certificate holder (subject).

Syntax

def get_key_info_item_subject_rdn(key_info_item_index: int) -> str: ...

Default Value

""

Remarks

A list of Property=Value pairs that uniquely identify the certificate holder (subject).

Depending on the purpose of the certificate and the policies of the CA that issued it, the values included in the subject record may differ drastically and contain business or personal names, web URLs, email addresses, and other data.

Example: /C=US/O=Oranges and Apples, Inc./OU=Accounts Receivable/1.2.3.4.5=Value with unknown OID/CN=Margaret Watkins.

The key_info_item_index parameter specifies the index of the item in the array. The size of the array is controlled by the key_info_item_count property.

This property is read-only.

key_info_certificate_count Property

The number of records in the KeyInfoCertificate arrays.

Syntax

def get_key_info_certificate_count() -> int: ...

key_info_certificate_count = property(get_key_info_certificate_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• key_info_certificate_bytes
• key_info_certificate_handle

The array indices start at 0 and end at key_info_certificate_count - 1.

This property is read-only.

key_info_certificate_bytes Property

Returns the raw certificate data in DER format.

Syntax

def get_key_info_certificate_bytes(key_info_certificate_index: int) -> bytes: ...

Remarks

Returns the raw certificate data in DER format.

The key_info_certificate_index parameter specifies the index of the item in the array. The size of the array is controlled by the key_info_certificate_count property.

This property is read-only.

key_info_certificate_handle Property

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Syntax

def get_key_info_certificate_handle(key_info_certificate_index: int) -> int: ...

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation.

 
 Copy
  pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

The key_info_certificate_index parameter specifies the index of the item in the array. The size of the array is controlled by the key_info_certificate_count property.

This property is read-only.

key_transport_method Property

Defines how the session key is encrypted.

Syntax

def get_key_transport_method() -> int: ...

key_transport_method = property(get_key_transport_method, None)

Possible Values

0   # RSA15
1   # RSAOAEP

Default Value

0

Remarks

This property defines how the session key is encrypted.

Supported values:

This property is read-only.

key_wrap_method Property

The key wrap method used to encrypt the session key.

Syntax

def get_key_wrap_method() -> str: ...

key_wrap_method = property(get_key_wrap_method, None)

Default Value

"Cammelia256"

Remarks

This property specifies the key wrap algorithm used to encrypt the session key.

Supported values:

This property is read-only.

output_bytes Property

Use this property to read the output the class object has produced.

Syntax

def get_output_bytes() -> bytes: ...

output_bytes = property(get_output_bytes, None)

Remarks

Read the contents of this property after the operation has completed to read the produced output. This property will only be set if the output_file and output_stream properties had not been assigned.

This property is read-only.

output_file Property

Defines where to save the decrypted XML document.

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

A path where the decrypted XML document should be saved.

use_gcm Property

Indicates if GCM mode was enabled.

Syntax

def get_use_gcm() -> bool: ...

use_gcm = property(get_use_gcm, None)

Default Value

TRUE

Remarks

Use this property to check if GCM encryption mode was enabled.

This property is read-only.

xml_element Property

Defines the XML element to decrypt.

Syntax

def get_xml_element() -> str: ...
def set_xml_element(value: str) -> None: ...

xml_element = property(get_xml_element, set_xml_element)

Default Value

""

Remarks

Defines the XML element to decrypt.

Supported values are:

add_known_namespace Method

Adds known prefix and correspondent namespace URI.

Syntax

def add_known_namespace(prefix: str, uri: str) -> None: ...

Remarks

Use this method to add a known prefix and namespace URI that are used in XPath expression within XMLElement/XMLNode property, and within TargetXMLElement and XPathPrefixList properties of the references.

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.

decrypt Method

Decrypts an XML document.

Syntax

def decrypt() -> None: ...

Remarks

Call this method to decrypt an XML document.

do_action Method

Performs an additional action.

Syntax

def do_action(action_id: str, action_params: str) -> str: ...

Remarks

do_action is a generic method available in every class. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insensitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

Common ActionIDs:

reset Method

Resets the class settings.

Syntax

def reset() -> None: ...

Remarks

reset is a generic method available in every class.

on_decryption_info_needed Event

Requests decryption information from the application.

Syntax

class XMLDecryptorDecryptionInfoNeededEventParams(object):
  @property
  def cancel_decryption() -> bool: ...
  @cancel_decryption.setter
  def cancel_decryption(value) -> None: ...

# In class XMLDecryptor:
@property
def on_decryption_info_needed() -> Callable[[XMLDecryptorDecryptionInfoNeededEventParams], None]: ...
@on_decryption_info_needed.setter
def on_decryption_info_needed(event_hook: Callable[[XMLDecryptorDecryptionInfoNeededEventParams], None]) -> None: ...

Remarks

This event is fired when the component needs decryption information (the private key) from the user.

Use encrypt_key, Config["KeyName"] and key_encryption_type properties to identify the encryption type and then set decryption_key or key_decryption_key or key_decryption_certificate properties accordingly.

if CancelDecryption property is set to true value (default value) then decryption would fail if provided key/certificate is invalid. Otherwise this event would be fired again.

on_error Event

Information about errors during signing.

Syntax

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

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

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

Remarks

The event is fired in case of exceptional conditions during signing.

ErrorCode contains an error code and Description contains a textual description of the error.

on_external_decrypt Event

Handles remote or external decryption.

Syntax

class XMLDecryptorExternalDecryptEventParams(object):
  @property
  def operation_id() -> str: ...

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

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

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

  @property
  def data() -> str: ...
  @data.setter
  def data(value) -> None: ...

# In class XMLDecryptor:
@property
def on_external_decrypt() -> Callable[[XMLDecryptorExternalDecryptEventParams], None]: ...
@on_external_decrypt.setter
def on_external_decrypt(event_hook: Callable[[XMLDecryptorExternalDecryptEventParams], None]) -> None: ...

Remarks

Assign a handler to this event if you need to delegate a low-level decryption operation to an external, remote, or custom decryption engine. The handler receives an encrypted value in the EncryptedData parameter, and is expected to decrypt it and place the decrypted value into the Data parameter.

OperationId provides a comment about the operation and its origin. It depends on the exact class being used, and may be empty. Algorithm specifies the encryption algorithm being used, and Pars contains algorithm-dependent parameters.

The class uses base16 (hex) encoding for the EncryptedData, Data, and Pars parameters. If your decryption engine uses a different input and output encoding, you may need to decode and/or encode the data before and/or after the decryption.

Sample data encoded in base16: a0dee2a0382afbb09120ffa7ccd8a152 - lower case base16 A0DEE2A0382AFBB09120FFA7CCD8A152 - upper case base16

on_notification Event

This event notifies the application about an underlying control flow event.

Syntax

class XMLDecryptorNotificationEventParams(object):
  @property
  def event_id() -> str: ...

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

# In class XMLDecryptor:
@property
def on_notification() -> Callable[[XMLDecryptorNotificationEventParams], None]: ...
@on_notification.setter
def on_notification(event_hook: Callable[[XMLDecryptorNotificationEventParams], None]) -> None: ...

Remarks

The class fires this event to let the application know about some event, occurrence, or milestone in the class. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in the EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the class, the exact action it is performing, or the document being processed, one or both may be omitted.

on_save_external_data Event

Request to save decrypted external data.

Syntax

class XMLDecryptorSaveExternalDataEventParams(object):
  @property
  def external_data() -> bytes: ...

# In class XMLDecryptor:
@property
def on_save_external_data() -> Callable[[XMLDecryptorSaveExternalDataEventParams], None]: ...
@on_save_external_data.setter
def on_save_external_data(event_hook: Callable[[XMLDecryptorSaveExternalDataEventParams], None]) -> None: ...

Remarks

This event is fired when the component successfully decrypted an external data and needs to save it. The same data could be read using external_data property.

It makes sense to use this event when the XML document contains several xenc:EncryptedData elements and the component decrypts them all.

XMLDecryptor Config Settings

XMLDecryptor Config Settings

Base Config Settings

 
 Copy
PKICache=certificate,crl,ocsp

 
 Copy
PKICachePath=C:\Temp\cache

 
 Copy
Config("XMLRDNDescriptorName[OID]=PrimaryName,Alias1,Alias2");

 
 Copy
Config("XMLRDNDescriptorName[2.5.4.5]=SERIALNUMBER");

 
 Copy
Config("XMLRDNDescriptorName[1.2.840.113549.1.9.1]=E,EMAIL,EMAILADDRESS");

XMLDecryptor Errors

XMLDecryptor Errors