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.

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 BitsInKey: Integer read get_BitsInKey write set_BitsInKey;

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.

EncryptionAlgorithm Property (MessageEncryptor Component)

The symmetric key algorithm to use for encryption.

Syntax

property EncryptionAlgorithm: String read get_EncryptionAlgorithm write set_EncryptionAlgorithm;

Default Value

'AES128'

Remarks

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

EncryptionCertificate Property (MessageEncryptor Component)

The certificate to use for encryption.

Syntax

property EncryptionCertificate: TsbxCertificate read get_EncryptionCertificate write set_EncryptionCertificate;

Remarks

Use this property to specify the certificate to be used for encryption. This is a "recipient's" certificate, and as such it does not need to have an associated private key.

If the certificate is provided, an output message of EnvelopedData type will be created. The private key corresponding to the encryption certificate will be needed to decrypt it.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

EncryptionType Property (MessageEncryptor Component)

Specifies the kind of encrypted message to create.

Syntax

property EncryptionType: TsbxMessageEncryptionTypes read get_EncryptionType write set_EncryptionType;

TsbxMessageEncryptionTypes = (
  metUnknown,
  metCertEncrypted,
  metKeyEncrypted,
  metCertEncryptedAndAuthenticated
);

Default Value

metCertEncrypted

Remarks

Possible values:

FIPSMode Property (MessageEncryptor Component)

Reserved.

Syntax

property FIPSMode: Boolean read get_FIPSMode write set_FIPSMode;

Default Value

false

Remarks

This property is reserved for future use.

InputBytes Property (MessageEncryptor Component)

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

Syntax

property InputBytes: TBytes read get_InputBytes write set_InputBytes;

Remarks

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

This property is not available at design time.

InputFile Property (MessageEncryptor Component)

A path to the source file.

Syntax

property InputFile: String read get_InputFile write set_InputFile;

Default Value

''

Remarks

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

Key Property (MessageEncryptor Component)

The symmetric key to use for encryption.

Syntax

property Key: TBytes read get_Key write set_Key;

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.

OutputBytes Property (MessageEncryptor Component)

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

Syntax

property OutputBytes: TBytes read get_OutputBytes;

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.

OutputFile Property (MessageEncryptor Component)

A path to the output file.

Syntax

property OutputFile: String read get_OutputFile write set_OutputFile;

Default Value

''

Remarks

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

SignedAttributes Property (MessageEncryptor Component)

Custom signature attributes to be covered by the electronic signature.

Syntax

property SignedAttributes: TsbxSignatureAttributeList read get_SignedAttributes;

Remarks

Signature attributes are used to store auxiliary information in the signature. Values included as signed attributes are covered by the signature.

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

Please refer to the SignatureAttribute type for a complete list of fields.

UnsignedAttributes Property (MessageEncryptor Component)

Custom unsigned attributes to be included in the electronic signature.

Syntax

property UnsignedAttributes: TsbxSignatureAttributeList read get_UnsignedAttributes;

Remarks

Signature attributes are used to store auxiliary information in the signature. Values included as unsigned attributes are not covered by the signature and can be changed or removed without affecting the signature.

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

Please refer to the SignatureAttribute type for a complete list of fields.

Config Method (MessageEncryptor Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): String;

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

function DoAction(ActionID: String; ActionParams: String): String;

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

Encrypt Method (MessageEncryptor Component)

Encrypts data.

Syntax

procedure 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.

Error Event (MessageEncryptor Component)

Information about errors during PKCS#7 message encryption.

Syntax

type TErrorEvent = procedure (
  Sender: TObject;
  ErrorCode: Integer;
  const Description: String
) of Object;

property OnError: TErrorEvent 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

type TNotificationEvent = procedure (
  Sender: TObject;
  const EventID: String;
  const EventParam: String
) of Object;

property OnNotification: TNotificationEvent 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.

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

Constructors

>

constructor Create();

Creates a new object with default field values.

SignatureAttribute Type

Represents an attribute of a digital PKCS#7/CMS signature.

Remarks

Attributes store auxiliary information about the signed message, the signature, or the owner. Each attribute is a OID=Value pair.

Common attributes are signing time, a content type, a policy identifier, and a signature timestamp.

Fields

Constructors

>

constructor Create();

Creates a new, empty, signature attribute.

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

	1048577   Invalid parameter value (SB_ERROR_INVALID_PARAMETER)
	1048578   Component 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)