XMLDecryptor Component

Properties   Methods   Events   Config Settings   Errors  

The XMLDecryptor component decrypts XML documents.

Syntax

TsbxXMLDecryptor

Remarks

XMlDecryptor decrypts XML documents encrypted with certificates or generic keys.

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.

DecryptionKey Property (XMLDecryptor Component)

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

Syntax

property DecryptionKey: TBytes read get_DecryptionKey write set_DecryptionKey;

Remarks

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

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

This property is not available at design time.

Encoding Property (XMLDecryptor Component)

Specifies XML encoding.

Syntax

property Encoding: String read get_Encoding write set_Encoding;

Default Value

''

Remarks

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

EncryptedDataType Property (XMLDecryptor Component)

Defines the type of data being encrypted.

Syntax

property EncryptedDataType: TsbxXMLEncryptedDataTypes read get_EncryptedDataType;

TsbxXMLEncryptedDataTypes = (
  cxedtElement,
  cxedtContent,
  cxedtExternal
);

Default Value

cxedtElement

Remarks

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

Supported values:

If the XMLNode property is set to the empty string, and the InputStream and InputFile 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 and not available at design time.

EncryptionMethod Property (XMLDecryptor Component)

The encryption method used to encrypt the document.

Syntax

property EncryptionMethod: String read get_EncryptionMethod;

Default Value

'AES256'

Remarks

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

Supported values:

If UseGCM property is enabled, then supported values are:

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

EncryptKey Property (XMLDecryptor Component)

Specifies if the encryption key is encrypted.

Syntax

property EncryptKey: Boolean read get_EncryptKey;

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 and not available at design time.

ExternalCrypto Property (XMLDecryptor Component)

Provides access to external signing and DC parameters.

Syntax

property ExternalCrypto: TsbxExternalCrypto read get_ExternalCrypto;

Remarks

Use this property to tune-up remote cryptography settings. SecureBlackbox supports two independent types of external cryptography: synchronous (based on the ExternalSign event) and asynchronous (based on the DC protocol and the DCAuth signing component).

This property is read-only.

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

ExternalData Property (XMLDecryptor Component)

The data that should be encrypted.

Syntax

property ExternalData: TBytes read get_ExternalData write set_ExternalData;

Remarks

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

This property is not available at design time.

FIPSMode Property (XMLDecryptor 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 (XMLDecryptor 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 (XMLDecryptor Component)

The XML file to be decrypted.

Syntax

property InputFile: String read get_InputFile write set_InputFile;

Default Value

''

Remarks

Provide the path to the XML document to be decrypted.

KeyDecryptionCertificate Property (XMLDecryptor Component)

The certificate used to decrypt a session key.

Syntax

property KeyDecryptionCertificate: TsbxCertificate read get_KeyDecryptionCertificate write set_KeyDecryptionCertificate;

Remarks

Use this property to provide the decryption certificate that will be used to decrypt a session key. It is required when EncryptKey property is enabled and KeyEncryptionType set to cxetKeyTransport value.

This property is not available at design time.

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

KeyDecryptionKey Property (XMLDecryptor Component)

The symmetric key used to decrypt a session key.

Syntax

property KeyDecryptionKey: TBytes read get_KeyDecryptionKey write set_KeyDecryptionKey;

Remarks

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

This property is not available at design time.

KeyEncryptionType Property (XMLDecryptor Component)

Defines how the session key is encrypted.

Syntax

property KeyEncryptionType: TsbxXMLKeyEncryptionTypes read get_KeyEncryptionType;

TsbxXMLKeyEncryptionTypes = (
  cxetKeyTransport,
  cxetKeyWrap
);

Default Value

cxetKeyTransport

Remarks

This property defines how the session key is encrypted.

Supported values:

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

KeyInfo Property (XMLDecryptor Component)

A collection of KeyInfo items found in the KeyInfo element.

Syntax

property KeyInfo: TsbxXMLKeyInfoItemList read get_KeyInfo;

Remarks

A collection of KeyInfo items that contains information about the public key that is used to perform encryption.

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

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

KeyInfoCertificates Property (XMLDecryptor Component)

A collection of certificates found in the KeyInfo element.

Syntax

property KeyInfoCertificates: TsbxCertificateList read get_KeyInfoCertificates;

Remarks

A collection of certificates that contains information about the public key that is used to perform encryption.

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

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

KeyTransportMethod Property (XMLDecryptor Component)

Defines how the session key is encrypted.

Syntax

property KeyTransportMethod: TsbxXMLKeyTransportMethods read get_KeyTransportMethod;

TsbxXMLKeyTransportMethods = (
  cxktRSA15,
  cxktRSAOAEP
);

Default Value

cxktRSA15

Remarks

This property defines how the session key is encrypted.

Supported values:

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

KeyWrapMethod Property (XMLDecryptor Component)

The key wrap method used to encrypt the session key.

Syntax

property KeyWrapMethod: String read get_KeyWrapMethod;

Default Value

'Cammelia256'

Remarks

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

Supported values:

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

OutputBytes Property (XMLDecryptor 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 (XMLDecryptor Component)

Defines where to save the decrypted XML document.

Syntax

property OutputFile: String read get_OutputFile write set_OutputFile;

Default Value

''

Remarks

A path where the decrypted XML document should be saved.

UseGCM Property (XMLDecryptor Component)

Indicates if GCM mode was enabled.

Syntax

property UseGCM: Boolean read get_UseGCM;

Default Value

true

Remarks

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

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

XMLElement Property (XMLDecryptor Component)

Defines the XML element to decrypt.

Syntax

property XMLElement: String read get_XMLElement write set_XMLElement;

Default Value

''

Remarks

Defines the XML element to decrypt.

Supported values are:

XPathNamespaces Property (XMLDecryptor Component)

Specifies namespaces for XPath expressions.

Syntax

property XPathNamespaces: TsbxXMLNamespaceList read get_XPathNamespaces write set_XPathNamespaces;

Remarks

This property contains a list of prefixes and namespaceURIs that used in XPath expression with XMLElement property.

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

Config Method (XMLDecryptor 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.

Decrypt Method (XMLDecryptor Component)

Decrypts an XML document.

Syntax

procedure Decrypt();

Remarks

Call this method to decrypt an XML document.

DoAction Method (XMLDecryptor 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;....

DecryptionInfoNeeded Event (XMLDecryptor Component)

Requests decryption information from the application.

Syntax

type TDecryptionInfoNeededEvent = procedure (
  Sender: TObject;
  var CancelDecryption: Boolean
) of Object;

property OnDecryptionInfoNeeded: TDecryptionInfoNeededEvent read FOnDecryptionInfoNeeded write FOnDecryptionInfoNeeded;

Remarks

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

Use EncryptKey, Config["KeyName"] and KeyEncryptionType properties to identify the encryption type and then set DecryptionKey or KeyDecryptionKey or KeyDecryptionCertificate 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.

Error Event (XMLDecryptor Component)

Information about errors during signing.

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

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

ExternalDecrypt Event (XMLDecryptor Component)

Handles remote or external decryption.

Syntax

type TExternalDecryptEvent = procedure (
  Sender: TObject;
  const OperationId: String;
  const Algorithm: String;
  const Pars: String;
  const EncryptedData: String;
  var Data: String
) of Object;

property OnExternalDecrypt: TExternalDecryptEvent read FOnExternalDecrypt write FOnExternalDecrypt;

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

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

Notification Event (XMLDecryptor 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.

SaveExternalData Event (XMLDecryptor Component)

Request to save decrypted external data.

Syntax

type TSaveExternalDataEvent = procedure (
  Sender: TObject;
  ExternalData: TBytes
) of Object;

property OnSaveExternalData: TSaveExternalDataEvent read FOnSaveExternalData write FOnSaveExternalData;

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 ExternalData property.

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

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.

ExternalCrypto Type

Specifies the parameters of external cryptographic calls.

Remarks

External cryptocalls are used in a Distributed Cryptography (DC) subsystem, which allows the delegation of security operations to the remote agent. For instance, it can be used to compute the signature value on the server, while retaining the client's private key locally.

Fields

Constructors

>

constructor Create();

Creates a new ExternalCrypto object with default field values.

XMLKeyInfoItem Type

Represents an XML KeyInfo item.

Remarks

This object contains information about the public key that was used to perform encryption or signing.

Fields

Constructors

>

constructor Create();

Creates a new XMLKeyInfo item object.

XMLNamespace Type

Represents an XML namespace map for XPath expressions.

Remarks

This class defines the correspondence between Prefixes and namespace URIs.

Fields

Constructors

>

constructor Create();

Creates a new XML namespace object.

Config Settings (XMLDecryptor 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.

XMLDecryptor Config Settings

Base Config Settings

Trappable Errors (XMLDecryptor Component)

XMLDecryptor 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) 
	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)