cbiedl
/
jose


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395
							<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>José: JWS</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">José
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#func-members">Functions</a>  </div>
  <div class="headertitle">
<div class="title">JWS</div>  </div>
</div><!--header-->
<div class="contents">

<p>JSON Web Signature (RFC 7515)  
<a href="#details">More...</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga25b7bfa0fc1293dbe349d2870479f80a"><td class="memItemLeft" align="right" valign="top">json_t *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jws.html#ga25b7bfa0fc1293dbe349d2870479f80a">jose_jws_hdr</a> (const json_t *sig)</td></tr>
<tr class="memdesc:ga25b7bfa0fc1293dbe349d2870479f80a"><td class="mdescLeft">&#160;</td><td class="mdescRight">Merges the JOSE headers of a JWS signature object.  <a href="#ga25b7bfa0fc1293dbe349d2870479f80a">More...</a><br /></td></tr>
<tr class="separator:ga25b7bfa0fc1293dbe349d2870479f80a"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga562d39b9b1d0ba321f9246e4d4c3b350"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jws.html#ga562d39b9b1d0ba321f9246e4d4c3b350">jose_jws_sig</a> (jose_cfg_t *cfg, json_t *jws, json_t *sig, const json_t *jwk)</td></tr>
<tr class="memdesc:ga562d39b9b1d0ba321f9246e4d4c3b350"><td class="mdescLeft">&#160;</td><td class="mdescRight">Creates one or more signatures in a JWS object.  <a href="#ga562d39b9b1d0ba321f9246e4d4c3b350">More...</a><br /></td></tr>
<tr class="separator:ga562d39b9b1d0ba321f9246e4d4c3b350"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga73152ceaf852dd2d897154fb250a7860"><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__jws.html#ga73152ceaf852dd2d897154fb250a7860">jose_jws_sig_io</a> (jose_cfg_t *cfg, json_t *jws, json_t *sig, const json_t *jwk)</td></tr>
<tr class="memdesc:ga73152ceaf852dd2d897154fb250a7860"><td class="mdescLeft">&#160;</td><td class="mdescRight">Creates one or more signatures in a JWS object using streaming.  <a href="#ga73152ceaf852dd2d897154fb250a7860">More...</a><br /></td></tr>
<tr class="separator:ga73152ceaf852dd2d897154fb250a7860"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga89a18c4b4d7cd0f9d42224ef5698abe7"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jws.html#ga89a18c4b4d7cd0f9d42224ef5698abe7">jose_jws_ver</a> (jose_cfg_t *cfg, const json_t *jws, const json_t *sig, const json_t *jwk, bool all)</td></tr>
<tr class="memdesc:ga89a18c4b4d7cd0f9d42224ef5698abe7"><td class="mdescLeft">&#160;</td><td class="mdescRight">Verifies signatures of one or more JWKs in a JWS object.  <a href="#ga89a18c4b4d7cd0f9d42224ef5698abe7">More...</a><br /></td></tr>
<tr class="separator:ga89a18c4b4d7cd0f9d42224ef5698abe7"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga35a5d3c37101fc127933f3c856b46cc8"><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__jws.html#ga35a5d3c37101fc127933f3c856b46cc8">jose_jws_ver_io</a> (jose_cfg_t *cfg, const json_t *jws, const json_t *sig, const json_t *jwk, bool all)</td></tr>
<tr class="memdesc:ga35a5d3c37101fc127933f3c856b46cc8"><td class="mdescLeft">&#160;</td><td class="mdescRight">Verifies signatures of one or more JWKs in a JWS object using streaming.  <a href="#ga35a5d3c37101fc127933f3c856b46cc8">More...</a><br /></td></tr>
<tr class="separator:ga35a5d3c37101fc127933f3c856b46cc8"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>JSON Web Signature (RFC 7515) </p>
<p>JSON Web Token (RFC 7519)</p>
<p>A JSON Web Signature (JWS) is a standard data format for expresing cryptographic signatures in JSON. The signatures are produced using a JSON Web Key (JWK).</p>
<p>For example, to create a simple signature of a string using a JWK (error handling omitted): </p><pre class="fragment">json_t *sig(const char *str, const json_t *jwk) {
    json_auto_t *jws = json_pack("{s:o}", "payload",
                                 jose_b64_enc(str, strlen(str)));
    jose_jws_sig(NULL, jws, NULL, jwk);
    return json_incref(jws);
}
</pre><p>Likewise, to verify this signature (again, error handling omitted): </p><pre class="fragment">char *ver(const json_t *jwe, const json_t *jwk) {
    char *str = NULL;
    size_t len = 0;

    if (!jose_jws_ver(NULL, jws, NULL, jwk))
        return NULL;

    len = jose_b64_dec(json_object_get(jwe, "payload"), NULL, 0);
    str = calloc(1, len + 1);
    jose_b64_dec(json_object_get(jwe, "payload"), str, len);
    return str;
}
</pre><dl class="section see"><dt>See also</dt><dd><a href="https://tools.ietf.org/html/rfc7515">https://tools.ietf.org/html/rfc7515</a></dd></dl>
<p>A JSON Web Token (JWT) is a standard data format for expresing claims transferred between to parties in JSON. The JWT is wrapped in any number of Signatures (JWS) or Encryptions (JWE).</p>
<dl class="section see"><dt>See also</dt><dd><a href="https://tools.ietf.org/html/rfc7515">https://tools.ietf.org/html/rfc7515</a> </dd></dl>
<h2 class="groupheader">Function Documentation</h2>
<a id="ga25b7bfa0fc1293dbe349d2870479f80a"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga25b7bfa0fc1293dbe349d2870479f80a">&#9670;&nbsp;</a></span>jose_jws_hdr()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">json_t* jose_jws_hdr </td>
          <td>(</td>
          <td class="paramtype">const json_t *&#160;</td>
          <td class="paramname"><em>sig</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Merges the JOSE headers of a JWS signature object. </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">sig</td><td>A JWS signature object. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>The newly allocated JOSE header. </dd></dl>

</div>
</div>
<a id="ga562d39b9b1d0ba321f9246e4d4c3b350"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga562d39b9b1d0ba321f9246e4d4c3b350">&#9670;&nbsp;</a></span>jose_jws_sig()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">bool jose_jws_sig </td>
          <td>(</td>
          <td class="paramtype">jose_cfg_t *&#160;</td>
          <td class="paramname"><em>cfg</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">json_t *&#160;</td>
          <td class="paramname"><em>jws</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">json_t *&#160;</td>
          <td class="paramname"><em>sig</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const json_t *&#160;</td>
          <td class="paramname"><em>jwk</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Creates one or more signatures in a JWS object. </p>
<p>The JWS object (<code>jws</code>) must contain the "payload" property.</p>
<p>All signatures created will be appended to the JWS specified by <code>jws</code>. If the resulting JWS (<code>jws</code>) would contain only a single signature, the JWS will be represented in Flattened JWS JSON Serialization Syntax. Otherwise, it will be represented in General JWS JSON Serialization Syntax.</p>
<p>If <code>jwk</code> contains a JWK, a single signature is created. In this case, <code>jws</code> must contain either a JWS signature object template or NULL. You may specify algorithms or other signature behaviors simply by specifying them in the JOSE headers of the JWS signature object template as defined by RFC 7515. If a required property is missing, sensible defaults will be used and inserted into the JOSE headers; inferring them from the JWK (<code>jwk</code>) where possible.</p>
<p>If <code>jwk</code> contains an array of JWKs or a JWKSet, multiple signatures are created. In this case, the <code>sig</code> parameter must contain one of the following values:</p>
<ol type="1">
<li>A JWS signature object template that will be used for all signatures. In this case, a copy will be made for each signature and <code>sig</code> will not be modified in any way.</li>
<li>An array of JWS signature object templates. Each template 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>
<li>NULL. This has the same effect as passing NULL for each separate key.</li>
</ol>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">cfg</td><td>The configuration context (optional). </td></tr>
    <tr><td class="paramname">jws</td><td>The JWS object. </td></tr>
    <tr><td class="paramname">sig</td><td>The JWS signature object template(s) or NULL. </td></tr>
    <tr><td class="paramname">jwk</td><td>The JWK(s) or JWKSet used for creating signatures. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>On success, true. Otherwise, false. </dd></dl>

</div>
</div>
<a id="ga73152ceaf852dd2d897154fb250a7860"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga73152ceaf852dd2d897154fb250a7860">&#9670;&nbsp;</a></span>jose_jws_sig_io()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="structjose__io__t.html">jose_io_t</a>* jose_jws_sig_io </td>
          <td>(</td>
          <td class="paramtype">jose_cfg_t *&#160;</td>
          <td class="paramname"><em>cfg</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">json_t *&#160;</td>
          <td class="paramname"><em>jws</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">json_t *&#160;</td>
          <td class="paramname"><em>sig</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const json_t *&#160;</td>
          <td class="paramname"><em>jwk</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Creates one or more signatures in a JWS object using streaming. </p>
<p>This function behaves substantially like <a class="el" href="group__jose__jws.html#ga562d39b9b1d0ba321f9246e4d4c3b350" title="Creates one or more signatures in a JWS object. ">jose_jws_sig()</a> except:</p>
<p>The payload is not specified in the JWS (<code>jws</code>). Rather, the payload is provided using the returned IO object. The input to the returned IO object will not be internally Base64 encoded. So you may need to prepend the IO chain with the result of <a class="el" href="group__jose__b64.html#gad72c180de43c9da3456bdb0d166092ff" title="Creates a new IO object which performs URL-safe Base64 encoding. ">jose_b64_enc_io()</a> (depending on your situation).</p>
<p>Likewise, the payload is not stored in the JWS object (<code>jws</code>). This allows for detached payloads and decreases memory use for signatures over large payloads. If you would like to attach the payload, it is your responsibility to do so manually.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">cfg</td><td>The configuration context (optional). </td></tr>
    <tr><td class="paramname">jws</td><td>The JWS object. </td></tr>
    <tr><td class="paramname">sig</td><td>The JWS signature object template(s) or NULL. </td></tr>
    <tr><td class="paramname">jwk</td><td>The JWK(s) or JWKSet used for creating signatures. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>The new IO object or NULL on error. </dd></dl>

</div>
</div>
<a id="ga89a18c4b4d7cd0f9d42224ef5698abe7"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga89a18c4b4d7cd0f9d42224ef5698abe7">&#9670;&nbsp;</a></span>jose_jws_ver()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">bool jose_jws_ver </td>
          <td>(</td>
          <td class="paramtype">jose_cfg_t *&#160;</td>
          <td class="paramname"><em>cfg</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const json_t *&#160;</td>
          <td class="paramname"><em>jws</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const json_t *&#160;</td>
          <td class="paramname"><em>sig</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const json_t *&#160;</td>
          <td class="paramname"><em>jwk</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">bool&#160;</td>
          <td class="paramname"><em>all</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Verifies signatures of one or more JWKs in a JWS object. </p>
<p>The JWS object (<code>jws</code>) must contain the "payload" property.</p>
<p>If a single JWK (<code>jwk</code>) is specified, the <code>all</code> parameter is ignored. In this case, if you would like to verify a particular JWS signature object, you may specify it using the <code>sig</code> parameter. Otherwise, you may simply pass NULL to verify any of the JWS signature objects in the JWS object.</p>
<p>If <code>jwk</code> contains an array of JWKs or a JWKSet, the <code>all</code> parameter determines whether a valid signature is required for every JWK in order to successfully validate the JWS. For example, if you set <code>all</code> to false this function will succeed if a valid signature is found for any of the provided JWKs. When using this multiple JWK signature mode, the <code>sig</code> parameter must contain one of the following values:</p>
<ol type="1">
<li>A single JWS signature object to validate against all/any of the provided JWKs.</li>
<li>An array of JWS signature objects. In this case, each JWS signature object will be mapped to 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>
<li>NULL. This has the same effect as passing NULL for each separate key.</li>
</ol>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">cfg</td><td>The configuration context (optional). </td></tr>
    <tr><td class="paramname">jws</td><td>The JWS object. </td></tr>
    <tr><td class="paramname">sig</td><td>The JWS signature object(s) to verify or NULL. </td></tr>
    <tr><td class="paramname">jwk</td><td>The JWK(s) or JWKSet used for verifying signatures. </td></tr>
    <tr><td class="paramname">all</td><td>Whether or not to require validation of all JWKs. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>On success, true. Otherwise, false. </dd></dl>

</div>
</div>
<a id="ga35a5d3c37101fc127933f3c856b46cc8"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga35a5d3c37101fc127933f3c856b46cc8">&#9670;&nbsp;</a></span>jose_jws_ver_io()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="structjose__io__t.html">jose_io_t</a>* jose_jws_ver_io </td>
          <td>(</td>
          <td class="paramtype">jose_cfg_t *&#160;</td>
          <td class="paramname"><em>cfg</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const json_t *&#160;</td>
          <td class="paramname"><em>jws</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const json_t *&#160;</td>
          <td class="paramname"><em>sig</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const json_t *&#160;</td>
          <td class="paramname"><em>jwk</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">bool&#160;</td>
          <td class="paramname"><em>all</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Verifies signatures of one or more JWKs in a JWS object using streaming. </p>
<p>This function behaves substantially like <a class="el" href="group__jose__jws.html#ga89a18c4b4d7cd0f9d42224ef5698abe7" title="Verifies signatures of one or more JWKs in a JWS object. ">jose_jws_ver()</a> except:</p>
<p>The payload is not specified in the JWS (<code>jws</code>). Rather, the payload is provided using the returned IO object. The input to the returned IO object will not be internally Base64 encoded. So you may need to prepend the IO chain with the result of <a class="el" href="group__jose__b64.html#gad72c180de43c9da3456bdb0d166092ff" title="Creates a new IO object which performs URL-safe Base64 encoding. ">jose_b64_enc_io()</a> (depending on your situation).</p>
<p>Final signature verification is delayed until <a class="el" href="structjose__io__t.html#a76d1eac0d05d3604c16686b08bd80aa0">jose_io_t::done()</a> returns.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">cfg</td><td>The configuration context (optional). </td></tr>
    <tr><td class="paramname">jws</td><td>The JWS object. </td></tr>
    <tr><td class="paramname">sig</td><td>The JWS signature object(s) to verify or NULL. </td></tr>
    <tr><td class="paramname">jwk</td><td>The JWK(s) or JWKSet used for verifying signatures. </td></tr>
    <tr><td class="paramname">all</td><td>Whether or not to require validation of all JWKs. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>The new IO object or NULL on error. </dd></dl>

</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>