mirror of
https://gitlab.redox-os.org/CoffeeCode/redox-ssh.git
synced 2025-12-28 20:42:18 +01:00
281 lines
No EOL
19 KiB
HTML
281 lines
No EOL
19 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="generator" content="rustdoc">
|
||
<meta name="description" content="API documentation for the Rust `hmac` mod in crate `ring`.">
|
||
<meta name="keywords" content="rust, rustlang, rust-lang, hmac">
|
||
|
||
<title>ring::hmac - Rust</title>
|
||
|
||
<link rel="stylesheet" type="text/css" href="../../normalize.css">
|
||
<link rel="stylesheet" type="text/css" href="../../rustdoc.css">
|
||
<link rel="stylesheet" type="text/css" href="../../main.css">
|
||
|
||
|
||
|
||
|
||
</head>
|
||
<body class="rustdoc mod">
|
||
<!--[if lte IE 8]>
|
||
<div class="warning">
|
||
This old browser is unsupported and will most likely display funky
|
||
things.
|
||
</div>
|
||
<![endif]-->
|
||
|
||
|
||
|
||
<nav class="sidebar">
|
||
|
||
<p class='location'>Module hmac</p><div class="block items"><ul><li><a href="#structs">Structs</a></li><li><a href="#functions">Functions</a></li></ul></div><p class='location'><a href='../index.html'>ring</a></p><script>window.sidebarCurrent = {name: 'hmac', ty: 'mod', relpath: '../'};</script><script defer src="../sidebar-items.js"></script>
|
||
</nav>
|
||
|
||
<nav class="sub">
|
||
<form class="search-form js-only">
|
||
<div class="search-container">
|
||
<input class="search-input" name="search"
|
||
autocomplete="off"
|
||
placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
|
||
type="search">
|
||
</div>
|
||
</form>
|
||
</nav>
|
||
|
||
<section id='main' class="content">
|
||
<h1 class='fqn'><span class='in-band'>Module <a href='../index.html'>ring</a>::<wbr><a class="mod" href=''>hmac</a></span><span class='out-of-band'><span id='render-detail'>
|
||
<a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
|
||
[<span class='inner'>−</span>]
|
||
</a>
|
||
</span><a class='srclink' href='../../src/ring/hmac.rs.html#15-483' title='goto source code'>[src]</a></span></h1>
|
||
<div class='docblock'><p>HMAC is specified in <a href="https://tools.ietf.org/html/rfc2104">RFC 2104</a>.</p>
|
||
|
||
<p>After a <code>SigningKey</code> or <code>VerificationKey</code> is constructed, it can be used
|
||
for multiple signing or verification operations. Separating the
|
||
construction of the key from the rest of the HMAC operation allows the
|
||
per-key precomputation to be done only once, instead of it being done in
|
||
every HMAC operation.</p>
|
||
|
||
<p>Frequently all the data to be signed in a message is available in a single
|
||
contiguous piece. In that case, the module-level <code>sign</code> function can be
|
||
used. Otherwise, if the input is in multiple parts, <code>SigningContext</code> should
|
||
be used.</p>
|
||
|
||
<h1 id='use-case-multi-party-communication' class='section-header'><a href='#use-case-multi-party-communication'>Use Case: Multi-party Communication</a></h1>
|
||
<p>Examples: TLS, SSH, and IPSEC record/packet authentication.</p>
|
||
|
||
<p>The key that is used to sign messages to send to other parties should be a
|
||
<code>SigningKey</code>; <code>SigningContext</code> or <code>sign</code> should be used for the signing.
|
||
Each key that is used to authenticate messages received from peers should
|
||
be a <code>VerificationKey</code>; <code>verify</code> should be used for the authentication. All
|
||
of the keys should have distinct, independent, values.</p>
|
||
|
||
<h1 id='use-case-one-party-anti-tampering-protection' class='section-header'><a href='#use-case-one-party-anti-tampering-protection'>Use Case: One-party Anti-tampering Protection</a></h1>
|
||
<p>Examples: Signed cookies, stateless CSRF protection.</p>
|
||
|
||
<p>The key that is used to sign the data should be a <code>SigningKey</code>;
|
||
<code>SigningContext</code> or <code>sign</code> should be used for the signing. Use
|
||
<code>verify_with_own_key</code> to verify the signature using the signing key; this
|
||
is equivalent to, but more efficient than, constructing a <code>VerificationKey</code>
|
||
with the same value as the signing key and then calling <code>verify</code>.</p>
|
||
|
||
<h1 id='use-case-key-derivation-and-password-hashing' class='section-header'><a href='#use-case-key-derivation-and-password-hashing'>Use Case: Key Derivation and Password Hashing</a></h1>
|
||
<p>Examples: HKDF, PBKDF2, the TLS PRF.</p>
|
||
|
||
<p>All keys used during the key derivation should be <code>SigningKey</code>s;
|
||
<code>SigningContext</code> should usually be used for the HMAC calculations. The
|
||
<a href="https://github.com/briansmith/ring/blob/master/src/pbkdf2.rs">code for <code>ring::pbkdf2</code></a> and the <a href="https://github.com/briansmith/ring/blob/master/src/hkdf.rs">code for <code>ring::hkdf</code></a> are good
|
||
examples of how to use <code>ring::hmac</code> efficiently for key derivation.</p>
|
||
|
||
<h1 id='examples' class='section-header'><a href='#examples'>Examples:</a></h1>
|
||
<h2 id='signing-a-value-and-verifying-it-wasnt-tampered-with' class='section-header'><a href='#signing-a-value-and-verifying-it-wasnt-tampered-with'>Signing a value and verifying it wasn't tampered with</a></h2>
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">ring</span>::{<span class="ident">digest</span>, <span class="ident">hmac</span>, <span class="ident">rand</span>};
|
||
|
||
<span class="kw">let</span> <span class="ident">rng</span> <span class="op">=</span> <span class="ident">rand</span>::<span class="ident">SystemRandom</span>::<span class="ident">new</span>();
|
||
<span class="kw">let</span> <span class="ident">key</span> <span class="op">=</span> <span class="ident">hmac</span>::<span class="ident">SigningKey</span>::<span class="ident">generate</span>(<span class="kw-2">&</span><span class="ident">digest</span>::<span class="ident">SHA256</span>, <span class="kw-2">&</span><span class="ident">rng</span>)<span class="question-mark">?</span>;
|
||
|
||
<span class="kw">let</span> <span class="ident">msg</span> <span class="op">=</span> <span class="string">"hello, world"</span>;
|
||
|
||
<span class="kw">let</span> <span class="ident">signature</span> <span class="op">=</span> <span class="ident">hmac</span>::<span class="ident">sign</span>(<span class="kw-2">&</span><span class="ident">key</span>, <span class="ident">msg</span>.<span class="ident">as_bytes</span>());
|
||
|
||
<span class="comment">// [We give access to the message to an untrusted party, and they give it</span>
|
||
<span class="comment">// back to us. We need to verify they didn't tamper with it.]</span>
|
||
|
||
<span class="ident">hmac</span>::<span class="ident">verify_with_own_key</span>(<span class="kw-2">&</span><span class="ident">key</span>, <span class="ident">msg</span>.<span class="ident">as_bytes</span>(), <span class="ident">signature</span>.<span class="ident">as_ref</span>())<span class="question-mark">?</span>;</pre>
|
||
|
||
<h2 id='using-the-one-shot-api' class='section-header'><a href='#using-the-one-shot-api'>Using the one-shot API:</a></h2>
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">ring</span>::{<span class="ident">digest</span>, <span class="ident">hmac</span>, <span class="ident">rand</span>};
|
||
<span class="kw">use</span> <span class="ident">ring</span>::<span class="ident">rand</span>::<span class="ident">SecureRandom</span>;
|
||
|
||
<span class="kw">let</span> <span class="ident">msg</span> <span class="op">=</span> <span class="string">"hello, world"</span>;
|
||
|
||
<span class="comment">// The sender generates a secure key value and signs the message with it.</span>
|
||
<span class="comment">// Note that in a real protocol, a key agreement protocol would be used to</span>
|
||
<span class="comment">// derive `key_value`.</span>
|
||
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">key_value</span> <span class="op">=</span> [<span class="number">0u8</span>; <span class="number">32</span>];
|
||
<span class="kw">let</span> <span class="ident">rng</span> <span class="op">=</span> <span class="ident">rand</span>::<span class="ident">SystemRandom</span>::<span class="ident">new</span>();
|
||
<span class="ident">rng</span>.<span class="ident">fill</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">key_value</span>)<span class="question-mark">?</span>;
|
||
|
||
<span class="kw">let</span> <span class="ident">s_key</span> <span class="op">=</span> <span class="ident">hmac</span>::<span class="ident">SigningKey</span>::<span class="ident">new</span>(<span class="kw-2">&</span><span class="ident">digest</span>::<span class="ident">SHA256</span>, <span class="ident">key_value</span>.<span class="ident">as_ref</span>());
|
||
<span class="kw">let</span> <span class="ident">signature</span> <span class="op">=</span> <span class="ident">hmac</span>::<span class="ident">sign</span>(<span class="kw-2">&</span><span class="ident">s_key</span>, <span class="ident">msg</span>.<span class="ident">as_bytes</span>());
|
||
|
||
<span class="comment">// The receiver (somehow!) knows the key value, and uses it to verify the</span>
|
||
<span class="comment">// integrity of the message.</span>
|
||
<span class="kw">let</span> <span class="ident">v_key</span> <span class="op">=</span> <span class="ident">hmac</span>::<span class="ident">VerificationKey</span>::<span class="ident">new</span>(<span class="kw-2">&</span><span class="ident">digest</span>::<span class="ident">SHA256</span>, <span class="ident">key_value</span>.<span class="ident">as_ref</span>());
|
||
<span class="ident">hmac</span>::<span class="ident">verify</span>(<span class="kw-2">&</span><span class="ident">v_key</span>, <span class="ident">msg</span>.<span class="ident">as_bytes</span>(), <span class="ident">signature</span>.<span class="ident">as_ref</span>())<span class="question-mark">?</span>;</pre>
|
||
|
||
<h2 id='using-the-multi-part-api' class='section-header'><a href='#using-the-multi-part-api'>Using the multi-part API:</a></h2>
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">ring</span>::{<span class="ident">digest</span>, <span class="ident">hmac</span>, <span class="ident">rand</span>};
|
||
<span class="kw">use</span> <span class="ident">ring</span>::<span class="ident">rand</span>::<span class="ident">SecureRandom</span>;
|
||
|
||
<span class="kw">let</span> <span class="ident">parts</span> <span class="op">=</span> [<span class="string">"hello"</span>, <span class="string">", "</span>, <span class="string">"world"</span>];
|
||
|
||
<span class="comment">// The sender generates a secure key value and signs the message with it.</span>
|
||
<span class="comment">// Note that in a real protocol, a key agreement protocol would be used to</span>
|
||
<span class="comment">// derive `key_value`.</span>
|
||
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">key_value</span> <span class="op">=</span> [<span class="number">0u8</span>; <span class="number">48</span>];
|
||
<span class="kw">let</span> <span class="ident">rng</span> <span class="op">=</span> <span class="ident">rand</span>::<span class="ident">SystemRandom</span>::<span class="ident">new</span>();
|
||
<span class="ident">rng</span>.<span class="ident">fill</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">key_value</span>)<span class="question-mark">?</span>;
|
||
|
||
<span class="kw">let</span> <span class="ident">s_key</span> <span class="op">=</span> <span class="ident">hmac</span>::<span class="ident">SigningKey</span>::<span class="ident">new</span>(<span class="kw-2">&</span><span class="ident">digest</span>::<span class="ident">SHA384</span>, <span class="ident">key_value</span>.<span class="ident">as_ref</span>());
|
||
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">s_ctx</span> <span class="op">=</span> <span class="ident">hmac</span>::<span class="ident">SigningContext</span>::<span class="ident">with_key</span>(<span class="kw-2">&</span><span class="ident">s_key</span>);
|
||
<span class="kw">for</span> <span class="ident">part</span> <span class="kw">in</span> <span class="kw-2">&</span><span class="ident">parts</span> {
|
||
<span class="ident">s_ctx</span>.<span class="ident">update</span>(<span class="ident">part</span>.<span class="ident">as_bytes</span>());
|
||
}
|
||
<span class="kw">let</span> <span class="ident">signature</span> <span class="op">=</span> <span class="ident">s_ctx</span>.<span class="ident">sign</span>();
|
||
|
||
<span class="comment">// The receiver (somehow!) knows the key value, and uses it to verify the</span>
|
||
<span class="comment">// integrity of the message.</span>
|
||
<span class="kw">let</span> <span class="ident">v_key</span> <span class="op">=</span> <span class="ident">hmac</span>::<span class="ident">VerificationKey</span>::<span class="ident">new</span>(<span class="kw-2">&</span><span class="ident">digest</span>::<span class="ident">SHA384</span>, <span class="ident">key_value</span>.<span class="ident">as_ref</span>());
|
||
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">msg</span> <span class="op">=</span> <span class="ident">Vec</span>::<span class="op"><</span><span class="ident">u8</span><span class="op">></span>::<span class="ident">new</span>();
|
||
<span class="kw">for</span> <span class="ident">part</span> <span class="kw">in</span> <span class="kw-2">&</span><span class="ident">parts</span> {
|
||
<span class="ident">msg</span>.<span class="ident">extend</span>(<span class="ident">part</span>.<span class="ident">as_bytes</span>());
|
||
}
|
||
<span class="ident">hmac</span>::<span class="ident">verify</span>(<span class="kw-2">&</span><span class="ident">v_key</span>, <span class="kw-2">&</span><span class="ident">msg</span>.<span class="ident">as_ref</span>(), <span class="ident">signature</span>.<span class="ident">as_ref</span>())<span class="question-mark">?</span>;</pre>
|
||
</div><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="struct" href="struct.Signature.html"
|
||
title='struct ring::hmac::Signature'>Signature</a></td>
|
||
<td class='docblock-short'>
|
||
<p>An HMAC signature.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="struct" href="struct.SigningContext.html"
|
||
title='struct ring::hmac::SigningContext'>SigningContext</a></td>
|
||
<td class='docblock-short'>
|
||
<p>A context for multi-step (Init-Update-Finish) HMAC signing.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="struct" href="struct.SigningKey.html"
|
||
title='struct ring::hmac::SigningKey'>SigningKey</a></td>
|
||
<td class='docblock-short'>
|
||
<p>A key to use for HMAC signing.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="struct" href="struct.VerificationKey.html"
|
||
title='struct ring::hmac::VerificationKey'>VerificationKey</a></td>
|
||
<td class='docblock-short'>
|
||
<p>A key to use for HMAC authentication.</p>
|
||
</td>
|
||
</tr></table><h2 id='functions' class='section-header'><a href="#functions">Functions</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="fn" href="fn.recommended_key_len.html"
|
||
title='fn ring::hmac::recommended_key_len'>recommended_key_len</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Returns the recommended key length for HMAC using the given digest
|
||
algorithm.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="fn" href="fn.sign.html"
|
||
title='fn ring::hmac::sign'>sign</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Calculates the HMAC of <code>data</code> using the key <code>key</code> in one step.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="fn" href="fn.verify.html"
|
||
title='fn ring::hmac::verify'>verify</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Calculates the HMAC of <code>data</code> using the key <code>key</code>, and verifies whether the
|
||
resultant value equals <code>signature</code>, in one step.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="fn" href="fn.verify_with_own_key.html"
|
||
title='fn ring::hmac::verify_with_own_key'>verify_with_own_key</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Calculates the HMAC of <code>data</code> using the signing key <code>key</code>, and verifies
|
||
whether the resultant value equals <code>signature</code>, in one step.</p>
|
||
</td>
|
||
</tr></table></section>
|
||
<section id='search' class="content hidden"></section>
|
||
|
||
<section class="footer"></section>
|
||
|
||
<aside id="help" class="hidden">
|
||
<div>
|
||
<h1 class="hidden">Help</h1>
|
||
|
||
<div class="shortcuts">
|
||
<h2>Keyboard Shortcuts</h2>
|
||
|
||
<dl>
|
||
<dt>?</dt>
|
||
<dd>Show this help dialog</dd>
|
||
<dt>S</dt>
|
||
<dd>Focus the search field</dd>
|
||
<dt>⇤</dt>
|
||
<dd>Move up in search results</dd>
|
||
<dt>⇥</dt>
|
||
<dd>Move down in search results</dd>
|
||
<dt>⏎</dt>
|
||
<dd>Go to active search result</dd>
|
||
<dt>+</dt>
|
||
<dd>Collapse/expand all sections</dd>
|
||
</dl>
|
||
</div>
|
||
|
||
<div class="infos">
|
||
<h2>Search Tricks</h2>
|
||
|
||
<p>
|
||
Prefix searches with a type followed by a colon (e.g.
|
||
<code>fn:</code>) to restrict the search to a given type.
|
||
</p>
|
||
|
||
<p>
|
||
Accepted types are: <code>fn</code>, <code>mod</code>,
|
||
<code>struct</code>, <code>enum</code>,
|
||
<code>trait</code>, <code>type</code>, <code>macro</code>,
|
||
and <code>const</code>.
|
||
</p>
|
||
|
||
<p>
|
||
Search functions by type signature (e.g.
|
||
<code>vec -> usize</code> or <code>* -> vec</code>)
|
||
</p>
|
||
</div>
|
||
</div>
|
||
</aside>
|
||
|
||
|
||
|
||
<script>
|
||
window.rootPath = "../../";
|
||
window.currentCrate = "ring";
|
||
</script>
|
||
<script src="../../jquery.js"></script>
|
||
<script src="../../main.js"></script>
|
||
<script defer src="../../search-index.js"></script>
|
||
</body>
|
||
</html> |