MessageEncryptor Component

Properties   Methods   Events   Config Settings   Errors  

The MessageEncryptor component encrypts data and stores it in the PKCS#7 format.

Syntax

TsbxMessageEncryptor

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.

MessageEncryptor can encrypt binary data into PKCS#7 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 MessageEncryptor is easy:

• Set up your source and destination via InputFile (InputBytes) and OutputFile (OutputBytes) properties.
• Set EncryptionType as per the desired encryption type (asymmetric, symmetric, asymmetric with authentication).
• Set EncryptionAlgorithm and, optionally, BitsInKey (if the encryption algorithm uses variable key lengths).
• For certificate-based (asymmetric) encryption, put the encryption certificate (or all of them, if there are more than one) to the EncryptionCertificates collection.
• For key-based (symmetric) encryption, assign the symmetric key to Key property.
• Call Encrypt to execute the operation.

Note that MessageEncryptor always produces binary PKCS#7-compliant encrypted messages. For S/MIME email encryption, see MailWriter. For PGP encryption, see PGPWriter. For raw symmetric encryption, see SymmetricCrypto. For XML-ENC encryption, see XMLEncryptor. MessageEncryptor encryptor = new MessageEncryptor(); // Set the encryption algorithm (default AES128) encryptor.setEncryptionAlgorithm("3DES"); // Select the file which contains the message that will be encrypted encryptor.setInputFile("decryptedMessage.txt"); // Select the file where the encrypted message will be written encryptor.setOutputFile("encryptedMessage.bin"); // We are using the public part of the certificate to encrypt data encryptor.setEncryptionCertificate(new Certificate("cert.cer")); encryptor.encrypt(); // Encrypt

Property List

---

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

Method List

---

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

Event List

---

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

Config Settings

---

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

BitsInKey Property (MessageEncryptor Component)

The length of the encryption key.

Syntax

__property int BitsInKey = { read=FBitsInKey, write=FSetBitsInKey };

Default Value

0

Remarks

When using a variable-key encryption algorithm (typical examples are RC4, RC2, and Blowfish), provide the desired key length via this property.

This value is ignored if a fixed-key algorithm (such as AES128 or 3DES) is used.

Data Type

Integer

EncryptionAlgorithm Property (MessageEncryptor Component)

The symmetric key algorithm to use for encryption.

Syntax

__property String EncryptionAlgorithm = { read=FEncryptionAlgorithm, write=FSetEncryptionAlgorithm };

Default Value

"AES128"

Remarks

Use this property to specify the symmetric algorithm to encrypt the data with.

Data Type

String

EncryptionCertCount Property (MessageEncryptor Component)

The number of records in the EncryptionCert arrays.

Syntax

__property int EncryptionCertCount = { read=FEncryptionCertCount, write=FSetEncryptionCertCount };

Default Value

0

Remarks

This property controls the size of the following arrays:

• EncryptionCertBytes
• EncryptionCertHandle

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

This property is not available at design time.

Data Type

Integer

EncryptionCertBytes Property (MessageEncryptor Component)

Returns the raw certificate data in DER format.

Syntax

__property DynamicArray EncryptionCertBytes[int EncryptionCertIndex] = { read=FEncryptionCertBytes };

Remarks

Returns the raw certificate data in DER format.

The EncryptionCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the EncryptionCertCount property.

This property is read-only and not available at design time.

Data Type

Byte Array

EncryptionCertHandle Property (MessageEncryptor Component)

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

Syntax

__property __int64 EncryptionCertHandle[int EncryptionCertIndex] = { read=FEncryptionCertHandle, write=FSetEncryptionCertHandle };

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

This property is not available at design time.

Data Type

Long64

EncryptionType Property (MessageEncryptor Component)

Specifies the kind of encrypted message to create.

Syntax

__property TsbxMessageEncryptorEncryptionTypes EncryptionType = { read=FEncryptionType, write=FSetEncryptionType };

enum TsbxMessageEncryptorEncryptionTypes {
  metUnknown=0,
  metCertEncrypted=1,
  metKeyEncrypted=2,
  metCertEncryptedAndAuthenticated=3
};

Default Value

metCertEncrypted

Remarks

Possible values:

Data Type

Integer

FIPSMode Property (MessageEncryptor Component)

Reserved.

Syntax

__property bool FIPSMode = { read=FFIPSMode, write=FSetFIPSMode };

Default Value

false

Remarks

This property is reserved for future use.

Data Type

Boolean

InputBytes Property (MessageEncryptor Component)

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

Syntax

__property DynamicArray InputBytes = { read=FInputBytes, write=FSetInputBytes };

Remarks

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

This property is not available at design time.

Data Type

Byte Array

InputFile Property (MessageEncryptor Component)

A path to the source file.

Syntax

__property String InputFile = { read=FInputFile, write=FSetInputFile };

Default Value

""

Remarks

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

Data Type

String

Key Property (MessageEncryptor Component)

The symmetric key to use for encryption.

Syntax

__property DynamicArray Key = { read=FKey, write=FSetKey };

Remarks

Use this property to provide a symmetric key to use for encryption. If the symmetric key is provided, an output message of EncryptedData type will be formed. The recipient of this message will need to have the same key to decrypt it.

This property is not available at design time.

Data Type

Byte Array

OutputBytes Property (MessageEncryptor Component)

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

Syntax

__property DynamicArray OutputBytes = { read=FOutputBytes };

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 OutputFile and OutputStream properties had not been assigned.

This property is read-only and not available at design time.

Data Type

Byte Array

OutputFile Property (MessageEncryptor Component)

A path to the output file.

Syntax

__property String OutputFile = { read=FOutputFile, write=FSetOutputFile };

Default Value

""

Remarks

Use this property to specify the file to save the encrypted message to.

Data Type

String

SignedAttributeCount Property (MessageEncryptor Component)

The number of records in the SignedAttribute arrays.

Syntax

__property int SignedAttributeCount = { read=FSignedAttributeCount, write=FSetSignedAttributeCount };

Default Value

0

Remarks

This property controls the size of the following arrays:

• SignedAttributeOID
• SignedAttributeValue

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

This property is not available at design time.

Data Type

Integer

SignedAttributeOID Property (MessageEncryptor Component)

The object identifier of the attribute.

Syntax

__property String SignedAttributeOID[int SignedAttributeIndex] = { read=FSignedAttributeOID, write=FSetSignedAttributeOID };

Default Value

""

Remarks

The object identifier of the attribute.

The SignedAttributeIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignedAttributeCount property.

This property is not available at design time.

Data Type

String

SignedAttributeValue Property (MessageEncryptor Component)

The value of the attribute.

Syntax

__property DynamicArray SignedAttributeValue[int SignedAttributeIndex] = { read=FSignedAttributeValue, write=FSetSignedAttributeValue };

Remarks

The value of the attribute.

The SignedAttributeIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignedAttributeCount property.

This property is not available at design time.

Data Type

Byte Array

UnsignedAttributeCount Property (MessageEncryptor Component)

The number of records in the UnsignedAttribute arrays.

Syntax

__property int UnsignedAttributeCount = { read=FUnsignedAttributeCount, write=FSetUnsignedAttributeCount };

Default Value

0

Remarks

This property controls the size of the following arrays:

• UnsignedAttributeOID
• UnsignedAttributeValue

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

This property is not available at design time.

Data Type

Integer

UnsignedAttributeOID Property (MessageEncryptor Component)

The object identifier of the attribute.

Syntax

__property String UnsignedAttributeOID[int UnsignedAttributeIndex] = { read=FUnsignedAttributeOID, write=FSetUnsignedAttributeOID };

Default Value

""

Remarks

The object identifier of the attribute.

The UnsignedAttributeIndex parameter specifies the index of the item in the array. The size of the array is controlled by the UnsignedAttributeCount property.

This property is not available at design time.

Data Type

String

UnsignedAttributeValue Property (MessageEncryptor Component)

The value of the attribute.

Syntax

__property DynamicArray UnsignedAttributeValue[int UnsignedAttributeIndex] = { read=FUnsignedAttributeValue, write=FSetUnsignedAttributeValue };

Remarks

The value of the attribute.

The UnsignedAttributeIndex parameter specifies the index of the item in the array. The size of the array is controlled by the UnsignedAttributeCount property.

This property is not available at design time.

Data Type

Byte Array

AddAttribute Method (MessageEncryptor Component)

Adds an attribute to the signature.

Syntax

int __fastcall AddAttribute(String OID, DynamicArray<Byte> Value, bool SignedAttribute);

Remarks

Use this method to add a signed or unsigned attribute to the collection of attributes included in the new signature.

Note that CAdESSigner creates certain mandatory and/or widely used attributes automatically in accordance with requirements for a specific signing profile. For example, attributes such as SigningCertificateV2 or SigningTime are always added. Policy attributes are added if specified via the PolicyID or PolicyURI properties of the signature object.

Use the OID parameter to provide the object identifier of the attribute, in string form. For example, the OID for the SigningCertificateV2 attribute is 1.2.840.113549.1.9.16.2.47. The Value parameter should contain a well-formed, DER-encoded representation of the attribute value, in accordance with its specification.

Config Method (MessageEncryptor Component)

Sets or retrieves a configuration setting.

Syntax

String __fastcall Config(String ConfigurationString);

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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.

DoAction Method (MessageEncryptor Component)

Performs an additional action.

Syntax

String __fastcall DoAction(String ActionID, String ActionParams);

Remarks

DoAction is a generic method available in every component. 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:

Encrypt Method (MessageEncryptor Component)

Encrypts data.

Syntax

void __fastcall Encrypt();

Remarks

This method encrypts the data provided via InputFile or InputStream in accordance with PKCS#7 standard.

If encrypted with an EncryptionCertificate a message of EnvelopedData subtype is created. The private key that corresponds to the certificate is needed to decrypt the data.

If encrypted with Key, a message of EncryptedData subtype is formed. The receiving party needs the same key as provided in Key to decrypt the message.

Reset Method (MessageEncryptor Component)

Resets the component settings.

Syntax

void __fastcall Reset();

Remarks

Reset is a generic method available in every component.

Error Event (MessageEncryptor Component)

Information about errors during PKCS#7 message encryption.

Syntax

typedef struct {
  int ErrorCode;
  String Description;
} TsbxMessageEncryptorErrorEventParams;
typedef void __fastcall (__closure *TsbxMessageEncryptorErrorEvent)(System::TObject* Sender, TsbxMessageEncryptorErrorEventParams *e);
__property TsbxMessageEncryptorErrorEvent OnError = { read=FOnError, write=FOnError };

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.

Notification Event (MessageEncryptor Component)

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

Syntax

typedef struct {
  String EventID;
  String EventParam;
} TsbxMessageEncryptorNotificationEventParams;
typedef void __fastcall (__closure *TsbxMessageEncryptorNotificationEvent)(System::TObject* Sender, TsbxMessageEncryptorNotificationEventParams *e);
__property TsbxMessageEncryptorNotificationEvent OnNotification = { read=FOnNotification, write=FOnNotification };

Remarks

The component 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 the 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.

Config Settings (MessageEncryptor Component)

The component 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 component, access to these internal properties is provided through the Config method.

MessageEncryptor Config Settings

Base Config Settings

Trappable Errors (MessageEncryptor Component)

MessageEncryptor Errors