cbiedl
/
jose


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419
							<!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é: JWK</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">JWK</div>  </div>
</div><!--header-->
<div class="contents">

<p>JSON Web Keys (RFC 7517)  
<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:gac4daef7aeb077caaa459f07af353e9a8"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwk.html#gac4daef7aeb077caaa459f07af353e9a8">jose_jwk_gen</a> (jose_cfg_t *cfg, json_t *jwk)</td></tr>
<tr class="memdesc:gac4daef7aeb077caaa459f07af353e9a8"><td class="mdescLeft">&#160;</td><td class="mdescRight">Generates a new JWK.  <a href="#gac4daef7aeb077caaa459f07af353e9a8">More...</a><br /></td></tr>
<tr class="separator:gac4daef7aeb077caaa459f07af353e9a8"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga3ebb220fa6f93ad00c6589400c1a441c"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwk.html#ga3ebb220fa6f93ad00c6589400c1a441c">jose_jwk_pub</a> (jose_cfg_t *cfg, json_t *jwk)</td></tr>
<tr class="memdesc:ga3ebb220fa6f93ad00c6589400c1a441c"><td class="mdescLeft">&#160;</td><td class="mdescRight">Removes all private key material from a JWK.  <a href="#ga3ebb220fa6f93ad00c6589400c1a441c">More...</a><br /></td></tr>
<tr class="separator:ga3ebb220fa6f93ad00c6589400c1a441c"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaa2023d0376c2e5ca14c2177f80f8ecd5"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwk.html#gaa2023d0376c2e5ca14c2177f80f8ecd5">jose_jwk_prm</a> (jose_cfg_t *cfg, const json_t *jwk, bool req, const char *op)</td></tr>
<tr class="memdesc:gaa2023d0376c2e5ca14c2177f80f8ecd5"><td class="mdescLeft">&#160;</td><td class="mdescRight">Determines if an operation is permitted for a JWK.  <a href="#gaa2023d0376c2e5ca14c2177f80f8ecd5">More...</a><br /></td></tr>
<tr class="separator:gaa2023d0376c2e5ca14c2177f80f8ecd5"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga4f5d2e9dc5f9e24646808b502b87b764"><td class="memItemLeft" align="right" valign="top">json_t *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwk.html#ga4f5d2e9dc5f9e24646808b502b87b764">jose_jwk_thp</a> (jose_cfg_t *cfg, const json_t *jwk, const char *alg)</td></tr>
<tr class="memdesc:ga4f5d2e9dc5f9e24646808b502b87b764"><td class="mdescLeft">&#160;</td><td class="mdescRight">Calculates the thumbprint of a JWK as a URL-safe Base64 encoded JSON string.  <a href="#ga4f5d2e9dc5f9e24646808b502b87b764">More...</a><br /></td></tr>
<tr class="separator:ga4f5d2e9dc5f9e24646808b502b87b764"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga03f820f8de4e63ffe2feb3490236040e"><td class="memItemLeft" align="right" valign="top">size_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwk.html#ga03f820f8de4e63ffe2feb3490236040e">jose_jwk_thp_buf</a> (jose_cfg_t *cfg, const json_t *jwk, const char *alg, uint8_t *thp, size_t len)</td></tr>
<tr class="memdesc:ga03f820f8de4e63ffe2feb3490236040e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Calculates the thumbprint of a JWK.  <a href="#ga03f820f8de4e63ffe2feb3490236040e">More...</a><br /></td></tr>
<tr class="separator:ga03f820f8de4e63ffe2feb3490236040e"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga9977a603c39b1b7c545f3f0c3dd0a7ef"><td class="memItemLeft" align="right" valign="top">json_t *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__jose__jwk.html#ga9977a603c39b1b7c545f3f0c3dd0a7ef">jose_jwk_exc</a> (jose_cfg_t *cfg, const json_t *prv, const json_t *pub)</td></tr>
<tr class="memdesc:ga9977a603c39b1b7c545f3f0c3dd0a7ef"><td class="mdescLeft">&#160;</td><td class="mdescRight">Perform a key exchange.  <a href="#ga9977a603c39b1b7c545f3f0c3dd0a7ef">More...</a><br /></td></tr>
<tr class="separator:ga9977a603c39b1b7c545f3f0c3dd0a7ef"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>JSON Web Keys (RFC 7517) </p>
<p>A JSON Web Key (JWS) is a standard data format for expresing cryptographic keys in JSON.</p>
<dl class="section see"><dt>See also</dt><dd><a href="https://tools.ietf.org/html/rfc7517">https://tools.ietf.org/html/rfc7517</a> </dd>
<dd>
<a href="https://tools.ietf.org/html/rfc7638">https://tools.ietf.org/html/rfc7638</a> </dd></dl>
<h2 class="groupheader">Function Documentation</h2>
<a id="gac4daef7aeb077caaa459f07af353e9a8"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gac4daef7aeb077caaa459f07af353e9a8">&#9670;&nbsp;</a></span>jose_jwk_gen()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">bool jose_jwk_gen </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>jwk</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Generates a new JWK. </p>
<p>The JWK is generated using hints from the input in exactly the same format as you would find in the output. For example, the most common way to generate a key is to specify the algorithm you'd like to use the key with. For example (error handling omitted): </p><pre class="fragment">json_t *gen(void) {
    json_auto_t *jwk = json_pack("{s:s}", "alg", "ES256");
    jose_jwk_gen(NULL, jwk);
    return json_incref(jwk);
}
</pre><p>This method is preferred because other metadata can be inferred from the algorithm name, such as the key usage. Additionally, the algorithm metadata can be used to automatically generate correct headers when creating signatures (JWS) or encryptions (JWE). Thus, you should always default to creating keys by their algorithm usage.</p>
<p>However, should your requirements differ, you can also generate a key using raw parameters (again, error handling omitted): </p><pre class="fragment">json_t *gen(void) {
    json_auto_t *jwk = json_pack("{s:s,s:s}", "kty", "EC", "crv", "P-256");
    jose_jwk_gen(NULL, jwk);
    return json_incref(jwk);
}

json_t *gen(void) {
    json_auto_t *jwk = json_pack("{s:s,s:i}", "kty", "RSA", "bits", 2048);
    jose_jwk_gen(NULL, jwk);
    return json_incref(jwk);
}

json_t *gen(void) {
    json_auto_t *jwk = json_pack("{s:s,s:i}", "kty", "oct", "bytes", 32);
    jose_jwk_gen(NULL, jwk);
    return json_incref(jwk);
}
</pre><p>In this case, "bits" and "bytes" will be removed from the final output.</p>
<dl class="section see"><dt>See also</dt><dd><a href="https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms">https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms</a> </dd></dl>
<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">jwk</td><td>The JWK to generate. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>On success, true. Otherwise, false. </dd></dl>

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

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">bool jose_jwk_pub </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>jwk</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Removes all private key material from a JWK. </p>
<p>In addition, this function will remove any key operations from the <code>key_ops</code> JWK property (if present) that apply only to the private key.</p>
<p>This function should be used before exporting keys to third parties.</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">jwk</td><td>The JWK to remove private keys from. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>On success, true. Otherwise, false. </dd></dl>

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

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">bool jose_jwk_prm </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>jwk</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">bool&#160;</td>
          <td class="paramname"><em>req</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const char *&#160;</td>
          <td class="paramname"><em>op</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Determines if an operation is permitted for a JWK. </p>
<p>The operation to be confirmed (<code>op</code>) is always specified according to the syntax of the "key_ops" JWK property, even when the "use" property is defined on the JWK.</p>
<p>This function has two modes of operation. If <code>req</code> is false, then JWKs which do not have any key use metadata will be approved for this operation. However, if <code>req</code> is true then this metadata will be required for approval.</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">jwk</td><td>The JWK from which to remove private keys. </td></tr>
    <tr><td class="paramname">req</td><td>Whether JWK key use metadata is required or not. </td></tr>
    <tr><td class="paramname">op</td><td>The opperation to seek approval for. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>When the JWK is approved, true. Otherwise, false. </dd></dl>

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

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">json_t* jose_jwk_thp </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>jwk</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const char *&#160;</td>
          <td class="paramname"><em>alg</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Calculates the thumbprint of a JWK as a URL-safe Base64 encoded JSON string. </p>
<p>This function is a thin wrapper around <a class="el" href="group__jose__jwk.html#ga03f820f8de4e63ffe2feb3490236040e" title="Calculates the thumbprint of a JWK. ">jose_jwk_thp_buf()</a>.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__jose__jwk.html#ga03f820f8de4e63ffe2feb3490236040e" title="Calculates the thumbprint of a JWK. ">jose_jwk_thp_buf()</a> </dd></dl>
<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">jwk</td><td>The JWK to calculate the thumbprint for. </td></tr>
    <tr><td class="paramname">alg</td><td>The hash algorithm to use. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>On success, a newly-allocated JSON string. Otherwise, NULL. </dd></dl>

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

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">size_t jose_jwk_thp_buf </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>jwk</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const char *&#160;</td>
          <td class="paramname"><em>alg</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">uint8_t *&#160;</td>
          <td class="paramname"><em>thp</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">size_t&#160;</td>
          <td class="paramname"><em>len</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Calculates the thumbprint of a JWK. </p>
<p>This function calculates the thumbprint of a JWK according to the method defined by RFC 7638.</p>
<p>If <code>thp</code> is NULL, this function returns the size of the buffer required for the thumbprint output.</p>
<dl class="section see"><dt>See also</dt><dd><a href="https://tools.ietf.org/html/rfc7638">https://tools.ietf.org/html/rfc7638</a> </dd></dl>
<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">jwk</td><td>The JWK to calculate the thumbprint for. </td></tr>
    <tr><td class="paramname">alg</td><td>The hash algorithm to use. </td></tr>
    <tr><td class="paramname">thp</td><td>The output hash buffer. </td></tr>
    <tr><td class="paramname">len</td><td>The size of the output hash buffer. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>On success, the number of bytes written. Otherwise, SIZE_MAX. </dd></dl>

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

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">json_t* jose_jwk_exc </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>prv</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const json_t *&#160;</td>
          <td class="paramname"><em>pub</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Perform a key exchange. </p>
<p>The only currently implemented algorithm is ECDH.</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">prv</td><td>The private JWK. </td></tr>
    <tr><td class="paramname">pub</td><td>The public JWK. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>On success, the JWK result of the key exchange. Otherwise, NULL. </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>