File: programming.html

package info (click to toggle)
xml-security-c 1.2.1-3%2Betch1
links: PTS
area: main
in suites: etch
size: 24,472 kB
ctags: 6,673
sloc: cpp: 36,830; xml: 23,415; sh: 2,365; makefile: 340; perl: 221
file content (674 lines) | stat: -rw-r--r-- 22,007 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="Apache Forrest" name="Generator">
<meta name="Forrest-version" content="0.6">
<meta name="Forrest-skin-name" content="pelt">
<title>XML Signature Programming</title>
<link type="text/css" href="../skin/basic.css" rel="stylesheet">
<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
<link type="text/css" href="../skin/profile.css" rel="stylesheet">
<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
</head>
<body onload="init()">
<script type="text/javascript">ndeSetTextSize();</script>
<div id="top">
<!--+
    |breadtrail
    +-->
<div class="breadtrail">
<a href="http://www.apache.org/">apache</a> &gt; <a href="http://xml.apache.org/">xml.apache</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
</div>
<!--+
    |header
    +-->
<div class="header">
<!--+
    |start group logo
    +-->
<div class="grouplogo">
<a href="http:///xml.apache.org"><img class="logoImage" alt="Apache XML" src="../images/group-logo.gif"></a>
</div>
<!--+
    |end group logo
    +-->
<!--+
    |start Project Logo
    +-->
<div class="projectlogo">
<a href="http://xml.apache.org/security"><img class="logoImage" alt="Apache XML Security" src="../images/project-logo.gif"></a>
</div>
<!--+
    |end Project Logo
    +-->
<!--+
    |start Search
    +-->
<div class="searchbox">
<form action="http://www.google.com/search" method="get" class="roundtopsmall">
<input value="xml.apache.org/security" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google:');" value="Search the site with google:" size="25" name="q" id="query" type="text">&nbsp; 
                    <input name="Search" value="Search" type="submit">
</form>
</div>
<!--+
    |end search
    +-->
<!--+
    |start Tabs
    +-->
<ul id="tabs">
<li>
<a class="base-not-selected" href="../index.html">Home</a>
</li>
<li>
<a class="base-not-selected" href="../Java/index.html">Java</a>
</li>
<li class="current">
<a class="base-selected" href="../c/index.html">C++</a>
</li>
</ul>
<!--+
    |end Tabs
    +-->
</div>
</div>
<div id="main">
<div id="publishedStrip">
<!--+
    |start Subtabs
    +-->
<div id="level2tabs"></div>
<!--+
    |end Endtabs
    +-->
<script type="text/javascript" language="JavaScript"><!--
              document.write("Published: " + document.lastModified);
              //  --></script>
</div>
<!--+
    |breadtrail
    +-->
<div class="breadtrail">
             
             &nbsp;
           </div>
<!--+
    |start Menu, mainarea
    +-->
<!--+
    |start Menu
    +-->
<div id="menu">
<div onclick="SwitchMenu('menu_1.1', '../skin/')" id="menu_1.1Title" class="menutitle">C++</div>
<div id="menu_1.1" class="menuitemgroup">
<div class="menuitem">
<a title="" href="../c/index.html">Index</a>
</div>
<div class="menuitem">
<a title="" href="../c/installation.html">Installation</a>
</div>
<div class="menuitem">
<a title="" href="../c/faq.html">FAQs</a>
</div>
<div class="menuitem">
<a title="" href="../c/apiDocs/index.html">API Docs</a>
</div>
<div class="menuitem">
<a title="" href="http://nagoya.apache.org/~blautenb/xml-security-c/apiDocs/">Nightly API build</a>
</div>
<div class="menuitem">
<a title="" href="../c/tools.html">Tools</a>
</div>
<div class="menuitem">
<a title="" href="../c/releases.html">Release Information</a>
</div>
<div class="menuitem">
<a title="" href="../c/credits.html">Credits</a>
</div>
<div class="menuitem">
<a title="" href="../c/interop.html">Interoperability</a>
</div>
</div>
<div onclick="SwitchMenu('menu_selected_1.2', '../skin/')" id="menu_selected_1.2Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Programming</div>
<div id="menu_selected_1.2" class="selectedmenuitemgroup" style="display: block;">
<div class="menupage">
<div class="menupagetitle">Signatures</div>
</div>
<div class="menuitem">
<a title="" href="../c/prog_enc.html">Encryption</a>
</div>
</div>
<div id="credit"></div>
<div id="roundbottom">
<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
<!--+
  |alternative credits
  +-->
</div>
<!--+
    |end Menu
    +-->
<!--+
    |start content
    +-->
<div id="content">
<div id="skinconf-txtlink"></div>
<h1>XML Signature Programming</h1>
    
<a name="N1000D"></a><a name="Overview"></a>
<h2 class="h3">Overview</h2>
<div class="section">
<p>
		There are two main signature modes of operation for the libraries.  
		Signing and verifying.  Verifying is the simplest operation, as 
		it (generally) operates on a DOM &lt;Signature&gt; structure that 
		has already been created.
	  </p>
<p>
		Signing on the other hand can be more difficult, as there may be a
		requirement to create the DOM structure necessary for the signature
		prior to the actual signing operation.
	  </p>
<p>
		The rest of this section provides a very high level overview on how
		to use the library for signing and verificataion of signatures.  
	  </p>
<div class="frame note">
<div class="label">Note</div>
<div class="content">
		Full API documentation for the current official release can be found 
		<a href="apiDocs/index.html">here</a>.  The API documentation is
		also generated <a class="external" href="http://nagoya.apache.org/~blautenb/xml-security-c/apiDocs/">nightly</a> from the CVS repository.
	  </div>
</div>
<p>
		Two samples are provided :
	  </p>
<ul>
		
<li>
<a href="programming.html#simplehmac">Simple HMAC Signing
		  </a>
</li>
		
<li>
<a href="programming.html#simpledsa">Simple DSA Validation
		  </a>
</li>
	  
</ul>
<p>
		The code snippets are taken directly from some of the sample code 
		provided in the src/samples directory in the distribution.  More 
		information on the API can be found in the API Documentation.
	  </p>
</div>
	
<a name="N1003B"></a><a name="simplehmac"></a>
<h2 class="h3">A simple HMAC Signing example</h2>
<div class="section">
<p>
		The first example is based on the simpleHMAC.cpp code in samples.  It
		creates an XML letter, the appends a dummy signature to the end, using
		an enveloped-signature transform.
	  </p>
<a name="N10044"></a><a name="Setup"></a>
<h3 class="h4">Setup</h3>
<p>
		  The following code snippet initialises Xerces, Xalan and XSEC.
		  Note that the enveloped transform is implemented using an XPath
		  expression, so it is imperitive the Xalan libraries are initialised.
		</p>
<pre class="code">
int main (int argc, char **argv) {

    try {
        XMLPlatformUtils::Initialize();
#ifndef XSEC_NO_XALAN
        XalanTransformer::initialize();
#endif
        XSECPlatformUtils::Initialise();
    }
    catch (const XMLException &amp;e) {

        cerr &lt;&lt; "Error during initialisation of Xerces" &lt;&lt; endl;
        cerr &lt;&lt; "Error Message = : "
		     &lt;&lt; e.getMessage() &lt;&lt; endl;

    }

    // Create a blank Document

    DOMImplementation *impl = 
        DOMImplementationRegistry::getDOMImplementation(MAKE_UNICODE_STRING("Core"));
	
    // Create a letter
    DOMDocument *doc = createLetter(impl);
    DOMElement *rootElem = doc-&gt;getDocumentElement();

</pre>
<p>
		  In the sample application, the call to <em>createLetter(impl)</em> 
		  simply creates a
		  letter DOM structure with a to and from address and some text.
		  This is done using standard DOM calls via Xerces.
		</p>
<p>
		  Once the system is initialised and the DOM document is created,
		  a DSIGSignature object is created via the <em>XSECProvider</em>
		  interface class.  The signature object is then used to create
		  a blank signature DOM node structure which is then inserted at 
		  the end of the document.
		</p>
<pre class="code">
    XSECProvider prov;
    DSIGSignature *sig;
    DOMElement *sigNode;

    try {
		
        // Create a signature object

        sig = prov.newSignature();
        sig-&gt;setDSIGNSPrefix("ds");

        // Use it to create a blank signature DOM structure from the doc

        sigNode = sig-&gt;createBlankSignature(doc, 
                                    CANON_C14N_COM, 
                                    SIGNATURE_HMAC, 
                                    HASH_SHA1);

</pre>
<p>
		  The call to <em>newSignature</em> creates a signature
		  object only.  No DOM nodes are created at this point.
		  The call to <em>setDSIGNSPrefix</em> tells the XSEC
		  library what namespace prefix to use for the signature object when
		  it starts to create DOM nodes (in this case "ds" will be used).  
		  By default, the library will use "dsig" as the prefix for the name 
		  space for Digital Signatures.
		</p>
<p>
		  Finally, the call to sig-&gt;createBlankSignature sets up both the 
		  DOM structure and the XSEC objects for a new signature with no
		  &lt;Reference&gt; elements.  In this case, the signature will be
		  made using Commented C14n canonicalisation, and a HMAC-SHA1
		  signature.
		</p>
<div class="frame warning">
<div class="label">Warning</div>
<div class="content">
		  The XSECProvider class still "owns" the DSIGSignature object.
		  To delete the object, the original provider.release(sig) call
		  should be used.  Never delete a DSIGSignature object directly.
		</div>
</div>
<a name="N10071"></a><a name="Create+a+Reference+and+Sign"></a>
<h3 class="h4">Create a Reference and Sign</h3>
<p>
		  Now that the signature object is created, the signature is inserted
		  into the document, and a reference is created and set for an
		  enveloping transform.
		</p>
<pre class="code">
        // Insert the signature DOM nodes into the doc

        rootElem-&gt;appendChild(doc-&gt;createTextNode(MAKE_UNICODE_STRING("\n")));
        rootElem-&gt;appendChild(sigNode);
        rootElem-&gt;appendChild(doc-&gt;createTextNode(MAKE_UNICODE_STRING("\n")));

        // Create an envelope reference for the text to be signed
        DSIGReference * ref = sig-&gt;createReference("");
        ref-&gt;appendEnvelopedSignatureTransform();

</pre>
<p>
		  The <em>""</em> parameter to <em>createReference</em> sets the
		  URI attribute for the reference to be "" - indicating the root
		  element of the document in which the signature resides.
		  The call to <em>appendEnvelopedSignatureTransform</em> adds
		  a standard eneveloped-signature transform to the Reference node.
		</p>
<p>
		  The macro MAKE_UNICODE_STRING is defined within the library
		  header files and is used to transcode local code page strings.
		</p>
<div class="frame note">
<div class="label">Note</div>
<div class="content">
		  There is no need to insert the reference object into the DOM structure.
		  This is done automatically by the <em>createReference</em> call.
		</div>
</div>
<p>
		  Finally we create a signing key and sign the document.
		</p>
<pre class="code">

        // Set the HMAC Key to be the string "secret"

        OpenSSLCryptoKeyHMAC * hmacKey = new OpenSSLCryptoKeyHMAC();
        hmacKey-&gt;setKey((unsigned char *) "secret", strlen("secret"));
        sig-&gt;setSigningKey(hmacKey);

        // Add a KeyInfo element
        sig-&gt;appendKeyName("The secret key is \"secret\"");

        // Sign

        sig-&gt;sign();
    }

    catch (XSECException &amp;e)
    {
        cerr &lt;&lt; "An error occured during a signature load\n   Message: "
             &lt;&lt; e.getMsg() &lt;&lt; endl;
        exit(1);
                
    }
</pre>
<p>
		  The first two code lines create an OpenSSLCryptoKeyHMAC object,
		  and set the key value to the string "secret".  The OpenSSL...
		  classes are the interface layer between XSEC and OpenSSL.  More
		  information can be found in the API documentation, but the main
		  point of note is that the XSEC library never deals directly with
		  OpenSSL - it works via the XSECCrypto abstract classes which are
		  implemented in the OpenSSLCrypto code.  This would allow another
		  person to re-implement the XSECCrypto code to use any cryptographic
		  provider required.
		</p>
<div class="frame note">
<div class="label">Note</div>
<div class="content">
		  Once the key is passed to the signature it is owned by the signature.
		  The signature object will delete the key when it is itself deleted,
		  or a new key is passed in.
		</div>
</div>
<p>
		  The call to <em>sig-&gt;appendKeyName()</em> is used to append a
		  &lt;KeyName&gt; element into the &lt;KeyInfo&gt; block.  The
		  KeyInfo block was created as part of this call.
		</p>
<p>
		  After the call to <em>sig-&gt;sign()</em> the DOM structure has the
		  correct hash and signature values.  The owner program can write,
		  store or further manipulate the document as required.  If a document
		  manipulation might affect the signature (in this case almost anything
		  would, as we are using an enveloping transform which effectively
		  signs everything that is not part of the signature), then a further
		  call to <em>sig-&gt;sign()</em> will re-sign the changes.
		</p>
<p>
		  The last part of the code does some work to output the new DOM
		  structure.  The output should look something like the following:
		</p>
<pre class="code">
&lt;Letter&gt;
&lt;ToAddress&gt;The address of the Recipient&lt;/ToAddress&gt;
&lt;FromAddress&gt;The address of the Sender&lt;/FromAddress&gt;
&lt;Text&gt;
To whom it may concern

...
&lt;/Text&gt;
&lt;ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"&gt;
&lt;ds:SignedInfo&gt;
&lt;ds:CanonicalizationMethod Algorithm=
"http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"/&gt;
&lt;ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#hmac-sha1"/&gt;
&lt;ds:Reference URI=""&gt;
&lt;ds:Transforms&gt;
&lt;ds:Transform Algorithm=
"http://www.w3.org/2000/09/xmldsig#enveloped-signature"/&gt;
&lt;/ds:Transforms&gt;
&lt;ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/&gt;
&lt;ds:DigestValue&gt;askxS/A3BaLCjFjZ/ttU9c12kA4=&lt;/ds:DigestValue&gt;
&lt;/ds:Reference&gt;
&lt;/ds:SignedInfo&gt;
&lt;ds:SignatureValue&gt;oYEdQYG1IHzbkR1UcJ9Q5VriRPs=
&lt;/ds:SignatureValue&gt;
&lt;ds:KeyInfo&gt;
&lt;ds:KeyName&gt;The secret key is "secret"&lt;/ds:KeyName&gt;
&lt;/ds:KeyInfo&gt;
&lt;/ds:Signature&gt;
&lt;/Letter&gt;
</pre>
<p>Note that the DigestValue and SignatureValue elements have been
		  filled in.
		</p>
</div>
	
<a name="N100BB"></a><a name="simpledsa"></a>
<h2 class="h3">A simple validation example</h2>
<div class="section">
<p>
		The second example takes a pre-signed document and an associated
		certificate and verifies the embedded signature.  The document in
		question is a simple purchase order, and changes are made to the
		value of the order to demonstrate a signature failing verification.
	  </p>
<a name="N100C4"></a><a name="Setup-N100C4"></a>
<h3 class="h4">Setup</h3>
<p>
		  As in the first example, Initialisation of the libraries is
		  performed, and Xerces is used to read in the document (which in
		  this case is stored in a string in the source code).
		</p>
<p>
		  In order to be able to modify the contents of the document later
		  on, we also quickly find the string containing the value of the
		  purchase order.
		</p>
<p>
		  For the sake of brevity, the code relating to parsing the in-memory
		  document has been removed from the snippet below.
		</p>
<pre class="code">
int main (int argc, char **argv) {

    try {
        XMLPlatformUtils::Initialize();
#ifndef XSEC_NO_XALAN
        XalanTransformer::initialize();
#endif
        XSECPlatformUtils::Initialise();
    }
    catch (const XMLException &amp;e) {

        cerr &lt;&lt; "Error during initialisation of Xerces" &lt;&lt; endl;
        cerr &lt;&lt; "Error Message = : "
             &lt;&lt; DOMString(e.getMessage()) &lt;&lt; endl;

    }

    ...
    
    Xerces is used to parse the document here
    
   

    DOM_Document doc = parser-&gt;getDocument();

    // Find the Amount node
    DOMNode *amt = doc-&gt;getDocumentElement();

    if (amt != NULL)
        amt = amt-&gt;getFirstChild();

    while (amt != NULL &amp;&amp; 
           (amt-&gt;getNodeType() != DOMNode::ELEMENT_NODE || 
           !strEquals(amt-&gt;getNodeName(), "Amount")))
        amt = amt-&gt;getNextSibling();

    if (amt != NULL)
        amt = amt-&gt;getFirstChild();

    if (amt == NULL || amt-&gt;getNodeType() != DOMNode::TEXT_NODE) {
        cerr &lt;&lt; "Error finding amount in purchase order" &lt;&lt; endl;
        exit (1);
    }
</pre>
<a name="N100D8"></a><a name="Create+the+Signature+and+Key+objects"></a>
<h3 class="h4">Create the Signature and Key objects</h3>
<p>
		  Now that the document is in memory, an XSECProvider is
		  created and used to create a new DSIGSignature object.  In
		  addition, the OpenSSL interface routines are used to
		  read in a certificate and obtain the associated public
		  key.
		</p>
<pre class="code">
    XSECProvider prov;

    DSIGSignature * sig = prov.newSignatureFromDOM(doc);


    try {
        // Use the OpenSSL interface objects to get a signing key

        OpenSSLCryptoX509 * x509 = new OpenSSLCryptoX509();
        x509-&gt;loadX509Base64Bin(cert, strlen(cert));
                
        sig-&gt;load();
</pre>
<p>
		  In this case, the signature is create with the 
		  <em>newSignatureFromDOM</em> method.  This tells the library that
		  the signature structure (although not necessarily a signed
		  structure) already exists in the DOM nodes.  The library attempts
		  to find the &lt;Signature&gt; node so that the load will work.
		  (The library will throw an XSECException if it cannot find the
		  Element.)
		</p>
<p>
		  The later call to <em>sig-&gt;load()</em> tells the library to
		  read the DOM structure and create the appropriate DSIG elements.
		</p>
<p>
		  In this case an OpenSSLCryptoX509 object is also created.  It is
		  used to read in the <em>cert</em> string and convert to an X509
		  structure.  This could also be done using standard calls directly
		  to OpenSSL, but this is a quick shortcut.
		</p>
<a name="N100F8"></a><a name="Find+a+key"></a>
<h3 class="h4">Find a key</h3>
<p>
		  As we already know the key, the following code snippet loads the 
		  key directly from the related X509.  However prior to doing this,
		  the code demonstrates
		  using the DSIGKeyInfo structures to find the key name that was
		  embedded in the certificate.  In an application, this could be
		  used to reference the correct key to be passed in.  (Maybe via
		  an XKMS call.)
		</p>
<p>
		  the <em>safeBuffer</em> type is used extensively within the XSEC
		  library to safely handle variable length strings and raw buffers.
		  The call to <em>rawCharBuffer()</em> simply returns a (char *)
		  type pointer to the buffer within the <em>safeBuffer</em>
		
</p>
<p>
		  The call to <em>clonePublicKey()</em> returns a copy of the
		  public key embedded in the certificate.  It is owned by the caller,
		  so in this case it can safely be passed to the DSIGSignature object
		  where it will be destroyed when another key is loaded or the 
		  object is released by the XSECProvider.
		</p>
<pre class="code">
        DSIGKeyInfoList * kinfList = sig-&gt;getKeyInfoList();
                
        // See if we can find a Key Name
        safeBuffer kname;
        DSIGKeyInfo * kinf = kinfList-&gt;getFirstKeyInfo();
        while (kinf != NULL) {
            kname = kinf-&gt;getKeyName();
            if (kname.sbStrcmp("")) {
                cout &lt;&lt; "Key Name = " 
                     &lt;&lt; kname.rawCharBuffer() &lt;&lt; endl;
            }
            kinf = kinfList-&gt;getNextKeyInfo();
        }

        sig-&gt;setSigningKey(x509-&gt;clonePublicKey());
</pre>
<a name="N10118"></a><a name="Validate+the+signature"></a>
<h3 class="h4">Validate the signature</h3>
<p>
		  Finally the signature is validated.  In this case, we validate it
		  three times.  First with the original DOM structure, then with the
		  price changed and finally with the price set back to the original
		  value.
		</p>
<pre class="code">
        cout &lt;&lt; "Amount = " &lt;&lt; amt &lt;&lt; " -&gt; ";

        if (sig-&gt;verify()) {
            cout &lt;&lt; "Signature Valid\n";
        }
        else {
            cout &lt;&lt; "Incorrect Signature\n";
        }

        amt.setNodeValue("$0.50");
                
        cout &lt;&lt; "Amount = " &lt;&lt; amt &lt;&lt; " -&gt; ";

        if (sig-&gt;verify()) {
            cout &lt;&lt; "Signature Valid\n";
        }
        else {
            cout &lt;&lt; "Incorrect Signature\n";
        }

        amt.setNodeValue("$16.50");
                
        cout &lt;&lt; "Amount = " &lt;&lt; amt &lt;&lt; " -&gt; ";

        if (sig-&gt;verify()) {
            cout &lt;&lt; "Signature Valid\n";
        }
        else {
            cout &lt;&lt; "Incorrect Signature\n";
        }
</pre>
<p>
		  When run, the program outputs the following:
		</p>
<pre class="code">
Key Name = C=AU, ST=Vic, O=XML-Security-C Project, 
CN=Samples Demo Certificate
Amount = $16.50 -&gt; Signature Valid
Amount = $0.50 -&gt; Incorrect Signature
Amount = $16.50 -&gt; Signature Valid
		  </pre>
</div>
  
</div>
<!--+
    |end content
    +-->
<div class="clearboth">&nbsp;</div>
</div>
<div id="footer">
<!--+
    |start bottomstrip
    +-->
<div class="lastmodified">
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
//  --></script>
</div>
<div class="copyright">
 Copyright &copy; 2002-2005 The Apache Software Foundation.</div>
<!--+
    |end bottomstrip
    +-->
</div>
</body>
</html>