docs/api/xmlsec-notes-contexts.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   4 <title>Using context objects.</title>
   5 <meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
   6 <link rel="HOME" title="XML Security Library Reference Manual" href="index.html">
   7 <link rel="UP" title="XML Security Library Tutorial" href="xmlsec-notes.html">
   8 <link rel="PREVIOUS" title="Transforms and transforms chain." href="xmlsec-notes-transforms.html">
   9 <link rel="NEXT" title="Adding support for new cryptographic library." href="xmlsec-notes-new-crypto.html">
  10 <style type="text/css">.synopsis, .classsynopsis {
  11     background: #eeeeee;
  12     border: solid 1px #aaaaaa;
  13     padding: 0.5em;
  14 }
  15 .programlisting {
  16     background: #eeeeff;
  17     border: solid 1px #aaaaff;
  18     padding: 0.5em;
  19 }
  20 .variablelist {
  21     padding: 4px;
  22     margin-left: 3em;
  23 }
  24 .navigation {
  25     background: #ffeeee;
  26     border: solid 1px #ffaaaa;
  27     margin-top: 0.5em;
  28     margin-bottom: 0.5em;
  29 }
  30 .navigation a {
  31     color: #770000;
  32 }
  33 .navigation a:visited {
  34     color: #550000;
  35 }
  36 .navigation .title {
  37     font-size: 200%;
  38 }</style>
  39 </head>
  40 <body><table witdh="100%" valign="top"><tr valign="top">
  41 <td valign="top" align="left" width="210">
  42 <img src="../images/logo.gif" alt="XML Security Library" border="0"><p></p>
  43 <ul>
  44 <li><a href="../index.html">Home</a></li>
  45 <li><a href="../download.html">Download</a></li>
  46 <li><a href="../news.html">News</a></li>
  47 <li><a href="../documentation.html">Documentation</a></li>
  48 <ul>
  49 <li><a href="../faq.html">FAQ</a></li>
  50 <li><a href="../api/xmlsec-notes.html">Tutorial</a></li>
  51 <li><a href="../api/xmlsec-reference.html">API reference</a></li>
  52 <li><a href="../api/xmlsec-examples.html">Examples</a></li>
  53 </ul>
  54 <li><a href="../xmldsig.html">XML Digital Signature</a></li>
  55 <ul><li><a href="http://www.aleksey.com/xmlsec/xmldsig-verifier.html">Online Verifier</a></li></ul>
  56 <li><a href="../xmlenc.html">XML Encryption</a></li>
  57 <li><a href="../c14n.html">XML Canonicalization</a></li>
  58 <li><a href="../bugs.html">Reporting Bugs</a></li>
  59 <li><a href="http://www.aleksey.com/pipermail/xmlsec">Mailing list</a></li>
  60 <li><a href="../related.html">Related</a></li>
  61 <li><a href="../authors.html">Authors</a></li>
  62 </ul>
  63 <table width="100%">
  64 <tr>
  65 <td width="15"></td>
  66 <td><a href="http://xmlsoft.org/"><img src="../images/libxml2-logo.png" alt="LibXML2" border="0"></a></td>
  67 </tr>
  68 <tr>
  69 <td width="15"></td>
  70 <td><a href="http://xmlsoft.org/XSLT"><img src="../images/libxslt-logo.png" alt="LibXSLT" border="0"></a></td>
  71 </tr>
  72 <tr>
  73 <td width="15"></td>
  74 <td><a href="http://www.openssl.org/"><img src="../images/openssl-logo.png" alt="OpenSSL" border="0"></a></td>
  75 </tr>
  76 <!--Links - start--><!--Links - end-->
  77 </table>
  78 </td>
  79 <td valign="top"><table width="100%" valign="top"><tr><td valign="top" align="left" id="xmlsecContent">
  80 <table width="100%" class="navigation" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
  81 <td><a accesskey="p" href="xmlsec-notes-transforms.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  82 <td><a accesskey="u" href="xmlsec-notes.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  83 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  84 <th width="100%" align="center">XML Security Library Reference Manual</th>
  85 <td><a accesskey="n" href="xmlsec-notes-new-crypto.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  86 </tr></table>
  87 <div class="CHAPTER">
  88 <h1>
  89 <a name="XMLSEC-NOTES-CONTEXTS"></a>Using context objects.</h1>
  90 <p>The great flexibility of XML Digital Signature and XML Encryption
  91     specification is one of the most interesting and in the same time,
  92     most dangerouse feature for an application developer.
  93     For example, XPath and XSLT transform can make it very difficult
  94     to find out what exactly was signed by just looking at the
  95     transforms and the input data. Many protocols based on
  96     XML Digital Signature and XML Encryption restrict allowed
  97     key data types, allowed transforms or possible input data.
  98     For example, signature in a simple SAML Response should have only
  99     one &lt;dsig:Reference/&gt; element with an empty or NULL
 100     URI attribute and only one enveloped transform.
 101     XML Security Library uses "context" objects to let application
 102     enable or disable particular features, return the result
 103     data and the information collected during the processing.
 104     Also all the context objects defined in XML Security library have
 105     a special <code class="STRUCTFIELD">userData</code> member which could
 106     be used by application to pass application specific data around.
 107     XML Security Library never use this field.
 108     The application creates a new
 109     <a href="xmlsec-xmldsig.html#XMLSECDSIGCTX">xmlSecDSigCtx</a>
 110     or <a href="xmlsec-xmlenc.html#XMLSECENCCTX">xmlSecEncCtx</a> object for each
 111     operation, sets necessary options and consumes result returned
 112     in the context after signature, verification, encryption or decryption.
 113     </p>
 114 <p>     </p>
 115 <div class="EXAMPLE">
 116 <a name="AEN489"></a><p><b>Example 1. SAML signature validation.</b></p>
 117 <pre class="PROGRAMLISTING">/**
 118  * verify_file:
 119  * @mngr:               the pointer to keys manager.
 120  * @xml_file:           the signed XML file name.
 121  *
 122  * Verifies XML signature in #xml_file.
 123  *
 124  * Returns 0 on success or a negative value if an error occurs.
 125  */
 126 int
 127 verify_file(xmlSecKeysMngrPtr mngr, const char* xml_file) {
 128     xmlDocPtr doc = NULL;
 129     xmlNodePtr node = NULL;
 130     xmlSecDSigCtxPtr dsigCtx = NULL;
 131     int res = -1;
 132
 133     assert(mngr);
 134     assert(xml_file);
 135
 136     /* load file */
 137     doc = xmlParseFile(xml_file);
 138     if ((doc == NULL) || (xmlDocGetRootElement(doc) == NULL)){
 139         fprintf(stderr, "Error: unable to parse file \"%s\"\n", xml_file);
 140         goto done;
 141     }
 142
 143     /* find start node */
 144     node = xmlSecFindNode(xmlDocGetRootElement(doc), xmlSecNodeSignature, xmlSecDSigNs);
 145     if(node == NULL) {
 146         fprintf(stderr, "Error: start node not found in \"%s\"\n", xml_file);
 147         goto done;
 148     }
 149
 150     /* create signature context */
 151     dsigCtx = xmlSecDSigCtxCreate(mngr);
 152     if(dsigCtx == NULL) {
 153         fprintf(stderr,"Error: failed to create signature context\n");
 154         goto done;
 155     }
 156
 157     /* limit the Reference URI attributes to empty or NULL */
 158     dsigCtx-&gt;enabledReferenceUris = xmlSecTransformUriTypeEmpty;
 159
 160     /* limit allowed transforms for siganture and reference processing */
 161     if((xmlSecDSigCtxEnableSignatureTransform(dsigCtx, xmlSecTransformInclC14NId) &lt; 0) ||
 162        (xmlSecDSigCtxEnableSignatureTransform(dsigCtx, xmlSecTransformExclC14NId) &lt; 0) ||
 163        (xmlSecDSigCtxEnableSignatureTransform(dsigCtx, xmlSecTransformSha1Id) &lt; 0) ||
 164        (xmlSecDSigCtxEnableSignatureTransform(dsigCtx, xmlSecTransformRsaSha1Id) &lt; 0)) {
 165
 166         fprintf(stderr,"Error: failed to limit allowed siganture transforms\n");
 167         goto done;
 168     }
 169     if((xmlSecDSigCtxEnableReferenceTransform(dsigCtx, xmlSecTransformInclC14NId) &lt; 0) ||
 170        (xmlSecDSigCtxEnableReferenceTransform(dsigCtx, xmlSecTransformExclC14NId) &lt; 0) ||
 171        (xmlSecDSigCtxEnableReferenceTransform(dsigCtx, xmlSecTransformSha1Id) &lt; 0) ||
 172        (xmlSecDSigCtxEnableReferenceTransform(dsigCtx, xmlSecTransformEnvelopedId) &lt; 0)) {
 173
 174         fprintf(stderr,"Error: failed to limit allowed reference transforms\n");
 175         goto done;
 176     }
 177
 178     /* in addition, limit possible key data to valid X509 certificates only */
 179     if(xmlSecPtrListAdd(&amp;(dsigCtx-&gt;keyInfoReadCtx.enabledKeyData), BAD_CAST xmlSecKeyDataX509Id) &lt; 0) {
 180         fprintf(stderr,"Error: failed to limit allowed key data\n");
 181         goto done;
 182     }
 183
 184     /* Verify signature */
 185     if(xmlSecDSigCtxVerify(dsigCtx, node) &lt; 0) {
 186         fprintf(stderr,"Error: signature verify\n");
 187         goto done;
 188     }
 189
 190     /* check that we have only one Reference */
 191     if((dsigCtx-&gt;status == xmlSecDSigStatusSucceeded) &amp;&amp;
 192         (xmlSecPtrListGetSize(&amp;(dsigCtx-&gt;signedInfoReferences)) != 1)) {
 193
 194         fprintf(stderr,"Error: only one reference is allowed\n");
 195         goto done;
 196     }
 197
 198     /* print verification result to stdout */
 199     if(dsigCtx-&gt;status == xmlSecDSigStatusSucceeded) {
 200         fprintf(stdout, "Signature is OK\n");
 201     } else {
 202         fprintf(stdout, "Signature is INVALID\n");
 203     }
 204
 205     /* success */
 206     res = 0;
 207
 208 done:
 209     /* cleanup */
 210     if(dsigCtx != NULL) {
 211         xmlSecDSigCtxDestroy(dsigCtx);
 212     }
 213
 214     if(doc != NULL) {
 215         xmlFreeDoc(doc);
 216     }
 217     return(res);
 218 }
 219
 220             </pre>
 221 </div>
 222     </div>
 223 <table class="navigation" width="100%" summary="Navigation footer" cellpadding="2" cellspacing="2"><tr valign="middle">
 224 <td align="left"><a accesskey="p" href="xmlsec-notes-transforms.html"><b>&lt;&lt;&lt; Transforms and transforms chain.</b></a></td>
 225 <td align="right"><a accesskey="n" href="xmlsec-notes-new-crypto.html"><b>Adding support for new cryptographic library. &gt;&gt;&gt;</b></a></td>
 226 </tr></table>
 227 </td></tr></table></td>
 228 </tr></table></body>
 229 </html>