git Service of IN-Ulm e.V. Explore Help
Sign In
cbiedl
/
jose
1
0
Fork 0
Files
Tree: 96785d4df4
Branches Tags
jose
/
doc
/
doxygen
/
html
/
group__jose__jwe.html

group__jose__jwe.html 47 KB
History Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831 
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    2. 

  2. <html xmlns="http://www.w3.org/1999/xhtml">
    3. 

  3. <head>
    4. 

  4. <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
    5. 

  5. <meta http-equiv="X-UA-Compatible" content="IE=9"/>
    6. 

  6. <meta name="generator" content="Doxygen 1.8.13"/>
    7. 

  7. <meta name="viewport" content="width=device-width, initial-scale=1"/>
    8. 

  8. <title>José: JWE</title>
    9. 

  9. <link href="tabs.css" rel="stylesheet" type="text/css"/>
    10. 

  10. <script type="text/javascript" src="jquery.js"></script>
    11. 

  11. <script type="text/javascript" src="dynsections.js"></script>
    12. 

  12. <link href="search/search.css" rel="stylesheet" type="text/css"/>
    13. 

  13. <script type="text/javascript" src="search/searchdata.js"></script>
    14. 

  14. <script type="text/javascript" src="search/search.js"></script>
    15. 

  15. <link href="doxygen.css" rel="stylesheet" type="text/css" />
    16. 

  16. </head>
    17. 

  17. <body>
    18. 

  18. <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
    19. 

  19. <div id="titlearea">
    20. 

  20. <table cellspacing="0" cellpadding="0">
    21. 

  21.  <tbody>
    22. 

  22.  <tr style="height: 56px;">
    23. 

  23.   <td id="projectalign" style="padding-left: 0.5em;">
    24. 

  24.    <div id="projectname">José
    25. 

  25.    </div>
    26. 

  26.   </td>
    27. 

  27.  </tr>
    28. 

  28.  </tbody>
    29. 

  29. </table>
    30. 

  30. </div>
    31. 

  31. <!-- end header part -->
    32. 

  32. <!-- Generated by Doxygen 1.8.13 -->
    33. 

  33. <script type="text/javascript">
    34. 

  34. var searchBox = new SearchBox("searchBox", "search",false,'Search');
    35. 

  35. </script>
    36. 

  36. <script type="text/javascript" src="menudata.js"></script>
    37. 

  37. <script type="text/javascript" src="menu.js"></script>
    38. 

  38. <script type="text/javascript">
    39. 

  39. $(function() {
    40. 

  40.   initMenu('',true,false,'search.php','Search');
    41. 

  41.   $(document).ready(function() { init_search(); });
    42. 

  42. });
    43. 

  43. </script>
    44. 

  44. <div id="main-nav"></div>
    45. 

  45. </div><!-- top -->
    46. 

  46. <!-- window showing the filter options -->
    47. 

  47. <div id="MSearchSelectWindow"
    48. 

  48.      onmouseover="return searchBox.OnSearchSelectShow()"
    49. 

  49.      onmouseout="return searchBox.OnSearchSelectHide()"
    50. 

  50.      onkeydown="return searchBox.OnSearchSelectKey(event)">
    51. 

  51. </div>
    52. 

  52. 

  53. <!-- iframe showing the search results (closed by default) -->
    54. 

  54. <div id="MSearchResultsWindow">
    55. 

  55. <iframe src="javascript:void(0)" frameborder="0" 
    56. 

  56.         name="MSearchResults" id="MSearchResults">
    57. 

  57. </iframe>
    58. 

  58. </div>
    59. 

  59. 

  60. <div class="header">
    61. 

  61.   <div class="summary">
    62. 

  62. <a href="#func-members">Functions</a>  </div>
    63. 

  63.   <div class="headertitle">
    64. 

  64. <div class="title">JWE</div>  </div>
    65. 

  65. </div><!--header-->
    66. 

  66. <div class="contents">
    67. 

  67. 

  68. <p>JSON Web Encryption (RFC 7516)  
    69. 

  69. <a href="#details">More...</a></p>
    70. 

  70. <table class="memberdecls">
    71. 

  71. <tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
    72. 

  72. Functions</h2></td></tr>
    73. 

  73. <tr class="memitem:ga5920b450d6f4b0aa1729a7230a48fb32"><td class="memItemLeft" align="right" valign="top">json_t *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwe.html#ga5920b450d6f4b0aa1729a7230a48fb32">jose_jwe_hdr</a> (const json_t *jwe, const json_t *rcp)</td></tr>
    74. 

  74. <tr class="memdesc:ga5920b450d6f4b0aa1729a7230a48fb32"><td class="mdescLeft">&#160;</td><td class="mdescRight">Merges the JOSE headers of a JWE object and a JWE recpient object.  <a href="#ga5920b450d6f4b0aa1729a7230a48fb32">More...</a><br /></td></tr>
    75. 

  75. <tr class="separator:ga5920b450d6f4b0aa1729a7230a48fb32"><td class="memSeparator" colspan="2">&#160;</td></tr>
    76. 

  76. <tr class="memitem:ga67fd2b695bfff58a3b7adaf6bce9a773"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwe.html#ga67fd2b695bfff58a3b7adaf6bce9a773">jose_jwe_enc</a> (jose_cfg_t *cfg, json_t *jwe, json_t *rcp, const json_t *jwk, const void *pt, size_t ptl)</td></tr>
    77. 

  77. <tr class="memdesc:ga67fd2b695bfff58a3b7adaf6bce9a773"><td class="mdescLeft">&#160;</td><td class="mdescRight">Wraps and encrypts plaintext.  <a href="#ga67fd2b695bfff58a3b7adaf6bce9a773">More...</a><br /></td></tr>
    78. 

  78. <tr class="separator:ga67fd2b695bfff58a3b7adaf6bce9a773"><td class="memSeparator" colspan="2">&#160;</td></tr>
    79. 

  79. <tr class="memitem:ga27e44e2144dc81b778158163661b7f9f"><td class="memItemLeft" align="right" valign="top"><a class="el" href="structjose__io__t.html">jose_io_t</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwe.html#ga27e44e2144dc81b778158163661b7f9f">jose_jwe_enc_io</a> (jose_cfg_t *cfg, json_t *jwe, json_t *rcp, const json_t *jwk, <a class="el" href="structjose__io__t.html">jose_io_t</a> *next)</td></tr>
    80. 

  80. <tr class="memdesc:ga27e44e2144dc81b778158163661b7f9f"><td class="mdescLeft">&#160;</td><td class="mdescRight">Wraps and encrypts plaintext using streaming.  <a href="#ga27e44e2144dc81b778158163661b7f9f">More...</a><br /></td></tr>
    81. 

  81. <tr class="separator:ga27e44e2144dc81b778158163661b7f9f"><td class="memSeparator" colspan="2">&#160;</td></tr>
    82. 

  82. <tr class="memitem:ga6cebc627dea8bb944d35acb776abe769"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwe.html#ga6cebc627dea8bb944d35acb776abe769">jose_jwe_enc_jwk</a> (jose_cfg_t *cfg, json_t *jwe, json_t *rcp, const json_t *jwk, json_t *cek)</td></tr>
    83. 

  83. <tr class="memdesc:ga6cebc627dea8bb944d35acb776abe769"><td class="mdescLeft">&#160;</td><td class="mdescRight">Wraps a CEK with a JWK.  <a href="#ga6cebc627dea8bb944d35acb776abe769">More...</a><br /></td></tr>
    84. 

  84. <tr class="separator:ga6cebc627dea8bb944d35acb776abe769"><td class="memSeparator" colspan="2">&#160;</td></tr>
    85. 

  85. <tr class="memitem:ga885caaa8a0f24bcbdf283478b26b614d"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwe.html#ga885caaa8a0f24bcbdf283478b26b614d">jose_jwe_enc_cek</a> (jose_cfg_t *cfg, json_t *jwe, const json_t *cek, const void *pt, size_t ptl)</td></tr>
    86. 

  86. <tr class="memdesc:ga885caaa8a0f24bcbdf283478b26b614d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Encrypts plaintext with the CEK.  <a href="#ga885caaa8a0f24bcbdf283478b26b614d">More...</a><br /></td></tr>
    87. 

  87. <tr class="separator:ga885caaa8a0f24bcbdf283478b26b614d"><td class="memSeparator" colspan="2">&#160;</td></tr>
    88. 

  88. <tr class="memitem:gae484a56237a35f5c18038a1b24952f0a"><td class="memItemLeft" align="right" valign="top"><a class="el" href="structjose__io__t.html">jose_io_t</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwe.html#gae484a56237a35f5c18038a1b24952f0a">jose_jwe_enc_cek_io</a> (jose_cfg_t *cfg, json_t *jwe, const json_t *cek, <a class="el" href="structjose__io__t.html">jose_io_t</a> *next)</td></tr>
    89. 

  89. <tr class="memdesc:gae484a56237a35f5c18038a1b24952f0a"><td class="mdescLeft">&#160;</td><td class="mdescRight">Encrypts plaintext with the CEK using streaming.  <a href="#gae484a56237a35f5c18038a1b24952f0a">More...</a><br /></td></tr>
    90. 

  90. <tr class="separator:gae484a56237a35f5c18038a1b24952f0a"><td class="memSeparator" colspan="2">&#160;</td></tr>
    91. 

  91. <tr class="memitem:gac873b95e6fad75e2d517970a94346c5d"><td class="memItemLeft" align="right" valign="top">void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwe.html#gac873b95e6fad75e2d517970a94346c5d">jose_jwe_dec</a> (jose_cfg_t *cfg, const json_t *jwe, const json_t *rcp, const json_t *jwk, size_t *ptl)</td></tr>
    92. 

  92. <tr class="memdesc:gac873b95e6fad75e2d517970a94346c5d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Unwraps and decrypts ciphertext.  <a href="#gac873b95e6fad75e2d517970a94346c5d">More...</a><br /></td></tr>
    93. 

  93. <tr class="separator:gac873b95e6fad75e2d517970a94346c5d"><td class="memSeparator" colspan="2">&#160;</td></tr>
    94. 

  94. <tr class="memitem:gacd3c7703b57c524bc2683f2c0d0db4b8"><td class="memItemLeft" align="right" valign="top"><a class="el" href="structjose__io__t.html">jose_io_t</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwe.html#gacd3c7703b57c524bc2683f2c0d0db4b8">jose_jwe_dec_io</a> (jose_cfg_t *cfg, const json_t *jwe, const json_t *rcp, const json_t *jwk, <a class="el" href="structjose__io__t.html">jose_io_t</a> *next)</td></tr>
    95. 

  95. <tr class="memdesc:gacd3c7703b57c524bc2683f2c0d0db4b8"><td class="mdescLeft">&#160;</td><td class="mdescRight">Unwraps and decrypts ciphertext using streaming.  <a href="#gacd3c7703b57c524bc2683f2c0d0db4b8">More...</a><br /></td></tr>
    96. 

  96. <tr class="separator:gacd3c7703b57c524bc2683f2c0d0db4b8"><td class="memSeparator" colspan="2">&#160;</td></tr>
    97. 

  97. <tr class="memitem:gab9608cf23da17fadce6078aa2d862608"><td class="memItemLeft" align="right" valign="top">json_t *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwe.html#gab9608cf23da17fadce6078aa2d862608">jose_jwe_dec_jwk</a> (jose_cfg_t *cfg, const json_t *jwe, const json_t *rcp, const json_t *jwk)</td></tr>
    98. 

  98. <tr class="memdesc:gab9608cf23da17fadce6078aa2d862608"><td class="mdescLeft">&#160;</td><td class="mdescRight">Unwraps a CEK with a JWK.  <a href="#gab9608cf23da17fadce6078aa2d862608">More...</a><br /></td></tr>
    99. 

  99. <tr class="separator:gab9608cf23da17fadce6078aa2d862608"><td class="memSeparator" colspan="2">&#160;</td></tr>
    100. 

  100. <tr class="memitem:ga64b1b6074f8643aa301007fc125aed59"><td class="memItemLeft" align="right" valign="top">void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwe.html#ga64b1b6074f8643aa301007fc125aed59">jose_jwe_dec_cek</a> (jose_cfg_t *cfg, const json_t *jwe, const json_t *cek, size_t *ptl)</td></tr>
    101. 

  101. <tr class="memdesc:ga64b1b6074f8643aa301007fc125aed59"><td class="mdescLeft">&#160;</td><td class="mdescRight">Decrypts ciphertext with the CEK.  <a href="#ga64b1b6074f8643aa301007fc125aed59">More...</a><br /></td></tr>
    102. 

  102. <tr class="separator:ga64b1b6074f8643aa301007fc125aed59"><td class="memSeparator" colspan="2">&#160;</td></tr>
    103. 

  103. <tr class="memitem:gaf22bbcd02627f938be28fa4b1778e29c"><td class="memItemLeft" align="right" valign="top"><a class="el" href="structjose__io__t.html">jose_io_t</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwe.html#gaf22bbcd02627f938be28fa4b1778e29c">jose_jwe_dec_cek_io</a> (jose_cfg_t *cfg, const json_t *jwe, const json_t *cek, <a class="el" href="structjose__io__t.html">jose_io_t</a> *next)</td></tr>
    104. 

  104. <tr class="memdesc:gaf22bbcd02627f938be28fa4b1778e29c"><td class="mdescLeft">&#160;</td><td class="mdescRight">Decrypts ciphertext with the CEK using streaming.  <a href="#gaf22bbcd02627f938be28fa4b1778e29c">More...</a><br /></td></tr>
    105. 

  105. <tr class="separator:gaf22bbcd02627f938be28fa4b1778e29c"><td class="memSeparator" colspan="2">&#160;</td></tr>
    106. 

  106. </table>
    107. 

  107. <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
    108. 

  108. <p>JSON Web Encryption (RFC 7516) </p>
    109. 

  109. <p>A JSON Web Encryption (JWE) object contains (usually) two levels of encryption. First, the plaintext is encrypted with a random symmetric key. In José, we call this key the Content Encryption Key (CEK). Next, the CEK is wrapped (encrypted) with one or more keys. These keys are standard JSON Web Keys (JWK) and may be symmetric or asymmetric.</p>
    110. 

  110. <p>Thus there is (usually) one CEK and one or more JWKs. However, there are some exceptions to this rule. Two such examples are the algorithms: "dir" and "ECDH-ES". In the first case, the JWK is a symmetric key and is used directly as the CEK. In the second case, an ECDH key exchange is performed and the result is used directly as the CEK. But in general, the maxim holds.</p>
    111. 

  111. <p>This means that you can encrypt the data using one CEK and then encrypt the CEK to multiple recipients. With this schema, multiple recipients can each decrypt the data using their own key without having to send separate ciphertext to each recipient.</p>
    112. 

  112. <p>For maximum flexibility, José structures its API to take advantage of this schema. For example, when encrypting to two recipients, the code could look like this (error handling omitted): </p><pre class="fragment">json_t *enc(void *plaintext, size_t len, json_t *jwk0, json_t *jwk1) {
    113. 

  113.     json_auto_t *jwe = json_object();
    114. 

  114.     json_auto_t *cek = json_object();
    115. 

  115. 

  116.     // Wrap to the first recipient (CEK generated implicitly)
    117. 

  117.     jose_jwe_enc_jwk(NULL, jwe, NULL, jwk0, cek);
    118. 

  118. 

  119.     // Wrap to the second recipient
    120. 

  120.     jose_jwe_enc_jwk(NULL, jwe, NULL, jwk1, cek);
    121. 

  121. 

  122.     // Encrypt plaintext using the generated CEK
    123. 

  123.     jose_jwe_enc_cek(NULL, jwe, cek, plaintext, len);
    124. 

  124. 

  125.     return json_incref(jwe);
    126. 

  126. }
    127. 

  127. </pre><p>However, because José intends to be easy to use, we also provide shortcuts. For example, you could use a JWKSet which contains multiple JWKs: </p><pre class="fragment">json_t *enc(void *plaintext, size_t len, json_t *jwkset) {
    128. 

  128.     json_auto_t *jwe = json_object();
    129. 

  129. 

  130.     // Perform wrapping and encryption to all recipients
    131. 

  131.     jose_jwe_enc(NULL, jwe, NULL, jwkset, plaintext, len);
    132. 

  132. 

  133.     return json_incref(jwe);
    134. 

  134. }
    135. 

  135. </pre><p>Here are two tips to remember. First, let José generate your CEK implicitly. Second, always perform wrapping before encryption. Both of these tips are important because some wrapping algorithms may impose constraints on the generation of the CEK.</p>
    136. 

  136. <p>To decrypt a JWE, we just reverse the process. First, we use a JWK to unwrap the CEK. Then we use the CEK to decrypt the ciphertext. Here is how that might look in code (again, error handling omitted): </p><pre class="fragment">void *dec(json_t *jwe, json_t *jwk, size_t *len) {
    137. 

  137.     json_auto_t *cek = NULL;
    138. 

  138. 

  139.     // Unwrap the CEK using our JWK
    140. 

  140.     cek = jose_jwe_dec_jwk(NULL, jwe, NULL, jwk);
    141. 

  141. 

  142.     // Decrypt ciphertext using the CEK
    143. 

  143.     return jose_jwe_dec_cek(NULL, jwe, cek, len);
    144. 

  144. }
    145. 

  145. </pre><p>Or, again, in simplified form: </p><pre class="fragment">void *dec(json_t *jwe, json_t *jwk, size_t *len) {
    146. 

  146.     return jose_jwe_dec(NULL, jwe, NULL, jwk, len);
    147. 

  147. }
    148. 

  148. </pre><p>If you need to forward a JWE to a new recipient, you can do this without performing re-encryption. Just unwrap the CEK and then wrap the CEK again using a new JWK. For example: </p><pre class="fragment">void fwd(json_t *jwe, json_t *oldjwk, json_t *newjwk) {
    149. 

  149.     json_auto_t *cek = NULL;
    150. 

  150. 

  151.     // Unwrap the CEK using the old JWK
    152. 

  152.     cek = jose_jwe_dec_jwk(NULL, jwe, NULL, oldjwk);
    153. 

  153. 

  154.     // Wrap the CEK to the new JWK
    155. 

  155.     jose_jwe_enc_jwk(NULL, jwe, NULL, newjwk, cek);
    156. 

  156. }
    157. 

  157. </pre><p>In all the above examples, parameters like which encryption algorithms to use were inferred from our keys. Where such an inference cannot be made, sensible and secure defaults were chosen automatically. If you would like more control over the process, simply set parameters in the appropriate objects (more on this in the function documentation). For example, to enable plaintext compression, you can specify the <code>zip</code> property in the JWE Protected Header: </p><pre class="fragment">json_t *enc(void *plaintext, size_t len, json_t *jwkset) {
    158. 

  158.     json_auto_t *jwe = json_pack("{s:{s:s}}", "protected", "zip", "DEF");
    159. 

  159. 

  160.     // Perform compressed wrapping and encryption to all recipients
    161. 

  161.     jose_jwe_enc(NULL, jwe, NULL, jwkset, plaintext, len);
    162. 

  162. 

  163.     return json_incref(jwe);
    164. 

  164. }
    165. 

  165. </pre><p>José currently supports the "alg", "enc" and "zip" header parameters, as well as any algorithm-specific header parameters used by the specific algorithms we implement. Other header parameters may be specified, but do not effect the behavior of José's JWE implementation.</p>
    166. 

  166. <dl class="section see"><dt>See also</dt><dd><a href="https://tools.ietf.org/html/rfc7516">https://tools.ietf.org/html/rfc7516</a> </dd></dl>
    167. 

  167. <h2 class="groupheader">Function Documentation</h2>
    168. 

  168. <a id="ga5920b450d6f4b0aa1729a7230a48fb32"></a>
    169. 

  169. <h2 class="memtitle"><span class="permalink"><a href="#ga5920b450d6f4b0aa1729a7230a48fb32">&#9670;&nbsp;</a></span>jose_jwe_hdr()</h2>
    170. 

  170. 

  171. <div class="memitem">
    172. 

  172. <div class="memproto">
    173. 

  173.       <table class="memname">
    174. 

  174.         <tr>
    175. 

  175.           <td class="memname">json_t* jose_jwe_hdr </td>
    176. 

  176.           <td>(</td>
    177. 

  177.           <td class="paramtype">const json_t *&#160;</td>
    178. 

  178.           <td class="paramname"><em>jwe</em>, </td>
    179. 

  179.         </tr>
    180. 

  180.         <tr>
    181. 

  181.           <td class="paramkey"></td>
    182. 

  182.           <td></td>
    183. 

  183.           <td class="paramtype">const json_t *&#160;</td>
    184. 

  184.           <td class="paramname"><em>rcp</em>&#160;</td>
    185. 

  185.         </tr>
    186. 

  186.         <tr>
    187. 

  187.           <td></td>
    188. 

  188.           <td>)</td>
    189. 

  189.           <td></td><td></td>
    190. 

  190.         </tr>
    191. 

  191.       </table>
    192. 

  192. </div><div class="memdoc">
    193. 

  193. 

  194. <p>Merges the JOSE headers of a JWE object and a JWE recpient object. </p>
    195. 

  195. <dl class="params"><dt>Parameters</dt><dd>
    196. 

  196.   <table class="params">
    197. 

  197.     <tr><td class="paramname">jwe</td><td>A JWE object. </td></tr>
    198. 

  198.     <tr><td class="paramname">rcp</td><td>A JWE recipient object. </td></tr>
    199. 

  199.   </table>
    200. 

  200.   </dd>
    201. 

  201. </dl>
    202. 

  202. <dl class="section return"><dt>Returns</dt><dd>The newly allocated JOSE header. </dd></dl>
    203. 

  203. 

  204. </div>
    205. 

  205. </div>
    206. 

  206. <a id="ga67fd2b695bfff58a3b7adaf6bce9a773"></a>
    207. 

  207. <h2 class="memtitle"><span class="permalink"><a href="#ga67fd2b695bfff58a3b7adaf6bce9a773">&#9670;&nbsp;</a></span>jose_jwe_enc()</h2>
    208. 

  208. 

  209. <div class="memitem">
    210. 

  210. <div class="memproto">
    211. 

  211.       <table class="memname">
    212. 

  212.         <tr>
    213. 

  213.           <td class="memname">bool jose_jwe_enc </td>
    214. 

  214.           <td>(</td>
    215. 

  215.           <td class="paramtype">jose_cfg_t *&#160;</td>
    216. 

  216.           <td class="paramname"><em>cfg</em>, </td>
    217. 

  217.         </tr>
    218. 

  218.         <tr>
    219. 

  219.           <td class="paramkey"></td>
    220. 

  220.           <td></td>
    221. 

  221.           <td class="paramtype">json_t *&#160;</td>
    222. 

  222.           <td class="paramname"><em>jwe</em>, </td>
    223. 

  223.         </tr>
    224. 

  224.         <tr>
    225. 

  225.           <td class="paramkey"></td>
    226. 

  226.           <td></td>
    227. 

  227.           <td class="paramtype">json_t *&#160;</td>
    228. 

  228.           <td class="paramname"><em>rcp</em>, </td>
    229. 

  229.         </tr>
    230. 

  230.         <tr>
    231. 

  231.           <td class="paramkey"></td>
    232. 

  232.           <td></td>
    233. 

  233.           <td class="paramtype">const json_t *&#160;</td>
    234. 

  234.           <td class="paramname"><em>jwk</em>, </td>
    235. 

  235.         </tr>
    236. 

  236.         <tr>
    237. 

  237.           <td class="paramkey"></td>
    238. 

  238.           <td></td>
    239. 

  239.           <td class="paramtype">const void *&#160;</td>
    240. 

  240.           <td class="paramname"><em>pt</em>, </td>
    241. 

  241.         </tr>
    242. 

  242.         <tr>
    243. 

  243.           <td class="paramkey"></td>
    244. 

  244.           <td></td>
    245. 

  245.           <td class="paramtype">size_t&#160;</td>
    246. 

  246.           <td class="paramname"><em>ptl</em>&#160;</td>
    247. 

  247.         </tr>
    248. 

  248.         <tr>
    249. 

  249.           <td></td>
    250. 

  250.           <td>)</td>
    251. 

  251.           <td></td><td></td>
    252. 

  252.         </tr>
    253. 

  253.       </table>
    254. 

  254. </div><div class="memdoc">
    255. 

  255. 

  256. <p>Wraps and encrypts plaintext. </p>
    257. 

  257. <p>This function is a thin wrapper around the <a class="el" href="group__jose__jwe.html#ga27e44e2144dc81b778158163661b7f9f" title="Wraps and encrypts plaintext using streaming. ">jose_jwe_enc_io()</a> function allowing the user to specify the plaintext in a single call. The ciphertext output will be appended to the JWE as the "ciphertext" property.</p>
    258. 

  258. <dl class="section see"><dt>See also</dt><dd><a class="el" href="group__jose__jwe.html#gae484a56237a35f5c18038a1b24952f0a" title="Encrypts plaintext with the CEK using streaming. ">jose_jwe_enc_cek_io()</a> </dd></dl>
    259. 

  259. <dl class="params"><dt>Parameters</dt><dd>
    260. 

  260.   <table class="params">
    261. 

  261.     <tr><td class="paramname">cfg</td><td>The configuration context (optional). </td></tr>
    262. 

  262.     <tr><td class="paramname">jwe</td><td>The JWE object. </td></tr>
    263. 

  263.     <tr><td class="paramname">rcp</td><td>The JWE recipient object(s) or NULL. </td></tr>
    264. 

  264.     <tr><td class="paramname">jwk</td><td>The JWK(s) or JWKSet used for wrapping. </td></tr>
    265. 

  265.     <tr><td class="paramname">pt</td><td>The plaintext. </td></tr>
    266. 

  266.     <tr><td class="paramname">ptl</td><td>The length of the plaintext. </td></tr>
    267. 

  267.   </table>
    268. 

  268.   </dd>
    269. 

  269. </dl>
    270. 

  270. <dl class="section return"><dt>Returns</dt><dd>On success, true. Otherwise, false. </dd></dl>
    271. 

  271. 

  272. </div>
    273. 

  273. </div>
    274. 

  274. <a id="ga27e44e2144dc81b778158163661b7f9f"></a>
    275. 

  275. <h2 class="memtitle"><span class="permalink"><a href="#ga27e44e2144dc81b778158163661b7f9f">&#9670;&nbsp;</a></span>jose_jwe_enc_io()</h2>
    276. 

  276. 

  277. <div class="memitem">
    278. 

  278. <div class="memproto">
    279. 

  279.       <table class="memname">
    280. 

  280.         <tr>
    281. 

  281.           <td class="memname"><a class="el" href="structjose__io__t.html">jose_io_t</a>* jose_jwe_enc_io </td>
    282. 

  282.           <td>(</td>
    283. 

  283.           <td class="paramtype">jose_cfg_t *&#160;</td>
    284. 

  284.           <td class="paramname"><em>cfg</em>, </td>
    285. 

  285.         </tr>
    286. 

  286.         <tr>
    287. 

  287.           <td class="paramkey"></td>
    288. 

  288.           <td></td>
    289. 

  289.           <td class="paramtype">json_t *&#160;</td>
    290. 

  290.           <td class="paramname"><em>jwe</em>, </td>
    291. 

  291.         </tr>
    292. 

  292.         <tr>
    293. 

  293.           <td class="paramkey"></td>
    294. 

  294.           <td></td>
    295. 

  295.           <td class="paramtype">json_t *&#160;</td>
    296. 

  296.           <td class="paramname"><em>rcp</em>, </td>
    297. 

  297.         </tr>
    298. 

  298.         <tr>
    299. 

  299.           <td class="paramkey"></td>
    300. 

  300.           <td></td>
    301. 

  301.           <td class="paramtype">const json_t *&#160;</td>
    302. 

  302.           <td class="paramname"><em>jwk</em>, </td>
    303. 

  303.         </tr>
    304. 

  304.         <tr>
    305. 

  305.           <td class="paramkey"></td>
    306. 

  306.           <td></td>
    307. 

  307.           <td class="paramtype"><a class="el" href="structjose__io__t.html">jose_io_t</a> *&#160;</td>
    308. 

  308.           <td class="paramname"><em>next</em>&#160;</td>
    309. 

  309.         </tr>
    310. 

  310.         <tr>
    311. 

  311.           <td></td>
    312. 

  312.           <td>)</td>
    313. 

  313.           <td></td><td></td>
    314. 

  314.         </tr>
    315. 

  315.       </table>
    316. 

  316. </div><div class="memdoc">
    317. 

  317. 

  318. <p>Wraps and encrypts plaintext using streaming. </p>
    319. 

  319. <p>This function is a thin wrapper around the <a class="el" href="group__jose__jwe.html#ga6cebc627dea8bb944d35acb776abe769" title="Wraps a CEK with a JWK. ">jose_jwe_enc_jwk()</a> and <a class="el" href="group__jose__jwe.html#gae484a56237a35f5c18038a1b24952f0a" title="Encrypts plaintext with the CEK using streaming. ">jose_jwe_enc_cek_io()</a> functions, removing the complexity of managing the CEK.</p>
    320. 

  320. <dl class="section see"><dt>See also</dt><dd><a class="el" href="group__jose__jwe.html#ga6cebc627dea8bb944d35acb776abe769" title="Wraps a CEK with a JWK. ">jose_jwe_enc_jwk()</a> </dd>
    321. 

  321. <dd>
    322. 

  322. <a class="el" href="group__jose__jwe.html#gae484a56237a35f5c18038a1b24952f0a" title="Encrypts plaintext with the CEK using streaming. ">jose_jwe_enc_cek_io()</a> </dd></dl>
    323. 

  323. <dl class="params"><dt>Parameters</dt><dd>
    324. 

  324.   <table class="params">
    325. 

  325.     <tr><td class="paramname">cfg</td><td>The configuration context (optional). </td></tr>
    326. 

  326.     <tr><td class="paramname">jwe</td><td>The JWE object. </td></tr>
    327. 

  327.     <tr><td class="paramname">rcp</td><td>The JWE recipient object(s) or NULL. </td></tr>
    328. 

  328.     <tr><td class="paramname">jwk</td><td>The JWK(s) or JWKSet used for wrapping. </td></tr>
    329. 

  329.     <tr><td class="paramname">next</td><td>The next IO object in the chain. </td></tr>
    330. 

  330.   </table>
    331. 

  331.   </dd>
    332. 

  332. </dl>
    333. 

  333. <dl class="section return"><dt>Returns</dt><dd>The new IO object or NULL on error. </dd></dl>
    334. 

  334. 

  335. </div>
    336. 

  336. </div>
    337. 

  337. <a id="ga6cebc627dea8bb944d35acb776abe769"></a>
    338. 

  338. <h2 class="memtitle"><span class="permalink"><a href="#ga6cebc627dea8bb944d35acb776abe769">&#9670;&nbsp;</a></span>jose_jwe_enc_jwk()</h2>
    339. 

  339. 

  340. <div class="memitem">
    341. 

  341. <div class="memproto">
    342. 

  342.       <table class="memname">
    343. 

  343.         <tr>
    344. 

  344.           <td class="memname">bool jose_jwe_enc_jwk </td>
    345. 

  345.           <td>(</td>
    346. 

  346.           <td class="paramtype">jose_cfg_t *&#160;</td>
    347. 

  347.           <td class="paramname"><em>cfg</em>, </td>
    348. 

  348.         </tr>
    349. 

  349.         <tr>
    350. 

  350.           <td class="paramkey"></td>
    351. 

  351.           <td></td>
    352. 

  352.           <td class="paramtype">json_t *&#160;</td>
    353. 

  353.           <td class="paramname"><em>jwe</em>, </td>
    354. 

  354.         </tr>
    355. 

  355.         <tr>
    356. 

  356.           <td class="paramkey"></td>
    357. 

  357.           <td></td>
    358. 

  358.           <td class="paramtype">json_t *&#160;</td>
    359. 

  359.           <td class="paramname"><em>rcp</em>, </td>
    360. 

  360.         </tr>
    361. 

  361.         <tr>
    362. 

  362.           <td class="paramkey"></td>
    363. 

  363.           <td></td>
    364. 

  364.           <td class="paramtype">const json_t *&#160;</td>
    365. 

  365.           <td class="paramname"><em>jwk</em>, </td>
    366. 

  366.         </tr>
    367. 

  367.         <tr>
    368. 

  368.           <td class="paramkey"></td>
    369. 

  369.           <td></td>
    370. 

  370.           <td class="paramtype">json_t *&#160;</td>
    371. 

  371.           <td class="paramname"><em>cek</em>&#160;</td>
    372. 

  372.         </tr>
    373. 

  373.         <tr>
    374. 

  374.           <td></td>
    375. 

  375.           <td>)</td>
    376. 

  376.           <td></td><td></td>
    377. 

  377.         </tr>
    378. 

  378.       </table>
    379. 

  379. </div><div class="memdoc">
    380. 

  380. 

  381. <p>Wraps a CEK with a JWK. </p>
    382. 

  382. <p>The purpose of this function is to wrap (encrypt) or, in some cases, produce the CEK (<code>cek</code>) from the provided JWK(s) (<code>jwk</code>). This function can be used in two modes: single-JWK and multi-JWK.</p>
    383. 

  383. <p>In single-JWK mode, the <code>jwk</code> parameter contains a JWK object and the <code>rcp</code> parameter must contain either a JWE recipient object or NULL, in which case a default empty JWE recipient object is created internally.</p>
    384. 

  384. <p>Multi-JWK mode works exactly the same as single-JWK mode except that it performs multiple wrappings in a single call. This mode is enabled by passing either an array of JWK objects or a JWKSet as the <code>jwk</code> parameter. In this mode, the <code>rcp</code> parameter contains one of the following values:</p>
    385. 

  385. <ol type="1">
    386. 

  386. <li>A JWE recipient object that will be used for all wrappings. In this case, a copy will be made for each wrapping and <code>rcp</code> will not be modified in any way.</li>
    387. 

  387. <li>An array of JWE recipient objects. Each object will be used with its corresponding JWK from <code>jwk</code>. If the arrays in <code>sig</code> and <code>jwk</code> are a different size, an error will occur.</li>
    388. 

  388. <li>NULL. This has the same effect as passing NULL for each separate JWK.</li>
    389. 

  389. </ol>
    390. 

  390. <p>In either mode, if the resulting JWE (<code>jwe</code>) would contain only a single recipient, the JWE will be represented in Flattened JWE JSON Serialization Syntax. Otherwise, it will be represented in General JWE JSON Serialization Syntax.</p>
    391. 

  391. <p>If the "alg" parameter is not specified in the JOSE Header, it will be inferred from the JWK and the chosen algorithm will be added to the JWE Per-Recipient Unprotected Header. Likewise, any missing, required, algorithm-specific parameters will be either inferred or sensible, secure defaults will be chosen and the results will be added to the JWE Per-Recipient Unprotected Header.</p>
    392. 

  392. <p>If the provided CEK (<code>cek</code>) does not contain key material, it will be implicitly generated during the first call to <a class="el" href="group__jose__jwe.html#ga6cebc627dea8bb944d35acb776abe769" title="Wraps a CEK with a JWK. ">jose_jwe_enc_jwk()</a>. This important feature enables the use of the "dir" and "ECDH-ES" algorithms. In the case of the "dir" algorithm, the JWK is the CEK and thus the key material is copied from <code>jwk</code> to <code>cek</code>. A similar situation arises with the algorithm "ECDH-ES" where the result of a key exchange is used as the CEK; thus, the CEK is produced during the wrapping process. This feature implies that if multiple wrappings are created, only one of them may have the algorithm "ECDH-ES" and it must be the first wrapping. Attempting to use "ECDH-ES" with an existing CEK will result in an error.</p>
    393. 

  393. <p>It is additionally possible to pass a password JSON string as key input to the PBES2 family of algorithms anywhere a JWK can be used. Likewise, if the "alg" JOSE Header parameter is not specified and a JSON string is used in place of a JWK, the PBES2 family of algorithms will be inferred.</p>
    394. 

  394. <dl class="params"><dt>Parameters</dt><dd>
    395. 

  395.   <table class="params">
    396. 

  396.     <tr><td class="paramname">cfg</td><td>The configuration context (optional). </td></tr>
    397. 

  397.     <tr><td class="paramname">jwe</td><td>The JWE object. </td></tr>
    398. 

  398.     <tr><td class="paramname">rcp</td><td>The JWE recipient object(s) or NULL. </td></tr>
    399. 

  399.     <tr><td class="paramname">jwk</td><td>The JWK(s) or JWKSet used for wrapping. </td></tr>
    400. 

  400.     <tr><td class="paramname">cek</td><td>The CEK to wrap (if empty, generated). </td></tr>
    401. 

  401.   </table>
    402. 

  402.   </dd>
    403. 

  403. </dl>
    404. 

  404. <dl class="section return"><dt>Returns</dt><dd>On success, true. Otherwise, false. </dd></dl>
    405. 

  405. 

  406. </div>
    407. 

  407. </div>
    408. 

  408. <a id="ga885caaa8a0f24bcbdf283478b26b614d"></a>
    409. 

  409. <h2 class="memtitle"><span class="permalink"><a href="#ga885caaa8a0f24bcbdf283478b26b614d">&#9670;&nbsp;</a></span>jose_jwe_enc_cek()</h2>
    410. 

  410. 

  411. <div class="memitem">
    412. 

  412. <div class="memproto">
    413. 

  413.       <table class="memname">
    414. 

  414.         <tr>
    415. 

  415.           <td class="memname">bool jose_jwe_enc_cek </td>
    416. 

  416.           <td>(</td>
    417. 

  417.           <td class="paramtype">jose_cfg_t *&#160;</td>
    418. 

  418.           <td class="paramname"><em>cfg</em>, </td>
    419. 

  419.         </tr>
    420. 

  420.         <tr>
    421. 

  421.           <td class="paramkey"></td>
    422. 

  422.           <td></td>
    423. 

  423.           <td class="paramtype">json_t *&#160;</td>
    424. 

  424.           <td class="paramname"><em>jwe</em>, </td>
    425. 

  425.         </tr>
    426. 

  426.         <tr>
    427. 

  427.           <td class="paramkey"></td>
    428. 

  428.           <td></td>
    429. 

  429.           <td class="paramtype">const json_t *&#160;</td>
    430. 

  430.           <td class="paramname"><em>cek</em>, </td>
    431. 

  431.         </tr>
    432. 

  432.         <tr>
    433. 

  433.           <td class="paramkey"></td>
    434. 

  434.           <td></td>
    435. 

  435.           <td class="paramtype">const void *&#160;</td>
    436. 

  436.           <td class="paramname"><em>pt</em>, </td>
    437. 

  437.         </tr>
    438. 

  438.         <tr>
    439. 

  439.           <td class="paramkey"></td>
    440. 

  440.           <td></td>
    441. 

  441.           <td class="paramtype">size_t&#160;</td>
    442. 

  442.           <td class="paramname"><em>ptl</em>&#160;</td>
    443. 

  443.         </tr>
    444. 

  444.         <tr>
    445. 

  445.           <td></td>
    446. 

  446.           <td>)</td>
    447. 

  447.           <td></td><td></td>
    448. 

  448.         </tr>
    449. 

  449.       </table>
    450. 

  450. </div><div class="memdoc">
    451. 

  451. 

  452. <p>Encrypts plaintext with the CEK. </p>
    453. 

  453. <p>This function is a thin wrapper around the <a class="el" href="group__jose__jwe.html#gae484a56237a35f5c18038a1b24952f0a" title="Encrypts plaintext with the CEK using streaming. ">jose_jwe_enc_cek_io()</a> function allowing the user to specify the plaintext in a single call. The ciphertext output will be appended to the JWE as the "ciphertext" property.</p>
    454. 

  454. <dl class="section see"><dt>See also</dt><dd><a class="el" href="group__jose__jwe.html#gae484a56237a35f5c18038a1b24952f0a" title="Encrypts plaintext with the CEK using streaming. ">jose_jwe_enc_cek_io()</a> </dd></dl>
    455. 

  455. <dl class="params"><dt>Parameters</dt><dd>
    456. 

  456.   <table class="params">
    457. 

  457.     <tr><td class="paramname">cfg</td><td>The configuration context (optional). </td></tr>
    458. 

  458.     <tr><td class="paramname">jwe</td><td>The JWE object. </td></tr>
    459. 

  459.     <tr><td class="paramname">cek</td><td>The CEK object. </td></tr>
    460. 

  460.     <tr><td class="paramname">pt</td><td>The plaintext. </td></tr>
    461. 

  461.     <tr><td class="paramname">ptl</td><td>The length of the plaintext. </td></tr>
    462. 

  462.   </table>
    463. 

  463.   </dd>
    464. 

  464. </dl>
    465. 

  465. <dl class="section return"><dt>Returns</dt><dd>On success, true. Otherwise, false. </dd></dl>
    466. 

  466. 

  467. </div>
    468. 

  468. </div>
    469. 

  469. <a id="gae484a56237a35f5c18038a1b24952f0a"></a>
    470. 

  470. <h2 class="memtitle"><span class="permalink"><a href="#gae484a56237a35f5c18038a1b24952f0a">&#9670;&nbsp;</a></span>jose_jwe_enc_cek_io()</h2>
    471. 

  471. 

  472. <div class="memitem">
    473. 

  473. <div class="memproto">
    474. 

  474.       <table class="memname">
    475. 

  475.         <tr>
    476. 

  476.           <td class="memname"><a class="el" href="structjose__io__t.html">jose_io_t</a>* jose_jwe_enc_cek_io </td>
    477. 

  477.           <td>(</td>
    478. 

  478.           <td class="paramtype">jose_cfg_t *&#160;</td>
    479. 

  479.           <td class="paramname"><em>cfg</em>, </td>
    480. 

  480.         </tr>
    481. 

  481.         <tr>
    482. 

  482.           <td class="paramkey"></td>
    483. 

  483.           <td></td>
    484. 

  484.           <td class="paramtype">json_t *&#160;</td>
    485. 

  485.           <td class="paramname"><em>jwe</em>, </td>
    486. 

  486.         </tr>
    487. 

  487.         <tr>
    488. 

  488.           <td class="paramkey"></td>
    489. 

  489.           <td></td>
    490. 

  490.           <td class="paramtype">const json_t *&#160;</td>
    491. 

  491.           <td class="paramname"><em>cek</em>, </td>
    492. 

  492.         </tr>
    493. 

  493.         <tr>
    494. 

  494.           <td class="paramkey"></td>
    495. 

  495.           <td></td>
    496. 

  496.           <td class="paramtype"><a class="el" href="structjose__io__t.html">jose_io_t</a> *&#160;</td>
    497. 

  497.           <td class="paramname"><em>next</em>&#160;</td>
    498. 

  498.         </tr>
    499. 

  499.         <tr>
    500. 

  500.           <td></td>
    501. 

  501.           <td>)</td>
    502. 

  502.           <td></td><td></td>
    503. 

  503.         </tr>
    504. 

  504.       </table>
    505. 

  505. </div><div class="memdoc">
    506. 

  506. 

  507. <p>Encrypts plaintext with the CEK using streaming. </p>
    508. 

  508. <p>The plaintext is provided through the returned IO object. The plaintext will be encrypted and written to the <code>next</code> IO object. This IO object works on binary data, so you may need to use a URL-safe Base64 decoder on input and a URL-safe Base64 encoder on output, depending on your situation.</p>
    509. 

  509. <p>Compressed plaintext can be implicitly enabled by specifying the "zip" parameter the JWE Protected Header.</p>
    510. 

  510. <p>If the JWE Protected Header is a JSON object rather than an encoded string, this function will encode the JWE Protected Header to its URL-safe Base64 encoding as defined in RFC 7516. However, this function will never modify a JWE Protected Header that is already encoded.</p>
    511. 

  511. <p>If the "enc" parameter is not specified in the JWE Protected Header or the JWE Shared Unprotected Header, it will be inferred from the CEK and stored in either the JWE Protected Header or the JWE Shared Unprotected Header (preferring the JWE Protected header if it can be modified).</p>
    512. 

  512. <p>Please note that the "tag" property will only be added to the JWE when <a class="el" href="structjose__io__t.html#a76d1eac0d05d3604c16686b08bd80aa0">jose_io_t::done()</a> returns.</p>
    513. 

  513. <dl class="params"><dt>Parameters</dt><dd>
    514. 

  514.   <table class="params">
    515. 

  515.     <tr><td class="paramname">cfg</td><td>The configuration context (optional). </td></tr>
    516. 

  516.     <tr><td class="paramname">jwe</td><td>The JWE object. </td></tr>
    517. 

  517.     <tr><td class="paramname">cek</td><td>The CEK object. </td></tr>
    518. 

  518.     <tr><td class="paramname">next</td><td>The next IO object in the chain. </td></tr>
    519. 

  519.   </table>
    520. 

  520.   </dd>
    521. 

  521. </dl>
    522. 

  522. <dl class="section return"><dt>Returns</dt><dd>The new IO object or NULL on error. </dd></dl>
    523. 

  523. 

  524. </div>
    525. 

  525. </div>
    526. 

  526. <a id="gac873b95e6fad75e2d517970a94346c5d"></a>
    527. 

  527. <h2 class="memtitle"><span class="permalink"><a href="#gac873b95e6fad75e2d517970a94346c5d">&#9670;&nbsp;</a></span>jose_jwe_dec()</h2>
    528. 

  528. 

  529. <div class="memitem">
    530. 

  530. <div class="memproto">
    531. 

  531.       <table class="memname">
    532. 

  532.         <tr>
    533. 

  533.           <td class="memname">void* jose_jwe_dec </td>
    534. 

  534.           <td>(</td>
    535. 

  535.           <td class="paramtype">jose_cfg_t *&#160;</td>
    536. 

  536.           <td class="paramname"><em>cfg</em>, </td>
    537. 

  537.         </tr>
    538. 

  538.         <tr>
    539. 

  539.           <td class="paramkey"></td>
    540. 

  540.           <td></td>
    541. 

  541.           <td class="paramtype">const json_t *&#160;</td>
    542. 

  542.           <td class="paramname"><em>jwe</em>, </td>
    543. 

  543.         </tr>
    544. 

  544.         <tr>
    545. 

  545.           <td class="paramkey"></td>
    546. 

  546.           <td></td>
    547. 

  547.           <td class="paramtype">const json_t *&#160;</td>
    548. 

  548.           <td class="paramname"><em>rcp</em>, </td>
    549. 

  549.         </tr>
    550. 

  550.         <tr>
    551. 

  551.           <td class="paramkey"></td>
    552. 

  552.           <td></td>
    553. 

  553.           <td class="paramtype">const json_t *&#160;</td>
    554. 

  554.           <td class="paramname"><em>jwk</em>, </td>
    555. 

  555.         </tr>
    556. 

  556.         <tr>
    557. 

  557.           <td class="paramkey"></td>
    558. 

  558.           <td></td>
    559. 

  559.           <td class="paramtype">size_t *&#160;</td>
    560. 

  560.           <td class="paramname"><em>ptl</em>&#160;</td>
    561. 

  561.         </tr>
    562. 

  562.         <tr>
    563. 

  563.           <td></td>
    564. 

  564.           <td>)</td>
    565. 

  565.           <td></td><td></td>
    566. 

  566.         </tr>
    567. 

  567.       </table>
    568. 

  568. </div><div class="memdoc">
    569. 

  569. 

  570. <p>Unwraps and decrypts ciphertext. </p>
    571. 

  571. <p>This function is a thin wrapper around the <a class="el" href="group__jose__jwe.html#gacd3c7703b57c524bc2683f2c0d0db4b8" title="Unwraps and decrypts ciphertext using streaming. ">jose_jwe_dec_io()</a> function allowing the user to obtain the plaintext in a single call. The ciphertext input will be obtained from the JWE "ciphertext" property.</p>
    572. 

  572. <dl class="section see"><dt>See also</dt><dd><a class="el" href="group__jose__jwe.html#gacd3c7703b57c524bc2683f2c0d0db4b8" title="Unwraps and decrypts ciphertext using streaming. ">jose_jwe_dec_io()</a> </dd></dl>
    573. 

  573. <dl class="params"><dt>Parameters</dt><dd>
    574. 

  574.   <table class="params">
    575. 

  575.     <tr><td class="paramname">cfg</td><td>The configuration context (optional). </td></tr>
    576. 

  576.     <tr><td class="paramname">jwe</td><td>The JWE object. </td></tr>
    577. 

  577.     <tr><td class="paramname">rcp</td><td>The JWE recipient object(s) or NULL. </td></tr>
    578. 

  578.     <tr><td class="paramname">jwk</td><td>The JWK(s) or JWKSet used for wrapping. </td></tr>
    579. 

  579.     <tr><td class="paramname">ptl</td><td>The length of the plaintext (output). </td></tr>
    580. 

  580.   </table>
    581. 

  581.   </dd>
    582. 

  582. </dl>
    583. 

  583. <dl class="section return"><dt>Returns</dt><dd>The newly-allocated plaintext. </dd></dl>
    584. 

  584. 

  585. </div>
    586. 

  586. </div>
    587. 

  587. <a id="gacd3c7703b57c524bc2683f2c0d0db4b8"></a>
    588. 

  588. <h2 class="memtitle"><span class="permalink"><a href="#gacd3c7703b57c524bc2683f2c0d0db4b8">&#9670;&nbsp;</a></span>jose_jwe_dec_io()</h2>
    589. 

  589. 

  590. <div class="memitem">
    591. 

  591. <div class="memproto">
    592. 

  592.       <table class="memname">
    593. 

  593.         <tr>
    594. 

  594.           <td class="memname"><a class="el" href="structjose__io__t.html">jose_io_t</a>* jose_jwe_dec_io </td>
    595. 

  595.           <td>(</td>
    596. 

  596.           <td class="paramtype">jose_cfg_t *&#160;</td>
    597. 

  597.           <td class="paramname"><em>cfg</em>, </td>
    598. 

  598.         </tr>
    599. 

  599.         <tr>
    600. 

  600.           <td class="paramkey"></td>
    601. 

  601.           <td></td>
    602. 

  602.           <td class="paramtype">const json_t *&#160;</td>
    603. 

  603.           <td class="paramname"><em>jwe</em>, </td>
    604. 

  604.         </tr>
    605. 

  605.         <tr>
    606. 

  606.           <td class="paramkey"></td>
    607. 

  607.           <td></td>
    608. 

  608.           <td class="paramtype">const json_t *&#160;</td>
    609. 

  609.           <td class="paramname"><em>rcp</em>, </td>
    610. 

  610.         </tr>
    611. 

  611.         <tr>
    612. 

  612.           <td class="paramkey"></td>
    613. 

  613.           <td></td>
    614. 

  614.           <td class="paramtype">const json_t *&#160;</td>
    615. 

  615.           <td class="paramname"><em>jwk</em>, </td>
    616. 

  616.         </tr>
    617. 

  617.         <tr>
    618. 

  618.           <td class="paramkey"></td>
    619. 

  619.           <td></td>
    620. 

  620.           <td class="paramtype"><a class="el" href="structjose__io__t.html">jose_io_t</a> *&#160;</td>
    621. 

  621.           <td class="paramname"><em>next</em>&#160;</td>
    622. 

  622.         </tr>
    623. 

  623.         <tr>
    624. 

  624.           <td></td>
    625. 

  625.           <td>)</td>
    626. 

  626.           <td></td><td></td>
    627. 

  627.         </tr>
    628. 

  628.       </table>
    629. 

  629. </div><div class="memdoc">
    630. 

  630. 

  631. <p>Unwraps and decrypts ciphertext using streaming. </p>
    632. 

  632. <p>This function is a thin wrapper around the <a class="el" href="group__jose__jwe.html#gab9608cf23da17fadce6078aa2d862608" title="Unwraps a CEK with a JWK. ">jose_jwe_dec_jwk()</a> and <a class="el" href="group__jose__jwe.html#gaf22bbcd02627f938be28fa4b1778e29c" title="Decrypts ciphertext with the CEK using streaming. ">jose_jwe_dec_cek_io()</a> functions, removing the complexity of managing the CEK.</p>
    633. 

  633. <dl class="section see"><dt>See also</dt><dd><a class="el" href="group__jose__jwe.html#gab9608cf23da17fadce6078aa2d862608" title="Unwraps a CEK with a JWK. ">jose_jwe_dec_jwk()</a> </dd>
    634. 

  634. <dd>
    635. 

  635. <a class="el" href="group__jose__jwe.html#gaf22bbcd02627f938be28fa4b1778e29c" title="Decrypts ciphertext with the CEK using streaming. ">jose_jwe_dec_cek_io()</a> </dd></dl>
    636. 

  636. <dl class="params"><dt>Parameters</dt><dd>
    637. 

  637.   <table class="params">
    638. 

  638.     <tr><td class="paramname">cfg</td><td>The configuration context (optional). </td></tr>
    639. 

  639.     <tr><td class="paramname">jwe</td><td>The JWE object. </td></tr>
    640. 

  640.     <tr><td class="paramname">rcp</td><td>The JWE recipient object(s) or NULL. </td></tr>
    641. 

  641.     <tr><td class="paramname">jwk</td><td>The JWK(s) or JWKSet used for unwrapping. </td></tr>
    642. 

  642.     <tr><td class="paramname">next</td><td>The next IO object in the chain. </td></tr>
    643. 

  643.   </table>
    644. 

  644.   </dd>
    645. 

  645. </dl>
    646. 

  646. <dl class="section return"><dt>Returns</dt><dd>The new IO object or NULL on error. </dd></dl>
    647. 

  647. 

  648. </div>
    649. 

  649. </div>
    650. 

  650. <a id="gab9608cf23da17fadce6078aa2d862608"></a>
    651. 

  651. <h2 class="memtitle"><span class="permalink"><a href="#gab9608cf23da17fadce6078aa2d862608">&#9670;&nbsp;</a></span>jose_jwe_dec_jwk()</h2>
    652. 

  652. 

  653. <div class="memitem">
    654. 

  654. <div class="memproto">
    655. 

  655.       <table class="memname">
    656. 

  656.         <tr>
    657. 

  657.           <td class="memname">json_t* jose_jwe_dec_jwk </td>
    658. 

  658.           <td>(</td>
    659. 

  659.           <td class="paramtype">jose_cfg_t *&#160;</td>
    660. 

  660.           <td class="paramname"><em>cfg</em>, </td>
    661. 

  661.         </tr>
    662. 

  662.         <tr>
    663. 

  663.           <td class="paramkey"></td>
    664. 

  664.           <td></td>
    665. 

  665.           <td class="paramtype">const json_t *&#160;</td>
    666. 

  666.           <td class="paramname"><em>jwe</em>, </td>
    667. 

  667.         </tr>
    668. 

  668.         <tr>
    669. 

  669.           <td class="paramkey"></td>
    670. 

  670.           <td></td>
    671. 

  671.           <td class="paramtype">const json_t *&#160;</td>
    672. 

  672.           <td class="paramname"><em>rcp</em>, </td>
    673. 

  673.         </tr>
    674. 

  674.         <tr>
    675. 

  675.           <td class="paramkey"></td>
    676. 

  676.           <td></td>
    677. 

  677.           <td class="paramtype">const json_t *&#160;</td>
    678. 

  678.           <td class="paramname"><em>jwk</em>&#160;</td>
    679. 

  679.         </tr>
    680. 

  680.         <tr>
    681. 

  681.           <td></td>
    682. 

  682.           <td>)</td>
    683. 

  683.           <td></td><td></td>
    684. 

  684.         </tr>
    685. 

  685.       </table>
    686. 

  686. </div><div class="memdoc">
    687. 

  687. 

  688. <p>Unwraps a CEK with a JWK. </p>
    689. 

  689. <p>The purpose of this function is to unwrap (decrypt) or, in some cases, produce the CEK (<code>cek</code>) from the provided JWK(s) (<code>jwk</code>). This function can be used in two modes: single-JWK and multi-JWK.</p>
    690. 

  690. <p>In single-JWK mode, the <code>jwk</code> parameter contains a JWK object and the <code>rcp</code> parameter must contain either a JWE recipient object you wish to unwrap or NULL, in which case all JWE recipients will be tried.</p>
    691. 

  691. <p>Multi-JWK mode works exactly the same as single-JWK mode except that it attempts to unwrap with multiple JWKs in a single call. This mode is enabled by passing either an array of JWK objects or a JWKSet as the <code>jwk</code> parameter. In this mode, the <code>rcp</code> parameter contains one of the following values:</p>
    692. 

  692. <ol type="1">
    693. 

  693. <li>A JWE recipient object that will be used for all attempted unwrappings.</li>
    694. 

  694. <li>An array of JWE recipient objects. Each object will be used with its corresponding JWK from <code>jwk</code>. If the arrays in <code>sig</code> and <code>jwk</code> are a different size, an error will occur.</li>
    695. 

  695. <li>NULL. This has the same effect as passing NULL for each separate JWK.</li>
    696. 

  696. </ol>
    697. 

  697. <p>In either mode, a CEK is returned for the first JWK that successfully unwraps a CEK. Two exceptions to this rule are if the "dir" or "ECDH-ES" algorithms are used. In this case, a CEK may be returned which will fail during decryption since there is no way to completely validate the JWK with these algorithms. Thus, we suggest placing the keys for these algorithms last when unwrapping with multiple JWKs.</p>
    698. 

  698. <p>If the "alg" parameter is not specified in the JOSE Header, it will be inferred from the JWK. This includes using a JSON string in place of a JWK for the PBES2 family of algorithms.</p>
    699. 

  699. <dl class="params"><dt>Parameters</dt><dd>
    700. 

  700.   <table class="params">
    701. 

  701.     <tr><td class="paramname">cfg</td><td>The configuration context (optional). </td></tr>
    702. 

  702.     <tr><td class="paramname">jwe</td><td>The JWE object. </td></tr>
    703. 

  703.     <tr><td class="paramname">rcp</td><td>The JWE recipient object(s) or NULL. </td></tr>
    704. 

  704.     <tr><td class="paramname">jwk</td><td>The JWK(s) or JWKSet used for wrapping. </td></tr>
    705. 

  705.   </table>
    706. 

  706.   </dd>
    707. 

  707. </dl>
    708. 

  708. <dl class="section return"><dt>Returns</dt><dd>On success, a newly-allocated CEK object. Otherwise, NULL. </dd></dl>
    709. 

  709. 

  710. </div>
    711. 

  711. </div>
    712. 

  712. <a id="ga64b1b6074f8643aa301007fc125aed59"></a>
    713. 

  713. <h2 class="memtitle"><span class="permalink"><a href="#ga64b1b6074f8643aa301007fc125aed59">&#9670;&nbsp;</a></span>jose_jwe_dec_cek()</h2>
    714. 

  714. 

  715. <div class="memitem">
    716. 

  716. <div class="memproto">
    717. 

  717.       <table class="memname">
    718. 

  718.         <tr>
    719. 

  719.           <td class="memname">void* jose_jwe_dec_cek </td>
    720. 

  720.           <td>(</td>
    721. 

  721.           <td class="paramtype">jose_cfg_t *&#160;</td>
    722. 

  722.           <td class="paramname"><em>cfg</em>, </td>
    723. 

  723.         </tr>
    724. 

  724.         <tr>
    725. 

  725.           <td class="paramkey"></td>
    726. 

  726.           <td></td>
    727. 

  727.           <td class="paramtype">const json_t *&#160;</td>
    728. 

  728.           <td class="paramname"><em>jwe</em>, </td>
    729. 

  729.         </tr>
    730. 

  730.         <tr>
    731. 

  731.           <td class="paramkey"></td>
    732. 

  732.           <td></td>
    733. 

  733.           <td class="paramtype">const json_t *&#160;</td>
    734. 

  734.           <td class="paramname"><em>cek</em>, </td>
    735. 

  735.         </tr>
    736. 

  736.         <tr>
    737. 

  737.           <td class="paramkey"></td>
    738. 

  738.           <td></td>
    739. 

  739.           <td class="paramtype">size_t *&#160;</td>
    740. 

  740.           <td class="paramname"><em>ptl</em>&#160;</td>
    741. 

  741.         </tr>
    742. 

  742.         <tr>
    743. 

  743.           <td></td>
    744. 

  744.           <td>)</td>
    745. 

  745.           <td></td><td></td>
    746. 

  746.         </tr>
    747. 

  747.       </table>
    748. 

  748. </div><div class="memdoc">
    749. 

  749. 

  750. <p>Decrypts ciphertext with the CEK. </p>
    751. 

  751. <p>This function is a thin wrapper around the <a class="el" href="group__jose__jwe.html#gaf22bbcd02627f938be28fa4b1778e29c" title="Decrypts ciphertext with the CEK using streaming. ">jose_jwe_dec_cek_io()</a> function allowing the user to obtain the plaintext in a single call. The ciphertext input will be obtained from the JWE "ciphertext" property.</p>
    752. 

  752. <dl class="section see"><dt>See also</dt><dd><a class="el" href="group__jose__jwe.html#gaf22bbcd02627f938be28fa4b1778e29c" title="Decrypts ciphertext with the CEK using streaming. ">jose_jwe_dec_cek_io()</a> </dd></dl>
    753. 

  753. <dl class="params"><dt>Parameters</dt><dd>
    754. 

  754.   <table class="params">
    755. 

  755.     <tr><td class="paramname">cfg</td><td>The configuration context (optional). </td></tr>
    756. 

  756.     <tr><td class="paramname">jwe</td><td>The JWE object. </td></tr>
    757. 

  757.     <tr><td class="paramname">cek</td><td>The CEK object. </td></tr>
    758. 

  758.     <tr><td class="paramname">ptl</td><td>The length of the plaintext (output). </td></tr>
    759. 

  759.   </table>
    760. 

  760.   </dd>
    761. 

  761. </dl>
    762. 

  762. <dl class="section return"><dt>Returns</dt><dd>The newly-allocated plaintext. </dd></dl>
    763. 

  763. 

  764. </div>
    765. 

  765. </div>
    766. 

  766. <a id="gaf22bbcd02627f938be28fa4b1778e29c"></a>
    767. 

  767. <h2 class="memtitle"><span class="permalink"><a href="#gaf22bbcd02627f938be28fa4b1778e29c">&#9670;&nbsp;</a></span>jose_jwe_dec_cek_io()</h2>
    768. 

  768. 

  769. <div class="memitem">
    770. 

  770. <div class="memproto">
    771. 

  771.       <table class="memname">
    772. 

  772.         <tr>
    773. 

  773.           <td class="memname"><a class="el" href="structjose__io__t.html">jose_io_t</a>* jose_jwe_dec_cek_io </td>
    774. 

  774.           <td>(</td>
    775. 

  775.           <td class="paramtype">jose_cfg_t *&#160;</td>
    776. 

  776.           <td class="paramname"><em>cfg</em>, </td>
    777. 

  777.         </tr>
    778. 

  778.         <tr>
    779. 

  779.           <td class="paramkey"></td>
    780. 

  780.           <td></td>
    781. 

  781.           <td class="paramtype">const json_t *&#160;</td>
    782. 

  782.           <td class="paramname"><em>jwe</em>, </td>
    783. 

  783.         </tr>
    784. 

  784.         <tr>
    785. 

  785.           <td class="paramkey"></td>
    786. 

  786.           <td></td>
    787. 

  787.           <td class="paramtype">const json_t *&#160;</td>
    788. 

  788.           <td class="paramname"><em>cek</em>, </td>
    789. 

  789.         </tr>
    790. 

  790.         <tr>
    791. 

  791.           <td class="paramkey"></td>
    792. 

  792.           <td></td>
    793. 

  793.           <td class="paramtype"><a class="el" href="structjose__io__t.html">jose_io_t</a> *&#160;</td>
    794. 

  794.           <td class="paramname"><em>next</em>&#160;</td>
    795. 

  795.         </tr>
    796. 

  796.         <tr>
    797. 

  797.           <td></td>
    798. 

  798.           <td>)</td>
    799. 

  799.           <td></td><td></td>
    800. 

  800.         </tr>
    801. 

  801.       </table>
    802. 

  802. </div><div class="memdoc">
    803. 

  803. 

  804. <p>Decrypts ciphertext with the CEK using streaming. </p>
    805. 

  805. <p>The ciphertext is provided through the returned IO object. The ciphertext will be decrypted and written to the <code>next</code> IO object. This IO object works on binary data, so you may need to use a URL-safe Base64 decoder on input and a URL-safe Base64 encoder on output, depending on your situation.</p>
    806. 

  806. <p>Please note that validation of the ciphertext integrity protection is delayed until <a class="el" href="structjose__io__t.html#a76d1eac0d05d3604c16686b08bd80aa0">jose_io_t::done()</a> returns. This means it is incredibly important to check this return value and it is also important to be careful with the plaintext emitted until this check is performed.</p>
    807. 

  807. <p>Compressed plaintext will be internally decompressed if the "zip" property is appropriately defined.</p>
    808. 

  808. <p>If the "enc" parameter is not specified in the JWE Protected Header or the JWE Shared Unprotected Header, it will be inferred from the CEK.</p>
    809. 

  809. <p>Please note that the "tag" property on the JWE will only be accessed when <a class="el" href="structjose__io__t.html#a76d1eac0d05d3604c16686b08bd80aa0">jose_io_t::done()</a> is called. So you may define it at any time on the JWE object before calling <a class="el" href="structjose__io__t.html#a76d1eac0d05d3604c16686b08bd80aa0">jose_io_t::done()</a>.</p>
    810. 

  810. <dl class="params"><dt>Parameters</dt><dd>
    811. 

  811.   <table class="params">
    812. 

  812.     <tr><td class="paramname">cfg</td><td>The configuration context (optional). </td></tr>
    813. 

  813.     <tr><td class="paramname">jwe</td><td>The JWE object. </td></tr>
    814. 

  814.     <tr><td class="paramname">cek</td><td>The CEK object. </td></tr>
    815. 

  815.     <tr><td class="paramname">next</td><td>The next IO object in the chain. </td></tr>
    816. 

  816.   </table>
    817. 

  817.   </dd>
    818. 

  818. </dl>
    819. 

  819. <dl class="section return"><dt>Returns</dt><dd>The new IO object or NULL on error. </dd></dl>
    820. 

  820. 

  821. </div>
    822. 

  822. </div>
    823. 

  823. </div><!-- contents -->
    824. 

  824. <!-- start footer part -->
    825. 

  825. <hr class="footer"/><address class="footer"><small>
    826. 

  826. Generated by &#160;<a href="http://www.doxygen.org/index.html">
    827. 

  827. <img class="footer" src="doxygen.png" alt="doxygen"/>
    828. 

  828. </a> 1.8.13
    829. 

  829. </small></address>
    830. 

  830. </body>
    831. 

  831. </html>
    832.