1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
3 <title>Heimdalx509library: hx509 CMS/pkcs7 functions</title>
4 <link href="doxygen.css" rel="stylesheet" type="text/css">
5 <link href="tabs.css" rel="stylesheet" type="text/css">
8 <a href="http://www.h5l.org/"><img src="http://www.h5l.org/keyhole-heimdal.png" alt="keyhole logo"/></a>
10 <!-- end of header marker -->
11 <!-- Generated by Doxygen 1.5.6 -->
12 <div class="navigation" id="top">
15 <li><a href="index.html"><span>Main Page</span></a></li>
16 <li><a href="pages.html"><span>Related Pages</span></a></li>
17 <li><a href="modules.html"><span>Modules</span></a></li>
21 <div class="contents">
22 <h1>hx509 CMS/pkcs7 functions</h1><table border="0" cellpadding="0" cellspacing="0">
24 <tr><td colspan="2"><br><h2>Functions</h2></td></tr>
25 <tr><td class="memItemLeft" nowrap align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__hx509__cms.html#g59a1f6dc31e384a0d378c8179f2be9c3">hx509_cms_wrap_ContentInfo</a> (const heim_oid *oid, const heim_octet_string *buf, heim_octet_string *res)</td></tr>
27 <tr><td class="memItemLeft" nowrap align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__hx509__cms.html#gacbd636f3053c560782d83251f42b71a">hx509_cms_unwrap_ContentInfo</a> (const heim_octet_string *in, heim_oid *oid, heim_octet_string *out, int *have_data)</td></tr>
29 <tr><td class="memItemLeft" nowrap align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__hx509__cms.html#gb13d28bf986e3b66c05e7e33799be07b">hx509_cms_unenvelope</a> (hx509_context context, hx509_certs certs, int flags, const void *data, size_t length, const heim_octet_string *encryptedContent, time_t time_now, heim_oid *contentType, heim_octet_string *content)</td></tr>
31 <tr><td class="memItemLeft" nowrap align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__hx509__cms.html#g618f32b35fa6f679cc5f32fb8abdbe85">hx509_cms_envelope_1</a> (hx509_context context, int flags, hx509_cert cert, const void *data, size_t length, const heim_oid *encryption_type, const heim_oid *contentType, heim_octet_string *content)</td></tr>
33 <tr><td class="memItemLeft" nowrap align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__hx509__cms.html#gedaf18507474021a8d092ca6ac90a1ad">hx509_cms_verify_signed</a> (hx509_context context, hx509_verify_ctx ctx, unsigned int flags, const void *data, size_t length, const heim_octet_string *signedContent, hx509_certs pool, heim_oid *contentType, heim_octet_string *content, hx509_certs *signer_certs)</td></tr>
35 <tr><td class="memItemLeft" nowrap align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__hx509__cms.html#g8dfb6d8d72f6a71caffaf11b9d847921">hx509_cms_create_signed_1</a> (hx509_context context, int flags, const heim_oid *eContentType, const void *data, size_t length, const AlgorithmIdentifier *digest_alg, hx509_cert cert, hx509_peer_info peer, hx509_certs anchors, hx509_certs pool, heim_octet_string *signed_data)</td></tr>
38 <hr><a name="_details"></a><h2>Detailed Description</h2>
39 See the <a class="el" href="page_cms.html">CMS/PKCS7 message functions.</a> for description and examples. <hr><h2>Function Documentation</h2>
40 <a class="anchor" name="g8dfb6d8d72f6a71caffaf11b9d847921"></a><!-- doxytag: member="cms.c::hx509_cms_create_signed_1" ref="g8dfb6d8d72f6a71caffaf11b9d847921" args="(hx509_context context, int flags, const heim_oid *eContentType, const void *data, size_t length, const AlgorithmIdentifier *digest_alg, hx509_cert cert, hx509_peer_info peer, hx509_certs anchors, hx509_certs pool, heim_octet_string *signed_data)" -->
42 <div class="memproto">
43 <table class="memname">
45 <td class="memname">int hx509_cms_create_signed_1 </td>
47 <td class="paramtype">hx509_context </td>
48 <td class="paramname"> <em>context</em>, </td>
51 <td class="paramkey"></td>
53 <td class="paramtype">int </td>
54 <td class="paramname"> <em>flags</em>, </td>
57 <td class="paramkey"></td>
59 <td class="paramtype">const heim_oid * </td>
60 <td class="paramname"> <em>eContentType</em>, </td>
63 <td class="paramkey"></td>
65 <td class="paramtype">const void * </td>
66 <td class="paramname"> <em>data</em>, </td>
69 <td class="paramkey"></td>
71 <td class="paramtype">size_t </td>
72 <td class="paramname"> <em>length</em>, </td>
75 <td class="paramkey"></td>
77 <td class="paramtype">const AlgorithmIdentifier * </td>
78 <td class="paramname"> <em>digest_alg</em>, </td>
81 <td class="paramkey"></td>
83 <td class="paramtype">hx509_cert </td>
84 <td class="paramname"> <em>cert</em>, </td>
87 <td class="paramkey"></td>
89 <td class="paramtype">hx509_peer_info </td>
90 <td class="paramname"> <em>peer</em>, </td>
93 <td class="paramkey"></td>
95 <td class="paramtype">hx509_certs </td>
96 <td class="paramname"> <em>anchors</em>, </td>
99 <td class="paramkey"></td>
101 <td class="paramtype">hx509_certs </td>
102 <td class="paramname"> <em>pool</em>, </td>
105 <td class="paramkey"></td>
107 <td class="paramtype">heim_octet_string * </td>
108 <td class="paramname"> <em>signed_data</em></td><td> </td>
113 <td></td><td></td><td></td>
120 Decode SignedData and verify that the signature is correct.<p>
121 <dl compact><dt><b>Parameters:</b></dt><dd>
122 <table border="0" cellspacing="2" cellpadding="0">
123 <tr><td valign="top"></td><td valign="top"><em>context</em> </td><td>A hx509 context. </td></tr>
124 <tr><td valign="top"></td><td valign="top"><em>flags</em> </td><td></td></tr>
125 <tr><td valign="top"></td><td valign="top"><em>eContentType</em> </td><td>the type of the data. </td></tr>
126 <tr><td valign="top"></td><td valign="top"><em>data</em> </td><td>data to sign </td></tr>
127 <tr><td valign="top"></td><td valign="top"><em>length</em> </td><td>length of the data that data point to. </td></tr>
128 <tr><td valign="top"></td><td valign="top"><em>digest_alg</em> </td><td>digest algorithm to use, use NULL to get the default or the peer determined algorithm. </td></tr>
129 <tr><td valign="top"></td><td valign="top"><em>cert</em> </td><td>certificate to use for sign the data. </td></tr>
130 <tr><td valign="top"></td><td valign="top"><em>peer</em> </td><td>info about the peer the message to send the message to, like what digest algorithm to use. </td></tr>
131 <tr><td valign="top"></td><td valign="top"><em>anchors</em> </td><td>trust anchors that the client will use, used to polulate the certificates included in the message </td></tr>
132 <tr><td valign="top"></td><td valign="top"><em>pool</em> </td><td>certificates to use in try to build the path to the trust anchors. </td></tr>
133 <tr><td valign="top"></td><td valign="top"><em>signed_data</em> </td><td>the output of the function, free with der_free_octet_string(). </td></tr>
139 <a class="anchor" name="g618f32b35fa6f679cc5f32fb8abdbe85"></a><!-- doxytag: member="cms.c::hx509_cms_envelope_1" ref="g618f32b35fa6f679cc5f32fb8abdbe85" args="(hx509_context context, int flags, hx509_cert cert, const void *data, size_t length, const heim_oid *encryption_type, const heim_oid *contentType, heim_octet_string *content)" -->
140 <div class="memitem">
141 <div class="memproto">
142 <table class="memname">
144 <td class="memname">int hx509_cms_envelope_1 </td>
146 <td class="paramtype">hx509_context </td>
147 <td class="paramname"> <em>context</em>, </td>
150 <td class="paramkey"></td>
152 <td class="paramtype">int </td>
153 <td class="paramname"> <em>flags</em>, </td>
156 <td class="paramkey"></td>
158 <td class="paramtype">hx509_cert </td>
159 <td class="paramname"> <em>cert</em>, </td>
162 <td class="paramkey"></td>
164 <td class="paramtype">const void * </td>
165 <td class="paramname"> <em>data</em>, </td>
168 <td class="paramkey"></td>
170 <td class="paramtype">size_t </td>
171 <td class="paramname"> <em>length</em>, </td>
174 <td class="paramkey"></td>
176 <td class="paramtype">const heim_oid * </td>
177 <td class="paramname"> <em>encryption_type</em>, </td>
180 <td class="paramkey"></td>
182 <td class="paramtype">const heim_oid * </td>
183 <td class="paramname"> <em>contentType</em>, </td>
186 <td class="paramkey"></td>
188 <td class="paramtype">heim_octet_string * </td>
189 <td class="paramname"> <em>content</em></td><td> </td>
194 <td></td><td></td><td></td>
201 Encrypt end encode EnvelopedData.<p>
202 Encrypt and encode EnvelopedData. The data is encrypted with a random key and the the random key is encrypted with the certificates private key. This limits what private key type can be used to RSA.<p>
203 <dl compact><dt><b>Parameters:</b></dt><dd>
204 <table border="0" cellspacing="2" cellpadding="0">
205 <tr><td valign="top"></td><td valign="top"><em>context</em> </td><td>A hx509 context. </td></tr>
206 <tr><td valign="top"></td><td valign="top"><em>flags</em> </td><td>flags to control the behavior.<ul>
207 <li>HX509_CMS_EV_NO_KU_CHECK - Dont check KU on certificate</li><li>HX509_CMS_EV_ALLOW_WEAK - Allow weak crytpo</li><li>HX509_CMS_EV_ID_NAME - prefer issuer name and serial number </li></ul>
209 <tr><td valign="top"></td><td valign="top"><em>cert</em> </td><td>Certificate to encrypt the EnvelopedData encryption key with. </td></tr>
210 <tr><td valign="top"></td><td valign="top"><em>data</em> </td><td>pointer the data to encrypt. </td></tr>
211 <tr><td valign="top"></td><td valign="top"><em>length</em> </td><td>length of the data that data point to. </td></tr>
212 <tr><td valign="top"></td><td valign="top"><em>encryption_type</em> </td><td>Encryption cipher to use for the bulk data, use NULL to get default. </td></tr>
213 <tr><td valign="top"></td><td valign="top"><em>contentType</em> </td><td>type of the data that is encrypted </td></tr>
214 <tr><td valign="top"></td><td valign="top"><em>content</em> </td><td>the output of the function, free with der_free_octet_string(). </td></tr>
220 <a class="anchor" name="gb13d28bf986e3b66c05e7e33799be07b"></a><!-- doxytag: member="cms.c::hx509_cms_unenvelope" ref="gb13d28bf986e3b66c05e7e33799be07b" args="(hx509_context context, hx509_certs certs, int flags, const void *data, size_t length, const heim_octet_string *encryptedContent, time_t time_now, heim_oid *contentType, heim_octet_string *content)" -->
221 <div class="memitem">
222 <div class="memproto">
223 <table class="memname">
225 <td class="memname">int hx509_cms_unenvelope </td>
227 <td class="paramtype">hx509_context </td>
228 <td class="paramname"> <em>context</em>, </td>
231 <td class="paramkey"></td>
233 <td class="paramtype">hx509_certs </td>
234 <td class="paramname"> <em>certs</em>, </td>
237 <td class="paramkey"></td>
239 <td class="paramtype">int </td>
240 <td class="paramname"> <em>flags</em>, </td>
243 <td class="paramkey"></td>
245 <td class="paramtype">const void * </td>
246 <td class="paramname"> <em>data</em>, </td>
249 <td class="paramkey"></td>
251 <td class="paramtype">size_t </td>
252 <td class="paramname"> <em>length</em>, </td>
255 <td class="paramkey"></td>
257 <td class="paramtype">const heim_octet_string * </td>
258 <td class="paramname"> <em>encryptedContent</em>, </td>
261 <td class="paramkey"></td>
263 <td class="paramtype">time_t </td>
264 <td class="paramname"> <em>time_now</em>, </td>
267 <td class="paramkey"></td>
269 <td class="paramtype">heim_oid * </td>
270 <td class="paramname"> <em>contentType</em>, </td>
273 <td class="paramkey"></td>
275 <td class="paramtype">heim_octet_string * </td>
276 <td class="paramname"> <em>content</em></td><td> </td>
281 <td></td><td></td><td></td>
288 Decode and unencrypt EnvelopedData.<p>
289 Extract data and parameteres from from the EnvelopedData. Also supports using detached EnvelopedData.<p>
290 <dl compact><dt><b>Parameters:</b></dt><dd>
291 <table border="0" cellspacing="2" cellpadding="0">
292 <tr><td valign="top"></td><td valign="top"><em>context</em> </td><td>A hx509 context. </td></tr>
293 <tr><td valign="top"></td><td valign="top"><em>certs</em> </td><td>Certificate that can decrypt the EnvelopedData encryption key. </td></tr>
294 <tr><td valign="top"></td><td valign="top"><em>flags</em> </td><td>HX509_CMS_UE flags to control the behavior. </td></tr>
295 <tr><td valign="top"></td><td valign="top"><em>data</em> </td><td>pointer the structure the contains the DER/BER encoded EnvelopedData stucture. </td></tr>
296 <tr><td valign="top"></td><td valign="top"><em>length</em> </td><td>length of the data that data point to. </td></tr>
297 <tr><td valign="top"></td><td valign="top"><em>encryptedContent</em> </td><td>in case of detached signature, this contains the actual encrypted data, othersize its should be NULL. </td></tr>
298 <tr><td valign="top"></td><td valign="top"><em>time_now</em> </td><td>set the current time, if zero the library uses now as the date. </td></tr>
299 <tr><td valign="top"></td><td valign="top"><em>contentType</em> </td><td>output type oid, should be freed with der_free_oid(). </td></tr>
300 <tr><td valign="top"></td><td valign="top"><em>content</em> </td><td>the data, free with der_free_octet_string(). </td></tr>
306 <a class="anchor" name="gacbd636f3053c560782d83251f42b71a"></a><!-- doxytag: member="cms.c::hx509_cms_unwrap_ContentInfo" ref="gacbd636f3053c560782d83251f42b71a" args="(const heim_octet_string *in, heim_oid *oid, heim_octet_string *out, int *have_data)" -->
307 <div class="memitem">
308 <div class="memproto">
309 <table class="memname">
311 <td class="memname">int hx509_cms_unwrap_ContentInfo </td>
313 <td class="paramtype">const heim_octet_string * </td>
314 <td class="paramname"> <em>in</em>, </td>
317 <td class="paramkey"></td>
319 <td class="paramtype">heim_oid * </td>
320 <td class="paramname"> <em>oid</em>, </td>
323 <td class="paramkey"></td>
325 <td class="paramtype">heim_octet_string * </td>
326 <td class="paramname"> <em>out</em>, </td>
329 <td class="paramkey"></td>
331 <td class="paramtype">int * </td>
332 <td class="paramname"> <em>have_data</em></td><td> </td>
337 <td></td><td></td><td></td>
344 Decode an ContentInfo and unwrap data and oid it.<p>
345 <dl compact><dt><b>Parameters:</b></dt><dd>
346 <table border="0" cellspacing="2" cellpadding="0">
347 <tr><td valign="top"></td><td valign="top"><em>in</em> </td><td>the encoded buffer. </td></tr>
348 <tr><td valign="top"></td><td valign="top"><em>oid</em> </td><td>type of the content. </td></tr>
349 <tr><td valign="top"></td><td valign="top"><em>out</em> </td><td>data to be wrapped. </td></tr>
350 <tr><td valign="top"></td><td valign="top"><em>have_data</em> </td><td>since the data is optional, this flags show dthe diffrence between no data and the zero length data.</td></tr>
353 <dl class="return" compact><dt><b>Returns:</b></dt><dd>Returns an hx509 error code. </dd></dl>
357 <a class="anchor" name="gedaf18507474021a8d092ca6ac90a1ad"></a><!-- doxytag: member="cms.c::hx509_cms_verify_signed" ref="gedaf18507474021a8d092ca6ac90a1ad" args="(hx509_context context, hx509_verify_ctx ctx, unsigned int flags, const void *data, size_t length, const heim_octet_string *signedContent, hx509_certs pool, heim_oid *contentType, heim_octet_string *content, hx509_certs *signer_certs)" -->
358 <div class="memitem">
359 <div class="memproto">
360 <table class="memname">
362 <td class="memname">int hx509_cms_verify_signed </td>
364 <td class="paramtype">hx509_context </td>
365 <td class="paramname"> <em>context</em>, </td>
368 <td class="paramkey"></td>
370 <td class="paramtype">hx509_verify_ctx </td>
371 <td class="paramname"> <em>ctx</em>, </td>
374 <td class="paramkey"></td>
376 <td class="paramtype">unsigned int </td>
377 <td class="paramname"> <em>flags</em>, </td>
380 <td class="paramkey"></td>
382 <td class="paramtype">const void * </td>
383 <td class="paramname"> <em>data</em>, </td>
386 <td class="paramkey"></td>
388 <td class="paramtype">size_t </td>
389 <td class="paramname"> <em>length</em>, </td>
392 <td class="paramkey"></td>
394 <td class="paramtype">const heim_octet_string * </td>
395 <td class="paramname"> <em>signedContent</em>, </td>
398 <td class="paramkey"></td>
400 <td class="paramtype">hx509_certs </td>
401 <td class="paramname"> <em>pool</em>, </td>
404 <td class="paramkey"></td>
406 <td class="paramtype">heim_oid * </td>
407 <td class="paramname"> <em>contentType</em>, </td>
410 <td class="paramkey"></td>
412 <td class="paramtype">heim_octet_string * </td>
413 <td class="paramname"> <em>content</em>, </td>
416 <td class="paramkey"></td>
418 <td class="paramtype">hx509_certs * </td>
419 <td class="paramname"> <em>signer_certs</em></td><td> </td>
424 <td></td><td></td><td></td>
431 Decode SignedData and verify that the signature is correct.<p>
432 <dl compact><dt><b>Parameters:</b></dt><dd>
433 <table border="0" cellspacing="2" cellpadding="0">
434 <tr><td valign="top"></td><td valign="top"><em>context</em> </td><td>A hx509 context. </td></tr>
435 <tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>a hx509 verify context. </td></tr>
436 <tr><td valign="top"></td><td valign="top"><em>flags</em> </td><td>to control the behaivor of the function.<ul>
437 <li>HX509_CMS_VS_NO_KU_CHECK - Don't check KeyUsage</li><li>HX509_CMS_VS_ALLOW_DATA_OID_MISMATCH - allow oid mismatch</li><li>HX509_CMS_VS_ALLOW_ZERO_SIGNER - no signer, see below. </li></ul>
439 <tr><td valign="top"></td><td valign="top"><em>data</em> </td><td>pointer to CMS SignedData encoded data. </td></tr>
440 <tr><td valign="top"></td><td valign="top"><em>length</em> </td><td>length of the data that data point to. </td></tr>
441 <tr><td valign="top"></td><td valign="top"><em>signedContent</em> </td><td>external data used for signature. </td></tr>
442 <tr><td valign="top"></td><td valign="top"><em>pool</em> </td><td>certificate pool to build certificates paths. </td></tr>
443 <tr><td valign="top"></td><td valign="top"><em>contentType</em> </td><td>free with der_free_oid(). </td></tr>
444 <tr><td valign="top"></td><td valign="top"><em>content</em> </td><td>the output of the function, free with der_free_octet_string(). </td></tr>
445 <tr><td valign="top"></td><td valign="top"><em>signer_certs</em> </td><td>list of the cerficates used to sign this request, free with <a class="el" href="group__hx509__keyset.html#ga3df96cfe4137beaea7e7b87b95dbe3f">hx509_certs_free()</a>. </td></tr>
450 If HX509_CMS_VS_NO_KU_CHECK is set, allow more liberal search for matching certificates by not considering KeyUsage bits on the certificates.<p>
451 If HX509_CMS_VS_ALLOW_DATA_OID_MISMATCH, allow encapContentInfo mismatch with the oid in signedAttributes (or if no signedAttributes where use, pkcs7-data oid). This is only needed to work with broken CMS implementations that doesn't follow CMS signedAttributes rules.<p>
452 If HX509_CMS_VS_NO_VALIDATE flags is set, do not verify the signing certificates and leave that up to the caller.<p>
453 If HX509_CMS_VS_ALLOW_ZERO_SIGNER is set, allow empty SignerInfo (no signatures). If SignedData have no signatures, the function will return 0 with signer_certs set to NULL. Zero signers is allowed by the standard, but since its only useful in corner cases, it make into a flag that the caller have to turn on.
456 <a class="anchor" name="g59a1f6dc31e384a0d378c8179f2be9c3"></a><!-- doxytag: member="cms.c::hx509_cms_wrap_ContentInfo" ref="g59a1f6dc31e384a0d378c8179f2be9c3" args="(const heim_oid *oid, const heim_octet_string *buf, heim_octet_string *res)" -->
457 <div class="memitem">
458 <div class="memproto">
459 <table class="memname">
461 <td class="memname">int hx509_cms_wrap_ContentInfo </td>
463 <td class="paramtype">const heim_oid * </td>
464 <td class="paramname"> <em>oid</em>, </td>
467 <td class="paramkey"></td>
469 <td class="paramtype">const heim_octet_string * </td>
470 <td class="paramname"> <em>buf</em>, </td>
473 <td class="paramkey"></td>
475 <td class="paramtype">heim_octet_string * </td>
476 <td class="paramname"> <em>res</em></td><td> </td>
481 <td></td><td></td><td></td>
488 Wrap data and oid in a ContentInfo and encode it.<p>
489 <dl compact><dt><b>Parameters:</b></dt><dd>
490 <table border="0" cellspacing="2" cellpadding="0">
491 <tr><td valign="top"></td><td valign="top"><em>oid</em> </td><td>type of the content. </td></tr>
492 <tr><td valign="top"></td><td valign="top"><em>buf</em> </td><td>data to be wrapped. If a NULL pointer is passed in, the optional content field in the ContentInfo is not going be filled in. </td></tr>
493 <tr><td valign="top"></td><td valign="top"><em>res</em> </td><td>the encoded buffer, the result should be freed with der_free_octet_string().</td></tr>
496 <dl class="return" compact><dt><b>Returns:</b></dt><dd>Returns an hx509 error code. </dd></dl>
501 <hr size="1"><address style="text-align: right;"><small>
502 Generated on Wed Jan 11 14:07:40 2012 for Heimdalx509library by <a href="http://www.doxygen.org/index.html"><img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.6</small></address>