MessageDecryptor Class

Properties   Methods   Events   Config Settings   Errors  

The MessageDecryptor class decrypts data that is stored in the PKCS#7 format.

Syntax

class secureblackbox.MessageDecryptor

Remarks

PKCS#7 (Public Key Cryptography Standard #7) is a common format used to store encrypted and signed data. It is used by a variety of protocols, including S/MIME and CMS.

MessageDecryptor is capable of decrypting encrypted PKCS#7 data stored in EnvelopedData (asymmetric encryption) and EncryptedData (symmetric encryption) subformats. RSA and ECDH key wrapping and all popular symmetric encryption algorithms are supported.

Setting up and using MessageDecryptor is easy:

• Set up your source and destination via input_file (input_bytes) and output_file (output_bytes) properties.
• For certificate-based (asymmetric) encryption, put the decryption certificate (with its private key included) to the certificates collection.
• For key-based (symmetric) encryption, assign the symmetric key to key property. Note: you can find out whether asymmetric or symmetric encryption was used on the input message using the check_encryption_type method.
• Call decrypt to execute the operation.

Note that MessageDecryptor only works with binary PKCS#7-compliant encrypted messages. For processing encrypted S/MIME emails, see MailReader. For decrypting PGP messages, see PGPReader. For raw symmetric encryption, see SymmetricCrypto. For processing XML-ENC messages, see XMLDecryptor.

 
 Copy
MessageDecryptor decryptor = new MessageDecryptor();

// Select the file which contains the message that will be decrypted
decryptor.setInputFile("encryptedMessage.bin");

// Select the file where the decrypted message will be written
decryptor.setOutputFile("decryptedMessage.txt");

// Providing the certificate with its private key to decrypt data
CertificateList certificateList = new CertificateList();
certificateList.add(new Certificate("cert.pfx","password"));
decryptor.setCertificates(certificateList);

decryptor.decrypt(); // Decrypt

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.

certificate_index Property

The index of certificate that was used to decrypt the message.

Syntax

def get_certificate_index() -> int: ...

certificate_index = property(get_certificate_index, None)

Default Value

-1

Remarks

This property contains the index of certificate (one of those residing in certificates collection) that was used to decrypt the message.

This property is read-only.

cert_count Property

The number of records in the Cert arrays.

Syntax

def get_cert_count() -> int: ...
def set_cert_count(value: int) -> None: ...

cert_count = property(get_cert_count, set_cert_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• cert_bytes
• cert_handle

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

cert_bytes Property

Returns the raw certificate data in DER format.

Syntax

def get_cert_bytes(cert_index: int) -> bytes: ...

Remarks

Returns the raw certificate data in DER format.

The cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the cert_count property.

This property is read-only.

cert_handle Property

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

Syntax

def get_cert_handle(cert_index: int) -> int: ...
def set_cert_handle(cert_index: int, value: int) -> None: ...

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 cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the cert_count property.

encryption_algorithm Property

The symmetric cipher that was used to encrypt the data.

Syntax

def get_encryption_algorithm() -> str: ...

encryption_algorithm = property(get_encryption_algorithm, None)

Default Value

""

Remarks

This property contains the symmetric algorithm that the creator had used to encrypt the message.

This property is read-only.

encryption_type Property

Specifies the kind of encrypted message to create.

Syntax

def get_encryption_type() -> int: ...

encryption_type = property(get_encryption_type, None)

Possible Values

0   # Unknown
1   # CertEncrypted
2   # KeyEncrypted
3   # CertEncryptedAndAuthenticated

Default Value

0

Remarks

Possible values:

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.

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

Path to the file containing the encrypted message.

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

Use this property to provide a file containing the encrypted data.

key Property

The symmetric key to use for decryption.

Syntax

def get_key() -> bytes: ...
def set_key(value: bytes) -> None: ...

key = property(get_key, set_key)

Remarks

Use this property to provide the symmetric key to decrypt the data. This property is only applicable for processing data of EncryptedData subtype.

Assign this property before calling decrypt.

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

Path to the file to save the decrypted data to.

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

Use this property to specify the output file where the decrypted message should be saved.

signed_attribute_count Property

The number of records in the SignedAttribute arrays.

Syntax

def get_signed_attribute_count() -> int: ...

signed_attribute_count = property(get_signed_attribute_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• signed_attribute_oid
• signed_attribute_value

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

This property is read-only.

signed_attribute_oid Property

The object identifier of the attribute.

Syntax

def get_signed_attribute_oid(signed_attribute_index: int) -> str: ...

Default Value

""

Remarks

The object identifier of the attribute.

The signed_attribute_index parameter specifies the index of the item in the array. The size of the array is controlled by the signed_attribute_count property.

This property is read-only.

signed_attribute_value Property

The value of the attribute.

Syntax

def get_signed_attribute_value(signed_attribute_index: int) -> bytes: ...

Remarks

The value of the attribute.

The signed_attribute_index parameter specifies the index of the item in the array. The size of the array is controlled by the signed_attribute_count property.

This property is read-only.

unsigned_attribute_count Property

The number of records in the UnsignedAttribute arrays.

Syntax

def get_unsigned_attribute_count() -> int: ...

unsigned_attribute_count = property(get_unsigned_attribute_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• unsigned_attribute_oid
• unsigned_attribute_value

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

This property is read-only.

unsigned_attribute_oid Property

The object identifier of the attribute.

Syntax

def get_unsigned_attribute_oid(unsigned_attribute_index: int) -> str: ...

Default Value

""

Remarks

The object identifier of the attribute.

The unsigned_attribute_index parameter specifies the index of the item in the array. The size of the array is controlled by the unsigned_attribute_count property.

This property is read-only.

unsigned_attribute_value Property

The value of the attribute.

Syntax

def get_unsigned_attribute_value(unsigned_attribute_index: int) -> bytes: ...

Remarks

The value of the attribute.

The unsigned_attribute_index parameter specifies the index of the item in the array. The size of the array is controlled by the unsigned_attribute_count property.

This property is read-only.

check_encryption_type Method

Determines the type of encrypted message in the supplied file.

Syntax

def check_encryption_type() -> int: ...

Remarks

Use this method to determine the kind of the signature stored in input_file (input_stream).

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

Attempts to decrypt an encrypted PKCS#7 message.

Syntax

def decrypt() -> None: ...

Remarks

Call this method to attempt to decrypt the PKCS#7 encrypted data. This call supports EnvelopedData and EncryptedData subtypes on input.

Use input_file or input_stream property to provide the data, and either certificates or key to supply the decryption key material.

When processing enveloped data, the class may fire on_recipient_found event to report recipient information.

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_error Event

Information about errors during PKCS#7 message decryption.

Syntax

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

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

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

Remarks

The event is fired in case of exceptional conditions during message processing.

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

on_external_decrypt Event

Handles remote or external decryption.

Syntax

class MessageDecryptorExternalDecryptEventParams(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 MessageDecryptor:
@property
def on_external_decrypt() -> Callable[[MessageDecryptorExternalDecryptEventParams], None]: ...
@on_external_decrypt.setter
def on_external_decrypt(event_hook: Callable[[MessageDecryptorExternalDecryptEventParams], 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 MessageDecryptorNotificationEventParams(object):
  @property
  def event_id() -> str: ...

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

# In class MessageDecryptor:
@property
def on_notification() -> Callable[[MessageDecryptorNotificationEventParams], None]: ...
@on_notification.setter
def on_notification(event_hook: Callable[[MessageDecryptorNotificationEventParams], 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_recipient_found Event

Fires to report a message addressee parameters.

Syntax

class MessageDecryptorRecipientFoundEventParams(object):
  @property
  def issuer_rdn() -> str: ...

  @property
  def serial_number() -> bytes: ...

  @property
  def subject_key_id() -> bytes: ...

  @property
  def cert_found() -> bool: ...

# In class MessageDecryptor:
@property
def on_recipient_found() -> Callable[[MessageDecryptorRecipientFoundEventParams], None]: ...
@on_recipient_found.setter
def on_recipient_found(event_hook: Callable[[MessageDecryptorRecipientFoundEventParams], None]) -> None: ...

Remarks

This event is fired for each addressee the message is encrypted for. It may fire several times in a row if the message is encrypted for more than one recipient.

The IssuerRDN, SerialNumber, and SubjectKeyID parameters to identify the recipient's certificate. CertFound indicates if the specified certificate has been located in certificates collection. If it wasn't, you might want to look up the certificate manually, and add it to the collection inside the event handler.

MessageDecryptor Config Settings

MessageDecryptor 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");

MessageDecryptor Errors

MessageDecryptor Errors