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)

Default Value

0

Remarks

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

Supported values:

If the xml_node property is set to the empty string, and the input_stream and input_file properties are not provided, then a new XML document will be created with the xenc:EncryptedData element as a document element.

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 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 all components. In particular, components operating with larger objects (PDFSigner, CAdESSigner, XAdESSigner) do not support it.

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 extra protection layer for the protocol and diminishes the risk of 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: 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)

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)

Default Value

0

Remarks

Specifies the external cryptography mode.

Available options:

external_crypto_public_key_algorithm Property

Provide 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 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 the 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 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 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. 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)

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 collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate issuer.

Syntax

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

Default Value

""

Remarks

A collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate issuer.

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 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 (fingerprint) of the certificate's private key.

Syntax

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

Remarks

Contains a unique identifier (fingerprint) of the certificate's private key.

Subject Key Identifier is a (non-critical) X.509 certificate extension which allows the identification of certificates containing a particular public key. In SecureBlackbox, the unique identifier is represented with a SHA1 hash of the bit string of the subject public key.

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 collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate holder (subject).

Syntax

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

Default Value

""

Remarks

A collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate holder (subject).

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 raw certificate data in DER format.

Syntax

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

Remarks

Returns 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. 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)

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 is completed to read the produced output. This property will only be set if 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:

namespace_count Property

The number of records in the Namespace arrays.

Syntax

def get_namespace_count() -> int: ...
def set_namespace_count(value: int) -> None: ...

namespace_count = property(get_namespace_count, set_namespace_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• namespace_prefix
• namespace_uri

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

namespace_prefix Property

A user-defined prefix value of a namespace.

Syntax

def get_namespace_prefix(namespace_index: int) -> str: ...
def set_namespace_prefix(namespace_index: int, value: str) -> None: ...

Default Value

""

Remarks

A user-defined prefix value of a namespace.

The namespace_index parameter specifies the index of the item in the array. The size of the array is controlled by the namespace_count property.

namespace_uri Property

A user-defined URI value of a namespace.

Syntax

def get_namespace_uri(namespace_index: int) -> str: ...
def set_namespace_uri(namespace_index: int, value: str) -> None: ...

Default Value

""

Remarks

A user-defined URI value of a namespace.

The namespace_index parameter specifies the index of the item in the array. The size of the array is controlled by the namespace_count property.

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 insencitive) 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;....

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 a 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 component being used, and may be empty. Algorithm specifies the encryption algorithm being used, and Pars contain algorithm-dependent parameters.

The component uses base16 (hex) encoding for 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.

A 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 component. 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 EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the component, 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

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.

XMLDecryptor Config Settings

Base Config Settings

XMLDecryptor Errors

XMLDecryptor Errors

	1048577   Invalid parameter value (SB_ERROR_INVALID_PARAMETER)
	1048578   Class is configured incorrectly (SB_ERROR_INVALID_SETUP)
	1048579   Operation cannot be executed in the current state (SB_ERROR_INVALID_STATE)
	1048580   Attempt to set an invalid value to a property (SB_ERROR_INVALID_VALUE)
	1048581   Certificate does not have its private key loaded (SB_ERROR_NO_PRIVATE_KEY)
	1048581   Cancelled by the user (SB_ERROR_CANCELLED_BY_USER) 
	39845889   Input file does not exist (SB_ERROR_XML_INPUTFILE_NOT_EXISTS)
	39845890   Data file does not exist (SB_ERROR_XML_DATAFILE_NOT_EXISTS)
	39845891   Unsupported signature method type (SB_ERROR_XML_UNSUPPORTED_SIGNATURE_METHOD_TYPE)
	39845892   Unsupported has algorithm (SB_ERROR_XML_UNSUPPORTED_HASH_ALGORITHM)
	39845893   Unsupported key type (SB_ERROR_XML_UNSUPPORTED_KEY_TYPE)
	39845894   Invalid key type (SB_ERROR_XML_INVALID_KEY_TYPE)
	39845895   Invalid encryption method (SB_ERROR_XML_INVALID_ENCRYPTION_METHOD)
	39845896   Not found (SB_ERROR_XML_NOT_FOUND)
	39845897   No element ID (SB_ERROR_XML_NO_ELEMENT_ID)