39 lines
7.8 KiB
HTML
39 lines
7.8 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="This crate provides a mechanism for “jumbling” byte slices in a reversible way."><title>f4jumble - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../static.files/rustdoc-c233d2bd.css"><meta name="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="f4jumble" data-themes="" data-resource-suffix="" data-rustdoc-version="1.88.0-nightly (6bc57c6bf 2025-04-22)" data-channel="nightly" data-search-js="search-f7877310.js" data-settings-js="settings-5514c975.js" ><script src="../static.files/storage-4e99c027.js"></script><script defer src="../crates.js"></script><script defer src="../static.files/main-7ef8a74a.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-893ab5e7.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-32x32-6580c154.png"><link rel="icon" type="image/svg+xml" href="../static.files/favicon-044be391.svg"></head><body class="rustdoc mod crate"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../f4jumble/index.html">f4jumble</a><span class="version">0.1.1</span></h2></div><div class="sidebar-elems"><ul class="block"><li><a id="all-types" href="all.html">All Items</a></li></ul><section id="rustdoc-toc"><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#efficiency" title="Efficiency">Efficiency</a></li></ul><h3><a href="#enums">Crate Items</a></h3><ul class="block"><li><a href="#enums" title="Enums">Enums</a></li><li><a href="#constants" title="Constants">Constants</a></li><li><a href="#functions" title="Functions">Functions</a></li></ul></section><div id="rustdoc-modnav"></div></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><h1>Crate <span>f4jumble</span><button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../src/f4jumble/lib.rs.html#1-392">Source</a> </span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>This crate provides a mechanism for “jumbling” byte slices in a reversible way.</p>
|
|
<p>Many byte encodings such as <a href="https://en.wikipedia.org/wiki/Base64">Base64</a> and <a href="https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki#Bech32">Bech32</a> do not have “cascading” behaviour:
|
|
changing an input byte at one position has no effect on the encoding of bytes at
|
|
distant positions. This can be a problem if users generally check the correctness of
|
|
encoded strings by eye, as they will tend to only check the first and/or last few
|
|
characters of the encoded string. In some situations (for example, a hardware device
|
|
displaying on its screen an encoded string provided by an untrusted computer), it is
|
|
potentially feasible for an adversary to change some internal portion of the encoded
|
|
string in a way that is beneficial to them, without the user noticing.</p>
|
|
<p>The function F4Jumble (and its inverse function, F4Jumble⁻¹) are length-preserving
|
|
transformations can be used to trivially introduce cascading behaviour to existing
|
|
encodings:</p>
|
|
<ul>
|
|
<li>Prepare the raw <code>message</code> bytes as usual.</li>
|
|
<li>Pass <code>message</code> through <a href="fn.f4jumble.html" title="fn f4jumble::f4jumble"><code>f4jumble</code></a> or <a href="fn.f4jumble_mut.html" title="fn f4jumble::f4jumble_mut"><code>f4jumble_mut</code></a> to obtain the jumbled bytes.</li>
|
|
<li>Encode the jumbled bytes with the encoding scheme.</li>
|
|
</ul>
|
|
<p>Changing any byte of <code>message</code> will result in a completely different sequence of
|
|
jumbled bytes. Specifically, F4Jumble uses an unkeyed 4-round Feistel construction to
|
|
approximate a random permutation.</p>
|
|
<p><img src="https://zips.z.cash/zip-0316-f4.png" alt="Diagram of 4-round unkeyed Feistel construction" /></p>
|
|
<h3 id="efficiency"><a class="doc-anchor" href="#efficiency">§</a>Efficiency</h3>
|
|
<p>The cost is dominated by 4 BLAKE2b compressions for message lengths up to 128 bytes.
|
|
For longer messages, the cost increases to 6 BLAKE2b compressions for 128 < lₘ ≤ 192,
|
|
and 10 BLAKE2b compressions for 192 < lₘ ≤ 256, for example. The maximum cost for
|
|
which the algorithm is defined would be 196608 BLAKE2b compressions at lₘ = 4194368.</p>
|
|
<p>The implementations in this crate require memory of roughly lₘ bytes plus the size of
|
|
a BLAKE2b hash state. It is possible to reduce this by (for example, with F4Jumble⁻¹)
|
|
streaming the <code>d</code> part of the jumbled encoding three times from a less
|
|
memory-constrained device. It is essential that the streamed value of <code>d</code> is the same
|
|
on each pass, which can be verified using a Message Authentication Code (with key held
|
|
only by the Consumer) or collision-resistant hash function. After the first pass of
|
|
<code>d</code>, the implementation is able to compute <code>y</code>; after the second pass it is able to
|
|
compute <code>a</code>; and the third allows it to compute and incrementally parse <code>b</code>. The
|
|
maximum memory usage during this process would be 128 bytes plus two BLAKE2b hash
|
|
states.</p>
|
|
</div></details><h2 id="enums" class="section-header">Enums<a href="#enums" class="anchor">§</a></h2><dl class="item-table"><dt><a class="enum" href="enum.Error.html" title="enum f4jumble::Error">Error</a></dt><dd>Errors produced by F4Jumble.</dd></dl><h2 id="constants" class="section-header">Constants<a href="#constants" class="anchor">§</a></h2><dl class="item-table"><dt><a class="constant" href="constant.VALID_LENGTH.html" title="constant f4jumble::VALID_LENGTH">VALID_<wbr>LENGTH</a></dt><dd>Length of F4Jumbled message must lie in the range VALID_LENGTH.</dd></dl><h2 id="functions" class="section-header">Functions<a href="#functions" class="anchor">§</a></h2><dl class="item-table"><dt><a class="fn" href="fn.f4jumble.html" title="fn f4jumble::f4jumble">f4jumble</a><wbr><span class="stab portability" title="Available on crate feature `alloc` only"><code>alloc</code></span></dt><dd>Encodes the given message using F4Jumble, and returns the encoded message as a vector
|
|
of bytes.</dd><dt><a class="fn" href="fn.f4jumble_inv.html" title="fn f4jumble::f4jumble_inv">f4jumble_<wbr>inv</a><wbr><span class="stab portability" title="Available on crate feature `alloc` only"><code>alloc</code></span></dt><dd>Decodes the given message using F4Jumble⁻¹, and returns the decoded message as a
|
|
vector of bytes.</dd><dt><a class="fn" href="fn.f4jumble_inv_mut.html" title="fn f4jumble::f4jumble_inv_mut">f4jumble_<wbr>inv_<wbr>mut</a></dt><dd>Decodes the given message in-place using F4Jumble⁻¹.</dd><dt><a class="fn" href="fn.f4jumble_mut.html" title="fn f4jumble::f4jumble_mut">f4jumble_<wbr>mut</a></dt><dd>Encodes the given message in-place using F4Jumble.</dd></dl></section></div></main></body></html> |