Note: This functionality is only available in WebMaker version 5.0+. For details on the latest WebMaker 10.5 version please see www.hyfinity.com.
Background
In application scenarios where sensitive data needs to be encrypted, the WebMaker Java Method Action can be used to encrypt and decrypt arbitrary XML fragments within the FactBase.
This thread contains three different, but related, example scenarios for encrypting XML data fragments:
All approaches use PKI for key generation and management, but utilise different approaches for encrypting, decrypting and safeguarding secret keys. You can learn more about these approaches from the W3C website.
Important! This example is for illustration purposes only and does not provide any guarantees about key lengths, key strength or safeguards against tampering efforts such as xml-rewriting, namespace exploits, etc. You must ensure you adapt the knowledge to your specific application requirements.
Pre-Requisites:
Apache Santuario
The main Santuario .jar file (xmlsec-1.5.3.jar) can be located on the relevant Apache Santuario distribution, which should also include a samples/keystore.jks directory. Please search for Apache Santuario on the web for more information.
Note: The sample keystore is only required if you are attempting to do some independent local testing.
xmlsec-1.5.3.jar
sample_xml_encryption.jar
Example Hyfinity Source Code
WebMaker utilises the Apache Santuario library to handle requests for data encryption and decryption. The sample source code that utilises the Apache Santuario library can be located within file SampleEncryption.java, which is included in the attached .zip file. The .jar file is also attached.
SampleEncryption.zip
Keystore for Keys and Certificates
Apache Santuario open source framework also includes a sample keystore, containing the necessary keys and certificates to enable data encryption and decryption. You can place the keystore in a location to suit your test requirements. You can of course use your own keystore if required. Please search on the internet for: Java keytool.exe.
Basic XML Encryption and Decryption
The encryption mechanism in this section uses a public key to encrypt the data and the recipient would use the secret, private key to decrypt the data. The sender therefore needs the public key of the recipient to encrypt the data.
This example encrypts an XML fragment to produce an encrypted string. The decryption routine receives the encrypted string and reproduces the original XML element. The example uses a test RSA certificate, generated and stored using the Java keytool.exe utility.
Please see "Symmetric XML Encryption and Decryption" and "Asymmetric XML Encryption and Decryption" where the creation of the standard EncryptedData Element is part of the W3C requirement.
Lets consider the following XML:
To encrypt the formData fragment, you can utilise the following Java Method Action:
(Images showing the Java Method call to encryptSimpleStrAsym)
You can 'Copy-and-Paste' the Java Method example below. The API signature details are also provided for reference:
The resulting fragment should look like the following, where formData has been replaced by the encrypted string.
In order to decrypt the string you can use the following Java Method Action call:
(Image showing the decryptSimpleStrAsym Java method call)
You can 'Copy-and-Paste' the Java Method example below. The API signature details are also provided for reference:
If the decryption is successful then you should see your original XML element before encryption, which was listed earlier.
Symmetric Key Encryption and Decryption
Symmetric encryption relies on a shared, secret key for encryption and decryption. The secret key in this example remains unencrypted and must be protected between the sender and receiver because, in unencrypted form, it would enable anyone intercepting the EncrypedData element to decrypt it. Please see the W3C information for more details and the differences between Symmetric and Asymmetric encryption.
This method produces the W3C EncryptedData element that can be used in different application scenarios. In addition it creates and wraps the unecrypted key encryption key, which can be protected and handled separately.
Consider the following XML FactBase in WebMaker:
You can use the following Java Method call to produce and EncryptedData element representing the formData element:
(image showing the encryptXMLSym Java method call)
You can 'Copy-and-Paste' the Java Method example below. The API signature details are also provided for reference:
If successful, you should observe the following in your FactBase:
You should note that the EncryptionWrapper contains two elements, the standard W3C EncryptedData, but also a KeyEncryptionKey element that contains the UNENCRYPTED key encryption key. This is the shared secret key between the sender and the receiver and must be protected.
You can use the following Java Method action to decrypt and EncryptedData element:
(Image showing the decryptXMLSym Java method call)
You can 'Copy-and-Paste' the Java Method example below. The API signature details are also provided for reference:
If successful, you should see the unencrypted version of your original XML fragment, as listed earlier.
Asymmetric Key Encryption and Decryption
Asymmetric encryption in this example is very similar to the Symmetric Key Encryption outlined earlier. The main difference is the additional step to encrypt the final key encryption key using the public key of the recipient. Please see the W3C information for more details and the differences between Symmetric and Asymmetric encryption.
This method produces the W3C EncryptedData element that can be used in different application scenarios. In addition, it creates and wraps the encrypted key encryption key.
Again, lets consider the following XML FactBase in WebMaker:
You can use the following Java Method call to produce and EncryptedData element, representing the formData element:
(Image showing the encryptXMLAsym Java method call)
You can 'Copy-and-Paste' the Java Method example below. The API signature details are also provided for reference:
If successful, you should observe the following in your Factbase:
You should note that the EncryptionWrapper contains two elements, the standard W3C EncryptedData, but also a KeyEncryptionKey element that contains the encrypted key encryption key. The encryption of the key encryption key is performed using the public key of the sender in this instance.
You can use the following Java Method action to decrypt and EncryptedData element:
(Image showing the decryptXMLAsym Java method call)
You can 'Copy-and-Paste' the Java Method example below. The API signature details are also provided for reference:
If successful you should see the unencrypted version of your original XML fragment.
Background
In application scenarios where sensitive data needs to be encrypted, the WebMaker Java Method Action can be used to encrypt and decrypt arbitrary XML fragments within the FactBase.
This thread contains three different, but related, example scenarios for encrypting XML data fragments:
- Basic Encryption and Decryption to create encrypted strings
- Symmetric Key Encryption and Decryption to create the EncryptedData element
- Asymmetric Key Encryption and Decryption to create the EncryptedData element
All approaches use PKI for key generation and management, but utilise different approaches for encrypting, decrypting and safeguarding secret keys. You can learn more about these approaches from the W3C website.
Important! This example is for illustration purposes only and does not provide any guarantees about key lengths, key strength or safeguards against tampering efforts such as xml-rewriting, namespace exploits, etc. You must ensure you adapt the knowledge to your specific application requirements.
Pre-Requisites:
Apache Santuario
The main Santuario .jar file (xmlsec-1.5.3.jar) can be located on the relevant Apache Santuario distribution, which should also include a samples/keystore.jks directory. Please search for Apache Santuario on the web for more information.
Note: The sample keystore is only required if you are attempting to do some independent local testing.
xmlsec-1.5.3.jar
sample_xml_encryption.jar
Example Hyfinity Source Code
WebMaker utilises the Apache Santuario library to handle requests for data encryption and decryption. The sample source code that utilises the Apache Santuario library can be located within file SampleEncryption.java, which is included in the attached .zip file. The .jar file is also attached.
SampleEncryption.zip
Keystore for Keys and Certificates
Apache Santuario open source framework also includes a sample keystore, containing the necessary keys and certificates to enable data encryption and decryption. You can place the keystore in a location to suit your test requirements. You can of course use your own keystore if required. Please search on the internet for: Java keytool.exe.
Basic XML Encryption and Decryption
The encryption mechanism in this section uses a public key to encrypt the data and the recipient would use the secret, private key to decrypt the data. The sender therefore needs the public key of the recipient to encrypt the data.
This example encrypts an XML fragment to produce an encrypted string. The decryption routine receives the encrypted string and reproduces the original XML element. The example uses a test RSA certificate, generated and stored using the Java keytool.exe utility.
Please see "Symmetric XML Encryption and Decryption" and "Asymmetric XML Encryption and Decryption" where the creation of the standard EncryptedData Element is part of the W3C requirement.
Lets consider the following XML:
<eForm xmlns="http://www.hyfinity.com/mvc" xmlns:mvc="http://www.hyfinity.com/mvc">
<Control>
<control_elements/>
</Control>
<Data>
<formData>
<message>Please close my account</message>
</formData>
</Data>
</eForm>To encrypt the formData fragment, you can utilise the following Java Method Action:
(Images showing the Java Method call to encryptSimpleStrAsym)
You can 'Copy-and-Paste' the Java Method example below. The API signature details are also provided for reference:
com.hyfinity.security.samples.encryption.SampleEncryption.encryptSimpleStrAsym(data,keystoreType,keystoreFile,keystorePass,certificateAlias)
/** Basic RSA public key data encryption using a public key obtained from the given certificate info. Encrypts an XML node.
* Secret key from the pair is required to decrypt the data.
* @param data Node, containing the data that requires encryption
* @param keystoreType keystore type
* @param keystoreFile location of the keystore file
* @param keystorePass keystore password
* @param certificateAlias certificate alias.
* @return Base64 encoded string of the encrypted data node.
*/
The resulting fragment should look like the following, where formData has been replaced by the encrypted string.
<eForm xmlns="http://www.hyfinity.com/mvc" xmlns:mvc="http://www.hyfinity.com/mvc">
<Control>
<control_elements/>
</Control>
<Data
<formData>RFX7TzP6IABZFuzFaYJjDnu8LiPYXXiIyYmMvRou3eGa+VxXpXk67
IM7siz+ZvBDRqyurIF3yOMpxWW81IrHnIQQsiFTUPnOFYwOnp5wkyxF3ZASm.
.........
</formData>
</Data>
</eForm>
In order to decrypt the string you can use the following Java Method Action call:
(Image showing the decryptSimpleStrAsym Java method call)
You can 'Copy-and-Paste' the Java Method example below. The API signature details are also provided for reference:
com.hyfinity.security.samples.encryption.SampleEncryption.decryptSimpleStrAsym(data,keystoreType,keystoreFile,keystorePass,pkAlias,pkPass)
/** Basic RSA data decryption using a private key from the original public/private key pair.
* @param data String, containing the data that requires decryption
* @param keystoreType keystore type
* @param keystoreFile location of the keystore file
* @param keystorePass keystore password
* @param pkAlias private key alias
* @param pkPass private key password
* @return The original decrypted XML node.
*/
If the decryption is successful then you should see your original XML element before encryption, which was listed earlier.
Symmetric Key Encryption and Decryption
Symmetric encryption relies on a shared, secret key for encryption and decryption. The secret key in this example remains unencrypted and must be protected between the sender and receiver because, in unencrypted form, it would enable anyone intercepting the EncrypedData element to decrypt it. Please see the W3C information for more details and the differences between Symmetric and Asymmetric encryption.
This method produces the W3C EncryptedData element that can be used in different application scenarios. In addition it creates and wraps the unecrypted key encryption key, which can be protected and handled separately.
Consider the following XML FactBase in WebMaker:
<eForm xmlns="http://www.hyfinity.com/mvc" xmlns:mvc="http://www.hyfinity.com/mvc">
<Control>
<control_elements/>
</Control>
<Data>
<formData>
<message>Please close my account</message>
</formData>
</Data>
</eForm>You can use the following Java Method call to produce and EncryptedData element representing the formData element:
(image showing the encryptXMLSym Java method call)
You can 'Copy-and-Paste' the Java Method example below. The API signature details are also provided for reference:
com.hyfinity.security.samples.encryption.SampleEncryption.encryptXMLSym(data,skJceAlgorithmName,kekJceAgorithmName)
/** Encryption method using symmetric keys.
* @param data Node, containing the data that requires encryption
* @param skJceAlgorithmName Name of the data encryption symmetric key algorithm. e.g. 'AES'.
* @param kekJceAlgorithmName Name of the key encryption key algorithm. e.g. 'DESede'.
* @return EncryptedData element wrapped within a container that also contains the unencrypted key encryption key.
*/
If successful, you should observe the following in your FactBase:
<eForm xmlns="http://www.hyfinity.com/mvc" xmlns:mvc="http://www.hyfinity.com/mvc">
<Control>
<control_elements/>
</Control>
<Data>
<EncryptionWrapper xmlns="">
<KeyEncryptionKey desc="***UNENCRYPTED*** symmetric secret key used to encrypt the data encryption key" encoding="Base64">
Ys5n0BbjeqvsYpIyLwttlzssGjhtiTHN
</KeyEncryptionKey>
<xenc:EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Element" xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<xenc:EncryptedKey>
<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#kw-tripledes"/>
<xenc:CipherData>
<xenc:CipherValue>GKPN4LC8/Pv8SdtFgUEKKp1lP6VM9DtIQzD6QYvZg+w=</xenc:CipherValue>
</xenc:CipherData>
</xenc:EncryptedKey>
</ds:KeyInfo>
<xenc:CipherData>
<xenc:CipherValue>
zCULPs/bQ2n6QzOCW0QnNSBwtovgJBaHTKNUZK10xvODkZYNjOmGs4JhHRdSXEUqsut0VJMzMLD/
skXW63LARtKuXp0fSxbDIywYNRlylfgLBIRAQYb9aIKauN8Zu/V1uW4BhPQxKfPl0npNjhdvuwEU
/Nggex2W614Wqu1KxNA=
</xenc:CipherValue>
</xenc:CipherData>
</xenc:EncryptedData>
</EncryptionWrapper>
</Data>
</eForm>
You should note that the EncryptionWrapper contains two elements, the standard W3C EncryptedData, but also a KeyEncryptionKey element that contains the UNENCRYPTED key encryption key. This is the shared secret key between the sender and the receiver and must be protected.
You can use the following Java Method action to decrypt and EncryptedData element:
(Image showing the decryptXMLSym Java method call)
You can 'Copy-and-Paste' the Java Method example below. The API signature details are also provided for reference:
com.hyfinity.security.samples.encryption.SampleEncryption.decryptXMLSym(data,kekString,kekJceAlgorithmName)
/** Decryption method using symmetric keys.
* @param data Node, containing the EncryptedData element that requires decrypting
* @param kekString The Base64 encoded and unencrypted secret key encryption key that was used during encryption.
* @param kekJceAlgorithmName Name of the key encryption key algorithm. e.g. 'DESede'.
* @return The original decrypted XML node.
*/
If successful, you should see the unencrypted version of your original XML fragment, as listed earlier.
Asymmetric Key Encryption and Decryption
Asymmetric encryption in this example is very similar to the Symmetric Key Encryption outlined earlier. The main difference is the additional step to encrypt the final key encryption key using the public key of the recipient. Please see the W3C information for more details and the differences between Symmetric and Asymmetric encryption.
This method produces the W3C EncryptedData element that can be used in different application scenarios. In addition, it creates and wraps the encrypted key encryption key.
Again, lets consider the following XML FactBase in WebMaker:
<eForm xmlns="http://www.hyfinity.com/mvc" xmlns:mvc="http://www.hyfinity.com/mvc">
<Control>
<control_elements/>
</Control>
<Data>
<formData>
<message>Please close my account</message>
</formData>
</Data>
</eForm>You can use the following Java Method call to produce and EncryptedData element, representing the formData element:
(Image showing the encryptXMLAsym Java method call)
You can 'Copy-and-Paste' the Java Method example below. The API signature details are also provided for reference:
com.hyfinity.security.samples.encryption.SampleEncryption.encryptXMLAsym
(data,keystoreType,keystoreFile,keystorePass,skJceAlgorithmName,kekJceAgorithmName,certifiateAlias)
/** Encryption method using Asymmetric keys. The final key encryption key in encrypted using a public key.
* @param data Node, containing the data that requires encryption
* @param keystore Type keystore type
* @param keystore File location of the keystore file
* @param keystore Pass keystore password
* @param skJceAlgorithmName Name of the data encryption symmetric key algorithm. e.g. 'AES'.
* @param kekJceAlgorithmName Name of the key encryption key algorithm. e.g. 'DESede'.
* @param certificateAlias certificate alias.
* @return EncryptedData element wrapped within a container that also contains the public key encrypted key encryption key.
*/
If successful, you should observe the following in your Factbase:
<eForm xmlns="http://www.hyfinity.com/mvc" xmlns:mvc="http://www.hyfinity.com/mvc">
<Control>
<control_elements/>
</Control>
<Data>
<EncryptionWrapper xmlns="">
<KeyEncryptionKey desc="Public key encrypted key encryption key" encoding="Base64">
UnMf2ifpNjLsK0TD9UWnW8rcXsqYa7FyXvbR314xEIifTq8S+x0dSQy4rpz11tUti67kp7RIr0szdyGsfbjf
O9CnNipTIpvaThP0hlSGAQ8Ly1mG4bSYiP877I9U2BBgJI8KDixZ5z3RFGkdMy9yjoyH2fUrlj0GfWpH
..........
</KeyEncryptionKey>
<xenc:EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Element" xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<xenc:EncryptedKey>
<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#kw-tripledes"/>
<xenc:CipherData>
<xenc:CipherValue>inH2g15czTmeMUyQ2MFTza2KG8ehHX7WD4kIV5xEHV0=</xenc:CipherValue>
</xenc:CipherData>
</xenc:EncryptedKey>
</ds:KeyInfo>
<xenc:CipherData>
<xenc:CipherValue>UskZQJKl5pqxfAhQJ8+lAHap5tnwmgxiiKPGC6tfeqcOThKAgPhmySrdmeJI5PqjwX9fOm0JLSXb
xQf5YX4pRszp7VIRn7CvUjo+gUri2Fpak0rd6iSXoI8kSc9OSlMGuw8baheN4hri0NLVs07B+zck
fICiJ4aIYzprF/hRA4A=
</xenc:CipherValue>
</xenc:CipherData>
</xenc:EncryptedData>
</EncryptionWrapper>
</Data>
</eForm>
You should note that the EncryptionWrapper contains two elements, the standard W3C EncryptedData, but also a KeyEncryptionKey element that contains the encrypted key encryption key. The encryption of the key encryption key is performed using the public key of the sender in this instance.
You can use the following Java Method action to decrypt and EncryptedData element:
(Image showing the decryptXMLAsym Java method call)
You can 'Copy-and-Paste' the Java Method example below. The API signature details are also provided for reference:
com.hyfinity.security.samples.encryption.SampleEncryption.decryptXMLAsym
(data,kekString,kekJceAgorithmName,keystoreType,keystoreFile,keystorePass,pkAlias,pkPass)
/** Decryption method using Asymmetric keys. The public key encrypted key encryption key is initially decrypted using the paired private key.
* @param data Node, containing the data that requires decryption
* @param kekString The Base64 encoded and public key encrypted secret key encryption key that was used during encryption.
* @param kekJceAlgorithmName Name of the key encryption key algorithm. e.g. 'DESede'.
* @param keystoreType keystore type
* @param keystoreFile location of the keystore file
* @param keystorePass keystore password
* @param pkAlias private key alias
* @param pkPass private key password
* @return The original decrypted XML node.
*/
If successful you should see the unencrypted version of your original XML fragment.
Attachment
