Back to Contents

The Signature class

Summary

• Syntax
• Methods
• Concepts
• Digest identifier
  • SHA-1
  • SHA-512
  • SHA-384
  • SHA-256
  • SHA-224
  • MD5
  • RIPEMD160
• Transformation identifier
  • Base64
  • Canonical XML
  • Canonical XML with comments
  • Exclusive canonical XML
  • Exclusive canonical XML with comments
  • Enveloped Signature Transform
  • XPath Filtering
  • XPath Filtering 2.0
• Examples
  • Create a detached signature using a HMAC key
  • Verify a detached signature using a HMAC key
  • Create an enveloping signature using a DSA key
  • Verify an enveloping signature using a X509 certificate
  • Create an enveloped signature using a RSA key
  • Verify an enveloped signature using a RSA key

See also: The Genero Web Services XML Library

Syntax

The Signature class provides methods to create detached, enveloped or enveloping XML signatures of one or more references of XML documents or document fragments, and to determine whether a signed referenced document has been modified afterwards. It follows the XML-Signature specifications.

The status is set to zero after a successful method call.

Syntax

xml.Signature

Methods

• Creation
• Key and certificate
• Modifier
• Access
• Reference modifier
• Reference access
• Object modifier
• Object access
• Signature computation and verification

Creation methods

Back to the top

Key and certificate methods

Back to the top

Modifier method

Back to the top

Access methods

Back to the top

Reference modifier methods

Back to the top

Reference access methods

Back to the top

Object modifier methods

Back to the top

Object access methods

Back to the top

Signature computation and verification methods

Back to the top

XML Signature concepts

The purpose of a signature is to verify the integrity of a XML document, that it was not altered, and that it still contains the same data as when it was created. The following points describe the different ways to achieve that.

Sign and verify with a common shared HMAC key

• When to use:
  • if the sender of the XML document and the receiver share a common secret key
• How to sign:
  1. create a HMAC key with the constructor of the CryptoKey class
  2. set or load the common shared key value in the CryptoKey object
  3. create a blank signature with the constructor of the Signature class
  4. assign the CryptoKey object to the Signature object
  5. create one or more references to be signed
  6. compute the signature
  7. retrieve the XML signature document from the Signature object
• How to verify:
  1. create a HMAC key with the constructor of the CryptoKey
  2. set or load the common shared key value in the CryptoKey object
  3. create a signature with the constructor of the Signature class and from a XML signature node obtain after the above compute operation
  4. assign the CryptoKey object to the Signature object
  5. verify the signature validity

Sign with the originator private RSA or DSA key, and verify with the originator public RSA or DSA key

• When to use:
  • if the receiver of the XML document has the RSA or DSA public key of the sender
• How to sign:
  1. create a RSA or DSA key with the constructor of the CryptoKey class
  2. load the RSA or DSA private key into the CryptoKey object
  3. create a blank signature with the constructor of the Signature class
  4. assign the CryptoKey object to the Signature object
  5. create one or more references to be signed
  6. compute the signature
  7. retrieve the XML signature document from the Signature object
• How to verify:
  1. create a RSA or DSA key with the constructor of the CryptoKey class
  2. load the RSA or DSA public key into the CryptoKey object
  3. create a signature with the constructor of the Signature class and from a XML signature node obtain after the above compute operation
  4. assign the CryptoKey object to the Signature object
  5. verify the signature validity

Sign with the originator private RSA or DSA key, and verify with a RSA or DSA retrieval method

• When to use:
  • if the sender of the XML document provides the public RSA or DSA key in XML form ( and via http, tcp or a file protocol)
• How to sign:
  1. create a RSA or DSA key with the constructor of the CryptoKey class
  2. load the RSA or DSA private key into the CryptoKey object
  3. set the RetrievalMethod feature on the CryptoKey object with the URL where the XML form of the public RSA or DSA key is available
  4. create a blank signature with the constructor of the Signature class
  5. assign the CryptoKey object to the Signature object
  6. create one or more references to be signed
  7. compute the signature
  8. retrieve the XML signature document from the Signature object
• How to verify:
  1. create a signature with the constructor of the Signature class and from a XML signature node obtain after the above compute operation
  2. verify the signature validity
  
  Note : there is no key nor certificate to set in the Signature object during validation.

Sign with the originator private RSA or DSA key, and verify with the originator X509 certificate associated to the private RSA or DSA key

• When to use:
  • if the receiver of the XML document has the X509 certificate associated to the RSA or DSA private key
• How to sign:
  1. create a RSA or DSA key with the constructor of the CryptoKey class
  2. load the RSA or DSA private key into the CryptoKey object
  3. create a blank signature with the constructor of the Signature class
  4. assign the CryptoKey object to the Signature object
  5. create one or more references to be signed
  6. compute the signature
  7. retrieve the XML signature document from the Signature object
• How to verify:
  1. create a X509 certificate with the constructor of the CryptoX509 class
  2. load the X509 certificate into the CryptoKey object
  3. create the RSA or DSA public key from the X509 certificate of the CryptoX509 object
  4. create a signature with the constructor of the Signature class and from a XML signature node obtain after the above compute operation
  5. assign the CryptoKey object containing the public key to the Signature object
  6. verify the signature validity

Sign with the originator private RSA or DSA key, and verify with trusted X509 certificates

• When to use:
  • if the sender of the XML document adds a X509 certificate that was signed by another trusted X509 certificate
• How to sign:
  1. create a RSA or DSA key with the constructor of the CryptoKey class
  2. load the RSA or DSA private key into the CryptoKey object
  3. create a X509 certificate with the constructor of the CryptoX509 class
  4. load the X509 certificate associated to the RSA or DSA private key into the CryptoKey object
  5. create a blank signature with the constructor of the Signature class
  6. assign the CryptoKey object to the Signature object
  7. assign the CryptoX509 object to the Signature object
  8. create one or more references to be signed
  9. compute the signature
  10. retrieve the XML signature document from the Signature object
• How to verify:
  1. create a X509 certificate with the constructor of the CryptoX509 class
  2. load the X509 certificate that was used to sign the originator X509 certificate into the CryptoX509 object
  3. add the X509 certificate as trusted certificate to the application
  4. create a signature with the constructor of the Signature class and from a XML signature node obtain after the above compute operation
  5. verify the signature validity
  
  Note 1 : point 1 to 3 can be omitted if entry xml.application.calist has been set in FGLPROFILE file with the trusted certificate.
  Note 2 : there is no key nor certificate to set in the Signature object during validation.

Sign with the originator private RSA or DSA key, and verify with a X509 certificate retrieval method and trusted X509 certificates

• When to use:
  • if the sender of the XML document adds a X509 retrieval method that was signed by another trusted X509 certificate
• How to sign:
  1. create a RSA or DSA key with the constructor of the CryptoKey class
  2. load the RSA or DSA private key into the CryptoKey object
  3. create a X509 certificate with the constructor of the CryptoX509 class
  4. set the RetrievalMethod feature on the CryptoX509 object with the URL where the XML form of the originator X509 certificate is available
  5. create a blank signature with the constructor of the Signature class
  6. assign the CryptoKey object to the Signature object
  7. assign the CryptoX509 object to the Signature object
  8. create one or more references to be signed
  9. compute the signature
  10. retrieve the XML signature document from the Signature object
• How to verify:
  1. create a X509 certificate with the constructor of the CryptoX509 class
  2. load the X509 certificate that was used to sign the originator X509 certificate into the CryptoX509 object
  3. add the X509 certificate as trusted certificate to the application
  4. create a signature with the constructor of the Signature class and from a XML signature node obtain after the above compute operation
  5. verify the signature validity
  
  Note 1 : point 1 to 3 can be omitted if entry xml.application.calist has been set in FGLPROFILE file with the trusted certificate.
  Note 2 : there is no key nor certificate to set in the Signature object during validation.

Sign with a named key and verify using the keystore

• When to use:
  • if the sender and the receiver exchanges multiple XML document signed with different keys
• How to sign:
  1. create a HMAC,RSA or DSA key with the constructor of the CryptoKey class
  2. set the HMAC key or load the RSA or DSA key in the CryptoKey object
  3. set the KeyName feature with the name identifying the key
  4. create a blank signature with the constructor of the Signature class
  5. assign the CryptoKey object to the Signature object
  6. create one or more references to be signed
  7. compute the signature
  8. retrieve the XML signature document from the Signature object
• How to verify:
  1. create a HMAC,RSA or DSA key with the constructor of the CryptoKey
  2. set the HMAC key or load the RSA or DSA key in the CryptoKey object
  3. set the KeyName feature with the name identifying the key
  4. register the key to be used by key name for any signature verification
  5. create a signature with the constructor of the Signature class and from a XML signature node obtain after the above compute operation
  6. verify the signature validity
  
  Note 1 : point 1 to 4 should be done once at application startup for each key used in the application.
  Note 2 : point 5 to 6 can then quickly be executed for any XML signature to be checked.

Back to the top

Digest identifier

Back to the top

Transformation identifier

CALL s.appendReferenceTransformation(
          i, "http://www.w3.org/TR/1999/REC-xpath-19991116",
          "ancestor-or-self::MyCode",
          NULL)

CALL s.appendReferenceTransformation(
          i, "http://www.w3.org/TR/1999/REC-xpath-19991116",
          "ancestor-or-self::p:MyCode",
          "p","http://www.tempuri.org")

CALL s.appendReferenceTransformation(
          i, "http://www.w3.org/2002/06/xmldsig-filter2",
          "subtract", "/MyElement/MyCode")

CALL s.appendReferenceTransformation(
          i, "http://www.w3.org/2002/06/xmldsig-filter2",
          "subtract", "/p1:MyElement/p2:MyCode",
          "p2","http://www.tempuri.org/ns2",
          "p1","http://www.tempuri.org/ns1")

Back to the top

Examples

Example 1 : Create a detached signature using a HMAC key

01 IMPORT xml
02
03 MAIN
04   DEFINE doc xml.DomDocument
05   DEFINE root xml.DomNode
06   DEFINE sig xml.Signature
07   DEFINE key xml.CryptoKey
08   DEFINE index INTEGER
09    # Create DomDocument object
10   LET doc = xml.DomDocument.Create()
11    # Notice that whitespaces are significant in crytography, 
12    # therefore it is recommended that you remove unnecessary ones 
13   CALL doc.setFeature("whitespace-in-element-content",FALSE)
14   TRY
15      # Load document to be signed
16     CALL doc.load("MyDocument.xml")
17      # Create HMAC key
18     LET key = xml.CryptoKey.Create("http://www.w3.org/2000/09/xmldsig#hmac-sha1")
19     CALL key.setKey("secretpassword")
20      # Create signature object with the key to use
21     LET sig = xml.Signature.Create()
22     CALL sig.setKey(key)
23      # Set XML node to be signed. In our case, the node with attribute 'xml:id="code"'
24     LET index = sig.createReference("#code","http://www.w3.org/2000/09/xmldsig#sha1")
25      # Set canonicalization method on the XML fragment to be signed.
26     CALL sig.appendReferenceTransformation(index,"http://www.w3.org/2001/10/xml-exc-c14n#")
27      # Compute detached signature
28     CALL sig.compute(doc)
29      # Retrieve signature document
30     LET doc=sig.getDocument()
31      # Save signature on disk
32     CALL doc.setFeature("format-pretty-print",TRUE)
33     CALL doc.save("MyDocumentDetachedSignature.xml") 
34   CATCH
35     DISPLAY "Unable to create a detached signature :",STATUS
36   END TRY
37 END MAIN 

Note: All keys or certificates in PEM or DER format were created with the OpenSSL tool.

Example 2 : Verify a detached signature using a HMAC key

01 IMPORT xml
02 
03 MAIN
04   DEFINE doc xml.DomDocument
05   DEFINE node xml.DomNode
06   DEFINE sig xml.Signature
07   DEFINE key xml.CryptoKey
08    # Create DomDocument object
09   LET doc = xml.DomDocument.Create() 
10    # Notice that whitespaces are significants in crytography, 
11    # therefore it is recommended to remove unnecessary ones 
12   CALL doc.setFeature("whitespace-in-element-content",FALSE) 
13   TRY
14      # Load Signature into a DomDocument object
15     CALL doc.load("MyDocumentDetachedSignature.xml") 
16      # Create signature object from DomDocument root node
17     LET sig = xml.Signature.CreateFromNode(doc.getDocumentElement()) 
18      # Create HMAC key and assign it to the signature object
19     LET key = xml.CryptoKey.Create("http://www.w3.org/2000/09/xmldsig#hmac-sha1")
20     CALL key.setKey("secretpassword")
21     CALL sig.setKey(key)
22      # Load original XML document into a DomDocument object
23     CALL doc.load("MyDocument.xml") 
24      # Verify detached signature validity of original document
25     LET isVerified = sig.verify(doc)
26      # Notice that if something has been modified in the node with attribute 'xml:id="code"' of the original XML document,
27      # the program will display "FAILED".
28     IF isVerified THEN
29       DISPLAY "Signature OK"
30     ELSE
31       DISPLAY "Signature FAILED"
32     END IF
33   CATCH
34     DISPLAY "Unable to verify the detached signature :",STATUS
35   END TRY 
36 END MAIN

Note: All keys or certificates in PEM or DER format were created with the OpenSSL tool.

Example 3 : Create an enveloping signature using a DSA key

01 IMPORT xml
02 
03 MAIN 
04   DEFINE doc xml.DomDocument
05   DEFINE root xml.DomNode
06   DEFINE sig xml.Signature
07   DEFINE key xml.CryptoKey
08   DEFINE index INTEGER
09   DEFINE objInd INTEGER
10    # Create DomDocument object
11   LET doc = xml.DomDocument.Create() 
12    # Notice that whitespaces are significants in crytography, 
13    # therefore it is recommended to remove unnecessary ones 
14   CALL doc.setFeature("whitespace-in-element-content",FALSE) 
15   TRY
16      # Load document to be signed
17     CALL doc.load("MyDocument.xml")
18      # Create DSA key and load it from file
19     LET key = xml.CryptoKey.Create("http://www.w3.org/2000/09/xmldsig#dsa-sha1")
20     CALL key.loadPEM("DSAKey.pem")
21      # Create signature object with the key to use
22     LET sig = xml.Signature.Create()
23     CALL sig.setKey(key)
24      # Create an object inside the signature to envelop the root node 
25     LET objInd = sig.createObject()
26      # Set the object id to get a reference
27     CALL sig.setObjectId(objInd,"data")
28      # Copy the enveloping node from the document
29     CALL sig.appendObjectData(objInd,doc.getDocumentElement())
30      # Set the reference to be signed on the object node. In our case, the object node with attribute 'data'
31     LET index = sig.createReference("#data","http://www.w3.org/2000/09/xmldsig#sha1")
32      # Set canonicalization method on the enveloping object to be signed.
33     CALL sig.appendReferenceTransformation(index,"http://www.w3.org/2001/10/xml-exc-c14n#")
34      # Compute enveloping signature
35     CALL sig.compute(NULL)
36      # Retrieve signature document
37     LET doc=sig.getDocument()
38      # Save signature on disk
39     CALL doc.setFeature("format-pretty-print",TRUE)
40     CALL doc.save("MyDocumentEnvelopingSignature.xml") 
41   CATCH
42     DISPLAY "Unable to create an enveloping signature :",STATUS
43   END TRY 
44 END MAIN 

Note: All keys or certificates in PEM or DER format were created with the OpenSSL tool.

Example 4 : Verify an enveloping signature using a X509 certificate

01 IMPORT xml
02 
03 MAIN
04   DEFINE doc xml.DomDocument
05   DEFINE node xml.DomNode
06   DEFINE sig xml.Signature
07   DEFINE cert xml.CryptoX509
08   DEFINE pub xml.CryptoKey
09    # Create DomDocument object
10   LET doc = xml.DomDocument.Create() 
11    # Notice that whitespaces are significants in crytography, 
12    # therefore it is recommended to remove unnecessary ones 
13   CALL doc.setFeature("whitespace-in-element-content",FALSE) 
14   TRY
15      # Load Signature into a DomDocument object
16     CALL doc.load("MyDocumentEnvelopingSignature.xml") 
17      # Create signature object from DomDocument root node
18     LET sig = xml.Signature.CreateFromNode(doc.getDocumentElement()) 
19      # Create X509 certificate 
20     LET cert = xml.CryptoX509.Create()
21     CALL cert.loadPEM("DSACertificate.crt")
22      # Create public key from that X509 certificate 
23     LET pub = cert.createPublicKey("http://www.w3.org/2000/09/xmldsig#dsa-sha1")
24      # Assign it to the signature 
25     CALL sig.setKey(pub)
26      # Verify enveloping signature validity 
27     LET isVerified = sig.verify(NULL)
28      # Notice that if something has been modified in the signature 
29      # or if the certificate isn't associated to the private DSA key of exemple 3,
30      # the program will display "FAILED".
31     IF isVerified THEN
32       DISPLAY "Signature OK"
33     ELSE
34       DISPLAY "Signature FAILED"
35     END IF
36   CATCH
37     DISPLAY "Unable to verify the enveloping signature :",STATUS
38   END TRY 
39 END MAIN 

Note: All keys or certificates in PEM or DER format were created with the OpenSSL tool.

Example 5 : Create an enveloped signature using a RSA key

01 IMPORT xml
02 
03 MAIN
04   DEFINE doc xml.DomDocument
05   DEFINE doc2 xml.DomDocument
06   DEFINE root xml.DomNode
07   DEFINE node xml.DomNode
08   DEFINE signNode xml.DomNode
09   DEFINE sig xml.Signature
10   DEFINE key xml.CryptoKey
11   DEFINE index INTEGER
12    # Create DomDocument object
13   LET doc = xml.DomDocument.Create() 
14    # Notice that whitespaces are significants in crytography, 
15    # therefore it is recommended to remove unnecessary ones 
16   CALL doc.setFeature("whitespace-in-element-content",FALSE) 
17   TRY
18      # Load document to be signed
19     CALL doc.load("MyDocument.xml")
20      # Create rsa key
21     LET key = xml.CryptoKey.Create("http://www.w3.org/2000/09/xmldsig#rsa-sha1")
22     CALL key.loadPEM("RSAKey.pem")
23      # Create signature object with the key to use
24     LET sig = xml.Signature.Create()
25     CALL sig.setKey(key)
26      # Set XML node to be signed. In our case, the node with attribute 'xml:id="code"'
27     LET index = sig.createReference("#code","http://www.w3.org/2000/09/xmldsig#sha1")
28      # Add enveloped method to not take the XML signature node into account when computing the entire document.
29     CALL sig.appendReferenceTransformation(index,"http://www.w3.org/2000/09/xmldsig#enveloped-signature")
30      # Set canonicalization method on the XML fragment to be signed.
31     CALL sig.appendReferenceTransformation(index,"http://www.w3.org/2001/10/xml-exc-c14n#")
32      # Compute enveloped signature
33     CALL sig.compute(doc)
34      # Retrieve signature document
35     LET doc2=sig.getDocument()
36      # Append the signature node to the original document to get a valid enveloped signature
37      # Notice that the enveloped signature can be added anywhere in the original document
38     LET signNode = doc2.getDocumentElement() # Get Signature node 
39     LET node = doc.importNode(signNode,true) # Import it into the original document
40     LET root = doc.getDocumentElement() # Retrieve the original document root node
41     CALL root.appendChild(node) # Append the signature node as last child of the original document
42      # Save document with enveloped signature back to disk
43     CALL doc.setFeature("format-pretty-print",TRUE)
44     CALL doc.save("MyDocumentEnvelopedSignature.xml") 
45   CATCH
46     DISPLAY "Unable to create an enveloped signature :",STATUS
47   END TRY
48 END MAIN

Note: All keys or certificates in PEM or DER format were created with the OpenSSL tool.

Example 6 : Verify an enveloped signature using a RSA key

01 IMPORT xml
02 
03 MAIN
04   DEFINE doc xml.DomDocument
05   DEFINE node xml.DomNode
06   DEFINE sig xml.Signature
07   DEFINE key xml.CryptoKey
08   DEFINE list xml.DomNodeList
09    # Create DomDocument object
10   LET doc = xml.DomDocument.Create() 
11    # Notice that whitespaces are significants in crytography, 
12    # therefore it is recommended to remove unnecessary ones 
13   CALL doc.setFeature("whitespace-in-element-content",FALSE) 
14   TRY
15      # Load original document with enveloped signature into a DomDocument object
16     CALL doc.load("MyDocumentEnvelopedSignature.xml") 
17      # Because the signature can be anywhere in the original document, we must first retrieve it
18     LET list = signature.getElementsByTagNameNS("Signature","http://www.w3.org/2000/09/xmldsig#")
19     IF list.getCount() != 1 THEN
20       DISPLAY "Unable to find one Signature node"
21       EXIT PROGRAM (-1)
22     ELSE
23       LET node = list.getItem(1)
24     END IF 
25      # Create RSA key
26     LET key = xml.CryptoKey.Create("http://www.w3.org/2000/09/xmldsig#rsa-sha1")
27     CALL key.loadPEM("RSAKey.pem")
28      # Create signature object from DomNode object and set RSA key to use
29     LET sig = xml.Signature.CreateFromNode(node) 
30     CALL sig.setKey(key)
31      # Verify enveloped signature validity of original document
32     LET isVerified = sig.verify(doc)
33      # Notice that if something has been modified in the node with attribute 'xml:id="code"' of the original XML document with the enveloped signature,
34      # the program will display "FAILED".
35     IF isVerified THEN
36       DISPLAY "Signature OK"
37     ELSE
38       DISPLAY "Signature FAILED"
39     END IF
40   CATCH
41     DISPLAY "Unable to verify the enveloped signature :",STATUS
42   END TRY 
43 END MAIN 

Note: All keys or certificates in PEM or DER format were created with the OpenSSL tool.

Back to the top