XMLDecryptor Component

Properties   Methods   Events   Config Settings   Errors  

The XMLDecryptor component decrypts XML documents.

Syntax

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

• C#
• VB.NET

public byte[] DecryptionKey { get; set; }

Public Property DecryptionKey As Byte()

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

• C#
• VB.NET

public string Encoding { get; set; }

Public Property Encoding As String

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

• C#
• VB.NET

public XmldecryptorEncryptedDataTypes EncryptedDataType { get; }

enum XmldecryptorEncryptedDataTypes {
  cxedtElement,
  cxedtContent,
  cxedtExternal
}

Public ReadOnly Property EncryptedDataType As XmldecryptorEncryptedDataTypes

Enum XmldecryptorEncryptedDataTypes
  cxedtElement
  cxedtContent
  cxedtExternal
End Enum

Default Value

0

Remarks

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

Supported values:

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

EncryptionMethod Property (XMLDecryptor Component)

The encryption method used to encrypt the document.

Syntax

• C#
• VB.NET

public string EncryptionMethod { get; }

Public ReadOnly Property EncryptionMethod As String

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

• C#
• VB.NET

public bool EncryptKey { get; }

Public ReadOnly Property EncryptKey As Boolean

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

• C#
• VB.NET

public ExternalCrypto ExternalCrypto { get; }

Public ReadOnly Property ExternalCrypto As 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.

ExternalData Property (XMLDecryptor Component)

The data that should be encrypted.

Syntax

• C#
• VB.NET

public byte[] ExternalData { get; set; }

Public Property ExternalData As Byte()

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

• C#
• VB.NET

public bool FIPSMode { get; set; }

Public Property FIPSMode As Boolean

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

• C#
• VB.NET

public byte[] InputBytes { get; set; }

Public Property InputBytes As Byte()

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

• C#
• VB.NET

public string InputFile { get; set; }

Public Property InputFile As String

Default Value

""

Remarks

Provide the path to the XML document to be decrypted.

InputStream Property (XMLDecryptor Component)

Stream containing the XML document.

Syntax

• C#
• VB.NET

public System.IO.Stream InputStream { get; set; }

Public Property InputStream As System.IO.Stream

Default Value

null

Remarks

Use this property to feed the XML document to the component via a stream.

This property is not available at design time.

KeyDecryptionCertificate Property (XMLDecryptor Component)

The certificate used to decrypt a session key.

Syntax

• C#
• VB.NET

public Certificate KeyDecryptionCertificate { get; set; }

Public Property KeyDecryptionCertificate As Certificate

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.

KeyDecryptionKey Property (XMLDecryptor Component)

The symmetric key used to decrypt a session key.

Syntax

• C#
• VB.NET

public byte[] KeyDecryptionKey { get; set; }

Public Property KeyDecryptionKey As Byte()

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

• C#
• VB.NET

public XmldecryptorKeyEncryptionTypes KeyEncryptionType { get; }

enum XmldecryptorKeyEncryptionTypes {
  cxetKeyTransport,
  cxetKeyWrap
}

Public ReadOnly Property KeyEncryptionType As XmldecryptorKeyEncryptionTypes

Enum XmldecryptorKeyEncryptionTypes
  cxetKeyTransport
  cxetKeyWrap
End Enum

Default Value

0

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

• C#
• VB.NET

public XMLKeyInfoItemList KeyInfo { get; }

Public ReadOnly Property KeyInfo As XMLKeyInfoItemList

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.

KeyInfoCertificates Property (XMLDecryptor Component)

A collection of certificates found in the KeyInfo element.

Syntax

• C#
• VB.NET

public CertificateList KeyInfoCertificates { get; }

Public ReadOnly Property KeyInfoCertificates As CertificateList

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.

KeyTransportMethod Property (XMLDecryptor Component)

Defines how the session key is encrypted.

Syntax

• C#
• VB.NET

public XmldecryptorKeyTransportMethods KeyTransportMethod { get; }

enum XmldecryptorKeyTransportMethods {
  cxktRSA15,
  cxktRSAOAEP
}

Public ReadOnly Property KeyTransportMethod As XmldecryptorKeyTransportMethods

Enum XmldecryptorKeyTransportMethods
  cxktRSA15
  cxktRSAOAEP
End Enum

Default Value

0

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

• C#
• VB.NET

public string KeyWrapMethod { get; }

Public ReadOnly Property KeyWrapMethod As String

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

• C#
• VB.NET

public byte[] OutputBytes { get; }

Public ReadOnly Property OutputBytes As Byte()

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

• C#
• VB.NET

public string OutputFile { get; set; }

Public Property OutputFile As String

Default Value

""

Remarks

A path where the decrypted XML document should be saved.

OutputStream Property (XMLDecryptor Component)

The stream where to write the decrypted XML document to.

Syntax

• C#
• VB.NET

public System.IO.Stream OutputStream { get; set; }

Public Property OutputStream As System.IO.Stream

Default Value

null

Remarks

Use this property to save the decrypted XML document to a stream.

This property is not available at design time.

UseGCM Property (XMLDecryptor Component)

Indicates if GCM mode was enabled.

Syntax

• C#
• VB.NET

public bool UseGCM { get; }

Public ReadOnly Property UseGCM As Boolean

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

• C#
• VB.NET

public string XMLElement { get; set; }

Public Property XMLElement As String

Default Value

""

Remarks

Defines the XML element to decrypt.

Supported values are:

XPathNamespaces Property (XMLDecryptor Component)

Specifies namespaces for XPath expressions.

Syntax

• C#
• VB.NET

public XMLNamespaceList XPathNamespaces { get; }

Public Property XPathNamespaces As XMLNamespaceList

Remarks

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

Config Method (XMLDecryptor Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Public Function Config(ByVal ConfigurationString As String) As 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

• C#
• VB.NET

public void Decrypt();

Public Sub Decrypt()

Remarks

Call this method to decrypt an XML document.

DoAction Method (XMLDecryptor Component)

Performs an additional action.

Syntax

• C#
• VB.NET

public string DoAction(string actionID, string actionParams);

Public Function DoAction(ByVal ActionID As String, ByVal ActionParams As String) As 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

• C#
• VB.NET

public event OnDecryptionInfoNeededHandler OnDecryptionInfoNeeded;

public delegate void OnDecryptionInfoNeededHandler(object sender, XmldecryptorDecryptionInfoNeededEventArgs e);

public class XmldecryptorDecryptionInfoNeededEventArgs : EventArgs {
  public bool CancelDecryption { get; set; }
}

Public Event OnDecryptionInfoNeeded As OnDecryptionInfoNeededHandler

Public Delegate Sub OnDecryptionInfoNeededHandler(sender As Object, e As XmldecryptorDecryptionInfoNeededEventArgs)

Public Class XmldecryptorDecryptionInfoNeededEventArgs Inherits EventArgs
  Public Property CancelDecryption As Boolean
End Class

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

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, XmldecryptorErrorEventArgs e);

public class XmldecryptorErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As XmldecryptorErrorEventArgs)

Public Class XmldecryptorErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

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

• C#
• VB.NET

public event OnExternalDecryptHandler OnExternalDecrypt;

public delegate void OnExternalDecryptHandler(object sender, XmldecryptorExternalDecryptEventArgs e);

public class XmldecryptorExternalDecryptEventArgs : EventArgs {
  public string OperationId { get; }
  public string Algorithm { get; }
  public string Pars { get; }
  public string EncryptedData { get; }
  public string Data { get; set; }
}

Public Event OnExternalDecrypt As OnExternalDecryptHandler

Public Delegate Sub OnExternalDecryptHandler(sender As Object, e As XmldecryptorExternalDecryptEventArgs)

Public Class XmldecryptorExternalDecryptEventArgs Inherits EventArgs
  Public ReadOnly Property OperationId As String
  Public ReadOnly Property Algorithm As String
  Public ReadOnly Property Pars As String
  Public ReadOnly Property EncryptedData As String
  Public Property Data As String
End Class

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

• C#
• VB.NET

public event OnNotificationHandler OnNotification;

public delegate void OnNotificationHandler(object sender, XmldecryptorNotificationEventArgs e);

public class XmldecryptorNotificationEventArgs : EventArgs {
  public string EventID { get; }
  public string EventParam { get; }
}

Public Event OnNotification As OnNotificationHandler

Public Delegate Sub OnNotificationHandler(sender As Object, e As XmldecryptorNotificationEventArgs)

Public Class XmldecryptorNotificationEventArgs Inherits EventArgs
  Public ReadOnly Property EventID As String
  Public ReadOnly Property EventParam As String
End Class

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

• C#
• VB.NET

public event OnSaveExternalDataHandler OnSaveExternalData;

public delegate void OnSaveExternalDataHandler(object sender, XmldecryptorSaveExternalDataEventArgs e);

public class XmldecryptorSaveExternalDataEventArgs : EventArgs {
  public byte[] ExternalData { get; }
}

Public Event OnSaveExternalData As OnSaveExternalDataHandler

Public Delegate Sub OnSaveExternalDataHandler(sender As Object, e As XmldecryptorSaveExternalDataEventArgs)

Public Class XmldecryptorSaveExternalDataEventArgs Inherits EventArgs
  Public ReadOnly Property ExternalData As Byte()
End Class

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

• C#
• VB.NET

public Certificate(byte[] bytes, int startIndex, int count, string password);

Public Certificate(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer, ByVal Password As String)

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(byte[] certBytes, int certStartIndex, int certCount, byte[] keyBytes, int keyStartIndex, int keyCount, string password);

Public Certificate(ByVal CertBytes As Byte(), ByVal CertStartIndex As Integer, ByVal CertCount As Integer, ByVal KeyBytes As Byte(), ByVal KeyStartIndex As Integer, ByVal KeyCount As Integer, ByVal Password As String)

Loads the X.509 certificate from a memory buffer. CertBytes is a buffer containing the raw certificate data. CertStartIndex and CertCount specify the number of bytes to be read from the buffer, respectively. KeyBytes is a buffer containing the private key data. KeyStartIndex and KeyCount specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(byte[] bytes, int startIndex, int count);

Public Certificate(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer)

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively.

• C#
• VB.NET

public Certificate(string path, string password);

Public Certificate(ByVal Path As String, ByVal Password As String)

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(string certPath, string keyPath, string password);

Public Certificate(ByVal CertPath As String, ByVal KeyPath As String, ByVal Password As String)

Loads the X.509 certificate from a file. CertPath specifies the full path to the file containing the certificate data. KeyPath specifies the full path to the file containing the private key. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(string path);

Public Certificate(ByVal Path As String)

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data.

• C#
• VB.NET

public Certificate(System.IO.Stream stream);

Public Certificate(ByVal Stream As System.IO.Stream)

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data.

• C#
• VB.NET

public Certificate(System.IO.Stream stream, string password);

Public Certificate(ByVal Stream As System.IO.Stream, ByVal Password As String)

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(System.IO.Stream certStream, System.IO.Stream keyStream, string password);

Public Certificate(ByVal CertStream As System.IO.Stream, ByVal KeyStream As System.IO.Stream, ByVal Password As String)

Loads the X.509 certificate from a stream. CertStream is a stream containing the certificate data. KeyStream is a stream containing the private key. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate();

Public Certificate()

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

• C#
• VB.NET

public ExternalCrypto();

Public ExternalCrypto()

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

• C#
• VB.NET

public XMLKeyInfoItem();

Public XMLKeyInfoItem()

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

• C#
• VB.NET

public XMLNamespace();

Public XMLNamespace()

Creates a new XML namespace object.

Config Settings (XMLDecryptor Component)

XMLDecryptor Config Settings

Base Config Settings

Trappable Errors (XMLDecryptor Component)

XMLDecryptor Errors