XMLEncrypt Class

Properties Methods Events Configuration Settings Errors

The XMLEncrypt component is used to encrypt and decrypt XML.

Class Name

IPWorksEncrypt_XMLEncrypt

Procedural Interface

 ipworksencrypt_xmlencrypt_open();
 ipworksencrypt_xmlencrypt_close($res);
 ipworksencrypt_xmlencrypt_register_callback($res, $id, $function);
 ipworksencrypt_xmlencrypt_get_last_error($res);
 ipworksencrypt_xmlencrypt_get_last_error_code($res);
 ipworksencrypt_xmlencrypt_set($res, $id, $index, $value);
 ipworksencrypt_xmlencrypt_get($res, $id, $index);
 ipworksencrypt_xmlencrypt_do_config($res, $configurationstring);
 ipworksencrypt_xmlencrypt_do_decrypt($res);
 ipworksencrypt_xmlencrypt_do_doevents($res);
 ipworksencrypt_xmlencrypt_do_encrypt($res);
 ipworksencrypt_xmlencrypt_do_reset($res);

Remarks

The XMLEncrypt class provides a simple API for encrypting and decrypting XML. The Encrypt method will encrypt the XML document, or a specific element. Multiple elements may be encrypted at one time by setting the EncryptedDataDetail* properties. The Decrypt method will decrypt the XML document.

The class supports encrypting and decrypting with a shared SymmetricKey, and also using asymmetric encryption to encrypt the SymmetricKey (session key) via the RecipientCert* and Cer* properties.

Encrypt

To begin first specify a XML document by setting InputFile, or InputXML.

The EncryptedDataDetail* properties specify the XML element to encrypt. By default the entire XML document is encrypted.

The SymmetricKey property specifies the key which will be used to encrypt the data.

If the RecipientCert* properties are set, then the SymmetricKey will be encrypted and included in the encrypted data. This allows for the recipient to decrypt the key, with their certificate. Encrypting the symmetric key is also referred to as using a session key. The benefit of using certificate to encrypt and decrypt a session key (SymmetricKey) is that knowledge of the key value is not needed ahead of time to process the encrypted data. Note that if specified, RecipientCert MUST have a RSA key, not a DSA key.

If the RecipientCert* properties are not set, then the recipient must know the value of SymmetricKey before decrypting the XML. The KeyName setting may be set to provide a key identifier to the recipient.

Optionally set EncryptingAlgorithm, and then call Encrypt to encrypt the XML.

The following properties are applicable when calling this method:

SymmetricKey (required)
EncryptingAlgorithm
EncryptedDataDetail*
RecipientCert*
KeyName

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

OutputFile
OutputXML: The output data is written to this property if no other destination is specified.

Decrypt

To begin first specify a XML document by setting InputFile, or InputXML.

The SymmetricKey property specifies the key used to decrypt the data. This may be set before calling Decrypt or inside the EncryptedDataInfo event. The EncryptedDataInfo event fires once for each encrypted element when Decrypt is called.

If the data was encrypted using an session key, set the Cert* properties to the certificate with private key before calling Decrypt. The certificate will be used to decrypt the encrypted session key. In this case the SymmetricKey property is ignored.

The following properties are applicable when calling this method:

SymmetricKey
Certificate

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

OutputFile
OutputXML: The output data is written to this property if no other destination is specified.

Property List

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


CertEncoded	The certificate (PEM/base64 encoded).
CertStore	The name of the certificate store for the client certificate.
CertStorePassword	If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
CertStoreType	The type of certificate store for this certificate.
CertSubject	The subject of the certificate used for client authentication.
EncryptedDataDetailCount	The number of records in the EncryptedDataDetail arrays.
EncryptedDataDetailId	This property is an optional identifier for the encrypted data.
EncryptedDataDetailMIMEType	This property specifies the MIME type of the encrypted data.
EncryptedDataDetailScope	This property specifies the scope of the encryption.
EncryptedDataDetailXMLElement	This property specifies the XPath to the element which will be encrypted.
EncryptingAlgorithm	Then encryption algorithm used when encrypting.
InputFile	The XML file to process.
InputXML	The XML to process.
OutputFile	The output file.
OutputXML	The output XML after processing.
Overwrite	Indicates whether or not the component should overwrite files.
RecipientCertEncoded	The certificate (PEM/base64 encoded).
RecipientCertStore	The name of the certificate store for the client certificate.
RecipientCertStorePassword	If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
RecipientCertStoreType	The type of certificate store for this certificate.
RecipientCertSubject	The subject of the certificate used for client authentication.
SymmetricKey	The symmetric key used to encrypt and decrypt the XML.

Method List

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


Config	Sets or retrieves a configuration setting .
Decrypt	Decrypts the XML.
DoEvents	Processes events from the internal message queue.
Encrypt	Encrypts the XML.
Reset	Resets the component.

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.


EncryptedDataInfo	Fired once for each encrypted element when Decrypt is called.
Error	Information about errors during data delivery.
Progress	Fired as progress is made.
Status	Provides information about the current operation.

Configuration Settings

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


KeyName	The name of the key used to encrypt the XML.
LogLevel	Specifies the level of detail that is logged.
EncryptedKeyXPath	The XPath of the EncryptedKey element.
OAEPParams	The hex encoded OAEP parameters.
MGF1HashAlgorithm	The MGF1 hash algorithm used with OAEP.
RSAHashAlgorithm	The RSA hash algorithm used when encrypting a key.
UseOAEP	Whether to use Optimal Asymmetric Encryption Padding (OAEP).
ReadFromProgressEvent	Whether to read input data from inside the progress event.
WriteToProgressEvent	Whether to write output data so it is accessible from inside the progress event.
DecryptWithCryptoAPI	Whether to use the Crypto API for decrypt operations.
CodePage	The system code page used for Unicode to Multibyte translations.