XMLDecryptor Class

Properties   Methods   Events   Config Settings   Errors  

The XMLDecryptor class decrypts XML documents.

Syntax

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

DecryptionKey Property (XMLDecryptor Class)

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

Syntax

public byte[] getDecryptionKey();
public void setDecryptionKey(byte[] 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 Class)

Specifies XML encoding.

Syntax

public String getEncoding();
public void setEncoding(String encoding);

Default Value

""

Remarks

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

EncryptedDataType Property (XMLDecryptor Class)

Defines the type of data being encrypted.

Syntax

public int getEncryptedDataType();

Enumerated values:
  public final static int cxedtElement = 0;
  public final static int cxedtContent = 1;
  public final static int cxedtExternal = 2;

Default Value

0

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

The encryption method used to encrypt the document.

Syntax

public String getEncryptionMethod();

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

Specifies if the encryption key is encrypted.

Syntax

public boolean isEncryptKey();

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

Provides access to external signing and DC parameters.

Syntax

public ExternalCrypto getExternalCrypto();

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

The data that should be encrypted.

Syntax

public byte[] getExternalData();
public void setExternalData(byte[] 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 Class)

Reserved.

Syntax

public boolean isFIPSMode();
public void setFIPSMode(boolean FIPSMode);

Default Value

False

Remarks

This property is reserved for future use.

InputBytes Property (XMLDecryptor Class)

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

Syntax

public byte[] getInputBytes();
public void setInputBytes(byte[] 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 Class)

The XML file to be decrypted.

Syntax

public String getInputFile();
public void setInputFile(String inputFile);

Default Value

""

Remarks

Provide the path to the XML document to be decrypted.

InputStream Property (XMLDecryptor Class)

Stream containing the XML document.

Syntax

public java.io.InputStream getInputStream();
public void setInputStream(java.io.InputStream inputStream);

Default Value

null

Remarks

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

This property is not available at design time.

KeyDecryptionCertificate Property (XMLDecryptor Class)

The certificate used to decrypt a session key.

Syntax

public Certificate getKeyDecryptionCertificate();
public void setKeyDecryptionCertificate(Certificate 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 Class)

The symmetric key used to decrypt a session key.

Syntax

public byte[] getKeyDecryptionKey();
public void setKeyDecryptionKey(byte[] 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 Class)

Defines how the session key is encrypted.

Syntax

public int getKeyEncryptionType();

Enumerated values:
  public final static int cxetKeyTransport = 0;
  public final static int cxetKeyWrap = 1;

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

A collection of KeyInfo items found in the KeyInfo element.

Syntax

public XMLKeyInfoItemList getKeyInfo();

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

A collection of certificates found in the KeyInfo element.

Syntax

public CertificateList getKeyInfoCertificates();

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

Defines how the session key is encrypted.

Syntax

public int getKeyTransportMethod();

Enumerated values:
  public final static int cxktRSA15 = 0;
  public final static int cxktRSAOAEP = 1;

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

The key wrap method used to encrypt the session key.

Syntax

public String getKeyWrapMethod();

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

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

Syntax

public byte[] getOutputBytes();

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

Defines where to save the decrypted XML document.

Syntax

public String getOutputFile();
public void setOutputFile(String outputFile);

Default Value

""

Remarks

A path where the decrypted XML document should be saved.

OutputStream Property (XMLDecryptor Class)

The stream where to write the decrypted XML document to.

Syntax

public java.io.OutputStream getOutputStream();
public void setOutputStream(java.io.OutputStream outputStream);

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

Indicates if GCM mode was enabled.

Syntax

public boolean isUseGCM();

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

Defines the XML element to decrypt.

Syntax

public String getXMLElement();
public void setXMLElement(String XMLElement);

Default Value

""

Remarks

Defines the XML element to decrypt.

Supported values are:

AddKnownNamespace Method (XMLDecryptor Class)

Adds known prefix and correspondent namespace URI.

Syntax

public void addKnownNamespace(String prefix, String URI);

Remarks

Use this method to add a known prefix and namespace URI that are used in XPath expression within XMLElement/XMLNode property, and within TargetXMLElement and XPathPrefixList properties of the references.

Config Method (XMLDecryptor Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

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

Decrypts an XML document.

Syntax

public void decrypt();

Remarks

Call this method to decrypt an XML document.

DoAction Method (XMLDecryptor Class)

Performs an additional action.

Syntax

public String doAction(String actionID, String actionParams);

Remarks

DoAction 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 (XMLDecryptor Class)

Resets the class settings.

Syntax

public void reset();

Remarks

Reset is a generic method available in every class.

DecryptionInfoNeeded Event (XMLDecryptor Class)

Requests decryption information from the application.

Syntax

public class DefaultXMLDecryptorEventListener implements XMLDecryptorEventListener {
  ...
  public void decryptionInfoNeeded(XMLDecryptorDecryptionInfoNeededEvent e) {}
  ...
}

public class XMLDecryptorDecryptionInfoNeededEvent {
  public boolean cancelDecryption; //read-write
}

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

Information about errors during signing.

Syntax

public class DefaultXMLDecryptorEventListener implements XMLDecryptorEventListener {
  ...
  public void error(XMLDecryptorErrorEvent e) {}
  ...
}

public class XMLDecryptorErrorEvent {
  public int errorCode;
  public String description;
}

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

Handles remote or external decryption.

Syntax

public class DefaultXMLDecryptorEventListener implements XMLDecryptorEventListener {
  ...
  public void externalDecrypt(XMLDecryptorExternalDecryptEvent e) {}
  ...
}

public class XMLDecryptorExternalDecryptEvent {
  public String operationId;
  public String algorithm;
  public String pars;
  public String encryptedData;
  public String data; //read-write
}

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

Notification Event (XMLDecryptor Class)

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

Syntax

public class DefaultXMLDecryptorEventListener implements XMLDecryptorEventListener {
  ...
  public void notification(XMLDecryptorNotificationEvent e) {}
  ...
}

public class XMLDecryptorNotificationEvent {
  public String eventID;
  public String eventParam;
}

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.

SaveExternalData Event (XMLDecryptor Class)

Request to save decrypted external data.

Syntax

public class DefaultXMLDecryptorEventListener implements XMLDecryptorEventListener {
  ...
  public void saveExternalData(XMLDecryptorSaveExternalDataEvent e) {}
  ...
}

public class XMLDecryptorSaveExternalDataEvent {
  public byte[] externalData;
}

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

Encapsulates an individual X.509 certificate.

Remarks

This type keeps and provides access to X.509 certificate details.

Fields

Constructors

public Certificate( bytes,  startIndex,  count,  password);

public Certificate( certBytes,  certStartIndex,  certCount,  keyBytes,  keyStartIndex,  keyCount,  password);

public Certificate( bytes,  startIndex,  count);

public Certificate( path,  password);

public Certificate( certPath,  keyPath,  password);

public Certificate( path);

public Certificate( stream);

public Certificate( stream,  password);

public Certificate( certStream,  keyStream,  password);

public Certificate();

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

public ExternalCrypto();

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

public XMLKeyInfoItem();

Config Settings (XMLDecryptor Class)

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

XMLDecryptor Config Settings

Base Config Settings

Trappable Errors (XMLDecryptor Class)

XMLDecryptor Errors