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 WebMaker application scenarios where XML information needs to be digitally signed according to the W3C standard you can utilise the Java Method Action to sign required XML fragments within the Factbase. Please search on the Internet for 'W3C XML Digital Signatures' for more background information. You can also search this forum for more information on how to use the Java Method Action.
Pre-Requisites:
Apache Santuario
WebMaker utilises the Apache Santuario library to handle requests for the creation and verification of signatures. The main Santuario .jar file xmlsec-1.5.3.jar can be located on the relevant Apache Santuario distribution, which should also include a sample keystore directory. Please search the internet for Apache Santuario for more information.
However, the current release .jar file is also attached to allow you to test the details in this forum post.
xmlsec-1.5.3.jar
To use the Apache Santuario library a sample .jar file sample_xml_signature.jar is provided to allow you to test the details in this forum post.
sample_xml_signature.jar
Example Hyfinity Source Code
The sample source code that utilises the Apache Santuario library can be located within file SampleSignature.java, which is included in the attached .zip file.
SampleSignature.zip
Keystore for Keys and Certificates
Apache Santuario also includes a sample samples/data/keystore.jks, containing the necessary keys and certificates to enable the creation of various hash values and encrypted keys within the signature. 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 for further details.
New Java Method Action introduced in WebMaker v5.0
Please search this forum and the WebMaker v5.0 Documentation for Java Method Action for additional information.
Creating an XML Digital Signature
Consider the following data as an example:
The sender may wish to sign the message that requests the closure of their account to enable the receiving party to authenticate the sender as genuine. Let's assume that you need to sign the formData element. In order to do this you can use the following Java Method Action in WebMaker.
You can 'Copy-and-Paste' the Java Method example below. The API signature details are also provided for reference:
If the parameter information is supplied as shown below:
(Image of Java Method call to create the Digital Signature)
Then your FactBase should look like the following after invocation:
Enveloped Signatures
You should observe from the above FactBase listing that the ds:Signature element is contained with the mvc:formData element. This is because the sample implementation uses the Enveloped Signature approach. You can read more about the different Signature formats on the W3C website.
Once you have signed your data, you should be able to manipulate the FactBase to wrap the ds:Signature element as required depending on the security scheme you are using. For example, you should be able to include the ds:Signature element with a SAML Assertion, a SOAP WS-Security container, etc.
Important! Please not that this example has demonstrated the creation of a ds:Signature element. The enveloping data remains unencrypted. For sensitive data you should utilise a suitable encryption mechanism to ensure your data is protected should it be intercepted. You may find the examples on the XML Data Encryption and Decryption forum entry useful.
Verifying the Digital Signature
In order to verify a ds:Signature element you can utilise the following Java Method details:
You can 'Copy-and-Paste' the Java Method example below. The API signature details are also provided for reference:
Thus, if you supplied the information as shown below to the Java Method Action:
(Image showing the verifySignature Java Method action)
You should observe the following in your FactBase:
If the signature failed to verify then you will receive an invalid message instead.
Troubleshooting
This example has illustrated a typical scenario by utilising the same underlying library for signing and verifying the Signature. In practice, the sender and receiver may use different technologies and sometimes this can result in subtle changes in the data and/or the interpretation of the XML data, resulting in verification failure.
Namespaces and their definition and interpretation by different environments can also lead to subtle changes, invalidating signatures. You can learn more about troubleshooting such issues by searching for "Namespace Problems XML Digital Signature" and "Canonicalization Problems XML Digital Signature".
Background
In WebMaker application scenarios where XML information needs to be digitally signed according to the W3C standard you can utilise the Java Method Action to sign required XML fragments within the Factbase. Please search on the Internet for 'W3C XML Digital Signatures' for more background information. You can also search this forum for more information on how to use the Java Method Action.
Pre-Requisites:
Apache Santuario
WebMaker utilises the Apache Santuario library to handle requests for the creation and verification of signatures. The main Santuario .jar file xmlsec-1.5.3.jar can be located on the relevant Apache Santuario distribution, which should also include a sample keystore directory. Please search the internet for Apache Santuario for more information.
However, the current release .jar file is also attached to allow you to test the details in this forum post.
xmlsec-1.5.3.jar
To use the Apache Santuario library a sample .jar file sample_xml_signature.jar is provided to allow you to test the details in this forum post.
sample_xml_signature.jar
Example Hyfinity Source Code
The sample source code that utilises the Apache Santuario library can be located within file SampleSignature.java, which is included in the attached .zip file.
SampleSignature.zip
Keystore for Keys and Certificates
Apache Santuario also includes a sample samples/data/keystore.jks, containing the necessary keys and certificates to enable the creation of various hash values and encrypted keys within the signature. 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 for further details.
New Java Method Action introduced in WebMaker v5.0
Please search this forum and the WebMaker v5.0 Documentation for Java Method Action for additional information.
Creating an XML Digital Signature
Consider the following data as an example:
<eForm xmlns="http://www.hyfinity.com/mvc" xmlns:mvc="http://www.hyfinity.com/mvc">
<Control>
</Control>
<Data>
<formData>
<message>Please close my account</message>
</formData>
</Data>
</eForm>The sender may wish to sign the message that requests the closure of their account to enable the receiving party to authenticate the sender as genuine. Let's assume that you need to sign the formData element. In order to do this you can use the following Java Method Action in WebMaker.
You can 'Copy-and-Paste' the Java Method example below. The API signature details are also provided for reference:
com.hyfinity.security.samples.signature.SampleSignature.createSignature( data,keystoreType,keystoreFile,keystorePass,privatekeyAlias,privatekeyPass,certificateAlias)
/** Method to create an enveloped signature within the 'data' to be signed.
* @param data The XML node that needs to be signed to create the Signature element
* @param keystoreType keystore type
* @param keystoreFile location of the keystore file
* @param keystorePass keystore password
* @param privatekeyAlias private key alias
* @param privatekeyPass private key password
* @param certificateAlias certificate alias
* @return The XML Digital Signature, contained within the 'data' element
*/
If the parameter information is supplied as shown below:
(Image of Java Method call to create the Digital Signature)
Then your FactBase should look like the following after invocation:
<eForm xmlns="http://www.hyfinity.com/mvc" xmlns:mvc="http://www.hyfinity.com/mvc">
<Control>
<abc/>
</Control>
<Data>
<formData>
<message>Please close my account</message>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1"/>
<ds:Reference URI="">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<ds:Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"/>
</ds:Transforms>
<ds :D igestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<ds :D igestValue>5aXfY8vFRvOiYpjU1hFYFsAtfOw=</ds :D igestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>eNaOtTlzCKwYmtC2ta3ERhhlmp1id8sTLMINnXvJMEBB28mO49DDvQ==</ds:SignatureValue>
<ds:KeyInfo>
<ds:X509Data>
<ds:X509Certificate>
MIIC9jCCArQCBDruqiowCwYHKoZIzjgEAwUAMGExCzAJBgNVBAYTAkRFMR0wGwYDVQQKExRVbml2
ZXJzaXR5IG9mIFNpZWdlbjEQMA4GA1UECxMHRkIxMk5VRTEhMB8GA1UEAxMYQ2hyaXN0aWFuIEdl
...........
</ds:X509Certificate>
</ds:X509Data>
<ds:KeyValue>
<ds :D SAKeyValue>
<ds :P >
/X9TgR11EilS30qcLuzk5/YRt1I870QAwx4/gLZRJmlFXUAiUftZPY1Y+r/F9bow9subVWzXgTuA
HTRv8mZgt2uZUKWkn5/oBHsQIsJPu6nX/rfGG/g7V+fGqKYVDwT7g/bTxR7DAjVUE1oWkTL2dfOu
K2HXKu/yIgMZndFIAcc=
</ds :P >
<ds:Q>l2BQjxUjC8yykrmCouuEC/BYHPU=</ds:Q>
<ds:G>
9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6EwoFhO3
zwkyjMim4TwWeotUfI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKL
Zl6Ae1UlZAFMO/7PSSo=
</ds:G>
<ds:Y>
Eln5/htZP51p7Y/Y1+zZOSSmoi2fQS0deniScan3990xy33RrPfF5odqEVmVYfTzFfKEz94aUXEY
qY2VGVRCKrAZThk1SwoOB+UyfNSVjoqa4fppIQpTalK/JeR7uxQUr0Aeop68nr2u49GijYiLyvL3
x04lGaZ8jUYZL3gZTNI=
</ds:Y>
</ds :D SAKeyValue>
</ds:KeyValue>
</ds:KeyInfo>
</ds:Signature>
</formData>
</Data>
</eForm>
Enveloped Signatures
You should observe from the above FactBase listing that the ds:Signature element is contained with the mvc:formData element. This is because the sample implementation uses the Enveloped Signature approach. You can read more about the different Signature formats on the W3C website.
Once you have signed your data, you should be able to manipulate the FactBase to wrap the ds:Signature element as required depending on the security scheme you are using. For example, you should be able to include the ds:Signature element with a SAML Assertion, a SOAP WS-Security container, etc.
Important! Please not that this example has demonstrated the creation of a ds:Signature element. The enveloping data remains unencrypted. For sensitive data you should utilise a suitable encryption mechanism to ensure your data is protected should it be intercepted. You may find the examples on the XML Data Encryption and Decryption forum entry useful.
Verifying the Digital Signature
In order to verify a ds:Signature element you can utilise the following Java Method details:
You can 'Copy-and-Paste' the Java Method example below. The API signature details are also provided for reference:
com.hyfinity.security.samples.signature.SampleSignature.verifySignature(signedData)
/**
* Verifies an XML node with an enveloped Signature element
* @param signedData The XML node containing the data that was used to create the signature. The data also contains the Signature element.
* @return A status Node indicating the state of the certificate info and the outcome of the verification process.
*/Thus, if you supplied the information as shown below to the Java Method Action:
(Image showing the verifySignature Java Method action)
You should observe the following in your FactBase:
<eForm xmlns="http://www.hyfinity.com/mvc" xmlns:mvc="http://www.hyfinity.com/mvc">
<Control>
<abc/>
</Control>
<Data>
<formData>
<message>Please close my account</message>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1"/>
<ds:Reference URI="">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<ds:Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"/>
</ds:Transforms>
<ds :D igestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<ds :D igestValue>5aXfY8vFRvOiYpjU1hFYFsAtfOw=</ds :D igestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>eNaOtTlzCKwYmtC2ta3ERhhlmp1id8sTLMINnXvJMEBB28mO49DDvQ==</ds:SignatureValue>
<ds:KeyInfo>
<ds:X509Data>
<ds:X509Certificate>
MIIC9jCCArQCBDruqiowCwYHKoZIzjgEAwUAMGExCzAJBgNVBAYTAkRFMR0wGwYDVQQKExRVbml2
ZXJzaXR5IG9mIFNpZWdlbjEQMA4GA1UECxMHRkIxMk5VRTEhMB8GA1UEAxMYQ2hyaXN0aWFuIEdl
...........
</ds:X509Certificate>
</ds:X509Data>
<ds:KeyValue>
<ds :D SAKeyValue>
<ds :P >
/X9TgR11EilS30qcLuzk5/YRt1I870QAwx4/gLZRJmlFXUAiUftZPY1Y+r/F9bow9subVWzXgTuA
HTRv8mZgt2uZUKWkn5/oBHsQIsJPu6nX/rfGG/g7V+fGqKYVDwT7g/bTxR7DAjVUE1oWkTL2dfOu
K2HXKu/yIgMZndFIAcc=
</ds :P >
<ds:Q>l2BQjxUjC8yykrmCouuEC/BYHPU=</ds:Q>
<ds:G>
9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6EwoFhO3
zwkyjMim4TwWeotUfI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKL
Zl6Ae1UlZAFMO/7PSSo=
</ds:G>
<ds:Y>
Eln5/htZP51p7Y/Y1+zZOSSmoi2fQS0deniScan3990xy33RrPfF5odqEVmVYfTzFfKEz94aUXEY
qY2VGVRCKrAZThk1SwoOB+UyfNSVjoqa4fppIQpTalK/JeR7uxQUr0Aeop68nr2u49GijYiLyvL3
x04lGaZ8jUYZL3gZTNI=
</ds:Y>
</ds :D SAKeyValue>
</ds:KeyValue>
</ds:KeyInfo>
</ds:Signature>
</formData>
<signature_verification status="valid" xmlns=""> Found X509Data within the KeyInfo element.** The XML signature is valid**</signature_verification>
</Data>
</eForm>
If the signature failed to verify then you will receive an invalid message instead.
Troubleshooting
This example has illustrated a typical scenario by utilising the same underlying library for signing and verifying the Signature. In practice, the sender and receiver may use different technologies and sometimes this can result in subtle changes in the data and/or the interpretation of the XML data, resulting in verification failure.
Namespaces and their definition and interpretation by different environments can also lead to subtle changes, invalidating signatures. You can learn more about troubleshooting such issues by searching for "Namespace Problems XML Digital Signature" and "Canonicalization Problems XML Digital Signature".
Attachment
