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

    /* load file */
    doc = xmlParseFile(xml_file);
    if ((doc == NULL) || (xmlDocGetRootElement(doc) == NULL)){
	fprintf(stderr, "Error: unable to parse file \"%s\"\n", xml_file);
	goto done;	
    }
    
    /* find start node */
    node = xmlSecFindNode(xmlDocGetRootElement(doc), xmlSecNodeSignature, xmlSecDSigNs);
    if(node == NULL) {
	fprintf(stderr, "Error: start node not found in \"%s\"\n", xml_file);
	goto done;	
    }

    /* create signature context */
    dsigCtx = xmlSecDSigCtxCreate(mngr);
    if(dsigCtx == NULL) {
        fprintf(stderr,"Error: failed to create signature context\n");
	goto done;
    }

    /* limit the Reference URI attributes to empty or NULL */
    dsigCtx-&gt;enabledReferenceUris = xmlSecTransformUriTypeEmpty;
    
    /* limit allowed transforms for signature and reference processing */
    if((xmlSecDSigCtxEnableSignatureTransform(dsigCtx, xmlSecTransformInclC14NId) &lt; 0) ||
       (xmlSecDSigCtxEnableSignatureTransform(dsigCtx, xmlSecTransformExclC14NId) &lt; 0) ||
       (xmlSecDSigCtxEnableSignatureTransform(dsigCtx, xmlSecTransformSha1Id) &lt; 0) ||
       (xmlSecDSigCtxEnableSignatureTransform(dsigCtx, xmlSecTransformRsaSha1Id) &lt; 0)) {

        fprintf(stderr,"Error: failed to limit allowed signature transforms\n");
	goto done;
    }
    if((xmlSecDSigCtxEnableReferenceTransform(dsigCtx, xmlSecTransformInclC14NId) &lt; 0) ||
       (xmlSecDSigCtxEnableReferenceTransform(dsigCtx, xmlSecTransformExclC14NId) &lt; 0) ||
       (xmlSecDSigCtxEnableReferenceTransform(dsigCtx, xmlSecTransformSha1Id) &lt; 0) ||
       (xmlSecDSigCtxEnableReferenceTransform(dsigCtx, xmlSecTransformEnvelopedId) &lt; 0)) {

        fprintf(stderr,"Error: failed to limit allowed reference transforms\n");
	goto done;
    }

    /* in addition, limit possible key data to valid X509 certificates only */
    if(xmlSecPtrListAdd(&amp;(dsigCtx-&gt;keyInfoReadCtx.enabledKeyData), BAD_CAST xmlSecKeyDataX509Id) &lt; 0) {
        fprintf(stderr,"Error: failed to limit allowed key data\n");
	goto done;
    }
    
    /* Verify signature */
    if(xmlSecDSigCtxVerify(dsigCtx, node) &lt; 0) {
        fprintf(stderr,"Error: signature verify\n");
	goto done;
    }

    /* check that we have only one Reference */
    if((dsigCtx-&gt;status == xmlSecDSigStatusSucceeded) &amp;&amp; 
        (xmlSecPtrListGetSize(&amp;(dsigCtx-&gt;signedInfoReferences)) != 1)) {
	
        fprintf(stderr,"Error: only one reference is allowed\n");
	goto done;
    }
        
    /* print verification result to stdout */
    if(dsigCtx-&gt;status == xmlSecDSigStatusSucceeded) {
	fprintf(stdout, "Signature is OK\n");
    } else {
	fprintf(stdout, "Signature is INVALID\n");
    }    

    /* success */
    res = 0;

done:    
    /* cleanup */
    if(dsigCtx != NULL) {
	xmlSecDSigCtxDestroy(dsigCtx);
    }
    
    if(doc != NULL) {
	xmlFreeDoc(doc); 
    }
    return(res);
}

	    </pre>
</div>
    </div>
<table class="navigation" width="100%" summary="Navigation footer" cellpadding="2" cellspacing="2"><tr valign="middle">
<td align="left"><a accesskey="p" href="xmlsec-notes-transforms.html"><b>&lt;&lt;&lt; Transforms and transforms chain.</b></a></td>
<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>
</tr></table>
</td></tr></table></td>
</tr></table></body>
</html>