diff options
| author | pukkamustard <pukkamustard@posteo.net> | 2021-02-05 21:02:47 +0100 |
|---|---|---|
| committer | pukkamustard <pukkamustard@posteo.net> | 2021-02-05 21:11:01 +0100 |
| commit | 5628804d6884232fe28fb8d5ead74197b52cde6d (patch) | |
| tree | 4724af0b0d39f07a724c55d28d925654a3290039 /vendor/doc | |
| parent | 6cef88d8d028db077e1b4e48a390d4648966536d (diff) | |
initial working commit
Diffstat (limited to 'vendor/doc')
187 files changed, 24908 insertions, 0 deletions
diff --git a/vendor/doc/html/crypto_aead_lock.html b/vendor/doc/html/crypto_aead_lock.html new file mode 100644 index 0000000..ef9450b --- /dev/null +++ b/vendor/doc/html/crypto_aead_lock.html @@ -0,0 +1,292 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_LOCK(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_LOCK(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_LOCK(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_aead_lock</b>, + <b class="Nm" title="Nm">crypto_aead_unlock</b>, + <b class="Nm" title="Nm">crypto_lock</b>, + <b class="Nm" title="Nm">crypto_unlock</b> — + <span class="Nd" title="Nd">authenticated encryption with additional + data</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock</b>(<var class="Fa" title="Fa">uint8_t + mac[16]</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock</b>(<var class="Fa" title="Fa">uint8_t + *plain_text</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">const uint8_t mac[16]</var>, + <var class="Fa" title="Fa">const uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_aead_lock</b>(<var class="Fa" title="Fa">uint8_t + mac[16]</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_aead_unlock</b>(<var class="Fa" title="Fa">uint8_t + *plain_text</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">const uint8_t mac[16]</var>, + <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>, + <var class="Fa" title="Fa">const uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<b class="Fn" title="Fn">crypto_lock</b>() encrypts and authenticates a + plaintext. It can be decrypted by + <b class="Fn" title="Fn">crypto_unlock</b>(). The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">A 32-byte session key, shared between the sender and the + recipient. It must be secret and random. Different methods can be used to + produce and exchange this key, such as Diffie-Hellman key exchange, + password key derivation (the password must be communicated on a secure + channel), or even meeting physically. See + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a> + for key exchange, and + <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a> + for password key derivation.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">nonce</var></dt> + <dd class="It-tag">A 24-byte number, used only once with any given session + key. It does not need to be secret or random, but it does have to be + unique. <i class="Em" title="Em">Never</i> use the same nonce twice with + the same key. This would reveal the XOR of 2 different messages, which + allows decryption and forgeries. The easiest (and recommended) way to + generate this nonce is to select it at random. See + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> about + random number generation (use your operating system's random number + generator).</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">mac</var></dt> + <dd class="It-tag">A 16-byte <i class="Em" title="Em">message authentication + code</i> (MAC), that can only be produced by someone who knows the session + key. This guarantee cannot be upheld if a nonce has been reused with the + session key, because doing so allows the attacker to learn the + authentication key associated with that nonce. The MAC is intended to be + sent along with the ciphertext.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">plain_text</var></dt> + <dd class="It-tag">The secret message. Its contents will be kept hidden from + attackers. Its length however, will <i class="Em" title="Em">not</i>. Be + careful when combining encryption with compression. See + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + details.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">cipher_text</var></dt> + <dd class="It-tag">The encrypted message.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">text_size</var></dt> + <dd class="It-tag">Length of both <var class="Fa" title="Fa">plain_text + and</var> <var class="Fa" title="Fa">cipher_text</var>, in bytes.</dd> +</dl> +<div class="Pp"></div> +The <var class="Fa" title="Fa">cipher_text</var> and + <var class="Fa" title="Fa">plain_text</var> arguments may point to the same + buffer for in-place encryption. Otherwise, the buffers they point to must not + overlap. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_unlock</b>() first checks the integrity of an + encrypted message. If it has been corrupted, + <b class="Fn" title="Fn">crypto_unlock</b>() returns -1 immediately. + Otherwise, it decrypts the message, then returns zero. + <i class="Em" title="Em">Always check the return value</i>. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_aead_lock</b>() and + <b class="Fn" title="Fn">crypto_aead_unlock</b>() are variants of + <b class="Fn" title="Fn">crypto_lock</b>() and + <b class="Fn" title="Fn">crypto_unlock</b>(), permitting additional data. + Additional data is authenticated, but <i class="Em" title="Em">not</i> + encrypted. This is used to authenticate relevant data that cannot be + encrypted. The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">ad</var></dt> + <dd class="It-tag">Additional data to authenticate. It will not be encrypted. + May be <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">ad_size</var> is zero. Setting + <var class="Fa" title="Fa">ad_size</var> to zero yields the same results + as <b class="Fn" title="Fn">crypto_lock</b>() and + <b class="Fn" title="Fn">crypto_unlock</b>().</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">ad_size</var></dt> + <dd class="It-tag">Length of the additional data, in bytes. + <b class="Sy" title="Sy">That length is not authenticated.</b> If the + additional data is of variable length, the length should be appended to + <var class="Fa" title="Fa">ad</var> so it gets authenticated, and should + be extracted from the end of the message when decrypting. Otherwise an + attacker could provide a false length, effectively moving the boundary + between the additional data and the ciphertext. This may cause buffer + overflows in some programs.</dd> +</dl> +<div class="Pp"></div> +An incremental interface is available; see + <a class="Xr" title="Xr" href="crypto_lock_init.html">crypto_lock_init(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_lock</b>() and + <b class="Fn" title="Fn">crypto_aead_lock</b>() return nothing. They cannot + fail. <b class="Fn" title="Fn">crypto_unlock</b>() and + <b class="Fn" title="Fn">crypto_aead_unlock</b>() return 0 on success or -1 if + the message was corrupted (i.e. <var class="Fa" title="Fa">mac</var> + mismatched the combination of <var class="Fa" title="Fa">key</var>, + <var class="Fa" title="Fa">nonce</var>, <var class="Fa" title="Fa">ad</var> + and <var class="Fa" title="Fa">cipher_text</var>). Corruption can be caused by + transmission errors, programmer error, or an attacker's interference. + <var class="Fa" title="Fa">plain_text</var> does not need to be wiped if the + decryption fails. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +Encryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [32]; /* Random, secret session key */ +const uint8_t nonce [24]; /* Use only once per key */ +const uint8_t plain_text [500]; /* Secret message */ +uint8_t mac [16]; /* Message authentication code */ +uint8_t cipher_text[500]; /* Encrypted message */ +crypto_lock(mac, cipher_text, key, nonce, plain_text, 500); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(plain_text, 500); +crypto_wipe(key, 32); +/* Transmit cipher_text, nonce, and mac over the network */ +</pre> +</div> +<div class="Pp"></div> +To decrypt the above: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [32]; /* Same as the above */ +const uint8_t nonce [24]; /* Same as the above */ +const uint8_t cipher_text[500]; /* Encrypted message */ +const uint8_t mac [16]; /* Received from the network */ +uint8_t plain_text [500]; /* Secret message */ +if (crypto_unlock(plain_text, key, nonce, mac, cipher_text, 500)) { + /* The message is corrupted. + * Wipe key if it is no longer needed, + * and abort the decryption. + */ + crypto_wipe(key, 32); +} +/* Wipe secrets if they are no longer needed */ +crypto_wipe(plain_text, 500); +crypto_wipe(key, 32); +</pre> +</div> +<div class="Pp"></div> +In-place encryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [32]; /* Random, secret session key */ +const uint8_t nonce[24]; /* Use only once per key */ +uint8_t text [500]; /* Secret message */ +uint8_t mac [16]; /* Message authentication code */ +crypto_lock(mac, text, key, nonce, text, 500); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(key, 32); +/* Transmit text, nonce, and mac over the network */ +</pre> +</div> +<div class="Pp"></div> +In-place decryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [32]; /* Same as the above */ +const uint8_t nonce[24]; /* Same as the above */ +const uint8_t mac [16]; /* Reived from the network */ +uint8_t text [500]; /* Message to decrypt */ +if (crypto_unlock(text, key, nonce, mac, text, 500)) { + /* The message is corrupted. + * Wipe key if it is no longer needed, + * and abort the decryption. + */ + crypto_wipe(key, 32); +} +/* Wipe secrets if they are no longer needed */ +crypto_wipe(text, 500); +crypto_wipe(key, 32); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock_init.html">crypto_lock_init(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement the XChacha20 (encryption) and Poly1305 (MAC) + primitives. Chacha20 and Poly1305 are described in RFC 7539. XChacha20 derives + from Chacha20 the same way XSalsa20 derives from Salsa20, and benefits from + the same security reduction (proven secure as long as Chacha20 itself is + secure). +<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION + DETAILS</a></h1> +<b class="Fn" title="Fn">crypto_aead_lock</b>() and + <b class="Fn" title="Fn">crypto_aead_unlock</b>() do not authenticate the + length themselves to make them compatible with + <b class="Fn" title="Fn">crypto_lock</b>() and + <b class="Fn" title="Fn">crypto_unlock</b>() when the size of the additional + data is zero. This also simplifies the implementation. +<div class="Pp"></div> +This rarely causes problems in practice, because most of the time, the length of + the additional data is either fixed or self-contained, and thus outside of + attacker control.</div> +<table class="foot"> + <tr> + <td class="foot-date">December 28, 2017</td> + <td class="foot-os">Linux 4.4.0-116-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_aead_unlock.html b/vendor/doc/html/crypto_aead_unlock.html new file mode 100644 index 0000000..ef9450b --- /dev/null +++ b/vendor/doc/html/crypto_aead_unlock.html @@ -0,0 +1,292 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_LOCK(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_LOCK(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_LOCK(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_aead_lock</b>, + <b class="Nm" title="Nm">crypto_aead_unlock</b>, + <b class="Nm" title="Nm">crypto_lock</b>, + <b class="Nm" title="Nm">crypto_unlock</b> — + <span class="Nd" title="Nd">authenticated encryption with additional + data</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock</b>(<var class="Fa" title="Fa">uint8_t + mac[16]</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock</b>(<var class="Fa" title="Fa">uint8_t + *plain_text</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">const uint8_t mac[16]</var>, + <var class="Fa" title="Fa">const uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_aead_lock</b>(<var class="Fa" title="Fa">uint8_t + mac[16]</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_aead_unlock</b>(<var class="Fa" title="Fa">uint8_t + *plain_text</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">const uint8_t mac[16]</var>, + <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>, + <var class="Fa" title="Fa">const uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<b class="Fn" title="Fn">crypto_lock</b>() encrypts and authenticates a + plaintext. It can be decrypted by + <b class="Fn" title="Fn">crypto_unlock</b>(). The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">A 32-byte session key, shared between the sender and the + recipient. It must be secret and random. Different methods can be used to + produce and exchange this key, such as Diffie-Hellman key exchange, + password key derivation (the password must be communicated on a secure + channel), or even meeting physically. See + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a> + for key exchange, and + <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a> + for password key derivation.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">nonce</var></dt> + <dd class="It-tag">A 24-byte number, used only once with any given session + key. It does not need to be secret or random, but it does have to be + unique. <i class="Em" title="Em">Never</i> use the same nonce twice with + the same key. This would reveal the XOR of 2 different messages, which + allows decryption and forgeries. The easiest (and recommended) way to + generate this nonce is to select it at random. See + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> about + random number generation (use your operating system's random number + generator).</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">mac</var></dt> + <dd class="It-tag">A 16-byte <i class="Em" title="Em">message authentication + code</i> (MAC), that can only be produced by someone who knows the session + key. This guarantee cannot be upheld if a nonce has been reused with the + session key, because doing so allows the attacker to learn the + authentication key associated with that nonce. The MAC is intended to be + sent along with the ciphertext.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">plain_text</var></dt> + <dd class="It-tag">The secret message. Its contents will be kept hidden from + attackers. Its length however, will <i class="Em" title="Em">not</i>. Be + careful when combining encryption with compression. See + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + details.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">cipher_text</var></dt> + <dd class="It-tag">The encrypted message.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">text_size</var></dt> + <dd class="It-tag">Length of both <var class="Fa" title="Fa">plain_text + and</var> <var class="Fa" title="Fa">cipher_text</var>, in bytes.</dd> +</dl> +<div class="Pp"></div> +The <var class="Fa" title="Fa">cipher_text</var> and + <var class="Fa" title="Fa">plain_text</var> arguments may point to the same + buffer for in-place encryption. Otherwise, the buffers they point to must not + overlap. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_unlock</b>() first checks the integrity of an + encrypted message. If it has been corrupted, + <b class="Fn" title="Fn">crypto_unlock</b>() returns -1 immediately. + Otherwise, it decrypts the message, then returns zero. + <i class="Em" title="Em">Always check the return value</i>. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_aead_lock</b>() and + <b class="Fn" title="Fn">crypto_aead_unlock</b>() are variants of + <b class="Fn" title="Fn">crypto_lock</b>() and + <b class="Fn" title="Fn">crypto_unlock</b>(), permitting additional data. + Additional data is authenticated, but <i class="Em" title="Em">not</i> + encrypted. This is used to authenticate relevant data that cannot be + encrypted. The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">ad</var></dt> + <dd class="It-tag">Additional data to authenticate. It will not be encrypted. + May be <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">ad_size</var> is zero. Setting + <var class="Fa" title="Fa">ad_size</var> to zero yields the same results + as <b class="Fn" title="Fn">crypto_lock</b>() and + <b class="Fn" title="Fn">crypto_unlock</b>().</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">ad_size</var></dt> + <dd class="It-tag">Length of the additional data, in bytes. + <b class="Sy" title="Sy">That length is not authenticated.</b> If the + additional data is of variable length, the length should be appended to + <var class="Fa" title="Fa">ad</var> so it gets authenticated, and should + be extracted from the end of the message when decrypting. Otherwise an + attacker could provide a false length, effectively moving the boundary + between the additional data and the ciphertext. This may cause buffer + overflows in some programs.</dd> +</dl> +<div class="Pp"></div> +An incremental interface is available; see + <a class="Xr" title="Xr" href="crypto_lock_init.html">crypto_lock_init(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_lock</b>() and + <b class="Fn" title="Fn">crypto_aead_lock</b>() return nothing. They cannot + fail. <b class="Fn" title="Fn">crypto_unlock</b>() and + <b class="Fn" title="Fn">crypto_aead_unlock</b>() return 0 on success or -1 if + the message was corrupted (i.e. <var class="Fa" title="Fa">mac</var> + mismatched the combination of <var class="Fa" title="Fa">key</var>, + <var class="Fa" title="Fa">nonce</var>, <var class="Fa" title="Fa">ad</var> + and <var class="Fa" title="Fa">cipher_text</var>). Corruption can be caused by + transmission errors, programmer error, or an attacker's interference. + <var class="Fa" title="Fa">plain_text</var> does not need to be wiped if the + decryption fails. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +Encryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [32]; /* Random, secret session key */ +const uint8_t nonce [24]; /* Use only once per key */ +const uint8_t plain_text [500]; /* Secret message */ +uint8_t mac [16]; /* Message authentication code */ +uint8_t cipher_text[500]; /* Encrypted message */ +crypto_lock(mac, cipher_text, key, nonce, plain_text, 500); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(plain_text, 500); +crypto_wipe(key, 32); +/* Transmit cipher_text, nonce, and mac over the network */ +</pre> +</div> +<div class="Pp"></div> +To decrypt the above: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [32]; /* Same as the above */ +const uint8_t nonce [24]; /* Same as the above */ +const uint8_t cipher_text[500]; /* Encrypted message */ +const uint8_t mac [16]; /* Received from the network */ +uint8_t plain_text [500]; /* Secret message */ +if (crypto_unlock(plain_text, key, nonce, mac, cipher_text, 500)) { + /* The message is corrupted. + * Wipe key if it is no longer needed, + * and abort the decryption. + */ + crypto_wipe(key, 32); +} +/* Wipe secrets if they are no longer needed */ +crypto_wipe(plain_text, 500); +crypto_wipe(key, 32); +</pre> +</div> +<div class="Pp"></div> +In-place encryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [32]; /* Random, secret session key */ +const uint8_t nonce[24]; /* Use only once per key */ +uint8_t text [500]; /* Secret message */ +uint8_t mac [16]; /* Message authentication code */ +crypto_lock(mac, text, key, nonce, text, 500); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(key, 32); +/* Transmit text, nonce, and mac over the network */ +</pre> +</div> +<div class="Pp"></div> +In-place decryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [32]; /* Same as the above */ +const uint8_t nonce[24]; /* Same as the above */ +const uint8_t mac [16]; /* Reived from the network */ +uint8_t text [500]; /* Message to decrypt */ +if (crypto_unlock(text, key, nonce, mac, text, 500)) { + /* The message is corrupted. + * Wipe key if it is no longer needed, + * and abort the decryption. + */ + crypto_wipe(key, 32); +} +/* Wipe secrets if they are no longer needed */ +crypto_wipe(text, 500); +crypto_wipe(key, 32); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock_init.html">crypto_lock_init(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement the XChacha20 (encryption) and Poly1305 (MAC) + primitives. Chacha20 and Poly1305 are described in RFC 7539. XChacha20 derives + from Chacha20 the same way XSalsa20 derives from Salsa20, and benefits from + the same security reduction (proven secure as long as Chacha20 itself is + secure). +<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION + DETAILS</a></h1> +<b class="Fn" title="Fn">crypto_aead_lock</b>() and + <b class="Fn" title="Fn">crypto_aead_unlock</b>() do not authenticate the + length themselves to make them compatible with + <b class="Fn" title="Fn">crypto_lock</b>() and + <b class="Fn" title="Fn">crypto_unlock</b>() when the size of the additional + data is zero. This also simplifies the implementation. +<div class="Pp"></div> +This rarely causes problems in practice, because most of the time, the length of + the additional data is either fixed or self-contained, and thus outside of + attacker control.</div> +<table class="foot"> + <tr> + <td class="foot-date">December 28, 2017</td> + <td class="foot-os">Linux 4.4.0-116-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_argon2i.html b/vendor/doc/html/crypto_argon2i.html new file mode 100644 index 0000000..ea49288 --- /dev/null +++ b/vendor/doc/html/crypto_argon2i.html @@ -0,0 +1,258 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_ARGON2I(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_ARGON2I(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_ARGON2I(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_argon2i</b> — + <span class="Nd" title="Nd">password key derivation</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_argon2i</b>(<var class="Fa" title="Fa">uint8_t + *hash</var>, <var class="Fa" title="Fa">uint32_t hash_size</var>, + <var class="Fa" title="Fa">void *work_area</var>, + <var class="Fa" title="Fa">uint32_t nb_blocks</var>, + <var class="Fa" title="Fa">uint32_t nb_iterations</var>, + <var class="Fa" title="Fa">const uint8_t *password</var>, + <var class="Fa" title="Fa">uint32_t password_size</var>, + <var class="Fa" title="Fa">const uint8_t *salt</var>, + <var class="Fa" title="Fa">uint32_t salt_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_argon2i_general</b>(<var class="Fa" title="Fa">uint8_t + *hash</var>, <var class="Fa" title="Fa">uint32_t hash_size</var>, + <var class="Fa" title="Fa">void *work_area</var>, + <var class="Fa" title="Fa">uint32_t nb_blocks</var>, + <var class="Fa" title="Fa">uint32_t nb_iterations</var>, + <var class="Fa" title="Fa">const uint8_t *password</var>, + <var class="Fa" title="Fa">uint32_t password_size</var>, + <var class="Fa" title="Fa">const uint8_t *salt</var>, + <var class="Fa" title="Fa">uint32_t salt_size</var>, + <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">uint32_t key_size</var>, + <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">uint32_t ad_size</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +Argon2i is a resource intensive password key derivation scheme optimised for the + typical x86-like processor. It runs in constant time with respect to the + contents of the password. +<div class="Pp"></div> +Typical applications are password checking (for online services), and key + derivation (for encryption). Derived keys can be used to encrypt, for example, + private keys or password databases. +<div class="Pp"></div> +The version provided by Monocypher has no threading support, so the degree of + parallelism is limited to 1. This is considered good enough for most purposes. +<div class="Pp"></div> +The arguments to <b class="Fn" title="Fn">crypto_argon2i</b>() are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash</var></dt> + <dd class="It-tag">The output hash.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">hash</var>, in bytes. + This argument should be set to 32 or 64 for compatibility with the + <b class="Fn" title="Fn">crypto_verify*</b>() constant time comparison + functions.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">work_area</var></dt> + <dd class="It-tag">Temporary buffer for the algorithm, allocated by the + caller. It must be <var class="Fa" title="Fa">nb_blocks</var> × + 1024 bytes big, and suitably aligned for 64-bit integers. If you are not + sure how to allocate that buffer, just use + <b class="Fn" title="Fn">malloc</b>(). + <div class="Pp"></div> + The work area is automatically wiped by + <b class="Fn" title="Fn">crypto_argon2i</b>().</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">nb_blocks</var></dt> + <dd class="It-tag">The number of blocks for the work area. Must be at least 8. + A value of 100000 (one hundred megabytes) is a good starting point. If the + computation takes too long, reduce this number. If it is too fast, + increase this number. If it is still too fast with all available memory, + increase <var class="Fa" title="Fa">nb_iterations</var>.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">nb_iterations</var></dt> + <dd class="It-tag">The number of iterations. It must be at least 1. A value of + 3 is <i class="Em" title="Em">strongly</i> recommended; any value lower + than 3 enables significantly more efficient attacks.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">password</var></dt> + <dd class="It-tag">The password to hash. It should be wiped with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + after being hashed.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">password_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">password</var>, in + bytes.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">salt</var></dt> + <dd class="It-tag">A password salt. This should be filled with random bytes, + generated separately for each password to be hashed. See + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about generating random bytes (use the operating system's random + number generator).</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">salt_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">salt</var>, in bytes. + Must be at least 8. 16 is recommended.</dd> +</dl> +<div class="Pp"></div> +The output hash must not overlap with the work area, or it will be wiped along + with it. Any other overlap is permitted. +<div class="Pp"></div> +Use + <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a> + or + <a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a> + to compare password hashes to prevent timing attacks. +<div class="Pp"></div> +To select the <var class="Fa" title="Fa">nb_blocks</var> and + <var class="Fa" title="Fa">nb_iterations</var> parameters, it should first be + decided how long the computation should take. For user authentication, values + somewhere between half a second (convenient) and several seconds (paranoid) + are recommended. The computation should use as much memory as can be spared. +<div class="Pp"></div> +Since parameter selection depends on your hardware, some trial and error will be + required in order to determine the ideal settings. Three iterations and 100000 + blocks (that is, one hundred megabytes of memory) is a good starting point. + Adjust <var class="Fa" title="Fa">nb_blocks</var> first. If using all + available memory is not slow enough, increase + <var class="Fa" title="Fa">nb_iterations</var>. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_argon2i_general</b>() is a variant of + <b class="Fn" title="Fn">crypto_argon2i</b>() that supports keyed hashing and + hashing of additional data. The additional arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">A key to use in the hash. Can be + <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">key_size</var> is zero. The key is generally + not needed, but it does have some uses. In the context of password + derivation, it would be stored separately from the password database, and + would remain secret even if an attacker were to steal the database. Note + that changing the key requires rehashing the user's password, which is + only possible upon user login.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">key</var>, in bytes. + Must be zero if there is no key.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">ad</var></dt> + <dd class="It-tag">Additional data. This is additional data that goes into the + hash, similar to the authenticated encryption with authenticated data + (AEAD) construction in + <a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(3monocypher)</a>. + This most likely has no practical application but is exposed for the sake + of completeness. This parameter may be + <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">ad_size</var> is zero.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">ad_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">ad</var>, in bytes. + Must be zero if there is no additional data.</dd> +</dl> +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following example assumes the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +This example shows how to hash a password with the recommended baseline + parameters: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash[32]; /* Output hash */ +char *password = "Okay Password!"; /* User's password */ +uint32_t password_size = 14; /* Password length */ +uint8_t salt[16]; /* Random salt */ +const uint32_t nb_blocks = 100000; /* 100 megabytes */ +const uint32_t nb_iterations = 3; /* 3 iterations */ +void *work_area = malloc(nb_blocks * 1024); /* Work area */ +if (work_area == NULL) { + /* Handle malloc() failure */ + /* Wipe secrets if they are no longer needed */ + crypto_wipe(password, password_size); +} else { + arc4random_buf(salt, 16); + crypto_argon2i(hash, 32, + work_area, nb_blocks, nb_iterations, + (uint8_t *)password, password_size, + salt, 16); + /* Wipe secrets if they are no longer needed */ + crypto_wipe(password, password_size); + free(work_area); +} +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement Argon2i. An RFC draft is being maintained. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_argon2i_general</b>() function first + appeared in Monocypher 0.1 but was called + <b class="Fn" title="Fn">crypto_argon2i</b>(); it was renamed to its current + name in Monocypher 1.1.0. The current + <b class="Fn" title="Fn">crypto_argon2i</b>() first appeared in Monocypher + 1.1.0. +<h1 class="Sh" title="Sh" id="CAVEATS"><a class="selflink" href="#CAVEATS">CAVEATS</a></h1> +Any deviation from the specified input and output length ranges results in + <b class="Sy" title="Sy">undefined behaviour</b>. Make sure your inputs are + correct.</div> +<table class="foot"> + <tr> + <td class="foot-date">April 8, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_argon2i_general.html b/vendor/doc/html/crypto_argon2i_general.html new file mode 100644 index 0000000..ea49288 --- /dev/null +++ b/vendor/doc/html/crypto_argon2i_general.html @@ -0,0 +1,258 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_ARGON2I(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_ARGON2I(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_ARGON2I(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_argon2i</b> — + <span class="Nd" title="Nd">password key derivation</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_argon2i</b>(<var class="Fa" title="Fa">uint8_t + *hash</var>, <var class="Fa" title="Fa">uint32_t hash_size</var>, + <var class="Fa" title="Fa">void *work_area</var>, + <var class="Fa" title="Fa">uint32_t nb_blocks</var>, + <var class="Fa" title="Fa">uint32_t nb_iterations</var>, + <var class="Fa" title="Fa">const uint8_t *password</var>, + <var class="Fa" title="Fa">uint32_t password_size</var>, + <var class="Fa" title="Fa">const uint8_t *salt</var>, + <var class="Fa" title="Fa">uint32_t salt_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_argon2i_general</b>(<var class="Fa" title="Fa">uint8_t + *hash</var>, <var class="Fa" title="Fa">uint32_t hash_size</var>, + <var class="Fa" title="Fa">void *work_area</var>, + <var class="Fa" title="Fa">uint32_t nb_blocks</var>, + <var class="Fa" title="Fa">uint32_t nb_iterations</var>, + <var class="Fa" title="Fa">const uint8_t *password</var>, + <var class="Fa" title="Fa">uint32_t password_size</var>, + <var class="Fa" title="Fa">const uint8_t *salt</var>, + <var class="Fa" title="Fa">uint32_t salt_size</var>, + <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">uint32_t key_size</var>, + <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">uint32_t ad_size</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +Argon2i is a resource intensive password key derivation scheme optimised for the + typical x86-like processor. It runs in constant time with respect to the + contents of the password. +<div class="Pp"></div> +Typical applications are password checking (for online services), and key + derivation (for encryption). Derived keys can be used to encrypt, for example, + private keys or password databases. +<div class="Pp"></div> +The version provided by Monocypher has no threading support, so the degree of + parallelism is limited to 1. This is considered good enough for most purposes. +<div class="Pp"></div> +The arguments to <b class="Fn" title="Fn">crypto_argon2i</b>() are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash</var></dt> + <dd class="It-tag">The output hash.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">hash</var>, in bytes. + This argument should be set to 32 or 64 for compatibility with the + <b class="Fn" title="Fn">crypto_verify*</b>() constant time comparison + functions.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">work_area</var></dt> + <dd class="It-tag">Temporary buffer for the algorithm, allocated by the + caller. It must be <var class="Fa" title="Fa">nb_blocks</var> × + 1024 bytes big, and suitably aligned for 64-bit integers. If you are not + sure how to allocate that buffer, just use + <b class="Fn" title="Fn">malloc</b>(). + <div class="Pp"></div> + The work area is automatically wiped by + <b class="Fn" title="Fn">crypto_argon2i</b>().</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">nb_blocks</var></dt> + <dd class="It-tag">The number of blocks for the work area. Must be at least 8. + A value of 100000 (one hundred megabytes) is a good starting point. If the + computation takes too long, reduce this number. If it is too fast, + increase this number. If it is still too fast with all available memory, + increase <var class="Fa" title="Fa">nb_iterations</var>.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">nb_iterations</var></dt> + <dd class="It-tag">The number of iterations. It must be at least 1. A value of + 3 is <i class="Em" title="Em">strongly</i> recommended; any value lower + than 3 enables significantly more efficient attacks.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">password</var></dt> + <dd class="It-tag">The password to hash. It should be wiped with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + after being hashed.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">password_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">password</var>, in + bytes.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">salt</var></dt> + <dd class="It-tag">A password salt. This should be filled with random bytes, + generated separately for each password to be hashed. See + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about generating random bytes (use the operating system's random + number generator).</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">salt_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">salt</var>, in bytes. + Must be at least 8. 16 is recommended.</dd> +</dl> +<div class="Pp"></div> +The output hash must not overlap with the work area, or it will be wiped along + with it. Any other overlap is permitted. +<div class="Pp"></div> +Use + <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a> + or + <a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a> + to compare password hashes to prevent timing attacks. +<div class="Pp"></div> +To select the <var class="Fa" title="Fa">nb_blocks</var> and + <var class="Fa" title="Fa">nb_iterations</var> parameters, it should first be + decided how long the computation should take. For user authentication, values + somewhere between half a second (convenient) and several seconds (paranoid) + are recommended. The computation should use as much memory as can be spared. +<div class="Pp"></div> +Since parameter selection depends on your hardware, some trial and error will be + required in order to determine the ideal settings. Three iterations and 100000 + blocks (that is, one hundred megabytes of memory) is a good starting point. + Adjust <var class="Fa" title="Fa">nb_blocks</var> first. If using all + available memory is not slow enough, increase + <var class="Fa" title="Fa">nb_iterations</var>. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_argon2i_general</b>() is a variant of + <b class="Fn" title="Fn">crypto_argon2i</b>() that supports keyed hashing and + hashing of additional data. The additional arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">A key to use in the hash. Can be + <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">key_size</var> is zero. The key is generally + not needed, but it does have some uses. In the context of password + derivation, it would be stored separately from the password database, and + would remain secret even if an attacker were to steal the database. Note + that changing the key requires rehashing the user's password, which is + only possible upon user login.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">key</var>, in bytes. + Must be zero if there is no key.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">ad</var></dt> + <dd class="It-tag">Additional data. This is additional data that goes into the + hash, similar to the authenticated encryption with authenticated data + (AEAD) construction in + <a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(3monocypher)</a>. + This most likely has no practical application but is exposed for the sake + of completeness. This parameter may be + <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">ad_size</var> is zero.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">ad_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">ad</var>, in bytes. + Must be zero if there is no additional data.</dd> +</dl> +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following example assumes the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +This example shows how to hash a password with the recommended baseline + parameters: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash[32]; /* Output hash */ +char *password = "Okay Password!"; /* User's password */ +uint32_t password_size = 14; /* Password length */ +uint8_t salt[16]; /* Random salt */ +const uint32_t nb_blocks = 100000; /* 100 megabytes */ +const uint32_t nb_iterations = 3; /* 3 iterations */ +void *work_area = malloc(nb_blocks * 1024); /* Work area */ +if (work_area == NULL) { + /* Handle malloc() failure */ + /* Wipe secrets if they are no longer needed */ + crypto_wipe(password, password_size); +} else { + arc4random_buf(salt, 16); + crypto_argon2i(hash, 32, + work_area, nb_blocks, nb_iterations, + (uint8_t *)password, password_size, + salt, 16); + /* Wipe secrets if they are no longer needed */ + crypto_wipe(password, password_size); + free(work_area); +} +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement Argon2i. An RFC draft is being maintained. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_argon2i_general</b>() function first + appeared in Monocypher 0.1 but was called + <b class="Fn" title="Fn">crypto_argon2i</b>(); it was renamed to its current + name in Monocypher 1.1.0. The current + <b class="Fn" title="Fn">crypto_argon2i</b>() first appeared in Monocypher + 1.1.0. +<h1 class="Sh" title="Sh" id="CAVEATS"><a class="selflink" href="#CAVEATS">CAVEATS</a></h1> +Any deviation from the specified input and output length ranges results in + <b class="Sy" title="Sy">undefined behaviour</b>. Make sure your inputs are + correct.</div> +<table class="foot"> + <tr> + <td class="foot-date">April 8, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_blake2b.html b/vendor/doc/html/crypto_blake2b.html new file mode 100644 index 0000000..727a748 --- /dev/null +++ b/vendor/doc/html/crypto_blake2b.html @@ -0,0 +1,279 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_BLAKE2B(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_BLAKE2B(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_BLAKE2B(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_blake2b</b>, + <b class="Nm" title="Nm">crypto_blake2b_general</b>, + <b class="Nm" title="Nm">crypto_blake2b_general_init</b>, + <b class="Nm" title="Nm">crypto_blake2b_init</b>, + <b class="Nm" title="Nm">crypto_blake2b_update</b>, + <b class="Nm" title="Nm">crypto_blake2b_final</b> — + <span class="Nd" title="Nd">cryptographic hashing</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b</b>(<var class="Fa" title="Fa">uint8_t + hash[64]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_general</b>(<var class="Fa" title="Fa">uint8_t + *hash</var>, <var class="Fa" title="Fa">size_t hash_size</var>, + <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>, + <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_init</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_general_init</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">size_t hash_size</var>, + <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_update</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_final</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *hash</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +BLAKE2b is a fast cryptographically secure hash, based on the ideas of Chacha20. + It is faster than MD5, yet just as secure as SHA-3. +<div class="Pp"></div> +Note that BLAKE2b itself is not suitable for hashing passwords and deriving keys + from them; use the + <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a> + family of functions for that purpose instead. +<div class="Pp"></div> +BLAKE2b is immune to length extension attacks, and as such does not require any + specific precautions, such as using the HMAC algorithm. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash</var></dt> + <dd class="It-tag">The output hash.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">hash</var>, in bytes. + Must be between 1 and 64. Anything below 32 is discouraged when using + Blake2b as a general-purpose hash function; anything below 16 is + discouraged when using Blake2b as a message authentication code.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">Some secret key. One cannot predict the final hash without + it. May be <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">key_size</var> is 0, in which case no key is + used. Keys can be used to create a message authentication code (MAC). Use + <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a>, + or + <a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a> + to compare MACs created this way. Choose the size of the hash accordingly. + Users may want to wipe the key with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + once they are done with it.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">key</var>, in bytes. + Must be between 0 and 64. 32 is a good default.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message</var></dt> + <dd class="It-tag">The message to hash. May overlap with + <var class="Fa" title="Fa">hash</var>. May be + <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">message_size</var> is 0.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">message</var>, in + bytes.</dd> +</dl> +<h2 class="Ss" title="Ss" id="Direct_interface"><a class="selflink" href="#Direct_interface">Direct + interface</a></h2> +The direct interface has two functions, + <b class="Fn" title="Fn">crypto_blake2b</b>() and + <b class="Fn" title="Fn">crypto_blake2b_general</b>(). + <b class="Fn" title="Fn">crypto_blake2b</b>() is provided for convenience, and + is equivalent to calling <b class="Fn" title="Fn">crypto_blake2b_general</b>() + with no key and a 64-byte hash. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_blake2b_general</b>() users can specify the size + of the hash, and use a secret key to make the hash unpredictable – + useful for message authentication codes. Even when using a key, you do not + have to wipe the context struct with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>. +<h2 class="Ss" title="Ss" id="Incremental_interface"><a class="selflink" href="#Incremental_interface">Incremental + interface</a></h2> +The incremental interface is useful for handling streams of data or large files + without using too much memory. This interface uses three steps: +<ul class="Bl-bullet"> + <li class="It-bullet">initialisation with + <b class="Fn" title="Fn">crypto_blake2b_general_init</b>() or + <b class="Fn" title="Fn">crypto_blake2b_init</b>(), which sets up a + context with the hashing parameters;</li> + <li class="It-bullet">update with + <b class="Fn" title="Fn">crypto_blake2b_update</b>(), which hashes the + message chunk by chunk, and keep the intermediary result in the + context;</li> + <li class="It-bullet">and finalisation with + <b class="Fn" title="Fn">crypto_blake2b_final</b>(), which produces the + final hash. The <var class="Ft" title="Ft">crypto_blake2b_ctx</var> is + automatically wiped upon finalisation.</li> +</ul> +<div class="Pp"></div> +The invariants of the parameters are the same as for + <b class="Fn" title="Fn">crypto_blake2b_general</b>(). + <b class="Fn" title="Fn">crypto_blake2b_init</b>() is a convenience + initialisation function that specifies a 64-byte hash and no key. This is + considered a good default. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Hashing a message all at once: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [64]; /* Output hash (64 bytes) */ +uint8_t message[12] = "Lorem ipsum"; /* Message to hash */ +crypto_blake2b(hash, message, 12); +</pre> +</div> +<div class="Pp"></div> +Computing a message authentication code all at once: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [16]; +uint8_t key [32]; +uint8_t message[11] = "Lorem ipsu"; /* Message to authenticate */ +arc4random_buf(key, 32); +crypto_blake2b_general(hash, 16, key, 32, message, 11); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(message, 11); +crypto_wipe(key, 32); +</pre> +</div> +<div class="Pp"></div> +Hashing a message incrementally (without a key): +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [ 64]; /* Output hash (64 bytes) */ +uint8_t message[500] = {1}; /* Message to hash */ +crypto_blake2b_ctx ctx; +crypto_blake2b_init(&ctx); +for (size_t i = 0; i < 500; i += 100) { + crypto_blake2b_update(&ctx, message + i, 100); +} +crypto_blake2b_final(&ctx, hash); +</pre> +</div> +<div class="Pp"></div> +Computing a message authentication code incrementally: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [ 16]; +uint8_t key [ 32]; +uint8_t message[500] = {1}; /* Message to authenticate */ +crypto_blake2b_ctx ctx; +arc4random_buf(key, 32); +crypto_blake2b_general_init(&ctx, 16, key, 32); +/* Wipe the key */ +crypto_wipe(key, 32); +for (size_t i = 0; i < 500; i += 100) { + crypto_blake2b_update(&ctx, message + i, 100); + /* Wipe secrets if they are no longer needed */ + crypto_wipe(message + i, 100); +} +crypto_blake2b_final(&ctx, hash); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement BLAKE2b, described in RFC 7693. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_blake2b</b>(), + <b class="Fn" title="Fn">crypto_blake2b_general</b>(), + <b class="Fn" title="Fn">crypto_blake2b_general_init</b>(), + <b class="Fn" title="Fn">crypto_blake2b_init</b>(), + <b class="Fn" title="Fn">crypto_blake2b_update</b>(), and + <b class="Fn" title="Fn">crypto_blake2b_final</b>() functions first appeared + in Monocypher 0.1. +<h1 class="Sh" title="Sh" id="CAVEATS"><a class="selflink" href="#CAVEATS">CAVEATS</a></h1> +Monocypher does not perform any input validation. Any deviation from the + specified input and output length ranges results in + <b class="Sy" title="Sy">undefined behaviour</b>. Make sure your inputs are + correct. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +BLAKE2b is a general-purpose cryptographic hash function; this means that it is + not suited for hashing passwords and deriving cryptographic keys from + passwords in particular. While cryptographic keys usually have hundreds of + bits of entropy, passwords are often much less complex. When storing passwords + as hashes or when deriving keys from them, the goal is normally to prevent + attackers from quickly iterating all possible passwords. Because passwords + tend to be simple, it is important to artificially slow down attackers by + using especially computationally difficult hashing algorithms. Monocypher + therefore provides + <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a> + for password hashing and deriving keys from passwords.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_blake2b_final.html b/vendor/doc/html/crypto_blake2b_final.html new file mode 100644 index 0000000..727a748 --- /dev/null +++ b/vendor/doc/html/crypto_blake2b_final.html @@ -0,0 +1,279 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_BLAKE2B(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_BLAKE2B(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_BLAKE2B(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_blake2b</b>, + <b class="Nm" title="Nm">crypto_blake2b_general</b>, + <b class="Nm" title="Nm">crypto_blake2b_general_init</b>, + <b class="Nm" title="Nm">crypto_blake2b_init</b>, + <b class="Nm" title="Nm">crypto_blake2b_update</b>, + <b class="Nm" title="Nm">crypto_blake2b_final</b> — + <span class="Nd" title="Nd">cryptographic hashing</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b</b>(<var class="Fa" title="Fa">uint8_t + hash[64]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_general</b>(<var class="Fa" title="Fa">uint8_t + *hash</var>, <var class="Fa" title="Fa">size_t hash_size</var>, + <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>, + <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_init</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_general_init</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">size_t hash_size</var>, + <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_update</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_final</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *hash</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +BLAKE2b is a fast cryptographically secure hash, based on the ideas of Chacha20. + It is faster than MD5, yet just as secure as SHA-3. +<div class="Pp"></div> +Note that BLAKE2b itself is not suitable for hashing passwords and deriving keys + from them; use the + <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a> + family of functions for that purpose instead. +<div class="Pp"></div> +BLAKE2b is immune to length extension attacks, and as such does not require any + specific precautions, such as using the HMAC algorithm. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash</var></dt> + <dd class="It-tag">The output hash.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">hash</var>, in bytes. + Must be between 1 and 64. Anything below 32 is discouraged when using + Blake2b as a general-purpose hash function; anything below 16 is + discouraged when using Blake2b as a message authentication code.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">Some secret key. One cannot predict the final hash without + it. May be <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">key_size</var> is 0, in which case no key is + used. Keys can be used to create a message authentication code (MAC). Use + <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a>, + or + <a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a> + to compare MACs created this way. Choose the size of the hash accordingly. + Users may want to wipe the key with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + once they are done with it.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">key</var>, in bytes. + Must be between 0 and 64. 32 is a good default.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message</var></dt> + <dd class="It-tag">The message to hash. May overlap with + <var class="Fa" title="Fa">hash</var>. May be + <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">message_size</var> is 0.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">message</var>, in + bytes.</dd> +</dl> +<h2 class="Ss" title="Ss" id="Direct_interface"><a class="selflink" href="#Direct_interface">Direct + interface</a></h2> +The direct interface has two functions, + <b class="Fn" title="Fn">crypto_blake2b</b>() and + <b class="Fn" title="Fn">crypto_blake2b_general</b>(). + <b class="Fn" title="Fn">crypto_blake2b</b>() is provided for convenience, and + is equivalent to calling <b class="Fn" title="Fn">crypto_blake2b_general</b>() + with no key and a 64-byte hash. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_blake2b_general</b>() users can specify the size + of the hash, and use a secret key to make the hash unpredictable – + useful for message authentication codes. Even when using a key, you do not + have to wipe the context struct with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>. +<h2 class="Ss" title="Ss" id="Incremental_interface"><a class="selflink" href="#Incremental_interface">Incremental + interface</a></h2> +The incremental interface is useful for handling streams of data or large files + without using too much memory. This interface uses three steps: +<ul class="Bl-bullet"> + <li class="It-bullet">initialisation with + <b class="Fn" title="Fn">crypto_blake2b_general_init</b>() or + <b class="Fn" title="Fn">crypto_blake2b_init</b>(), which sets up a + context with the hashing parameters;</li> + <li class="It-bullet">update with + <b class="Fn" title="Fn">crypto_blake2b_update</b>(), which hashes the + message chunk by chunk, and keep the intermediary result in the + context;</li> + <li class="It-bullet">and finalisation with + <b class="Fn" title="Fn">crypto_blake2b_final</b>(), which produces the + final hash. The <var class="Ft" title="Ft">crypto_blake2b_ctx</var> is + automatically wiped upon finalisation.</li> +</ul> +<div class="Pp"></div> +The invariants of the parameters are the same as for + <b class="Fn" title="Fn">crypto_blake2b_general</b>(). + <b class="Fn" title="Fn">crypto_blake2b_init</b>() is a convenience + initialisation function that specifies a 64-byte hash and no key. This is + considered a good default. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Hashing a message all at once: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [64]; /* Output hash (64 bytes) */ +uint8_t message[12] = "Lorem ipsum"; /* Message to hash */ +crypto_blake2b(hash, message, 12); +</pre> +</div> +<div class="Pp"></div> +Computing a message authentication code all at once: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [16]; +uint8_t key [32]; +uint8_t message[11] = "Lorem ipsu"; /* Message to authenticate */ +arc4random_buf(key, 32); +crypto_blake2b_general(hash, 16, key, 32, message, 11); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(message, 11); +crypto_wipe(key, 32); +</pre> +</div> +<div class="Pp"></div> +Hashing a message incrementally (without a key): +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [ 64]; /* Output hash (64 bytes) */ +uint8_t message[500] = {1}; /* Message to hash */ +crypto_blake2b_ctx ctx; +crypto_blake2b_init(&ctx); +for (size_t i = 0; i < 500; i += 100) { + crypto_blake2b_update(&ctx, message + i, 100); +} +crypto_blake2b_final(&ctx, hash); +</pre> +</div> +<div class="Pp"></div> +Computing a message authentication code incrementally: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [ 16]; +uint8_t key [ 32]; +uint8_t message[500] = {1}; /* Message to authenticate */ +crypto_blake2b_ctx ctx; +arc4random_buf(key, 32); +crypto_blake2b_general_init(&ctx, 16, key, 32); +/* Wipe the key */ +crypto_wipe(key, 32); +for (size_t i = 0; i < 500; i += 100) { + crypto_blake2b_update(&ctx, message + i, 100); + /* Wipe secrets if they are no longer needed */ + crypto_wipe(message + i, 100); +} +crypto_blake2b_final(&ctx, hash); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement BLAKE2b, described in RFC 7693. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_blake2b</b>(), + <b class="Fn" title="Fn">crypto_blake2b_general</b>(), + <b class="Fn" title="Fn">crypto_blake2b_general_init</b>(), + <b class="Fn" title="Fn">crypto_blake2b_init</b>(), + <b class="Fn" title="Fn">crypto_blake2b_update</b>(), and + <b class="Fn" title="Fn">crypto_blake2b_final</b>() functions first appeared + in Monocypher 0.1. +<h1 class="Sh" title="Sh" id="CAVEATS"><a class="selflink" href="#CAVEATS">CAVEATS</a></h1> +Monocypher does not perform any input validation. Any deviation from the + specified input and output length ranges results in + <b class="Sy" title="Sy">undefined behaviour</b>. Make sure your inputs are + correct. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +BLAKE2b is a general-purpose cryptographic hash function; this means that it is + not suited for hashing passwords and deriving cryptographic keys from + passwords in particular. While cryptographic keys usually have hundreds of + bits of entropy, passwords are often much less complex. When storing passwords + as hashes or when deriving keys from them, the goal is normally to prevent + attackers from quickly iterating all possible passwords. Because passwords + tend to be simple, it is important to artificially slow down attackers by + using especially computationally difficult hashing algorithms. Monocypher + therefore provides + <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a> + for password hashing and deriving keys from passwords.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_blake2b_general.html b/vendor/doc/html/crypto_blake2b_general.html new file mode 100644 index 0000000..727a748 --- /dev/null +++ b/vendor/doc/html/crypto_blake2b_general.html @@ -0,0 +1,279 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_BLAKE2B(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_BLAKE2B(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_BLAKE2B(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_blake2b</b>, + <b class="Nm" title="Nm">crypto_blake2b_general</b>, + <b class="Nm" title="Nm">crypto_blake2b_general_init</b>, + <b class="Nm" title="Nm">crypto_blake2b_init</b>, + <b class="Nm" title="Nm">crypto_blake2b_update</b>, + <b class="Nm" title="Nm">crypto_blake2b_final</b> — + <span class="Nd" title="Nd">cryptographic hashing</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b</b>(<var class="Fa" title="Fa">uint8_t + hash[64]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_general</b>(<var class="Fa" title="Fa">uint8_t + *hash</var>, <var class="Fa" title="Fa">size_t hash_size</var>, + <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>, + <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_init</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_general_init</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">size_t hash_size</var>, + <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_update</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_final</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *hash</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +BLAKE2b is a fast cryptographically secure hash, based on the ideas of Chacha20. + It is faster than MD5, yet just as secure as SHA-3. +<div class="Pp"></div> +Note that BLAKE2b itself is not suitable for hashing passwords and deriving keys + from them; use the + <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a> + family of functions for that purpose instead. +<div class="Pp"></div> +BLAKE2b is immune to length extension attacks, and as such does not require any + specific precautions, such as using the HMAC algorithm. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash</var></dt> + <dd class="It-tag">The output hash.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">hash</var>, in bytes. + Must be between 1 and 64. Anything below 32 is discouraged when using + Blake2b as a general-purpose hash function; anything below 16 is + discouraged when using Blake2b as a message authentication code.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">Some secret key. One cannot predict the final hash without + it. May be <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">key_size</var> is 0, in which case no key is + used. Keys can be used to create a message authentication code (MAC). Use + <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a>, + or + <a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a> + to compare MACs created this way. Choose the size of the hash accordingly. + Users may want to wipe the key with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + once they are done with it.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">key</var>, in bytes. + Must be between 0 and 64. 32 is a good default.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message</var></dt> + <dd class="It-tag">The message to hash. May overlap with + <var class="Fa" title="Fa">hash</var>. May be + <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">message_size</var> is 0.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">message</var>, in + bytes.</dd> +</dl> +<h2 class="Ss" title="Ss" id="Direct_interface"><a class="selflink" href="#Direct_interface">Direct + interface</a></h2> +The direct interface has two functions, + <b class="Fn" title="Fn">crypto_blake2b</b>() and + <b class="Fn" title="Fn">crypto_blake2b_general</b>(). + <b class="Fn" title="Fn">crypto_blake2b</b>() is provided for convenience, and + is equivalent to calling <b class="Fn" title="Fn">crypto_blake2b_general</b>() + with no key and a 64-byte hash. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_blake2b_general</b>() users can specify the size + of the hash, and use a secret key to make the hash unpredictable – + useful for message authentication codes. Even when using a key, you do not + have to wipe the context struct with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>. +<h2 class="Ss" title="Ss" id="Incremental_interface"><a class="selflink" href="#Incremental_interface">Incremental + interface</a></h2> +The incremental interface is useful for handling streams of data or large files + without using too much memory. This interface uses three steps: +<ul class="Bl-bullet"> + <li class="It-bullet">initialisation with + <b class="Fn" title="Fn">crypto_blake2b_general_init</b>() or + <b class="Fn" title="Fn">crypto_blake2b_init</b>(), which sets up a + context with the hashing parameters;</li> + <li class="It-bullet">update with + <b class="Fn" title="Fn">crypto_blake2b_update</b>(), which hashes the + message chunk by chunk, and keep the intermediary result in the + context;</li> + <li class="It-bullet">and finalisation with + <b class="Fn" title="Fn">crypto_blake2b_final</b>(), which produces the + final hash. The <var class="Ft" title="Ft">crypto_blake2b_ctx</var> is + automatically wiped upon finalisation.</li> +</ul> +<div class="Pp"></div> +The invariants of the parameters are the same as for + <b class="Fn" title="Fn">crypto_blake2b_general</b>(). + <b class="Fn" title="Fn">crypto_blake2b_init</b>() is a convenience + initialisation function that specifies a 64-byte hash and no key. This is + considered a good default. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Hashing a message all at once: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [64]; /* Output hash (64 bytes) */ +uint8_t message[12] = "Lorem ipsum"; /* Message to hash */ +crypto_blake2b(hash, message, 12); +</pre> +</div> +<div class="Pp"></div> +Computing a message authentication code all at once: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [16]; +uint8_t key [32]; +uint8_t message[11] = "Lorem ipsu"; /* Message to authenticate */ +arc4random_buf(key, 32); +crypto_blake2b_general(hash, 16, key, 32, message, 11); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(message, 11); +crypto_wipe(key, 32); +</pre> +</div> +<div class="Pp"></div> +Hashing a message incrementally (without a key): +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [ 64]; /* Output hash (64 bytes) */ +uint8_t message[500] = {1}; /* Message to hash */ +crypto_blake2b_ctx ctx; +crypto_blake2b_init(&ctx); +for (size_t i = 0; i < 500; i += 100) { + crypto_blake2b_update(&ctx, message + i, 100); +} +crypto_blake2b_final(&ctx, hash); +</pre> +</div> +<div class="Pp"></div> +Computing a message authentication code incrementally: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [ 16]; +uint8_t key [ 32]; +uint8_t message[500] = {1}; /* Message to authenticate */ +crypto_blake2b_ctx ctx; +arc4random_buf(key, 32); +crypto_blake2b_general_init(&ctx, 16, key, 32); +/* Wipe the key */ +crypto_wipe(key, 32); +for (size_t i = 0; i < 500; i += 100) { + crypto_blake2b_update(&ctx, message + i, 100); + /* Wipe secrets if they are no longer needed */ + crypto_wipe(message + i, 100); +} +crypto_blake2b_final(&ctx, hash); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement BLAKE2b, described in RFC 7693. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_blake2b</b>(), + <b class="Fn" title="Fn">crypto_blake2b_general</b>(), + <b class="Fn" title="Fn">crypto_blake2b_general_init</b>(), + <b class="Fn" title="Fn">crypto_blake2b_init</b>(), + <b class="Fn" title="Fn">crypto_blake2b_update</b>(), and + <b class="Fn" title="Fn">crypto_blake2b_final</b>() functions first appeared + in Monocypher 0.1. +<h1 class="Sh" title="Sh" id="CAVEATS"><a class="selflink" href="#CAVEATS">CAVEATS</a></h1> +Monocypher does not perform any input validation. Any deviation from the + specified input and output length ranges results in + <b class="Sy" title="Sy">undefined behaviour</b>. Make sure your inputs are + correct. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +BLAKE2b is a general-purpose cryptographic hash function; this means that it is + not suited for hashing passwords and deriving cryptographic keys from + passwords in particular. While cryptographic keys usually have hundreds of + bits of entropy, passwords are often much less complex. When storing passwords + as hashes or when deriving keys from them, the goal is normally to prevent + attackers from quickly iterating all possible passwords. Because passwords + tend to be simple, it is important to artificially slow down attackers by + using especially computationally difficult hashing algorithms. Monocypher + therefore provides + <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a> + for password hashing and deriving keys from passwords.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_blake2b_general_init.html b/vendor/doc/html/crypto_blake2b_general_init.html new file mode 100644 index 0000000..727a748 --- /dev/null +++ b/vendor/doc/html/crypto_blake2b_general_init.html @@ -0,0 +1,279 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_BLAKE2B(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_BLAKE2B(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_BLAKE2B(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_blake2b</b>, + <b class="Nm" title="Nm">crypto_blake2b_general</b>, + <b class="Nm" title="Nm">crypto_blake2b_general_init</b>, + <b class="Nm" title="Nm">crypto_blake2b_init</b>, + <b class="Nm" title="Nm">crypto_blake2b_update</b>, + <b class="Nm" title="Nm">crypto_blake2b_final</b> — + <span class="Nd" title="Nd">cryptographic hashing</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b</b>(<var class="Fa" title="Fa">uint8_t + hash[64]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_general</b>(<var class="Fa" title="Fa">uint8_t + *hash</var>, <var class="Fa" title="Fa">size_t hash_size</var>, + <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>, + <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_init</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_general_init</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">size_t hash_size</var>, + <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_update</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_final</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *hash</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +BLAKE2b is a fast cryptographically secure hash, based on the ideas of Chacha20. + It is faster than MD5, yet just as secure as SHA-3. +<div class="Pp"></div> +Note that BLAKE2b itself is not suitable for hashing passwords and deriving keys + from them; use the + <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a> + family of functions for that purpose instead. +<div class="Pp"></div> +BLAKE2b is immune to length extension attacks, and as such does not require any + specific precautions, such as using the HMAC algorithm. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash</var></dt> + <dd class="It-tag">The output hash.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">hash</var>, in bytes. + Must be between 1 and 64. Anything below 32 is discouraged when using + Blake2b as a general-purpose hash function; anything below 16 is + discouraged when using Blake2b as a message authentication code.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">Some secret key. One cannot predict the final hash without + it. May be <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">key_size</var> is 0, in which case no key is + used. Keys can be used to create a message authentication code (MAC). Use + <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a>, + or + <a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a> + to compare MACs created this way. Choose the size of the hash accordingly. + Users may want to wipe the key with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + once they are done with it.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">key</var>, in bytes. + Must be between 0 and 64. 32 is a good default.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message</var></dt> + <dd class="It-tag">The message to hash. May overlap with + <var class="Fa" title="Fa">hash</var>. May be + <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">message_size</var> is 0.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">message</var>, in + bytes.</dd> +</dl> +<h2 class="Ss" title="Ss" id="Direct_interface"><a class="selflink" href="#Direct_interface">Direct + interface</a></h2> +The direct interface has two functions, + <b class="Fn" title="Fn">crypto_blake2b</b>() and + <b class="Fn" title="Fn">crypto_blake2b_general</b>(). + <b class="Fn" title="Fn">crypto_blake2b</b>() is provided for convenience, and + is equivalent to calling <b class="Fn" title="Fn">crypto_blake2b_general</b>() + with no key and a 64-byte hash. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_blake2b_general</b>() users can specify the size + of the hash, and use a secret key to make the hash unpredictable – + useful for message authentication codes. Even when using a key, you do not + have to wipe the context struct with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>. +<h2 class="Ss" title="Ss" id="Incremental_interface"><a class="selflink" href="#Incremental_interface">Incremental + interface</a></h2> +The incremental interface is useful for handling streams of data or large files + without using too much memory. This interface uses three steps: +<ul class="Bl-bullet"> + <li class="It-bullet">initialisation with + <b class="Fn" title="Fn">crypto_blake2b_general_init</b>() or + <b class="Fn" title="Fn">crypto_blake2b_init</b>(), which sets up a + context with the hashing parameters;</li> + <li class="It-bullet">update with + <b class="Fn" title="Fn">crypto_blake2b_update</b>(), which hashes the + message chunk by chunk, and keep the intermediary result in the + context;</li> + <li class="It-bullet">and finalisation with + <b class="Fn" title="Fn">crypto_blake2b_final</b>(), which produces the + final hash. The <var class="Ft" title="Ft">crypto_blake2b_ctx</var> is + automatically wiped upon finalisation.</li> +</ul> +<div class="Pp"></div> +The invariants of the parameters are the same as for + <b class="Fn" title="Fn">crypto_blake2b_general</b>(). + <b class="Fn" title="Fn">crypto_blake2b_init</b>() is a convenience + initialisation function that specifies a 64-byte hash and no key. This is + considered a good default. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Hashing a message all at once: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [64]; /* Output hash (64 bytes) */ +uint8_t message[12] = "Lorem ipsum"; /* Message to hash */ +crypto_blake2b(hash, message, 12); +</pre> +</div> +<div class="Pp"></div> +Computing a message authentication code all at once: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [16]; +uint8_t key [32]; +uint8_t message[11] = "Lorem ipsu"; /* Message to authenticate */ +arc4random_buf(key, 32); +crypto_blake2b_general(hash, 16, key, 32, message, 11); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(message, 11); +crypto_wipe(key, 32); +</pre> +</div> +<div class="Pp"></div> +Hashing a message incrementally (without a key): +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [ 64]; /* Output hash (64 bytes) */ +uint8_t message[500] = {1}; /* Message to hash */ +crypto_blake2b_ctx ctx; +crypto_blake2b_init(&ctx); +for (size_t i = 0; i < 500; i += 100) { + crypto_blake2b_update(&ctx, message + i, 100); +} +crypto_blake2b_final(&ctx, hash); +</pre> +</div> +<div class="Pp"></div> +Computing a message authentication code incrementally: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [ 16]; +uint8_t key [ 32]; +uint8_t message[500] = {1}; /* Message to authenticate */ +crypto_blake2b_ctx ctx; +arc4random_buf(key, 32); +crypto_blake2b_general_init(&ctx, 16, key, 32); +/* Wipe the key */ +crypto_wipe(key, 32); +for (size_t i = 0; i < 500; i += 100) { + crypto_blake2b_update(&ctx, message + i, 100); + /* Wipe secrets if they are no longer needed */ + crypto_wipe(message + i, 100); +} +crypto_blake2b_final(&ctx, hash); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement BLAKE2b, described in RFC 7693. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_blake2b</b>(), + <b class="Fn" title="Fn">crypto_blake2b_general</b>(), + <b class="Fn" title="Fn">crypto_blake2b_general_init</b>(), + <b class="Fn" title="Fn">crypto_blake2b_init</b>(), + <b class="Fn" title="Fn">crypto_blake2b_update</b>(), and + <b class="Fn" title="Fn">crypto_blake2b_final</b>() functions first appeared + in Monocypher 0.1. +<h1 class="Sh" title="Sh" id="CAVEATS"><a class="selflink" href="#CAVEATS">CAVEATS</a></h1> +Monocypher does not perform any input validation. Any deviation from the + specified input and output length ranges results in + <b class="Sy" title="Sy">undefined behaviour</b>. Make sure your inputs are + correct. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +BLAKE2b is a general-purpose cryptographic hash function; this means that it is + not suited for hashing passwords and deriving cryptographic keys from + passwords in particular. While cryptographic keys usually have hundreds of + bits of entropy, passwords are often much less complex. When storing passwords + as hashes or when deriving keys from them, the goal is normally to prevent + attackers from quickly iterating all possible passwords. Because passwords + tend to be simple, it is important to artificially slow down attackers by + using especially computationally difficult hashing algorithms. Monocypher + therefore provides + <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a> + for password hashing and deriving keys from passwords.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_blake2b_init.html b/vendor/doc/html/crypto_blake2b_init.html new file mode 100644 index 0000000..727a748 --- /dev/null +++ b/vendor/doc/html/crypto_blake2b_init.html @@ -0,0 +1,279 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_BLAKE2B(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_BLAKE2B(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_BLAKE2B(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_blake2b</b>, + <b class="Nm" title="Nm">crypto_blake2b_general</b>, + <b class="Nm" title="Nm">crypto_blake2b_general_init</b>, + <b class="Nm" title="Nm">crypto_blake2b_init</b>, + <b class="Nm" title="Nm">crypto_blake2b_update</b>, + <b class="Nm" title="Nm">crypto_blake2b_final</b> — + <span class="Nd" title="Nd">cryptographic hashing</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b</b>(<var class="Fa" title="Fa">uint8_t + hash[64]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_general</b>(<var class="Fa" title="Fa">uint8_t + *hash</var>, <var class="Fa" title="Fa">size_t hash_size</var>, + <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>, + <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_init</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_general_init</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">size_t hash_size</var>, + <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_update</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_final</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *hash</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +BLAKE2b is a fast cryptographically secure hash, based on the ideas of Chacha20. + It is faster than MD5, yet just as secure as SHA-3. +<div class="Pp"></div> +Note that BLAKE2b itself is not suitable for hashing passwords and deriving keys + from them; use the + <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a> + family of functions for that purpose instead. +<div class="Pp"></div> +BLAKE2b is immune to length extension attacks, and as such does not require any + specific precautions, such as using the HMAC algorithm. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash</var></dt> + <dd class="It-tag">The output hash.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">hash</var>, in bytes. + Must be between 1 and 64. Anything below 32 is discouraged when using + Blake2b as a general-purpose hash function; anything below 16 is + discouraged when using Blake2b as a message authentication code.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">Some secret key. One cannot predict the final hash without + it. May be <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">key_size</var> is 0, in which case no key is + used. Keys can be used to create a message authentication code (MAC). Use + <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a>, + or + <a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a> + to compare MACs created this way. Choose the size of the hash accordingly. + Users may want to wipe the key with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + once they are done with it.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">key</var>, in bytes. + Must be between 0 and 64. 32 is a good default.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message</var></dt> + <dd class="It-tag">The message to hash. May overlap with + <var class="Fa" title="Fa">hash</var>. May be + <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">message_size</var> is 0.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">message</var>, in + bytes.</dd> +</dl> +<h2 class="Ss" title="Ss" id="Direct_interface"><a class="selflink" href="#Direct_interface">Direct + interface</a></h2> +The direct interface has two functions, + <b class="Fn" title="Fn">crypto_blake2b</b>() and + <b class="Fn" title="Fn">crypto_blake2b_general</b>(). + <b class="Fn" title="Fn">crypto_blake2b</b>() is provided for convenience, and + is equivalent to calling <b class="Fn" title="Fn">crypto_blake2b_general</b>() + with no key and a 64-byte hash. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_blake2b_general</b>() users can specify the size + of the hash, and use a secret key to make the hash unpredictable – + useful for message authentication codes. Even when using a key, you do not + have to wipe the context struct with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>. +<h2 class="Ss" title="Ss" id="Incremental_interface"><a class="selflink" href="#Incremental_interface">Incremental + interface</a></h2> +The incremental interface is useful for handling streams of data or large files + without using too much memory. This interface uses three steps: +<ul class="Bl-bullet"> + <li class="It-bullet">initialisation with + <b class="Fn" title="Fn">crypto_blake2b_general_init</b>() or + <b class="Fn" title="Fn">crypto_blake2b_init</b>(), which sets up a + context with the hashing parameters;</li> + <li class="It-bullet">update with + <b class="Fn" title="Fn">crypto_blake2b_update</b>(), which hashes the + message chunk by chunk, and keep the intermediary result in the + context;</li> + <li class="It-bullet">and finalisation with + <b class="Fn" title="Fn">crypto_blake2b_final</b>(), which produces the + final hash. The <var class="Ft" title="Ft">crypto_blake2b_ctx</var> is + automatically wiped upon finalisation.</li> +</ul> +<div class="Pp"></div> +The invariants of the parameters are the same as for + <b class="Fn" title="Fn">crypto_blake2b_general</b>(). + <b class="Fn" title="Fn">crypto_blake2b_init</b>() is a convenience + initialisation function that specifies a 64-byte hash and no key. This is + considered a good default. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Hashing a message all at once: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [64]; /* Output hash (64 bytes) */ +uint8_t message[12] = "Lorem ipsum"; /* Message to hash */ +crypto_blake2b(hash, message, 12); +</pre> +</div> +<div class="Pp"></div> +Computing a message authentication code all at once: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [16]; +uint8_t key [32]; +uint8_t message[11] = "Lorem ipsu"; /* Message to authenticate */ +arc4random_buf(key, 32); +crypto_blake2b_general(hash, 16, key, 32, message, 11); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(message, 11); +crypto_wipe(key, 32); +</pre> +</div> +<div class="Pp"></div> +Hashing a message incrementally (without a key): +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [ 64]; /* Output hash (64 bytes) */ +uint8_t message[500] = {1}; /* Message to hash */ +crypto_blake2b_ctx ctx; +crypto_blake2b_init(&ctx); +for (size_t i = 0; i < 500; i += 100) { + crypto_blake2b_update(&ctx, message + i, 100); +} +crypto_blake2b_final(&ctx, hash); +</pre> +</div> +<div class="Pp"></div> +Computing a message authentication code incrementally: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [ 16]; +uint8_t key [ 32]; +uint8_t message[500] = {1}; /* Message to authenticate */ +crypto_blake2b_ctx ctx; +arc4random_buf(key, 32); +crypto_blake2b_general_init(&ctx, 16, key, 32); +/* Wipe the key */ +crypto_wipe(key, 32); +for (size_t i = 0; i < 500; i += 100) { + crypto_blake2b_update(&ctx, message + i, 100); + /* Wipe secrets if they are no longer needed */ + crypto_wipe(message + i, 100); +} +crypto_blake2b_final(&ctx, hash); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement BLAKE2b, described in RFC 7693. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_blake2b</b>(), + <b class="Fn" title="Fn">crypto_blake2b_general</b>(), + <b class="Fn" title="Fn">crypto_blake2b_general_init</b>(), + <b class="Fn" title="Fn">crypto_blake2b_init</b>(), + <b class="Fn" title="Fn">crypto_blake2b_update</b>(), and + <b class="Fn" title="Fn">crypto_blake2b_final</b>() functions first appeared + in Monocypher 0.1. +<h1 class="Sh" title="Sh" id="CAVEATS"><a class="selflink" href="#CAVEATS">CAVEATS</a></h1> +Monocypher does not perform any input validation. Any deviation from the + specified input and output length ranges results in + <b class="Sy" title="Sy">undefined behaviour</b>. Make sure your inputs are + correct. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +BLAKE2b is a general-purpose cryptographic hash function; this means that it is + not suited for hashing passwords and deriving cryptographic keys from + passwords in particular. While cryptographic keys usually have hundreds of + bits of entropy, passwords are often much less complex. When storing passwords + as hashes or when deriving keys from them, the goal is normally to prevent + attackers from quickly iterating all possible passwords. Because passwords + tend to be simple, it is important to artificially slow down attackers by + using especially computationally difficult hashing algorithms. Monocypher + therefore provides + <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a> + for password hashing and deriving keys from passwords.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_blake2b_update.html b/vendor/doc/html/crypto_blake2b_update.html new file mode 100644 index 0000000..727a748 --- /dev/null +++ b/vendor/doc/html/crypto_blake2b_update.html @@ -0,0 +1,279 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_BLAKE2B(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_BLAKE2B(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_BLAKE2B(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_blake2b</b>, + <b class="Nm" title="Nm">crypto_blake2b_general</b>, + <b class="Nm" title="Nm">crypto_blake2b_general_init</b>, + <b class="Nm" title="Nm">crypto_blake2b_init</b>, + <b class="Nm" title="Nm">crypto_blake2b_update</b>, + <b class="Nm" title="Nm">crypto_blake2b_final</b> — + <span class="Nd" title="Nd">cryptographic hashing</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b</b>(<var class="Fa" title="Fa">uint8_t + hash[64]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_general</b>(<var class="Fa" title="Fa">uint8_t + *hash</var>, <var class="Fa" title="Fa">size_t hash_size</var>, + <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>, + <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_init</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_general_init</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">size_t hash_size</var>, + <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_update</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_blake2b_final</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *hash</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +BLAKE2b is a fast cryptographically secure hash, based on the ideas of Chacha20. + It is faster than MD5, yet just as secure as SHA-3. +<div class="Pp"></div> +Note that BLAKE2b itself is not suitable for hashing passwords and deriving keys + from them; use the + <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a> + family of functions for that purpose instead. +<div class="Pp"></div> +BLAKE2b is immune to length extension attacks, and as such does not require any + specific precautions, such as using the HMAC algorithm. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash</var></dt> + <dd class="It-tag">The output hash.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">hash</var>, in bytes. + Must be between 1 and 64. Anything below 32 is discouraged when using + Blake2b as a general-purpose hash function; anything below 16 is + discouraged when using Blake2b as a message authentication code.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">Some secret key. One cannot predict the final hash without + it. May be <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">key_size</var> is 0, in which case no key is + used. Keys can be used to create a message authentication code (MAC). Use + <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a>, + or + <a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a> + to compare MACs created this way. Choose the size of the hash accordingly. + Users may want to wipe the key with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + once they are done with it.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">key</var>, in bytes. + Must be between 0 and 64. 32 is a good default.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message</var></dt> + <dd class="It-tag">The message to hash. May overlap with + <var class="Fa" title="Fa">hash</var>. May be + <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">message_size</var> is 0.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">message</var>, in + bytes.</dd> +</dl> +<h2 class="Ss" title="Ss" id="Direct_interface"><a class="selflink" href="#Direct_interface">Direct + interface</a></h2> +The direct interface has two functions, + <b class="Fn" title="Fn">crypto_blake2b</b>() and + <b class="Fn" title="Fn">crypto_blake2b_general</b>(). + <b class="Fn" title="Fn">crypto_blake2b</b>() is provided for convenience, and + is equivalent to calling <b class="Fn" title="Fn">crypto_blake2b_general</b>() + with no key and a 64-byte hash. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_blake2b_general</b>() users can specify the size + of the hash, and use a secret key to make the hash unpredictable – + useful for message authentication codes. Even when using a key, you do not + have to wipe the context struct with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>. +<h2 class="Ss" title="Ss" id="Incremental_interface"><a class="selflink" href="#Incremental_interface">Incremental + interface</a></h2> +The incremental interface is useful for handling streams of data or large files + without using too much memory. This interface uses three steps: +<ul class="Bl-bullet"> + <li class="It-bullet">initialisation with + <b class="Fn" title="Fn">crypto_blake2b_general_init</b>() or + <b class="Fn" title="Fn">crypto_blake2b_init</b>(), which sets up a + context with the hashing parameters;</li> + <li class="It-bullet">update with + <b class="Fn" title="Fn">crypto_blake2b_update</b>(), which hashes the + message chunk by chunk, and keep the intermediary result in the + context;</li> + <li class="It-bullet">and finalisation with + <b class="Fn" title="Fn">crypto_blake2b_final</b>(), which produces the + final hash. The <var class="Ft" title="Ft">crypto_blake2b_ctx</var> is + automatically wiped upon finalisation.</li> +</ul> +<div class="Pp"></div> +The invariants of the parameters are the same as for + <b class="Fn" title="Fn">crypto_blake2b_general</b>(). + <b class="Fn" title="Fn">crypto_blake2b_init</b>() is a convenience + initialisation function that specifies a 64-byte hash and no key. This is + considered a good default. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Hashing a message all at once: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [64]; /* Output hash (64 bytes) */ +uint8_t message[12] = "Lorem ipsum"; /* Message to hash */ +crypto_blake2b(hash, message, 12); +</pre> +</div> +<div class="Pp"></div> +Computing a message authentication code all at once: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [16]; +uint8_t key [32]; +uint8_t message[11] = "Lorem ipsu"; /* Message to authenticate */ +arc4random_buf(key, 32); +crypto_blake2b_general(hash, 16, key, 32, message, 11); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(message, 11); +crypto_wipe(key, 32); +</pre> +</div> +<div class="Pp"></div> +Hashing a message incrementally (without a key): +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [ 64]; /* Output hash (64 bytes) */ +uint8_t message[500] = {1}; /* Message to hash */ +crypto_blake2b_ctx ctx; +crypto_blake2b_init(&ctx); +for (size_t i = 0; i < 500; i += 100) { + crypto_blake2b_update(&ctx, message + i, 100); +} +crypto_blake2b_final(&ctx, hash); +</pre> +</div> +<div class="Pp"></div> +Computing a message authentication code incrementally: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [ 16]; +uint8_t key [ 32]; +uint8_t message[500] = {1}; /* Message to authenticate */ +crypto_blake2b_ctx ctx; +arc4random_buf(key, 32); +crypto_blake2b_general_init(&ctx, 16, key, 32); +/* Wipe the key */ +crypto_wipe(key, 32); +for (size_t i = 0; i < 500; i += 100) { + crypto_blake2b_update(&ctx, message + i, 100); + /* Wipe secrets if they are no longer needed */ + crypto_wipe(message + i, 100); +} +crypto_blake2b_final(&ctx, hash); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement BLAKE2b, described in RFC 7693. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_blake2b</b>(), + <b class="Fn" title="Fn">crypto_blake2b_general</b>(), + <b class="Fn" title="Fn">crypto_blake2b_general_init</b>(), + <b class="Fn" title="Fn">crypto_blake2b_init</b>(), + <b class="Fn" title="Fn">crypto_blake2b_update</b>(), and + <b class="Fn" title="Fn">crypto_blake2b_final</b>() functions first appeared + in Monocypher 0.1. +<h1 class="Sh" title="Sh" id="CAVEATS"><a class="selflink" href="#CAVEATS">CAVEATS</a></h1> +Monocypher does not perform any input validation. Any deviation from the + specified input and output length ranges results in + <b class="Sy" title="Sy">undefined behaviour</b>. Make sure your inputs are + correct. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +BLAKE2b is a general-purpose cryptographic hash function; this means that it is + not suited for hashing passwords and deriving cryptographic keys from + passwords in particular. While cryptographic keys usually have hundreds of + bits of entropy, passwords are often much less complex. When storing passwords + as hashes or when deriving keys from them, the goal is normally to prevent + attackers from quickly iterating all possible passwords. Because passwords + tend to be simple, it is important to artificially slow down attackers by + using especially computationally difficult hashing algorithms. Monocypher + therefore provides + <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a> + for password hashing and deriving keys from passwords.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_chacha20.html b/vendor/doc/html/crypto_chacha20.html new file mode 100644 index 0000000..a3c0ec7 --- /dev/null +++ b/vendor/doc/html/crypto_chacha20.html @@ -0,0 +1,331 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_CHACHA20(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_CHACHA20(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_CHACHA20(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_chacha20</b>, + <b class="Nm" title="Nm">crypto_chacha20_ctr</b>, + <b class="Nm" title="Nm">crypto_xchacha20</b>, + <b class="Nm" title="Nm">crypto_xchacha20_ctr</b> — + <span class="Nd" title="Nd">Chacha20 and XChacha20 encryption functions</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20</b>(<var class="Fa" title="Fa">uint8_t + *cipher_text</var>, <var class="Fa" title="Fa">const uint8_t + *plain_text</var>, <var class="Fa" title="Fa">size_t text_size</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[8]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_xchacha20</b>(<var class="Fa" title="Fa">uint8_t + *cipher_text</var>, <var class="Fa" title="Fa">const uint8_t + *plain_text</var>, <var class="Fa" title="Fa">size_t text_size</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">uint64_t</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_ctr</b>(<var class="Fa" title="Fa">uint8_t + *cipher_text</var>, <var class="Fa" title="Fa">const uint8_t + *plain_text</var>, <var class="Fa" title="Fa">size_t text_size</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[8]</var>, + <var class="Fa" title="Fa">uint64_t ctr</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">uint64_t</var> +<br/> +<b class="Fn" title="Fn">crypto_xchacha20_ctr</b>(<var class="Fa" title="Fa">uint8_t + *cipher_text</var>, <var class="Fa" title="Fa">const uint8_t + *plain_text</var>, <var class="Fa" title="Fa">size_t text_size</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">uint64_t ctr</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions provide an interface for the Chacha20 encryption primitive. +<div class="Pp"></div> +Chacha20 is a low-level primitive. Consider using authenticated encryption, + implemented by + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">A 32-byte secret key.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">nonce</var></dt> + <dd class="It-tag">An 8-byte or 24-byte number, used only once with any given + key. It does not need to be secret or random, but it does have to be + unique. Repeating a nonce with the same key reveals the XOR of two + different messages, which allows decryption. 24-byte nonces can be + selected at random. 8-byte nonces <i class="Em" title="Em">cannot</i>. + They are too small, and the same nonce may be selected twice by accident. + See <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about generating random numbers (use the operating system's random + number generator).</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">plain_text</var></dt> + <dd class="It-tag">The message to encrypt. It is allowed to be + <code class="Dv" title="Dv">NULL</code>, in which case it will be + interpreted as an all zero input. + <var class="Fa" title="Fa">cipher_text</var> will then contain the raw + Chacha20 stream.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">cipher_text</var></dt> + <dd class="It-tag">The encrypted message.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">text_size</var></dt> + <dd class="It-tag">Length of both <var class="Fa" title="Fa">plain_text</var> + and <var class="Fa" title="Fa">cipher_text</var>, in bytes.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">ctr</var></dt> + <dd class="It-tag">The number of 64-byte blocks since the beginning of the + stream.</dd> +</dl> +<div class="Pp"></div> +The <var class="Fa" title="Fa">key</var> and + <var class="Fa" title="Fa">nonce</var> buffers may overlap. + <var class="Fa" title="Fa">plain_text</var> and + <var class="Fa" title="Fa">cipher_text</var> must either be the same buffer + (for in-place encryption), or non-overlapping. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_chacha20</b>() performs a Chacha20 operation. It + uses an 8-byte nonce, which is too small to be selected at random. Use a + message counter as a nonce instead. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_xchacha20</b>() performs an XChacha20 operation. + It uses a 24-byte nonce, which is large enough to be selected at random. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_xchacha20</b>() is recommended over + <b class="Fn" title="Fn">crypto_chacha20</b>(). The ability to use random + nonces makes it easier to use securely, and the performance hit is often + negligible in practice. +<div class="Pp"></div> +The <b class="Fn" title="Fn">crypto_chacha20</b>() and + <b class="Fn" title="Fn">crypto_xchacha20</b>() encrypt + <var class="Fa" title="Fa">plain_text</var> by XORing it with a pseudo-random + stream of numbers, seeded by the provided <var class="Fa" title="Fa">key</var> + and <var class="Fa" title="Fa">nonce</var>. +<div class="Pp"></div> +Since XOR is its own inverse, decryption is the same operation as encryption. To + decrypt the cipher text, “encrypt” it again with the same key + and nonce. You will likely want to wipe the key when you are done with + encryption or decryption. Use + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + to wipe them. +<div class="Pp"></div> +The <var class="Fa" title="Fa">plain_text</var> pointer is allowed to be + <code class="Dv" title="Dv">NULL</code>, in which case it will be interpreted + as an all zero input. This is useful as a user space random number generator. + While <b class="Sy" title="Sy">this should not be used as a random number + generator for secrets</b>, for which the operating system random number + generator should be preferred, it can be handy outside of a security context. + Deterministic procedural generation and reproducible property-based tests come + to mind. Additionally, it <i class="Em" title="Em">can</i> be used to generate + large amounts of random-looking data quickly, for example to generate padding. +<div class="Pp"></div> +The <b class="Fn" title="Fn">crypto_chacha20_ctr</b>() and + <b class="Fn" title="Fn">crypto_xchacha20_ctr</b>() perform a Chacha20 or + XChacha20 encryption, respectively, starting the stream at the block + <var class="Fa" title="Fa">ctr</var> (which is the byte + ‘<code class="Li">ctr × 64</code>’). This can be used to + encrypt (or decrypt) part of a long message, or to implement some AEAD + constructions such as the one described in RFC 8439. Be careful when using + this not to accidentally reuse parts of the random stream as that would + destroy confidentiality. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_chacha20</b>() and + <b class="Fn" title="Fn">crypto_xchacha20</b>() return nothing. + <b class="Fn" title="Fn">crypto_chacha20_ctr</b>() and + <b class="Fn" title="Fn">crypto_xchacha20_ctr</b>() functions return the next + <var class="Fa" title="Fa">ctr</var> to use with the same key and nonce + values; this is always <var class="Fa" title="Fa">text_size</var> divided by + 64; plus one if there was a remainder. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Simple encryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key [ 32]; /* Secret random key */ +uint8_t nonce [ 24]; /* Unique nonce (possibly random) */ +uint8_t plain_text [500] = {1}; /* Secret message */ +uint8_t cipher_text[500]; /* Encrypted message */ +arc4random_buf(key, 32); +arc4random_buf(nonce, 24); +crypto_xchacha20(cipher_text, plain_text, 500, key, nonce); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(key, 32); +crypto_wipe(plain_text, 500); +</pre> +</div> +<div class="Pp"></div> +To decrypt the above: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key [ 32]; /* Same key as above */ +const uint8_t nonce [ 24]; /* Same nonce as above */ +uint8_t plain_text [500]; /* Message to decrypt */ +uint8_t cipher_text[500]; /* Secret message */ +crypto_xchacha20(cipher_text, plain_text, 500, key, nonce); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(key, 32); +/* The plain text likely needs to be processed before you wipe it */ +crypto_wipe(plain_text, 12); +</pre> +</div> +<div class="Pp"></div> +Incremental encryption (in blocks of 64 bytes): +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key [ 32]; /* Secret random key */ +uint8_t nonce [ 24]; /* Unique nonce (possibly random) */ +uint8_t plain_text [500]; /* Secret message */ +uint8_t cipher_text[500]; /* Encrypted message */ +uint64_t ctr = 0; /* Block counter */ +unsigned int i; +arc4random_buf(key, 32); +arc4random_buf(nonce, 24); +for(i = 0; i < 500; i += 64) { + ctr = crypto_xchacha20_ctr(cipher_text+i, plain_text+i, 64, + key, nonce, ctr); +} +/* Process data that didn't fit into 64 byte pieces */ +crypto_xchacha20_ctr(cipher_text+500-(i-64), + plain_text+500-(i-64), + 500-(i-64), + key, nonce, ctr); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(key, 32); +crypto_wipe(plain_text, 500); +</pre> +</div> +<div class="Pp"></div> +Encryption by jumping around (do not do that, this is only meant to show how + <b class="Fn" title="Fn">crypto_xchacha20_ctr</b>() works): +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key [ 32]; /* Secret random key */ +uint8_t nonce [ 24]; /* Unique nonce (possibly random) */ +uint8_t plain_text [500] = {1}; /* Message to be encrypted */ +uint8_t cipher_text[500]; /* Will be the encrypted message */ +arc4random_buf(key, 32); +arc4random_buf(nonce, 24); +/* Encrypt the second part of the message first... */ +crypto_xchacha20_ctr(cipher_text + (3 * 64), + plain_text + (3 * 64), + 500 - (3 * 64), + key, nonce, 3); +/* ...then encrypt the first part */ +crypto_xchacha20_ctr(cipher_text, plain_text, 3 * 64, key, nonce, 0); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(key, 32); +crypto_wipe(plain_text, 500); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_ietf_chacha20.html">crypto_ietf_chacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement Chacha20 and XChacha20. Chacha20 is described in: + <cite class="Rs" title="Rs"><span class="RsA">Daniel J. Bernstein</span>, + <span class="RsT">ChaCha, a variant of Salsa20</span>, <i class="RsJ">SASC + 2008 – The State of the Art of Stream Ciphers</i>, + <span class="RsP">pp. 273–278</span>.</cite> The nonce and counter + sizes were modified in RFC 8439. XChacha20 derives from Chacha20 the same way + XSalsa20 derives from Salsa20, and benefits from the same security reduction + (proven secure as long as Chacha20 itself is secure). +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +<b class="Fn" title="Fn">crypto_chacha20</b>(), + <b class="Fn" title="Fn">crypto_chacha20_ctr</b>(), + <b class="Fn" title="Fn">crypto_xchacha20</b>(), and + <b class="Fn" title="Fn">crypto_xchacha20_ctr</b>() were added in Monocypher + 3.0.0. They replace <b class="Fn" title="Fn">crypto_chacha20_encrypt</b>(), + <b class="Fn" title="Fn">crypto_chacha20_init</b>(), + <b class="Fn" title="Fn">crypto_chacha20_stream</b>(), + <b class="Fn" title="Fn">crypto_chacha20_x_init</b>(), and + <b class="Fn" title="Fn">crypto_chacha20_set_ctr</b>() that were deprecated in + Monocypher 3.0.0. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +<h2 class="Ss" title="Ss" id="Encrypted_does_not_mean_secure"><a class="selflink" href="#Encrypted_does_not_mean_secure">Encrypted + does not mean secure</a></h2> +Chacha20 only protects against eavesdropping, not forgeries. Most applications + need protection against forgeries to be properly secure. To ensure the + integrity of a message, use Blake2b in keyed mode, or authenticated + encryption; see + <a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>. +<h2 class="Ss" title="Ss" id="Nonce_reuse"><a class="selflink" href="#Nonce_reuse">Nonce + reuse</a></h2> +Repeating a nonce with the same key exposes the XOR of two or more plain text + messages, effectively destroying confidentiality. +<div class="Pp"></div> +For the same reason, <b class="Sy" title="Sy">do not select small nonces at + random</b>. The <b class="Fn" title="Fn">crypto_chacha20</b>() nonce spans + only 64 bits, which is small enough to trigger accidental reuses. A message + counter should be used instead. If multiple parties send out messages, Each + can start with an initial nonce of 0, 1 .. n-1 respectively, and increment + them by n for each new message. Make sure the counters never wrap around. +<h2 class="Ss" title="Ss" id="Secure_random_number_generation"><a class="selflink" href="#Secure_random_number_generation">Secure + random number generation</a></h2> +Do not use these functions as a cryptographic random number generator. Always + use the operating system's random number generator for cryptographic purposes, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a>. +<h2 class="Ss" title="Ss" id="Protection_against_side_channels"><a class="selflink" href="#Protection_against_side_channels">Protection + against side channels</a></h2> +Secrets should not dwell in memory longer than needed. Use + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + to erase secrets you no longer need. For Chacha20, this means the key and in + some cases the plain text itself.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_chacha20_H.html b/vendor/doc/html/crypto_chacha20_H.html new file mode 100644 index 0000000..04177b6 --- /dev/null +++ b/vendor/doc/html/crypto_chacha20_H.html @@ -0,0 +1,110 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_HCHACHA20(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_HCHACHA20(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_HCHACHA20(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_hchacha20</b> — + <span class="Nd" title="Nd">HChacha20 special-purpose hashing</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hchacha20</b>(<var class="Fa" title="Fa">uint8_t + out[32]</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t in[16]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<b class="Fn" title="Fn">crypto_hchacha20</b>() provides a not-so-cryptographic + hash. It may be used for some specific purposes, such as X25519 key + derivation, or XChacha20 initialisation. If in doubt, do not use directly. Use + <a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a> + instead. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">A sufficiently random key, such as the output of + <a class="Xr" title="Xr" href="crypto_x25519.html">crypto_x25519(3monocypher)</a>.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">in</var></dt> + <dd class="It-tag">The space reserved for the Chacha20 nonce and counter. It + does not have to be random.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">out</var></dt> + <dd class="It-tag">A cryptographically secure random number + <i class="Em" title="Em">if</i> there is enough entropy in + <var class="Fa" title="Fa">key</var>. X25519 shared secrets have enough + entropy.</dd> +</dl> +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +This function returns nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following example assumes the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Simple hash: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key[32]; /* Must have enough entropy */ +uint8_t in [16]; /* Does not have to be random */ +uint8_t out[32]; /* Will be random iff the above holds */ +arc4random_buf(key, 32); +crypto_hchacha20(out, key, in); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(key, 32); +crypto_wipe(in , 16); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_chacha20_encrypt.html">crypto_chacha20_encrypt(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +This function implements HChacha20. HChacha20 derives from Chacha20 the same way + HSalsa20 derives from Salsa20. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_hchacha20</b>() function first appeared in + Monocypher 0.1 as <b class="Fn" title="Fn">crypto_chacha20_H</b>(). It was + renamed to <b class="Fn" title="Fn">crypto_hchacha20</b>() in Monocypher + 3.0.0. +<h1 class="Sh" title="Sh" id="CAVEATS"><a class="selflink" href="#CAVEATS">CAVEATS</a></h1> +<b class="Sy" title="Sy">This is not a general-purpose cryptographic hash + function</b>.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 2, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_chacha20_ctr.html b/vendor/doc/html/crypto_chacha20_ctr.html new file mode 100644 index 0000000..a3c0ec7 --- /dev/null +++ b/vendor/doc/html/crypto_chacha20_ctr.html @@ -0,0 +1,331 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_CHACHA20(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_CHACHA20(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_CHACHA20(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_chacha20</b>, + <b class="Nm" title="Nm">crypto_chacha20_ctr</b>, + <b class="Nm" title="Nm">crypto_xchacha20</b>, + <b class="Nm" title="Nm">crypto_xchacha20_ctr</b> — + <span class="Nd" title="Nd">Chacha20 and XChacha20 encryption functions</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20</b>(<var class="Fa" title="Fa">uint8_t + *cipher_text</var>, <var class="Fa" title="Fa">const uint8_t + *plain_text</var>, <var class="Fa" title="Fa">size_t text_size</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[8]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_xchacha20</b>(<var class="Fa" title="Fa">uint8_t + *cipher_text</var>, <var class="Fa" title="Fa">const uint8_t + *plain_text</var>, <var class="Fa" title="Fa">size_t text_size</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">uint64_t</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_ctr</b>(<var class="Fa" title="Fa">uint8_t + *cipher_text</var>, <var class="Fa" title="Fa">const uint8_t + *plain_text</var>, <var class="Fa" title="Fa">size_t text_size</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[8]</var>, + <var class="Fa" title="Fa">uint64_t ctr</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">uint64_t</var> +<br/> +<b class="Fn" title="Fn">crypto_xchacha20_ctr</b>(<var class="Fa" title="Fa">uint8_t + *cipher_text</var>, <var class="Fa" title="Fa">const uint8_t + *plain_text</var>, <var class="Fa" title="Fa">size_t text_size</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">uint64_t ctr</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions provide an interface for the Chacha20 encryption primitive. +<div class="Pp"></div> +Chacha20 is a low-level primitive. Consider using authenticated encryption, + implemented by + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">A 32-byte secret key.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">nonce</var></dt> + <dd class="It-tag">An 8-byte or 24-byte number, used only once with any given + key. It does not need to be secret or random, but it does have to be + unique. Repeating a nonce with the same key reveals the XOR of two + different messages, which allows decryption. 24-byte nonces can be + selected at random. 8-byte nonces <i class="Em" title="Em">cannot</i>. + They are too small, and the same nonce may be selected twice by accident. + See <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about generating random numbers (use the operating system's random + number generator).</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">plain_text</var></dt> + <dd class="It-tag">The message to encrypt. It is allowed to be + <code class="Dv" title="Dv">NULL</code>, in which case it will be + interpreted as an all zero input. + <var class="Fa" title="Fa">cipher_text</var> will then contain the raw + Chacha20 stream.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">cipher_text</var></dt> + <dd class="It-tag">The encrypted message.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">text_size</var></dt> + <dd class="It-tag">Length of both <var class="Fa" title="Fa">plain_text</var> + and <var class="Fa" title="Fa">cipher_text</var>, in bytes.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">ctr</var></dt> + <dd class="It-tag">The number of 64-byte blocks since the beginning of the + stream.</dd> +</dl> +<div class="Pp"></div> +The <var class="Fa" title="Fa">key</var> and + <var class="Fa" title="Fa">nonce</var> buffers may overlap. + <var class="Fa" title="Fa">plain_text</var> and + <var class="Fa" title="Fa">cipher_text</var> must either be the same buffer + (for in-place encryption), or non-overlapping. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_chacha20</b>() performs a Chacha20 operation. It + uses an 8-byte nonce, which is too small to be selected at random. Use a + message counter as a nonce instead. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_xchacha20</b>() performs an XChacha20 operation. + It uses a 24-byte nonce, which is large enough to be selected at random. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_xchacha20</b>() is recommended over + <b class="Fn" title="Fn">crypto_chacha20</b>(). The ability to use random + nonces makes it easier to use securely, and the performance hit is often + negligible in practice. +<div class="Pp"></div> +The <b class="Fn" title="Fn">crypto_chacha20</b>() and + <b class="Fn" title="Fn">crypto_xchacha20</b>() encrypt + <var class="Fa" title="Fa">plain_text</var> by XORing it with a pseudo-random + stream of numbers, seeded by the provided <var class="Fa" title="Fa">key</var> + and <var class="Fa" title="Fa">nonce</var>. +<div class="Pp"></div> +Since XOR is its own inverse, decryption is the same operation as encryption. To + decrypt the cipher text, “encrypt” it again with the same key + and nonce. You will likely want to wipe the key when you are done with + encryption or decryption. Use + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + to wipe them. +<div class="Pp"></div> +The <var class="Fa" title="Fa">plain_text</var> pointer is allowed to be + <code class="Dv" title="Dv">NULL</code>, in which case it will be interpreted + as an all zero input. This is useful as a user space random number generator. + While <b class="Sy" title="Sy">this should not be used as a random number + generator for secrets</b>, for which the operating system random number + generator should be preferred, it can be handy outside of a security context. + Deterministic procedural generation and reproducible property-based tests come + to mind. Additionally, it <i class="Em" title="Em">can</i> be used to generate + large amounts of random-looking data quickly, for example to generate padding. +<div class="Pp"></div> +The <b class="Fn" title="Fn">crypto_chacha20_ctr</b>() and + <b class="Fn" title="Fn">crypto_xchacha20_ctr</b>() perform a Chacha20 or + XChacha20 encryption, respectively, starting the stream at the block + <var class="Fa" title="Fa">ctr</var> (which is the byte + ‘<code class="Li">ctr × 64</code>’). This can be used to + encrypt (or decrypt) part of a long message, or to implement some AEAD + constructions such as the one described in RFC 8439. Be careful when using + this not to accidentally reuse parts of the random stream as that would + destroy confidentiality. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_chacha20</b>() and + <b class="Fn" title="Fn">crypto_xchacha20</b>() return nothing. + <b class="Fn" title="Fn">crypto_chacha20_ctr</b>() and + <b class="Fn" title="Fn">crypto_xchacha20_ctr</b>() functions return the next + <var class="Fa" title="Fa">ctr</var> to use with the same key and nonce + values; this is always <var class="Fa" title="Fa">text_size</var> divided by + 64; plus one if there was a remainder. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Simple encryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key [ 32]; /* Secret random key */ +uint8_t nonce [ 24]; /* Unique nonce (possibly random) */ +uint8_t plain_text [500] = {1}; /* Secret message */ +uint8_t cipher_text[500]; /* Encrypted message */ +arc4random_buf(key, 32); +arc4random_buf(nonce, 24); +crypto_xchacha20(cipher_text, plain_text, 500, key, nonce); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(key, 32); +crypto_wipe(plain_text, 500); +</pre> +</div> +<div class="Pp"></div> +To decrypt the above: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key [ 32]; /* Same key as above */ +const uint8_t nonce [ 24]; /* Same nonce as above */ +uint8_t plain_text [500]; /* Message to decrypt */ +uint8_t cipher_text[500]; /* Secret message */ +crypto_xchacha20(cipher_text, plain_text, 500, key, nonce); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(key, 32); +/* The plain text likely needs to be processed before you wipe it */ +crypto_wipe(plain_text, 12); +</pre> +</div> +<div class="Pp"></div> +Incremental encryption (in blocks of 64 bytes): +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key [ 32]; /* Secret random key */ +uint8_t nonce [ 24]; /* Unique nonce (possibly random) */ +uint8_t plain_text [500]; /* Secret message */ +uint8_t cipher_text[500]; /* Encrypted message */ +uint64_t ctr = 0; /* Block counter */ +unsigned int i; +arc4random_buf(key, 32); +arc4random_buf(nonce, 24); +for(i = 0; i < 500; i += 64) { + ctr = crypto_xchacha20_ctr(cipher_text+i, plain_text+i, 64, + key, nonce, ctr); +} +/* Process data that didn't fit into 64 byte pieces */ +crypto_xchacha20_ctr(cipher_text+500-(i-64), + plain_text+500-(i-64), + 500-(i-64), + key, nonce, ctr); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(key, 32); +crypto_wipe(plain_text, 500); +</pre> +</div> +<div class="Pp"></div> +Encryption by jumping around (do not do that, this is only meant to show how + <b class="Fn" title="Fn">crypto_xchacha20_ctr</b>() works): +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key [ 32]; /* Secret random key */ +uint8_t nonce [ 24]; /* Unique nonce (possibly random) */ +uint8_t plain_text [500] = {1}; /* Message to be encrypted */ +uint8_t cipher_text[500]; /* Will be the encrypted message */ +arc4random_buf(key, 32); +arc4random_buf(nonce, 24); +/* Encrypt the second part of the message first... */ +crypto_xchacha20_ctr(cipher_text + (3 * 64), + plain_text + (3 * 64), + 500 - (3 * 64), + key, nonce, 3); +/* ...then encrypt the first part */ +crypto_xchacha20_ctr(cipher_text, plain_text, 3 * 64, key, nonce, 0); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(key, 32); +crypto_wipe(plain_text, 500); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_ietf_chacha20.html">crypto_ietf_chacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement Chacha20 and XChacha20. Chacha20 is described in: + <cite class="Rs" title="Rs"><span class="RsA">Daniel J. Bernstein</span>, + <span class="RsT">ChaCha, a variant of Salsa20</span>, <i class="RsJ">SASC + 2008 – The State of the Art of Stream Ciphers</i>, + <span class="RsP">pp. 273–278</span>.</cite> The nonce and counter + sizes were modified in RFC 8439. XChacha20 derives from Chacha20 the same way + XSalsa20 derives from Salsa20, and benefits from the same security reduction + (proven secure as long as Chacha20 itself is secure). +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +<b class="Fn" title="Fn">crypto_chacha20</b>(), + <b class="Fn" title="Fn">crypto_chacha20_ctr</b>(), + <b class="Fn" title="Fn">crypto_xchacha20</b>(), and + <b class="Fn" title="Fn">crypto_xchacha20_ctr</b>() were added in Monocypher + 3.0.0. They replace <b class="Fn" title="Fn">crypto_chacha20_encrypt</b>(), + <b class="Fn" title="Fn">crypto_chacha20_init</b>(), + <b class="Fn" title="Fn">crypto_chacha20_stream</b>(), + <b class="Fn" title="Fn">crypto_chacha20_x_init</b>(), and + <b class="Fn" title="Fn">crypto_chacha20_set_ctr</b>() that were deprecated in + Monocypher 3.0.0. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +<h2 class="Ss" title="Ss" id="Encrypted_does_not_mean_secure"><a class="selflink" href="#Encrypted_does_not_mean_secure">Encrypted + does not mean secure</a></h2> +Chacha20 only protects against eavesdropping, not forgeries. Most applications + need protection against forgeries to be properly secure. To ensure the + integrity of a message, use Blake2b in keyed mode, or authenticated + encryption; see + <a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>. +<h2 class="Ss" title="Ss" id="Nonce_reuse"><a class="selflink" href="#Nonce_reuse">Nonce + reuse</a></h2> +Repeating a nonce with the same key exposes the XOR of two or more plain text + messages, effectively destroying confidentiality. +<div class="Pp"></div> +For the same reason, <b class="Sy" title="Sy">do not select small nonces at + random</b>. The <b class="Fn" title="Fn">crypto_chacha20</b>() nonce spans + only 64 bits, which is small enough to trigger accidental reuses. A message + counter should be used instead. If multiple parties send out messages, Each + can start with an initial nonce of 0, 1 .. n-1 respectively, and increment + them by n for each new message. Make sure the counters never wrap around. +<h2 class="Ss" title="Ss" id="Secure_random_number_generation"><a class="selflink" href="#Secure_random_number_generation">Secure + random number generation</a></h2> +Do not use these functions as a cryptographic random number generator. Always + use the operating system's random number generator for cryptographic purposes, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a>. +<h2 class="Ss" title="Ss" id="Protection_against_side_channels"><a class="selflink" href="#Protection_against_side_channels">Protection + against side channels</a></h2> +Secrets should not dwell in memory longer than needed. Use + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + to erase secrets you no longer need. For Chacha20, this means the key and in + some cases the plain text itself.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_chacha20_encrypt.html b/vendor/doc/html/crypto_chacha20_encrypt.html new file mode 100644 index 0000000..4b1409b --- /dev/null +++ b/vendor/doc/html/crypto_chacha20_encrypt.html @@ -0,0 +1,121 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_CHACHA20_ENCRYPT(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_CHACHA20_ENCRYPT(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_CHACHA20_ENCRYPT(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_chacha20_encrypt</b>, + <b class="Nm" title="Nm">crypto_chacha20_init</b>, + <b class="Nm" title="Nm">crypto_chacha20_x_init</b>, + <b class="Nm" title="Nm">crypto_chacha20_stream</b>, + <b class="Nm" title="Nm">crypto_chacha20_set_ctr</b> — + <span class="Nd" title="Nd">deprecated Chacha20 and XChacha20 encryption + functions</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_init</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[8]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_x_init</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_encrypt</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_stream</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *stream</var>, + <var class="Fa" title="Fa">size_t stream_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_set_ctr</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">uint64_t ctr</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions provided an incremental interface for the Chacha20 cipher. They + are deprecated in favor of + <a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_xchacha20.html">crypto_xchacha20(3monocypher)</a>, + and + <a class="Xr" title="Xr" href="crypto_xchacha20_ctr.html">crypto_xchacha20_ctr(3monocypher)</a>. +<div class="Pp"></div> +For encryption, you can achieve an identical effect as the deprecated functions + by using + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr(3monocypher)</a> + or + <a class="Xr" title="Xr" href="crypto_xchacha20_ctr.html">crypto_xchacha20_ctr(3monocypher)</a>. + Care needs to be taken with regards to handling the counter value when + migrating old code to use the new functions. The new functions + <i class="Em" title="Em">always return next counter value</i>. This means that + input ciphertexts or plaintexts whose lengths are not exactly multiples of 64 + bytes advance the counter, even though there is theoretically some space left + in a Chacha20 block. New applications should design their code so that either + the protocl is not reliant on the counter covering the entire text (e.g. by + cutting input into independent chunks) or inputs are always such that their + lengths are multiples of 64 bytes (e.g. by buffering input until 64 bytes have + been obtained). +<div class="Pp"></div> +To obtain the raw Chacha20 stream previously provided by + <b class="Fn" title="Fn">crypto_chacha20_stream</b>(), pass + <code class="Dv" title="Dv">NULL</code> to + <a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20</a> as + plaintext. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_xchacha20.html">crypto_xchacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_xchacha20_ctr.html">crypto_xchacha20_ctr(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_chacha20_encrypt</b>(), + <b class="Fn" title="Fn">crypto_chacha20_init</b>(), functions first appeared + in Monocypher 0.1. <b class="Fn" title="Fn">crypto_chacha20_stream</b>() was + added in Monocypher 0.2. <b class="Fn" title="Fn">crypto_chacha20_x_init</b>() + and <b class="Fn" title="Fn">crypto_chacha20_set_ctr</b>() were added in + Monocypher 1.0. They were deprecated in Monocypher 3.0.0 and will be removed + in Monocypher 4.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">December 2, 2019</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_chacha20_init.html b/vendor/doc/html/crypto_chacha20_init.html new file mode 100644 index 0000000..4b1409b --- /dev/null +++ b/vendor/doc/html/crypto_chacha20_init.html @@ -0,0 +1,121 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_CHACHA20_ENCRYPT(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_CHACHA20_ENCRYPT(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_CHACHA20_ENCRYPT(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_chacha20_encrypt</b>, + <b class="Nm" title="Nm">crypto_chacha20_init</b>, + <b class="Nm" title="Nm">crypto_chacha20_x_init</b>, + <b class="Nm" title="Nm">crypto_chacha20_stream</b>, + <b class="Nm" title="Nm">crypto_chacha20_set_ctr</b> — + <span class="Nd" title="Nd">deprecated Chacha20 and XChacha20 encryption + functions</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_init</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[8]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_x_init</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_encrypt</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_stream</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *stream</var>, + <var class="Fa" title="Fa">size_t stream_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_set_ctr</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">uint64_t ctr</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions provided an incremental interface for the Chacha20 cipher. They + are deprecated in favor of + <a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_xchacha20.html">crypto_xchacha20(3monocypher)</a>, + and + <a class="Xr" title="Xr" href="crypto_xchacha20_ctr.html">crypto_xchacha20_ctr(3monocypher)</a>. +<div class="Pp"></div> +For encryption, you can achieve an identical effect as the deprecated functions + by using + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr(3monocypher)</a> + or + <a class="Xr" title="Xr" href="crypto_xchacha20_ctr.html">crypto_xchacha20_ctr(3monocypher)</a>. + Care needs to be taken with regards to handling the counter value when + migrating old code to use the new functions. The new functions + <i class="Em" title="Em">always return next counter value</i>. This means that + input ciphertexts or plaintexts whose lengths are not exactly multiples of 64 + bytes advance the counter, even though there is theoretically some space left + in a Chacha20 block. New applications should design their code so that either + the protocl is not reliant on the counter covering the entire text (e.g. by + cutting input into independent chunks) or inputs are always such that their + lengths are multiples of 64 bytes (e.g. by buffering input until 64 bytes have + been obtained). +<div class="Pp"></div> +To obtain the raw Chacha20 stream previously provided by + <b class="Fn" title="Fn">crypto_chacha20_stream</b>(), pass + <code class="Dv" title="Dv">NULL</code> to + <a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20</a> as + plaintext. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_xchacha20.html">crypto_xchacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_xchacha20_ctr.html">crypto_xchacha20_ctr(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_chacha20_encrypt</b>(), + <b class="Fn" title="Fn">crypto_chacha20_init</b>(), functions first appeared + in Monocypher 0.1. <b class="Fn" title="Fn">crypto_chacha20_stream</b>() was + added in Monocypher 0.2. <b class="Fn" title="Fn">crypto_chacha20_x_init</b>() + and <b class="Fn" title="Fn">crypto_chacha20_set_ctr</b>() were added in + Monocypher 1.0. They were deprecated in Monocypher 3.0.0 and will be removed + in Monocypher 4.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">December 2, 2019</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_chacha20_set_ctr.html b/vendor/doc/html/crypto_chacha20_set_ctr.html new file mode 100644 index 0000000..4b1409b --- /dev/null +++ b/vendor/doc/html/crypto_chacha20_set_ctr.html @@ -0,0 +1,121 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_CHACHA20_ENCRYPT(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_CHACHA20_ENCRYPT(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_CHACHA20_ENCRYPT(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_chacha20_encrypt</b>, + <b class="Nm" title="Nm">crypto_chacha20_init</b>, + <b class="Nm" title="Nm">crypto_chacha20_x_init</b>, + <b class="Nm" title="Nm">crypto_chacha20_stream</b>, + <b class="Nm" title="Nm">crypto_chacha20_set_ctr</b> — + <span class="Nd" title="Nd">deprecated Chacha20 and XChacha20 encryption + functions</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_init</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[8]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_x_init</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_encrypt</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_stream</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *stream</var>, + <var class="Fa" title="Fa">size_t stream_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_set_ctr</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">uint64_t ctr</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions provided an incremental interface for the Chacha20 cipher. They + are deprecated in favor of + <a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_xchacha20.html">crypto_xchacha20(3monocypher)</a>, + and + <a class="Xr" title="Xr" href="crypto_xchacha20_ctr.html">crypto_xchacha20_ctr(3monocypher)</a>. +<div class="Pp"></div> +For encryption, you can achieve an identical effect as the deprecated functions + by using + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr(3monocypher)</a> + or + <a class="Xr" title="Xr" href="crypto_xchacha20_ctr.html">crypto_xchacha20_ctr(3monocypher)</a>. + Care needs to be taken with regards to handling the counter value when + migrating old code to use the new functions. The new functions + <i class="Em" title="Em">always return next counter value</i>. This means that + input ciphertexts or plaintexts whose lengths are not exactly multiples of 64 + bytes advance the counter, even though there is theoretically some space left + in a Chacha20 block. New applications should design their code so that either + the protocl is not reliant on the counter covering the entire text (e.g. by + cutting input into independent chunks) or inputs are always such that their + lengths are multiples of 64 bytes (e.g. by buffering input until 64 bytes have + been obtained). +<div class="Pp"></div> +To obtain the raw Chacha20 stream previously provided by + <b class="Fn" title="Fn">crypto_chacha20_stream</b>(), pass + <code class="Dv" title="Dv">NULL</code> to + <a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20</a> as + plaintext. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_xchacha20.html">crypto_xchacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_xchacha20_ctr.html">crypto_xchacha20_ctr(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_chacha20_encrypt</b>(), + <b class="Fn" title="Fn">crypto_chacha20_init</b>(), functions first appeared + in Monocypher 0.1. <b class="Fn" title="Fn">crypto_chacha20_stream</b>() was + added in Monocypher 0.2. <b class="Fn" title="Fn">crypto_chacha20_x_init</b>() + and <b class="Fn" title="Fn">crypto_chacha20_set_ctr</b>() were added in + Monocypher 1.0. They were deprecated in Monocypher 3.0.0 and will be removed + in Monocypher 4.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">December 2, 2019</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_chacha20_stream.html b/vendor/doc/html/crypto_chacha20_stream.html new file mode 100644 index 0000000..4b1409b --- /dev/null +++ b/vendor/doc/html/crypto_chacha20_stream.html @@ -0,0 +1,121 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_CHACHA20_ENCRYPT(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_CHACHA20_ENCRYPT(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_CHACHA20_ENCRYPT(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_chacha20_encrypt</b>, + <b class="Nm" title="Nm">crypto_chacha20_init</b>, + <b class="Nm" title="Nm">crypto_chacha20_x_init</b>, + <b class="Nm" title="Nm">crypto_chacha20_stream</b>, + <b class="Nm" title="Nm">crypto_chacha20_set_ctr</b> — + <span class="Nd" title="Nd">deprecated Chacha20 and XChacha20 encryption + functions</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_init</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[8]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_x_init</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_encrypt</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_stream</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *stream</var>, + <var class="Fa" title="Fa">size_t stream_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_set_ctr</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">uint64_t ctr</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions provided an incremental interface for the Chacha20 cipher. They + are deprecated in favor of + <a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_xchacha20.html">crypto_xchacha20(3monocypher)</a>, + and + <a class="Xr" title="Xr" href="crypto_xchacha20_ctr.html">crypto_xchacha20_ctr(3monocypher)</a>. +<div class="Pp"></div> +For encryption, you can achieve an identical effect as the deprecated functions + by using + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr(3monocypher)</a> + or + <a class="Xr" title="Xr" href="crypto_xchacha20_ctr.html">crypto_xchacha20_ctr(3monocypher)</a>. + Care needs to be taken with regards to handling the counter value when + migrating old code to use the new functions. The new functions + <i class="Em" title="Em">always return next counter value</i>. This means that + input ciphertexts or plaintexts whose lengths are not exactly multiples of 64 + bytes advance the counter, even though there is theoretically some space left + in a Chacha20 block. New applications should design their code so that either + the protocl is not reliant on the counter covering the entire text (e.g. by + cutting input into independent chunks) or inputs are always such that their + lengths are multiples of 64 bytes (e.g. by buffering input until 64 bytes have + been obtained). +<div class="Pp"></div> +To obtain the raw Chacha20 stream previously provided by + <b class="Fn" title="Fn">crypto_chacha20_stream</b>(), pass + <code class="Dv" title="Dv">NULL</code> to + <a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20</a> as + plaintext. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_xchacha20.html">crypto_xchacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_xchacha20_ctr.html">crypto_xchacha20_ctr(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_chacha20_encrypt</b>(), + <b class="Fn" title="Fn">crypto_chacha20_init</b>(), functions first appeared + in Monocypher 0.1. <b class="Fn" title="Fn">crypto_chacha20_stream</b>() was + added in Monocypher 0.2. <b class="Fn" title="Fn">crypto_chacha20_x_init</b>() + and <b class="Fn" title="Fn">crypto_chacha20_set_ctr</b>() were added in + Monocypher 1.0. They were deprecated in Monocypher 3.0.0 and will be removed + in Monocypher 4.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">December 2, 2019</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_chacha20_x_init.html b/vendor/doc/html/crypto_chacha20_x_init.html new file mode 100644 index 0000000..4b1409b --- /dev/null +++ b/vendor/doc/html/crypto_chacha20_x_init.html @@ -0,0 +1,121 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_CHACHA20_ENCRYPT(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_CHACHA20_ENCRYPT(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_CHACHA20_ENCRYPT(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_chacha20_encrypt</b>, + <b class="Nm" title="Nm">crypto_chacha20_init</b>, + <b class="Nm" title="Nm">crypto_chacha20_x_init</b>, + <b class="Nm" title="Nm">crypto_chacha20_stream</b>, + <b class="Nm" title="Nm">crypto_chacha20_set_ctr</b> — + <span class="Nd" title="Nd">deprecated Chacha20 and XChacha20 encryption + functions</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_init</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[8]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_x_init</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_encrypt</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_stream</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *stream</var>, + <var class="Fa" title="Fa">size_t stream_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_chacha20_set_ctr</b>(<var class="Fa" title="Fa">crypto_chacha_ctx + *ctx</var>, <var class="Fa" title="Fa">uint64_t ctr</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions provided an incremental interface for the Chacha20 cipher. They + are deprecated in favor of + <a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_xchacha20.html">crypto_xchacha20(3monocypher)</a>, + and + <a class="Xr" title="Xr" href="crypto_xchacha20_ctr.html">crypto_xchacha20_ctr(3monocypher)</a>. +<div class="Pp"></div> +For encryption, you can achieve an identical effect as the deprecated functions + by using + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr(3monocypher)</a> + or + <a class="Xr" title="Xr" href="crypto_xchacha20_ctr.html">crypto_xchacha20_ctr(3monocypher)</a>. + Care needs to be taken with regards to handling the counter value when + migrating old code to use the new functions. The new functions + <i class="Em" title="Em">always return next counter value</i>. This means that + input ciphertexts or plaintexts whose lengths are not exactly multiples of 64 + bytes advance the counter, even though there is theoretically some space left + in a Chacha20 block. New applications should design their code so that either + the protocl is not reliant on the counter covering the entire text (e.g. by + cutting input into independent chunks) or inputs are always such that their + lengths are multiples of 64 bytes (e.g. by buffering input until 64 bytes have + been obtained). +<div class="Pp"></div> +To obtain the raw Chacha20 stream previously provided by + <b class="Fn" title="Fn">crypto_chacha20_stream</b>(), pass + <code class="Dv" title="Dv">NULL</code> to + <a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20</a> as + plaintext. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_xchacha20.html">crypto_xchacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_xchacha20_ctr.html">crypto_xchacha20_ctr(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_chacha20_encrypt</b>(), + <b class="Fn" title="Fn">crypto_chacha20_init</b>(), functions first appeared + in Monocypher 0.1. <b class="Fn" title="Fn">crypto_chacha20_stream</b>() was + added in Monocypher 0.2. <b class="Fn" title="Fn">crypto_chacha20_x_init</b>() + and <b class="Fn" title="Fn">crypto_chacha20_set_ctr</b>() were added in + Monocypher 1.0. They were deprecated in Monocypher 3.0.0 and will be removed + in Monocypher 4.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">December 2, 2019</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_check.html b/vendor/doc/html/crypto_check.html new file mode 100644 index 0000000..85b8686 --- /dev/null +++ b/vendor/doc/html/crypto_check.html @@ -0,0 +1,215 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_SIGN(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_SIGN(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_SIGN(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_sign</b>, + <b class="Nm" title="Nm">crypto_check</b>, + <b class="Nm" title="Nm">crypto_sign_public_key</b> — + <span class="Nd" title="Nd">public key signatures</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_sign_public_key</b>(<var class="Fa" title="Fa">uint8_t + public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t + secret_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_sign</b>(<var class="Fa" title="Fa">uint8_t + signature[64]</var>, <var class="Fa" title="Fa">const uint8_t + secret_key[32]</var>, <var class="Fa" title="Fa">const uint8_t + public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_check</b>(<var class="Fa" title="Fa">const + uint8_t signature[64]</var>, <var class="Fa" title="Fa">const uint8_t + public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<b class="Fn" title="Fn">crypto_sign</b>() and + <b class="Fn" title="Fn">crypto_check</b>() provide EdDSA public key + signatures and verification. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">signature</var></dt> + <dd class="It-tag">The signature.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">secret_key</var></dt> + <dd class="It-tag">A 32-byte random number, known only to you. See + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> about + random number generation (use your operating system's random number + generator). Do not use the same private key for both signatures and key + exchanges. The public keys are different, and revealing both may leak + information.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">public_key</var></dt> + <dd class="It-tag">The public key, generated from + <var class="Fa" title="Fa">secret_key</var> with + <b class="Fn" title="Fn">crypto_sign_public_key</b>().</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message</var></dt> + <dd class="It-tag">Message to sign.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">message</var>, in + bytes.</dd> +</dl> +<div class="Pp"></div> +<var class="Fa" title="Fa">signature</var> and + <var class="Fa" title="Fa">message</var> may overlap. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_sign_public_key</b>() computes the public key of + the specified secret key. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_sign</b>() signs a message with + <var class="Fa" title="Fa">secret_key</var>. The public key is optional, and + will be recomputed if not provided. This recomputation doubles the execution + time. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_check</b>() checks that a given signature is + genuine. Meaning, only someone who had the private key could have signed the + message. <b class="Sy" title="Sy">It does not run in constant time</b>. It + does not have to in most threat models, because nothing is secret: everyone + knows the public key, and the signature and message are rarely secret. If the + message needs to be secret, use + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(3monocypher)</a> + instead. +<div class="Pp"></div> +An incremental interface is available; see + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_sign_public_key</b>() and + <b class="Fn" title="Fn">crypto_sign</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_check</b>() returns 0 for legitimate messages + and -1 for forgeries. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Generate a public key from a random secret key: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t sk[32]; /* Random secret key */ +uint8_t pk[32]; /* Matching public key */ +arc4random_buf(sk, 32); +crypto_sign_public_key(pk, sk); +/* Wipe the secret key if it is no longer needed */ +crypto_wipe(sk, 32); +</pre> +</div> +<div class="Pp"></div> +Sign a message: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t sk [32]; /* Secret key from above */ +const uint8_t pk [32]; /* Matching public key */ +const uint8_t message [11] = "Lorem ipsu"; /* Message to sign */ +uint8_t signature[64]; +crypto_sign(signature, sk, pk, message, 10); +/* Wipe the secret key if it is no longer needed */ +crypto_wipe(sk, 32); +</pre> +</div> +<div class="Pp"></div> +Check the above: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t pk [32]; /* Their public key */ +const uint8_t message [11] = "Lorem ipsu"; /* Signed message */ +const uint8_t signature[64]; /* Signature to check */ +if (crypto_check(signature, pk, message, 10)) { + /* Message is corrupted, abort processing */ +} else { + /* Message is genuine */ +} +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement PureEdDSA with Curve25519 and Blake2b, as described in + RFC 8032. This is the same as Ed25519, with Blake2b instead of SHA-512. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_sign</b>(), + <b class="Fn" title="Fn">crypto_check</b>(), and + <b class="Fn" title="Fn">crypto_sign_public_key</b>() functions appeared in + Monocypher 0.2. +<div class="Pp"></div> +<b class="Sy" title="Sy">A critical security vulnerability</b> that caused + all-zero signatures to be accepted was introduced in Monocypher 0.3; it was + fixed in Monocypher 1.1.1 and 2.0.4. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +<h2 class="Ss" title="Ss" id="Signature_malleability"><a class="selflink" href="#Signature_malleability">Signature + malleability</a></h2> +EdDSA signatures are not unique like cryptographic hashes. For any given public + key and message, there are many possible valid signatures. Some of them + require knowledge of the private key. Others only require knowledge of an + existing signature. Observing a valid signature only proves that someone with + knowledge of the private key signed the message at some point. Do not rely on + any other security property. +<h2 class="Ss" title="Ss" id="Fault_injection_and_power_analysis"><a class="selflink" href="#Fault_injection_and_power_analysis">Fault + injection and power analysis</a></h2> +Fault injection (also known as glitching) and power analysis may be used to + manipulate the resulting signature and recover the secret key in some cases. + This requires hardware access. If attackers are expected to have such access + and have the relevant equipment, you may try use the incremental interface + provided by + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a> + to mitigate the side channel attacks. Note that there may still be other + power-related side channels (such as if the CPU leaks information when an + operation overflows a register) that must be considered.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_check_final.html b/vendor/doc/html/crypto_check_final.html new file mode 100644 index 0000000..23bf438 --- /dev/null +++ b/vendor/doc/html/crypto_check_final.html @@ -0,0 +1,269 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_sign_init_first_pass</b>, + <b class="Nm" title="Nm">crypto_sign_update</b>, + <b class="Nm" title="Nm">crypto_sign_final</b>, + <b class="Nm" title="Nm">crypto_sign_init_second_pass</b>, + <b class="Nm" title="Nm">crypto_check_init</b>, + <b class="Nm" title="Nm">crypto_check_update</b>, + <b class="Nm" title="Nm">crypto_check_final</b> — + <span class="Nd" title="Nd">incremental public key signatures</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(<var class="Fa" title="Fa">crypto_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t secret_key[32]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_sign_update</b>(<var class="Fa" title="Fa">crypto_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_sign_final</b>(<var class="Fa" title="Fa">crypto_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t signature[64]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_sign_init_second_pass</b>(<var class="Fa" title="Fa">crypto_sign_ctx + *ctx</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_check_init</b>(<var class="Fa" title="Fa">crypto_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t signature[64]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_check_update</b>(<var class="Fa" title="Fa">crypto_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_check_final</b>(<var class="Fa" title="Fa">crypto_check_ctx + *ctx</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions are variants of + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_check.html">crypto_check(3monocypher)</a>. + Prefer those simpler functions if possible. +<div class="Pp"></div> +The arguments are the same as those described in + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +This incremental interface can be used to sign or verify messages too large to + fit in a single buffer. The arguments are the same as the direct interface + described in + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +The direct and incremental interface produce and accept the same signatures. +<div class="Pp"></div> +Signing is done in two passes. This requires five steps: +<ul class="Bl-bullet"> + <li class="It-bullet">Initialisation of the first pass with + <b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(). The public key + is optional, and will be recomputed if not provided. This recomputation + doubles the execution time for short messages.</li> + <li class="It-bullet">The first pass proper, with + <b class="Fn" title="Fn">crypto_sign_update</b>(). + <b class="Sy" title="Sy">Under no circumstances must you forget the first + pass</b>: Forgetting to call + <b class="Fn" title="Fn">crypto_sign_update</b>() will appear to work in + that it produces valid signatures, but also loses all security because + attackers may now recover the secret key.</li> + <li class="It-bullet">Initialisation of the second pass with + <b class="Fn" title="Fn">crypto_sign_init_second_pass</b>().</li> + <li class="It-bullet">The second pass proper, with + <b class="Fn" title="Fn">crypto_sign_update</b>(). The same update + function is used for both passes.</li> + <li class="It-bullet">Signature generation with + <b class="Fn" title="Fn">crypto_sign_final</b>(). This also wipes the + context.</li> +</ul> +<div class="Pp"></div> +Verification requires three steps: +<ul class="Bl-bullet"> + <li class="It-bullet">Initialisation with + <b class="Fn" title="Fn">crypto_check_init</b>().</li> + <li class="It-bullet">Update with + <b class="Fn" title="Fn">crypto_check_update</b>().</li> + <li class="It-bullet">Signature verification with + <b class="Fn" title="Fn">crypto_check_final</b>().</li> +</ul> +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_sign_update</b>(), + <b class="Fn" title="Fn">crypto_sign_final</b>(), + <b class="Fn" title="Fn">crypto_check_init</b>() and + <b class="Fn" title="Fn">crypto_check_update</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_check_final</b>() returns 0 for legitimate + messages and -1 for forgeries. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +Sign a message: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t sk [ 32]; /* Secret key */ +const uint8_t pk [ 32]; /* Public key (optional) */ +const uint8_t message [500]; /* Message to sign */ +uint8_t signature[ 64]; /* Output signature */ +crypto_sign_ctx ctx; +crypto_sign_init_first_pass((crypto_sign_ctx_abstract*)&ctx, sk, pk); +/* Wipe the secret key if no longer needed */ +crypto_wipe(sk, 32); +for (size_t i = 0; i < 500; i += 100) { + crypto_sign_update((crypto_sign_ctx_abstract*)&ctx, message + i, 100); +} +crypto_sign_init_second_pass((crypto_sign_ctx_abstract*)&ctx); +for (size_t i = 0; i < 500; i += 100) { + crypto_sign_update((crypto_sign_ctx_abstract*)&ctx, message + i, 100); +} +crypto_sign_final((crypto_sign_ctx_abstract*)&ctx, signature); +</pre> +</div> +<div class="Pp"></div> +Check the above: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t pk [ 32]; /* Public key */ +const uint8_t message [500]; /* Message to sign */ +const uint8_t signature[ 64]; /* Signature to check */ +crypto_check_ctx ctx; +crypto_check_init((crypto_sign_ctx_abstract*)&ctx, signature, pk); +for (size_t i = 0; i < 500; i += 100) { + crypto_check_update((crypto_sign_ctx_abstract*)&ctx, message + i, 100); +} +if (crypto_check_final((crypto_sign_ctx_abstract*)&ctx)) { + /* Message is corrupted, abort processing */ +} else { + /* Message is genuine */ +} +</pre> +</div> +<div class="Pp"></div> +This interface can be used to mitigate attacks that leverage power analysis and + fault injection (glitching) – both of which require physical access and + appropriate equipment – by injecting additional randomness (at least 32 + bytes) and padding (to the hash function's block size, which is 128 bytes for + all hash functions supported by Monocypher), of which 32 bytes are already + inserted into the buffer by + <b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(). Access to a + cryptographically secure pseudo-random generator is a requirement for + effective side channel mitigation. Signing a message with increased + power-related side channel mitigations: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t message [ 500]; /* Message to sign */ +uint8_t sk [ 32]; /* Secret key */ +const uint8_t pk [ 32]; /* Public key (optional) */ +uint8_t signature[ 64]; /* Output signature */ +uint8_t buf [128-32] = {0}; /* Mitigation buffer */ +crypto_sign_ctx ctx; +crypto_sign_ctx_abstract *actx = (crypto_sign_ctx_abstract *)&ctx; + +arc4random_buf(buf, 32); +/* The rest of buf MUST be zeroes. */ + +crypto_sign_init_first_pass(actx, sk, pk); +crypto_sign_update (actx, buf, sizeof(buf)); +crypto_sign_update (actx, message, 500); + +crypto_sign_init_second_pass(actx); +crypto_sign_update (actx, message, 500); +crypto_sign_final (actx, signature); + +crypto_wipe(buf, 32); +/* Wipe the secret key if no longer needed */ +crypto_wipe(sk, 32); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement PureEdDSA with Curve25519 and Blake2b, as described in + RFC 8032. This is the same as Ed25519, with Blake2b instead of SHA-512. +<div class="Pp"></div> +The example for side channel mitigation follows the methodology outlined in + I-D.draft-mattsson-cfrg-det-sigs-with-noise-02. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_sign_update</b>(), + <b class="Fn" title="Fn">crypto_sign_final</b>(), + <b class="Fn" title="Fn">crypto_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_check_init</b>(), + <b class="Fn" title="Fn">crypto_check_update</b>(), and + <b class="Fn" title="Fn">crypto_check_final</b>() functions first appeared in + Monocypher 1.1.0. +<div class="Pp"></div> +<b class="Sy" title="Sy">A critical security vulnerability</b> that caused + all-zero signatures to be accepted was introduced in Monocypher 0.3; it was + fixed in Monocypher 1.1.1 and 2.0.4. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +Messages are not verified until the call to + <b class="Fn" title="Fn">crypto_check_final</b>(). Messages may be stored + before they are verified, but they cannot be + <i class="Em" title="Em">trusted</i>. Processing untrusted messages increases + the attack surface of the system. Doing so securely is hard. Do not process + messages before calling <b class="Fn" title="Fn">crypto_check_final</b>(). +<div class="Pp"></div> +When signing messages, the security considerations documented in + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a> + also apply. In particular, if power-related side channels are part of your + threat model, note that there may still be other power-related side channels + (such as if the CPU leaks information when an operation overflows a register) + that must be considered. +<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION + DETAILS</a></h1> +EdDSA signatures require two passes that cannot be performed in parallel. There + are ways around this limitation, but they all lower security in some way. For + this reason, Monocypher does not support them.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_check_init.html b/vendor/doc/html/crypto_check_init.html new file mode 100644 index 0000000..23bf438 --- /dev/null +++ b/vendor/doc/html/crypto_check_init.html @@ -0,0 +1,269 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_sign_init_first_pass</b>, + <b class="Nm" title="Nm">crypto_sign_update</b>, + <b class="Nm" title="Nm">crypto_sign_final</b>, + <b class="Nm" title="Nm">crypto_sign_init_second_pass</b>, + <b class="Nm" title="Nm">crypto_check_init</b>, + <b class="Nm" title="Nm">crypto_check_update</b>, + <b class="Nm" title="Nm">crypto_check_final</b> — + <span class="Nd" title="Nd">incremental public key signatures</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(<var class="Fa" title="Fa">crypto_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t secret_key[32]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_sign_update</b>(<var class="Fa" title="Fa">crypto_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_sign_final</b>(<var class="Fa" title="Fa">crypto_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t signature[64]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_sign_init_second_pass</b>(<var class="Fa" title="Fa">crypto_sign_ctx + *ctx</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_check_init</b>(<var class="Fa" title="Fa">crypto_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t signature[64]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_check_update</b>(<var class="Fa" title="Fa">crypto_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_check_final</b>(<var class="Fa" title="Fa">crypto_check_ctx + *ctx</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions are variants of + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_check.html">crypto_check(3monocypher)</a>. + Prefer those simpler functions if possible. +<div class="Pp"></div> +The arguments are the same as those described in + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +This incremental interface can be used to sign or verify messages too large to + fit in a single buffer. The arguments are the same as the direct interface + described in + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +The direct and incremental interface produce and accept the same signatures. +<div class="Pp"></div> +Signing is done in two passes. This requires five steps: +<ul class="Bl-bullet"> + <li class="It-bullet">Initialisation of the first pass with + <b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(). The public key + is optional, and will be recomputed if not provided. This recomputation + doubles the execution time for short messages.</li> + <li class="It-bullet">The first pass proper, with + <b class="Fn" title="Fn">crypto_sign_update</b>(). + <b class="Sy" title="Sy">Under no circumstances must you forget the first + pass</b>: Forgetting to call + <b class="Fn" title="Fn">crypto_sign_update</b>() will appear to work in + that it produces valid signatures, but also loses all security because + attackers may now recover the secret key.</li> + <li class="It-bullet">Initialisation of the second pass with + <b class="Fn" title="Fn">crypto_sign_init_second_pass</b>().</li> + <li class="It-bullet">The second pass proper, with + <b class="Fn" title="Fn">crypto_sign_update</b>(). The same update + function is used for both passes.</li> + <li class="It-bullet">Signature generation with + <b class="Fn" title="Fn">crypto_sign_final</b>(). This also wipes the + context.</li> +</ul> +<div class="Pp"></div> +Verification requires three steps: +<ul class="Bl-bullet"> + <li class="It-bullet">Initialisation with + <b class="Fn" title="Fn">crypto_check_init</b>().</li> + <li class="It-bullet">Update with + <b class="Fn" title="Fn">crypto_check_update</b>().</li> + <li class="It-bullet">Signature verification with + <b class="Fn" title="Fn">crypto_check_final</b>().</li> +</ul> +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_sign_update</b>(), + <b class="Fn" title="Fn">crypto_sign_final</b>(), + <b class="Fn" title="Fn">crypto_check_init</b>() and + <b class="Fn" title="Fn">crypto_check_update</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_check_final</b>() returns 0 for legitimate + messages and -1 for forgeries. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +Sign a message: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t sk [ 32]; /* Secret key */ +const uint8_t pk [ 32]; /* Public key (optional) */ +const uint8_t message [500]; /* Message to sign */ +uint8_t signature[ 64]; /* Output signature */ +crypto_sign_ctx ctx; +crypto_sign_init_first_pass((crypto_sign_ctx_abstract*)&ctx, sk, pk); +/* Wipe the secret key if no longer needed */ +crypto_wipe(sk, 32); +for (size_t i = 0; i < 500; i += 100) { + crypto_sign_update((crypto_sign_ctx_abstract*)&ctx, message + i, 100); +} +crypto_sign_init_second_pass((crypto_sign_ctx_abstract*)&ctx); +for (size_t i = 0; i < 500; i += 100) { + crypto_sign_update((crypto_sign_ctx_abstract*)&ctx, message + i, 100); +} +crypto_sign_final((crypto_sign_ctx_abstract*)&ctx, signature); +</pre> +</div> +<div class="Pp"></div> +Check the above: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t pk [ 32]; /* Public key */ +const uint8_t message [500]; /* Message to sign */ +const uint8_t signature[ 64]; /* Signature to check */ +crypto_check_ctx ctx; +crypto_check_init((crypto_sign_ctx_abstract*)&ctx, signature, pk); +for (size_t i = 0; i < 500; i += 100) { + crypto_check_update((crypto_sign_ctx_abstract*)&ctx, message + i, 100); +} +if (crypto_check_final((crypto_sign_ctx_abstract*)&ctx)) { + /* Message is corrupted, abort processing */ +} else { + /* Message is genuine */ +} +</pre> +</div> +<div class="Pp"></div> +This interface can be used to mitigate attacks that leverage power analysis and + fault injection (glitching) – both of which require physical access and + appropriate equipment – by injecting additional randomness (at least 32 + bytes) and padding (to the hash function's block size, which is 128 bytes for + all hash functions supported by Monocypher), of which 32 bytes are already + inserted into the buffer by + <b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(). Access to a + cryptographically secure pseudo-random generator is a requirement for + effective side channel mitigation. Signing a message with increased + power-related side channel mitigations: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t message [ 500]; /* Message to sign */ +uint8_t sk [ 32]; /* Secret key */ +const uint8_t pk [ 32]; /* Public key (optional) */ +uint8_t signature[ 64]; /* Output signature */ +uint8_t buf [128-32] = {0}; /* Mitigation buffer */ +crypto_sign_ctx ctx; +crypto_sign_ctx_abstract *actx = (crypto_sign_ctx_abstract *)&ctx; + +arc4random_buf(buf, 32); +/* The rest of buf MUST be zeroes. */ + +crypto_sign_init_first_pass(actx, sk, pk); +crypto_sign_update (actx, buf, sizeof(buf)); +crypto_sign_update (actx, message, 500); + +crypto_sign_init_second_pass(actx); +crypto_sign_update (actx, message, 500); +crypto_sign_final (actx, signature); + +crypto_wipe(buf, 32); +/* Wipe the secret key if no longer needed */ +crypto_wipe(sk, 32); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement PureEdDSA with Curve25519 and Blake2b, as described in + RFC 8032. This is the same as Ed25519, with Blake2b instead of SHA-512. +<div class="Pp"></div> +The example for side channel mitigation follows the methodology outlined in + I-D.draft-mattsson-cfrg-det-sigs-with-noise-02. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_sign_update</b>(), + <b class="Fn" title="Fn">crypto_sign_final</b>(), + <b class="Fn" title="Fn">crypto_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_check_init</b>(), + <b class="Fn" title="Fn">crypto_check_update</b>(), and + <b class="Fn" title="Fn">crypto_check_final</b>() functions first appeared in + Monocypher 1.1.0. +<div class="Pp"></div> +<b class="Sy" title="Sy">A critical security vulnerability</b> that caused + all-zero signatures to be accepted was introduced in Monocypher 0.3; it was + fixed in Monocypher 1.1.1 and 2.0.4. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +Messages are not verified until the call to + <b class="Fn" title="Fn">crypto_check_final</b>(). Messages may be stored + before they are verified, but they cannot be + <i class="Em" title="Em">trusted</i>. Processing untrusted messages increases + the attack surface of the system. Doing so securely is hard. Do not process + messages before calling <b class="Fn" title="Fn">crypto_check_final</b>(). +<div class="Pp"></div> +When signing messages, the security considerations documented in + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a> + also apply. In particular, if power-related side channels are part of your + threat model, note that there may still be other power-related side channels + (such as if the CPU leaks information when an operation overflows a register) + that must be considered. +<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION + DETAILS</a></h1> +EdDSA signatures require two passes that cannot be performed in parallel. There + are ways around this limitation, but they all lower security in some way. For + this reason, Monocypher does not support them.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_check_init_custom_hash.html b/vendor/doc/html/crypto_check_init_custom_hash.html new file mode 100644 index 0000000..9976495 --- /dev/null +++ b/vendor/doc/html/crypto_check_init_custom_hash.html @@ -0,0 +1,267 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_SIGN_INIT_FIRST_PASS_CUSTOM_HASH(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_SIGN_INIT_FIRST_PASS_CUSTOM_HASH(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_SIGN_INIT_FIRST_PASS_CUSTOM_HASH(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_sign_init_first_pass_custom_hash</b>, + <b class="Nm" title="Nm">crypto_sign_public_key_custom_hash</b>, + <b class="Nm" title="Nm">crypto_check_init_custom_hash</b> — + <span class="Nd" title="Nd">public key signatures with custom hash + functions</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_sign_init_first_pass_custom_hash</b>(<var class="Fa" title="Fa">crypto_sign_ctx_abstract + *ctx</var>, <var class="Fa" title="Fa">const uint8_t secret_key[32]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>, + <var class="Fa" title="Fa">const crypto_sign_vtable *hash</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_sign_public_key_custom_hash</b>(<var class="Fa" title="Fa">uint8_t + public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t + secret_key[32]</var>, <var class="Fa" title="Fa">const crypto_sign_vtable + *hash</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_check_init_custom_hash</b>(<var class="Fa" title="Fa">crypto_sign_ctx_abstract + *ctx</var>, <var class="Fa" title="Fa">const uint8_t signature[64]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>, + <var class="Fa" title="Fa">const crypto_sign_vtable *hash</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions are variants of the + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a> + family of functions: They provide the ability to replace the EdDSA hash + function with any user-provided hash function. +<div class="Pp"></div> +<b class="Sy" title="Sy">This is a highly advanced feature</b>. Interoperability + of public key signatures with other cryptographic libraries can normally be + achieved by using + <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a> + or + <a class="Xr" title="Xr" href="crypto_ed25519_sign_init_first_pass.html">crypto_ed25519_sign_init_first_pass(3monocypher)</a> + already. This interface is exposed only for completeness and to handle special + situations (e.g. to use the hash function of the future winner of the NIST + lightweight crypto competition on a device with highly constrained resources + or taking advantage of hardware support for cryptographic hash functions). + Whenever possible, these functions should be avoided. +<div class="Pp"></div> +To make available a custom hash algorithm for use with these functions, a + <var class="Vt" title="Vt">crypto_sign_vtable</var> structure must be + provided. It is defined as: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 0.00ex;"> +<pre class="Li"> +typedef struct { + void (*hash)(uint8_t hash[64], const uint8_t *message, + size_t message_size); + void (*init )(void *ctx); + void (*update)(void *ctx, const uint8_t *message, + size_t message_size); + void (*final )(void *ctx, uint8_t hash[64]); + size_t ctx_size; +} crypto_sign_vtable; +</pre> +</div> +<div class="Pp"></div> +The context argument to the functions shall be referred to as “outer + signing context”. The outer signing context must contain a + <var class="Vt" title="Vt">crypto_sign_ctx_abstract</var> as + <i class="Em" title="Em">its first member</i>. Other than that, the outer + signing context may be defined freely. Logically, it is required to contain + some kind of hash context as well, else it cannot work as a custom hash + function. +<div class="Pp"></div> +Because the calling code cannot know the real type of the outer signing context, + it is cast to <var class="Vt" title="Vt">void *</var> when calling the hash + functions in the vtable, but the <var class="Fa" title="Fa">ctx</var> argument + to the functions in the vtable is always guaranteed to be the outer signing + context. +<div class="Pp"></div> +The hash functions must not fail. If they somehow can fail, they have no way to + propagate its error status, and thus the only ways to handle errors are to + either assume an error never occurs (if reasonable), or to induce a crash in + the code when an error occurs. +<div class="Pp"></div> +The fields of <var class="Vt" title="Vt">crypto_sign_vtable</var> are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hash</var></dt> + <dd class="It-tag">Function that computes a 64-byte hash for a given message + and writes the computed hash to <var class="Fa" title="Fa">hash</var>. The + output length <i class="Em" title="Em">must</i> be exactly 64 bytes. This + will normally be constructed using the functions that provide the + <var class="Fa" title="Fa">init</var>, + <var class="Fa" title="Fa">update</var> and + <var class="Fa" title="Fa">final</var> members.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">init</var></dt> + <dd class="It-tag">Function that initialises the hash context of an outer + signing context.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">update</var></dt> + <dd class="It-tag">Function that updates the hash context of an outer signing + context. It must be able to handle message sizes of at least 32 + bytes.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">final</var></dt> + <dd class="It-tag">Function that finalises the hash context of an outer + signing context and writes the computed hash to + <var class="Fa" title="Fa">hash</var>. The output length + <i class="Em" title="Em">must</i> be exactly 64 bytes. This function + should wipe the hash context with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + if it contains pointers to objects outside the outer signing context. + Monocypher takes care of wiping the outer signing context.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">ctx_size</var></dt> + <dd class="It-tag">The size of the outer signing context as determined by + <b class="Fn" title="Fn">sizeof</b>().</dd> +</dl> +<div class="Pp"></div> +The functions indicated in the + <var class="Vt" title="Vt">crypto_sign_vtable</var> must be thread-safe if any + of Monocypher's signing functions are accessed from multiple threads. +<div class="Pp"></div> +After calling + <b class="Fn" title="Fn">crypto_sign_init_first_pass_custom_hash</b>() or + <b class="Fn" title="Fn">crypto_check_init_custom_hash</b>(), the + <a class="Xr" title="Xr" href="crypto_sign_update.html">crypto_sign_update(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign_final.html">crypto_sign_final(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign_init_second_pass.html">crypto_sign_init_second_pass(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_check_update.html">crypto_check_update(3monocypher)</a>, + and + <a class="Xr" title="Xr" href="crypto_check_final.html">crypto_check_final(3monocypher)</a> + functions can be used as usual. They will call into the hash vtable as + required. The same security considerations and semantics apply. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +Defining and using a custom implementation of SHA-512 and crudely checking its + results against + <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a>: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +struct outer_ctx { + crypto_sign_ctx_abstract sctx; + SHA2_CTX hash_ctx; +}; + +static void +my_hash(uint8_t hash[64], const uint8_t *msg, size_t len) +{ + SHA2_CTX ctx; + SHA512Init(&ctx); + SHA512Update(&ctx, msg, len); + SHA512Final(hash, &ctx); +} + +static void +my_init(void *ctx) +{ + struct outer_ctx *octx = (struct outer_ctx *)ctx; + SHA512Init(&octx->hash_ctx); +} + +static void +my_update(void *ctx, const uint8_t *msg, size_t len) +{ + struct outer_ctx *octx = (struct outer_ctx *)ctx; + SHA512Update(&octx->hash_ctx, msg, len); +} + +static void +my_final(void *ctx, uint8_t *hash) +{ + struct outer_ctx *octx = (struct outer_ctx *)ctx; + SHA512Final(hash, &octx->hash_ctx); +} + +static const crypto_sign_vtable my_vtable = { + my_hash, + my_init, + my_update, + my_final, + sizeof(struct outer_ctx) +}; + +int +main(void) +{ + uint8_t theirs[64], mine[64]; + uint8_t sk[32] = {0x01, 0x02, 0x03, 0x04}; + const uint8_t msg[] = { + 0x00, 0x01, 0x02, 0x04 + }; + + crypto_ed25519_sign(theirs, sk, NULL, msg, sizeof(msg)); + + struct outer_ctx ctx; + crypto_sign_ctx_abstract *actx = (crypto_sign_ctx_abstract*)&ctx; + crypto_sign_init_first_pass_custom_hash(actx, + sk, NULL, &my_vtable); + crypto_wipe(sk, sizeof(sk)); + crypto_sign_update( actx, msg, sizeof(msg)); + crypto_sign_init_second_pass(actx); + crypto_sign_update( actx, msg, sizeof(msg)); + crypto_sign_final( actx, mine); + + if (crypto_verify64(theirs, mine) != 0) { + fprintf(stderr, "theirs != mine\n"); + return 1; + } + puts("ok"); + return 0; +} +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_sign_init_first_pass_custom_hash</b>(), + <b class="Fn" title="Fn">crypto_sign_public_key_custom_hash</b>(), + <b class="Fn" title="Fn">crypto_check_init_first_pass_custom_hash</b>() + functions first appeared in Monocypher 3.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">December 28, 2019</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_check_update.html b/vendor/doc/html/crypto_check_update.html new file mode 100644 index 0000000..23bf438 --- /dev/null +++ b/vendor/doc/html/crypto_check_update.html @@ -0,0 +1,269 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_sign_init_first_pass</b>, + <b class="Nm" title="Nm">crypto_sign_update</b>, + <b class="Nm" title="Nm">crypto_sign_final</b>, + <b class="Nm" title="Nm">crypto_sign_init_second_pass</b>, + <b class="Nm" title="Nm">crypto_check_init</b>, + <b class="Nm" title="Nm">crypto_check_update</b>, + <b class="Nm" title="Nm">crypto_check_final</b> — + <span class="Nd" title="Nd">incremental public key signatures</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(<var class="Fa" title="Fa">crypto_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t secret_key[32]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_sign_update</b>(<var class="Fa" title="Fa">crypto_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_sign_final</b>(<var class="Fa" title="Fa">crypto_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t signature[64]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_sign_init_second_pass</b>(<var class="Fa" title="Fa">crypto_sign_ctx + *ctx</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_check_init</b>(<var class="Fa" title="Fa">crypto_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t signature[64]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_check_update</b>(<var class="Fa" title="Fa">crypto_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_check_final</b>(<var class="Fa" title="Fa">crypto_check_ctx + *ctx</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions are variants of + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_check.html">crypto_check(3monocypher)</a>. + Prefer those simpler functions if possible. +<div class="Pp"></div> +The arguments are the same as those described in + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +This incremental interface can be used to sign or verify messages too large to + fit in a single buffer. The arguments are the same as the direct interface + described in + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +The direct and incremental interface produce and accept the same signatures. +<div class="Pp"></div> +Signing is done in two passes. This requires five steps: +<ul class="Bl-bullet"> + <li class="It-bullet">Initialisation of the first pass with + <b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(). The public key + is optional, and will be recomputed if not provided. This recomputation + doubles the execution time for short messages.</li> + <li class="It-bullet">The first pass proper, with + <b class="Fn" title="Fn">crypto_sign_update</b>(). + <b class="Sy" title="Sy">Under no circumstances must you forget the first + pass</b>: Forgetting to call + <b class="Fn" title="Fn">crypto_sign_update</b>() will appear to work in + that it produces valid signatures, but also loses all security because + attackers may now recover the secret key.</li> + <li class="It-bullet">Initialisation of the second pass with + <b class="Fn" title="Fn">crypto_sign_init_second_pass</b>().</li> + <li class="It-bullet">The second pass proper, with + <b class="Fn" title="Fn">crypto_sign_update</b>(). The same update + function is used for both passes.</li> + <li class="It-bullet">Signature generation with + <b class="Fn" title="Fn">crypto_sign_final</b>(). This also wipes the + context.</li> +</ul> +<div class="Pp"></div> +Verification requires three steps: +<ul class="Bl-bullet"> + <li class="It-bullet">Initialisation with + <b class="Fn" title="Fn">crypto_check_init</b>().</li> + <li class="It-bullet">Update with + <b class="Fn" title="Fn">crypto_check_update</b>().</li> + <li class="It-bullet">Signature verification with + <b class="Fn" title="Fn">crypto_check_final</b>().</li> +</ul> +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_sign_update</b>(), + <b class="Fn" title="Fn">crypto_sign_final</b>(), + <b class="Fn" title="Fn">crypto_check_init</b>() and + <b class="Fn" title="Fn">crypto_check_update</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_check_final</b>() returns 0 for legitimate + messages and -1 for forgeries. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +Sign a message: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t sk [ 32]; /* Secret key */ +const uint8_t pk [ 32]; /* Public key (optional) */ +const uint8_t message [500]; /* Message to sign */ +uint8_t signature[ 64]; /* Output signature */ +crypto_sign_ctx ctx; +crypto_sign_init_first_pass((crypto_sign_ctx_abstract*)&ctx, sk, pk); +/* Wipe the secret key if no longer needed */ +crypto_wipe(sk, 32); +for (size_t i = 0; i < 500; i += 100) { + crypto_sign_update((crypto_sign_ctx_abstract*)&ctx, message + i, 100); +} +crypto_sign_init_second_pass((crypto_sign_ctx_abstract*)&ctx); +for (size_t i = 0; i < 500; i += 100) { + crypto_sign_update((crypto_sign_ctx_abstract*)&ctx, message + i, 100); +} +crypto_sign_final((crypto_sign_ctx_abstract*)&ctx, signature); +</pre> +</div> +<div class="Pp"></div> +Check the above: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t pk [ 32]; /* Public key */ +const uint8_t message [500]; /* Message to sign */ +const uint8_t signature[ 64]; /* Signature to check */ +crypto_check_ctx ctx; +crypto_check_init((crypto_sign_ctx_abstract*)&ctx, signature, pk); +for (size_t i = 0; i < 500; i += 100) { + crypto_check_update((crypto_sign_ctx_abstract*)&ctx, message + i, 100); +} +if (crypto_check_final((crypto_sign_ctx_abstract*)&ctx)) { + /* Message is corrupted, abort processing */ +} else { + /* Message is genuine */ +} +</pre> +</div> +<div class="Pp"></div> +This interface can be used to mitigate attacks that leverage power analysis and + fault injection (glitching) – both of which require physical access and + appropriate equipment – by injecting additional randomness (at least 32 + bytes) and padding (to the hash function's block size, which is 128 bytes for + all hash functions supported by Monocypher), of which 32 bytes are already + inserted into the buffer by + <b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(). Access to a + cryptographically secure pseudo-random generator is a requirement for + effective side channel mitigation. Signing a message with increased + power-related side channel mitigations: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t message [ 500]; /* Message to sign */ +uint8_t sk [ 32]; /* Secret key */ +const uint8_t pk [ 32]; /* Public key (optional) */ +uint8_t signature[ 64]; /* Output signature */ +uint8_t buf [128-32] = {0}; /* Mitigation buffer */ +crypto_sign_ctx ctx; +crypto_sign_ctx_abstract *actx = (crypto_sign_ctx_abstract *)&ctx; + +arc4random_buf(buf, 32); +/* The rest of buf MUST be zeroes. */ + +crypto_sign_init_first_pass(actx, sk, pk); +crypto_sign_update (actx, buf, sizeof(buf)); +crypto_sign_update (actx, message, 500); + +crypto_sign_init_second_pass(actx); +crypto_sign_update (actx, message, 500); +crypto_sign_final (actx, signature); + +crypto_wipe(buf, 32); +/* Wipe the secret key if no longer needed */ +crypto_wipe(sk, 32); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement PureEdDSA with Curve25519 and Blake2b, as described in + RFC 8032. This is the same as Ed25519, with Blake2b instead of SHA-512. +<div class="Pp"></div> +The example for side channel mitigation follows the methodology outlined in + I-D.draft-mattsson-cfrg-det-sigs-with-noise-02. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_sign_update</b>(), + <b class="Fn" title="Fn">crypto_sign_final</b>(), + <b class="Fn" title="Fn">crypto_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_check_init</b>(), + <b class="Fn" title="Fn">crypto_check_update</b>(), and + <b class="Fn" title="Fn">crypto_check_final</b>() functions first appeared in + Monocypher 1.1.0. +<div class="Pp"></div> +<b class="Sy" title="Sy">A critical security vulnerability</b> that caused + all-zero signatures to be accepted was introduced in Monocypher 0.3; it was + fixed in Monocypher 1.1.1 and 2.0.4. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +Messages are not verified until the call to + <b class="Fn" title="Fn">crypto_check_final</b>(). Messages may be stored + before they are verified, but they cannot be + <i class="Em" title="Em">trusted</i>. Processing untrusted messages increases + the attack surface of the system. Doing so securely is hard. Do not process + messages before calling <b class="Fn" title="Fn">crypto_check_final</b>(). +<div class="Pp"></div> +When signing messages, the security considerations documented in + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a> + also apply. In particular, if power-related side channels are part of your + threat model, note that there may still be other power-related side channels + (such as if the CPU leaks information when an operation overflows a register) + that must be considered. +<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION + DETAILS</a></h1> +EdDSA signatures require two passes that cannot be performed in parallel. There + are ways around this limitation, but they all lower security in some way. For + this reason, Monocypher does not support them.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_curve_to_hidden.html b/vendor/doc/html/crypto_curve_to_hidden.html new file mode 100644 index 0000000..bdbc6cb --- /dev/null +++ b/vendor/doc/html/crypto_curve_to_hidden.html @@ -0,0 +1,234 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_CURVE_TO_HIDDEN(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_CURVE_TO_HIDDEN(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_CURVE_TO_HIDDEN(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_curve_to_hidden</b>, + <b class="Nm" title="Nm">crypto_hidden_to_curve</b>, + <b class="Nm" title="Nm">crypto_hidden_key_pair</b> — + <span class="Nd" title="Nd">hiding of X25519 public keys</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_curve_to_hidden</b>(<var class="Fa" title="Fa">uint8_t + hidden[32]</var>, <var class="Fa" title="Fa">const uint8_t curve[32]</var>, + <var class="Fa" title="Fa">uint8_t tweak</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hidden_to_curve</b>(<var class="Fa" title="Fa">uint8_t + curve[32]</var>, <var class="Fa" title="Fa">const uint8_t hidden[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hidden_key_pair</b>(<var class="Fa" title="Fa">uint8_t + hidden[32]</var>, <var class="Fa" title="Fa">uint8_t secret_key[32]</var>, + <var class="Fa" title="Fa">uint8_t seed[32]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions allow obfuscating X25519 public keys by making them appear + effectively indistinguishable from random noise. This is of interest for key + exchange protocols that require indistinguishability from randomness, such as + padded uniform random blobs (PURBs). They are intended for ephemeral + (short-lived, possibly just one-time) X25519 keys, not for long-term public + keys. After an initial key exchange involving hidden keys, subsequent key + exchange messages should be encrypted instead; see, for example, the Noise + protocol. This is an <i class="Em" title="Em">advanced feature</i> – + unless you are implementing an protocol that requires indistinguishability of + all communications from random noise, consider + <a class="Xr" title="Xr" href="crypto_key_exchange_public_key.html">crypto_key_exchange_public_key(3monocypher)</a> + instead. +<div class="Pp"></div> +For understanding what these functions do, it is important to note that a + “public key” in this context refers to a + <i class="Em" title="Em">point on Curve25519</i>. This also means that these + functions are not compatible with + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a> + and related functions. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_curve_to_hidden</b>() takes a public key + <var class="Fa" title="Fa">curve</var> and a + <var class="Fa" title="Fa">tweak</var>, hiding the public key it so that it is + effectively indistinguishable from random noise. Note that only + <a class="Xr" title="Xr" href="crypto_x25519_dirty_fast.html">crypto_x25519_dirty_fast(3monocypher)</a> + or + <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a> + can generate a suitable public key; the + <a class="Xr" title="Xr" href="crypto_x25519.html">crypto_x25519(3monocypher)</a> + function is insufficient. The <var class="Fa" title="Fa">tweak</var> must be + chosen at random. Even then, this operation <i class="Em" title="Em">may</i> + fail: Not all curve points are capable of being hidden. In this case, + <b class="Fn" title="Fn">crypto_curve_to_hidden</b>() must be tried again with + a new key pair; the <var class="Fa" title="Fa">tweak</var> does not need to be + changed. On average, two attempts are needed. Once a suitable public key has + been found, <b class="Fn" title="Fn">crypto_curve_to_hidden</b>() always + succeeds for it. Given the same values for + <var class="Fa" title="Fa">tweak</var> and + <var class="Fa" title="Fa">curve</var>, + <b class="Fn" title="Fn">crypto_curve_to_hidden</b>() yields the same output + value <var class="Fa" title="Fa">hidden</var>. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_hidden_to_curve</b>() performs the inverse + operation: It decodes a hidden point to a curve point on Curve25519. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_hidden_key_pair</b>() is a convenience function + that generates a secret key and its corresponding public key, which is + effectively indistinguishable from random noise, from a random seed. + <i class="Em" title="Em">The execution time of this function is + unpredictable</i> because it may take many failures until a key pair could be + generated successfully. <b class="Fn" title="Fn">crypto_hidden_key_pair</b>() + uses + <a class="Xr" title="Xr" href="crypto_x25519_dirty_fast.html">crypto_x25519_dirty_fast(3monocypher)</a> + internally; if code size is an important concern, its functionality can be + replicated with + <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a> + instead. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">curve</var></dt> + <dd class="It-tag">A point on the curve, which is a Curve25519 public key + generated with either + <a class="Xr" title="Xr" href="crypto_x25519_dirty_fast.html">crypto_x25519_dirty_fast(3monocypher)</a> + or + <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a>.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hidden</var></dt> + <dd class="It-tag">The hidden encoding of a point on the curve which is + effectively indistinguishable from random.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">secret_key</var></dt> + <dd class="It-tag">The secret key that was generated from the given + <var class="Fa" title="Fa">seed</var>.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">seed</var></dt> + <dd class="It-tag">A 32-byte random number from which to derive a key pair. + See <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about generating random bytes (use the operating system's random + number generator). The <var class="Fa" title="Fa">seed</var> is wiped + automatically.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">tweak</var></dt> + <dd class="It-tag">A 1-byte random number, which influences the final output + of <b class="Fn" title="Fn">crypto_curve_to_hidden</b>().</dd> +</dl> +<div class="Pp"></div> +The <var class="Fa" title="Fa">hidden</var> and + <var class="Fa" title="Fa">curve</var> arguments may overlap or point at the + same buffer. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_curve_to_hidden</b>() returns 0 on success, -1 + if the given <var class="Fa" title="Fa">curve</var> argument is unsuitable for + hiding. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_hidden_to_curve</b>() and + <b class="Fn" title="Fn">crypto_hidden_key_pair</b>() return nothing; they + cannot fail. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +Generate a key pair manually using + <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a> + instead of its fast variant: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t sk [32]; /* Secret key output */ +uint8_t pk [32]; /* Hidden public key output */ +uint8_t tweak; /* Random tweak input */ +arc4random_buf(&tweak, 1); +for (;;) { + arc4random_buf(sk, 32); + crypto_x25519_dirty_small(pk, sk); + if (crypto_curve_to_hidden(pk, pk, tweak) == 0) + break; +} +/* Now save the secret key and send the hidden public key. */ +</pre> +</div> +<div class="Pp"></div> +Performing a key exchange with the other party's public key having been hidden: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hidden_pk [32]; /* Their hidden public key */ +uint8_t their_pk [32]; /* Their unhidden public key */ +uint8_t your_sk [32]; /* Your secret key */ +uint8_t shared_key[32]; /* Shared session key */ +crypto_hidden_to_curve(their_pk, hidden_pk); +crypto_key_exchange(shared_key, your_sk, their_pk); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(your_sk, 32); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_x25519.html">crypto_x25519(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement the Elligator 2 mapping for Curve25519. This mapping + is incompatible with both the hash-to-curve Internet draft and the + implementation of Elligator 2 in libsodium. Elligator 2 was described in: + <cite class="Rs" title="Rs"><span class="RsA">Daniel J. Bernstein</span>, + <span class="RsA">Mike Hamburg</span>, <span class="RsA">Anna Krasnova</span>, + and <span class="RsA">Tanja Lange</span>, <span class="RsT">Elligator: + Elliptic-curve points indistinguishable from uniform random strings</span>, + <i class="RsI">Association for Computing Machinery</i>, <i class="RsJ">CCS + '13: Proceedings of the 2013 ACM SIGSAC conference on Computer & + communications security</i>, <span class="RsP">pp. 967–980</span>, + <span class="RsD">2013</span>.</cite> +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_curve_to_hidden</b>(), + <b class="Fn" title="Fn">crypto_hidden_to_curve</b>(), and + <b class="Fn" title="Fn">crypto_hidden_key_pair</b>() functions first appeared + in Monocypher 3.1.0. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +The secret keys for the public keys fed into + <b class="Fn" title="Fn">crypto_curve_to_hidden</b>() + <b class="Sy" title="Sy">must be chosen randomly</b>, rather than + deterministically. Otherwise, the timing information given by the required + number of retries also leaks information on the secret keys. +<div class="Pp"></div> +These functions <i class="Em" title="Em">help</i> build highly + difficult-to-analyze protocols, but are insufficient by themselves: Other + metadata, such as the amount of bytes sent in a packet or the size of the + 32-byte random-looking string that represents the curve point itself, can be + very strong indicators of the use of cryptography. Consider using appropriate + padding algorithms, such as PADME, and obscure other metadata as much as + possible.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_ed25519_check.html b/vendor/doc/html/crypto_ed25519_check.html new file mode 100644 index 0000000..a31017a --- /dev/null +++ b/vendor/doc/html/crypto_ed25519_check.html @@ -0,0 +1,95 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_ED25519_SIGN(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_ED25519_SIGN(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_ED25519_SIGN(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_ed25519_sign</b>, + <b class="Nm" title="Nm">crypto_ed25519_check</b>, + <b class="Nm" title="Nm">crypto_ed25519_public_key</b> — + <span class="Nd" title="Nd">public key signatures</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher-ed25519.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_public_key</b>(<var class="Fa" title="Fa">uint8_t + public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t + secret_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign</b>(<var class="Fa" title="Fa">uint8_t + signature[64]</var>, <var class="Fa" title="Fa">const uint8_t + secret_key[32]</var>, <var class="Fa" title="Fa">const uint8_t + public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check</b>(<var class="Fa" title="Fa">const + uint8_t signature[64]</var>, <var class="Fa" title="Fa">const uint8_t + public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +The <b class="Fn" title="Fn">crypto_ed25519_sign</b>() and + <b class="Fn" title="Fn">crypto_ed25519_check</b>() functions provide Ed25519 + public key signatures and verification with SHA-512 as the underlying hash + function; they are interoperable with other Ed25519 implementations. If you + have no interoperability requirements, prefer + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +The arguments and security considerations are the same as those described in + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +An incremental interface is available; see + <a class="Xr" title="Xr" href="crypto_ed25519_sign_init_first_pass.html">crypto_ed25519_sign_init_first_pass(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_ed25519_public_key</b>() and + <b class="Fn" title="Fn">crypto_ed25519_sign</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_ed25519_check</b>() returns 0 for legitimate + messages and -1 for forgeries. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_check.html">crypto_check(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement Ed25519 as described in RFC 8032. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_ed25519_sign</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check</b>(), and + <b class="Fn" title="Fn">crypto_ed25519_public_key</b>() functions appeared in + Monocypher 3.0.0. They replace recompilation of Monocypher with the + <code class="Dv" title="Dv">ED25519_SHA512</code> preprocessor + definition.</div> +<table class="foot"> + <tr> + <td class="foot-date">May 24, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_ed25519_check_final.html b/vendor/doc/html/crypto_ed25519_check_final.html new file mode 100644 index 0000000..ed0a2a6 --- /dev/null +++ b/vendor/doc/html/crypto_ed25519_check_final.html @@ -0,0 +1,133 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_ed25519_sign_init_first_pass</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_update</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_final</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_init_second_pass</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_init</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_update</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_final</b> — + <span class="Nd" title="Nd">incremental public key signatures</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher-ed25519.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t secret_key[32]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t signature[64]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_init</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t signature[64]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_update</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_final</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions are variants of + <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_ed25519_check.html">crypto_ed25519_check(3monocypher)</a>. + Prefer those simpler functions if possible. +<div class="Pp"></div> +These functions provide Ed25519 public key signatures and verification with + SHA-512 as the underlying hash function; they are interoperable with other + Ed25519 implementations. If you have no interoperability requirements, prefer + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +The arguments, security considerations and semantics are the same as those + described in + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_init</b>() and + <b class="Fn" title="Fn">crypto_ed25519_check_update</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_ed25519_check_final</b>() returns 0 for + legitimate messages and -1 for forgeries. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement Ed25519 as described in RFC 8032. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_init</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_update</b>(), and + <b class="Fn" title="Fn">crypto_ed25519_check_final</b>() functions first + appeared in Monocypher 3.0.0. They replace recompilation of Monocypher with + the <code class="Dv" title="Dv">ED25519_SHA512</code> preprocessor + definition.</div> +<table class="foot"> + <tr> + <td class="foot-date">May 24, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_ed25519_check_init.html b/vendor/doc/html/crypto_ed25519_check_init.html new file mode 100644 index 0000000..ed0a2a6 --- /dev/null +++ b/vendor/doc/html/crypto_ed25519_check_init.html @@ -0,0 +1,133 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_ed25519_sign_init_first_pass</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_update</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_final</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_init_second_pass</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_init</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_update</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_final</b> — + <span class="Nd" title="Nd">incremental public key signatures</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher-ed25519.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t secret_key[32]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t signature[64]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_init</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t signature[64]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_update</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_final</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions are variants of + <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_ed25519_check.html">crypto_ed25519_check(3monocypher)</a>. + Prefer those simpler functions if possible. +<div class="Pp"></div> +These functions provide Ed25519 public key signatures and verification with + SHA-512 as the underlying hash function; they are interoperable with other + Ed25519 implementations. If you have no interoperability requirements, prefer + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +The arguments, security considerations and semantics are the same as those + described in + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_init</b>() and + <b class="Fn" title="Fn">crypto_ed25519_check_update</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_ed25519_check_final</b>() returns 0 for + legitimate messages and -1 for forgeries. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement Ed25519 as described in RFC 8032. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_init</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_update</b>(), and + <b class="Fn" title="Fn">crypto_ed25519_check_final</b>() functions first + appeared in Monocypher 3.0.0. They replace recompilation of Monocypher with + the <code class="Dv" title="Dv">ED25519_SHA512</code> preprocessor + definition.</div> +<table class="foot"> + <tr> + <td class="foot-date">May 24, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_ed25519_check_update.html b/vendor/doc/html/crypto_ed25519_check_update.html new file mode 100644 index 0000000..ed0a2a6 --- /dev/null +++ b/vendor/doc/html/crypto_ed25519_check_update.html @@ -0,0 +1,133 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_ed25519_sign_init_first_pass</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_update</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_final</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_init_second_pass</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_init</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_update</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_final</b> — + <span class="Nd" title="Nd">incremental public key signatures</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher-ed25519.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t secret_key[32]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t signature[64]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_init</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t signature[64]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_update</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_final</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions are variants of + <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_ed25519_check.html">crypto_ed25519_check(3monocypher)</a>. + Prefer those simpler functions if possible. +<div class="Pp"></div> +These functions provide Ed25519 public key signatures and verification with + SHA-512 as the underlying hash function; they are interoperable with other + Ed25519 implementations. If you have no interoperability requirements, prefer + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +The arguments, security considerations and semantics are the same as those + described in + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_init</b>() and + <b class="Fn" title="Fn">crypto_ed25519_check_update</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_ed25519_check_final</b>() returns 0 for + legitimate messages and -1 for forgeries. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement Ed25519 as described in RFC 8032. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_init</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_update</b>(), and + <b class="Fn" title="Fn">crypto_ed25519_check_final</b>() functions first + appeared in Monocypher 3.0.0. They replace recompilation of Monocypher with + the <code class="Dv" title="Dv">ED25519_SHA512</code> preprocessor + definition.</div> +<table class="foot"> + <tr> + <td class="foot-date">May 24, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_ed25519_public_key.html b/vendor/doc/html/crypto_ed25519_public_key.html new file mode 100644 index 0000000..a31017a --- /dev/null +++ b/vendor/doc/html/crypto_ed25519_public_key.html @@ -0,0 +1,95 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_ED25519_SIGN(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_ED25519_SIGN(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_ED25519_SIGN(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_ed25519_sign</b>, + <b class="Nm" title="Nm">crypto_ed25519_check</b>, + <b class="Nm" title="Nm">crypto_ed25519_public_key</b> — + <span class="Nd" title="Nd">public key signatures</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher-ed25519.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_public_key</b>(<var class="Fa" title="Fa">uint8_t + public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t + secret_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign</b>(<var class="Fa" title="Fa">uint8_t + signature[64]</var>, <var class="Fa" title="Fa">const uint8_t + secret_key[32]</var>, <var class="Fa" title="Fa">const uint8_t + public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check</b>(<var class="Fa" title="Fa">const + uint8_t signature[64]</var>, <var class="Fa" title="Fa">const uint8_t + public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +The <b class="Fn" title="Fn">crypto_ed25519_sign</b>() and + <b class="Fn" title="Fn">crypto_ed25519_check</b>() functions provide Ed25519 + public key signatures and verification with SHA-512 as the underlying hash + function; they are interoperable with other Ed25519 implementations. If you + have no interoperability requirements, prefer + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +The arguments and security considerations are the same as those described in + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +An incremental interface is available; see + <a class="Xr" title="Xr" href="crypto_ed25519_sign_init_first_pass.html">crypto_ed25519_sign_init_first_pass(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_ed25519_public_key</b>() and + <b class="Fn" title="Fn">crypto_ed25519_sign</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_ed25519_check</b>() returns 0 for legitimate + messages and -1 for forgeries. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_check.html">crypto_check(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement Ed25519 as described in RFC 8032. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_ed25519_sign</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check</b>(), and + <b class="Fn" title="Fn">crypto_ed25519_public_key</b>() functions appeared in + Monocypher 3.0.0. They replace recompilation of Monocypher with the + <code class="Dv" title="Dv">ED25519_SHA512</code> preprocessor + definition.</div> +<table class="foot"> + <tr> + <td class="foot-date">May 24, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_ed25519_sign.html b/vendor/doc/html/crypto_ed25519_sign.html new file mode 100644 index 0000000..a31017a --- /dev/null +++ b/vendor/doc/html/crypto_ed25519_sign.html @@ -0,0 +1,95 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_ED25519_SIGN(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_ED25519_SIGN(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_ED25519_SIGN(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_ed25519_sign</b>, + <b class="Nm" title="Nm">crypto_ed25519_check</b>, + <b class="Nm" title="Nm">crypto_ed25519_public_key</b> — + <span class="Nd" title="Nd">public key signatures</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher-ed25519.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_public_key</b>(<var class="Fa" title="Fa">uint8_t + public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t + secret_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign</b>(<var class="Fa" title="Fa">uint8_t + signature[64]</var>, <var class="Fa" title="Fa">const uint8_t + secret_key[32]</var>, <var class="Fa" title="Fa">const uint8_t + public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check</b>(<var class="Fa" title="Fa">const + uint8_t signature[64]</var>, <var class="Fa" title="Fa">const uint8_t + public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +The <b class="Fn" title="Fn">crypto_ed25519_sign</b>() and + <b class="Fn" title="Fn">crypto_ed25519_check</b>() functions provide Ed25519 + public key signatures and verification with SHA-512 as the underlying hash + function; they are interoperable with other Ed25519 implementations. If you + have no interoperability requirements, prefer + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +The arguments and security considerations are the same as those described in + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +An incremental interface is available; see + <a class="Xr" title="Xr" href="crypto_ed25519_sign_init_first_pass.html">crypto_ed25519_sign_init_first_pass(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_ed25519_public_key</b>() and + <b class="Fn" title="Fn">crypto_ed25519_sign</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_ed25519_check</b>() returns 0 for legitimate + messages and -1 for forgeries. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_check.html">crypto_check(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement Ed25519 as described in RFC 8032. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_ed25519_sign</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check</b>(), and + <b class="Fn" title="Fn">crypto_ed25519_public_key</b>() functions appeared in + Monocypher 3.0.0. They replace recompilation of Monocypher with the + <code class="Dv" title="Dv">ED25519_SHA512</code> preprocessor + definition.</div> +<table class="foot"> + <tr> + <td class="foot-date">May 24, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_ed25519_sign_final.html b/vendor/doc/html/crypto_ed25519_sign_final.html new file mode 100644 index 0000000..ed0a2a6 --- /dev/null +++ b/vendor/doc/html/crypto_ed25519_sign_final.html @@ -0,0 +1,133 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_ed25519_sign_init_first_pass</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_update</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_final</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_init_second_pass</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_init</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_update</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_final</b> — + <span class="Nd" title="Nd">incremental public key signatures</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher-ed25519.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t secret_key[32]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t signature[64]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_init</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t signature[64]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_update</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_final</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions are variants of + <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_ed25519_check.html">crypto_ed25519_check(3monocypher)</a>. + Prefer those simpler functions if possible. +<div class="Pp"></div> +These functions provide Ed25519 public key signatures and verification with + SHA-512 as the underlying hash function; they are interoperable with other + Ed25519 implementations. If you have no interoperability requirements, prefer + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +The arguments, security considerations and semantics are the same as those + described in + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_init</b>() and + <b class="Fn" title="Fn">crypto_ed25519_check_update</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_ed25519_check_final</b>() returns 0 for + legitimate messages and -1 for forgeries. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement Ed25519 as described in RFC 8032. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_init</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_update</b>(), and + <b class="Fn" title="Fn">crypto_ed25519_check_final</b>() functions first + appeared in Monocypher 3.0.0. They replace recompilation of Monocypher with + the <code class="Dv" title="Dv">ED25519_SHA512</code> preprocessor + definition.</div> +<table class="foot"> + <tr> + <td class="foot-date">May 24, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_ed25519_sign_init_first_pass.html b/vendor/doc/html/crypto_ed25519_sign_init_first_pass.html new file mode 100644 index 0000000..ed0a2a6 --- /dev/null +++ b/vendor/doc/html/crypto_ed25519_sign_init_first_pass.html @@ -0,0 +1,133 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_ed25519_sign_init_first_pass</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_update</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_final</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_init_second_pass</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_init</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_update</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_final</b> — + <span class="Nd" title="Nd">incremental public key signatures</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher-ed25519.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t secret_key[32]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t signature[64]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_init</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t signature[64]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_update</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_final</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions are variants of + <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_ed25519_check.html">crypto_ed25519_check(3monocypher)</a>. + Prefer those simpler functions if possible. +<div class="Pp"></div> +These functions provide Ed25519 public key signatures and verification with + SHA-512 as the underlying hash function; they are interoperable with other + Ed25519 implementations. If you have no interoperability requirements, prefer + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +The arguments, security considerations and semantics are the same as those + described in + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_init</b>() and + <b class="Fn" title="Fn">crypto_ed25519_check_update</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_ed25519_check_final</b>() returns 0 for + legitimate messages and -1 for forgeries. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement Ed25519 as described in RFC 8032. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_init</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_update</b>(), and + <b class="Fn" title="Fn">crypto_ed25519_check_final</b>() functions first + appeared in Monocypher 3.0.0. They replace recompilation of Monocypher with + the <code class="Dv" title="Dv">ED25519_SHA512</code> preprocessor + definition.</div> +<table class="foot"> + <tr> + <td class="foot-date">May 24, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_ed25519_sign_init_second_pass.html b/vendor/doc/html/crypto_ed25519_sign_init_second_pass.html new file mode 100644 index 0000000..ed0a2a6 --- /dev/null +++ b/vendor/doc/html/crypto_ed25519_sign_init_second_pass.html @@ -0,0 +1,133 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_ed25519_sign_init_first_pass</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_update</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_final</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_init_second_pass</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_init</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_update</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_final</b> — + <span class="Nd" title="Nd">incremental public key signatures</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher-ed25519.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t secret_key[32]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t signature[64]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_init</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t signature[64]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_update</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_final</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions are variants of + <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_ed25519_check.html">crypto_ed25519_check(3monocypher)</a>. + Prefer those simpler functions if possible. +<div class="Pp"></div> +These functions provide Ed25519 public key signatures and verification with + SHA-512 as the underlying hash function; they are interoperable with other + Ed25519 implementations. If you have no interoperability requirements, prefer + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +The arguments, security considerations and semantics are the same as those + described in + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_init</b>() and + <b class="Fn" title="Fn">crypto_ed25519_check_update</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_ed25519_check_final</b>() returns 0 for + legitimate messages and -1 for forgeries. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement Ed25519 as described in RFC 8032. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_init</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_update</b>(), and + <b class="Fn" title="Fn">crypto_ed25519_check_final</b>() functions first + appeared in Monocypher 3.0.0. They replace recompilation of Monocypher with + the <code class="Dv" title="Dv">ED25519_SHA512</code> preprocessor + definition.</div> +<table class="foot"> + <tr> + <td class="foot-date">May 24, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_ed25519_sign_update.html b/vendor/doc/html/crypto_ed25519_sign_update.html new file mode 100644 index 0000000..ed0a2a6 --- /dev/null +++ b/vendor/doc/html/crypto_ed25519_sign_update.html @@ -0,0 +1,133 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_ED25519_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_ed25519_sign_init_first_pass</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_update</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_final</b>, + <b class="Nm" title="Nm">crypto_ed25519_sign_init_second_pass</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_init</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_update</b>, + <b class="Nm" title="Nm">crypto_ed25519_check_final</b> — + <span class="Nd" title="Nd">incremental public key signatures</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher-ed25519.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t secret_key[32]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t signature[64]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(<var class="Fa" title="Fa">crypto_ed25519_sign_ctx + *ctx</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_init</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t signature[64]</var>, + <var class="Fa" title="Fa">const uint8_t public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_update</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_ed25519_check_final</b>(<var class="Fa" title="Fa">crypto_ed25519_check_ctx + *ctx</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions are variants of + <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_ed25519_check.html">crypto_ed25519_check(3monocypher)</a>. + Prefer those simpler functions if possible. +<div class="Pp"></div> +These functions provide Ed25519 public key signatures and verification with + SHA-512 as the underlying hash function; they are interoperable with other + Ed25519 implementations. If you have no interoperability requirements, prefer + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<div class="Pp"></div> +The arguments, security considerations and semantics are the same as those + described in + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_init</b>() and + <b class="Fn" title="Fn">crypto_ed25519_check_update</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_ed25519_check_final</b>() returns 0 for + legitimate messages and -1 for forgeries. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement Ed25519 as described in RFC 8032. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_ed25519_sign_init_first_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_update</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_final</b>(), + <b class="Fn" title="Fn">crypto_ed25519_sign_init_second_pass</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_init</b>(), + <b class="Fn" title="Fn">crypto_ed25519_check_update</b>(), and + <b class="Fn" title="Fn">crypto_ed25519_check_final</b>() functions first + appeared in Monocypher 3.0.0. They replace recompilation of Monocypher with + the <code class="Dv" title="Dv">ED25519_SHA512</code> preprocessor + definition.</div> +<table class="foot"> + <tr> + <td class="foot-date">May 24, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_from_ed25519_private.html b/vendor/doc/html/crypto_from_ed25519_private.html new file mode 100644 index 0000000..ca08f10 --- /dev/null +++ b/vendor/doc/html/crypto_from_ed25519_private.html @@ -0,0 +1,64 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_FROM_ED25519_PRIVATE(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_FROM_ED25519_PRIVATE(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_FROM_ED25519_PRIVATE(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_from_ed25519_private</b>, + <b class="Nm" title="Nm">crypto_from_ed25519_public</b> — + <span class="Nd" title="Nd">conversion of key pairs for EdDSA with BLAKE2b to + X25519 key pairs</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher-ed25519.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_from_ed25519_private</b>(<var class="Fa" title="Fa">uint8_t + x25519[32]</var>, <var class="Fa" title="Fa">const uint8_t eddsa[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_from_ed25519_public</b>(<var class="Fa" title="Fa">uint8_t + x25519[32]</var>, <var class="Fa" title="Fa">const uint8_t eddsa[32]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions work like + <a class="Xr" title="Xr" href="crypto_from_eddsa_private.html">crypto_from_eddsa_private(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_from_eddsa_public.html">crypto_from_eddsa_public(3monocypher)</a>, + except that they operate on Ed25519 key pairs rather than key pairs for EdDSA + with BLAKE2b. Please see the documentation for those functions for details. +<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION + DETAILS</a></h1> +<b class="Fn" title="Fn">crypto_from_ed25519_public</b>() is actually + implemented as a macro that aliases to + <a class="Xr" title="Xr" href="crypto_from_eddsa_public.html">crypto_from_eddsa_public(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_from_ed25519_private</b>() and + <b class="Fn" title="Fn">crypto_from_ed25519_public</b>() functions first + appeared in Monocypher 3.1.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">May 24, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_from_ed25519_public.html b/vendor/doc/html/crypto_from_ed25519_public.html new file mode 100644 index 0000000..ca08f10 --- /dev/null +++ b/vendor/doc/html/crypto_from_ed25519_public.html @@ -0,0 +1,64 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_FROM_ED25519_PRIVATE(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_FROM_ED25519_PRIVATE(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_FROM_ED25519_PRIVATE(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_from_ed25519_private</b>, + <b class="Nm" title="Nm">crypto_from_ed25519_public</b> — + <span class="Nd" title="Nd">conversion of key pairs for EdDSA with BLAKE2b to + X25519 key pairs</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher-ed25519.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_from_ed25519_private</b>(<var class="Fa" title="Fa">uint8_t + x25519[32]</var>, <var class="Fa" title="Fa">const uint8_t eddsa[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_from_ed25519_public</b>(<var class="Fa" title="Fa">uint8_t + x25519[32]</var>, <var class="Fa" title="Fa">const uint8_t eddsa[32]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions work like + <a class="Xr" title="Xr" href="crypto_from_eddsa_private.html">crypto_from_eddsa_private(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_from_eddsa_public.html">crypto_from_eddsa_public(3monocypher)</a>, + except that they operate on Ed25519 key pairs rather than key pairs for EdDSA + with BLAKE2b. Please see the documentation for those functions for details. +<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION + DETAILS</a></h1> +<b class="Fn" title="Fn">crypto_from_ed25519_public</b>() is actually + implemented as a macro that aliases to + <a class="Xr" title="Xr" href="crypto_from_eddsa_public.html">crypto_from_eddsa_public(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_from_ed25519_private</b>() and + <b class="Fn" title="Fn">crypto_from_ed25519_public</b>() functions first + appeared in Monocypher 3.1.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">May 24, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_from_eddsa_private.html b/vendor/doc/html/crypto_from_eddsa_private.html new file mode 100644 index 0000000..4b55a99 --- /dev/null +++ b/vendor/doc/html/crypto_from_eddsa_private.html @@ -0,0 +1,106 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_FROM_EDDSA_PRIVATE(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_FROM_EDDSA_PRIVATE(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_FROM_EDDSA_PRIVATE(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_from_eddsa_private</b>, + <b class="Nm" title="Nm">crypto_from_eddsa_public</b> — + <span class="Nd" title="Nd">conversion of key pairs for EdDSA with BLAKE2b to + X25519 key pairs</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_from_eddsa_private</b>(<var class="Fa" title="Fa">uint8_t + x25519[32]</var>, <var class="Fa" title="Fa">const uint8_t eddsa[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_from_eddsa_public</b>(<var class="Fa" title="Fa">uint8_t + x25519[32]</var>, <var class="Fa" title="Fa">const uint8_t eddsa[32]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions convert keys for use with + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a> + (EdDSA with the BLAKE2b hash function) to keys for use with + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_x25519.html">crypto_x25519(3monocypher)</a>. + This may be useful in some resource-constrained contexts or when no other key + is available (for example, when retrieving SSH public keys from GitHub and + reusing the SSH public keys as X25519 public keys). +<div class="Pp"></div> +The <b class="Fn" title="Fn">crypto_from_eddsa_private</b>() function converts + an EdDSA (with BLAKE2b) private key to an X25519 private key. The + <b class="Fn" title="Fn">crypto_from_eddsa_public</b>() function converts an + EdDSA public key to an X25519 public key. +<div class="Pp"></div> +X25519 key pairs cannot be converted back to EdDSA key pairs. The conversion of + private keys is specific to EdDSA with BLAKE2b because of the way EdDSA works. + In particular, this means that the output of + <b class="Fn" title="Fn">crypto_from_eddsa_private</b>() differs from + <a class="Xr" title="Xr" href="crypto_from_ed25519_private.html">crypto_from_ed25519_private(3monocypher)</a> + in the optional code. However, the output of + <b class="Fn" title="Fn">crypto_from_eddsa_public</b>() is identical to + <a class="Xr" title="Xr" href="crypto_from_ed25519_public.html">crypto_from_ed25519_public(3monocypher)</a>. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">eddsa</var></dt> + <dd class="It-tag">The signing public key or private key to convert to a + X25519 public key or private key, respectively.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">x25519</var></dt> + <dd class="It-tag">The converted private key or public key.</dd> +</dl> +<div class="Pp"></div> +The arguments may overlap or point at the same buffer. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. They cannot fail. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange_public_key.html">crypto_key_exchange_public_key(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign_public_key.html">crypto_sign_public_key(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_from_eddsa_private</b>() and + <b class="Fn" title="Fn">crypto_from_eddsa_public</b>() functions first + appeared in Monocypher 3.1.0. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +It is generally considered poor form to reuse the same key for different + purposes. While this conversion is technically safe, avoid these functions + nonetheless unless you are particularly resource-constrained or have some + other kind of hard requirement. It is otherwise an unnecessary risk + factor.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 25, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_from_eddsa_public.html b/vendor/doc/html/crypto_from_eddsa_public.html new file mode 100644 index 0000000..4b55a99 --- /dev/null +++ b/vendor/doc/html/crypto_from_eddsa_public.html @@ -0,0 +1,106 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_FROM_EDDSA_PRIVATE(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_FROM_EDDSA_PRIVATE(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_FROM_EDDSA_PRIVATE(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_from_eddsa_private</b>, + <b class="Nm" title="Nm">crypto_from_eddsa_public</b> — + <span class="Nd" title="Nd">conversion of key pairs for EdDSA with BLAKE2b to + X25519 key pairs</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_from_eddsa_private</b>(<var class="Fa" title="Fa">uint8_t + x25519[32]</var>, <var class="Fa" title="Fa">const uint8_t eddsa[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_from_eddsa_public</b>(<var class="Fa" title="Fa">uint8_t + x25519[32]</var>, <var class="Fa" title="Fa">const uint8_t eddsa[32]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions convert keys for use with + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a> + (EdDSA with the BLAKE2b hash function) to keys for use with + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_x25519.html">crypto_x25519(3monocypher)</a>. + This may be useful in some resource-constrained contexts or when no other key + is available (for example, when retrieving SSH public keys from GitHub and + reusing the SSH public keys as X25519 public keys). +<div class="Pp"></div> +The <b class="Fn" title="Fn">crypto_from_eddsa_private</b>() function converts + an EdDSA (with BLAKE2b) private key to an X25519 private key. The + <b class="Fn" title="Fn">crypto_from_eddsa_public</b>() function converts an + EdDSA public key to an X25519 public key. +<div class="Pp"></div> +X25519 key pairs cannot be converted back to EdDSA key pairs. The conversion of + private keys is specific to EdDSA with BLAKE2b because of the way EdDSA works. + In particular, this means that the output of + <b class="Fn" title="Fn">crypto_from_eddsa_private</b>() differs from + <a class="Xr" title="Xr" href="crypto_from_ed25519_private.html">crypto_from_ed25519_private(3monocypher)</a> + in the optional code. However, the output of + <b class="Fn" title="Fn">crypto_from_eddsa_public</b>() is identical to + <a class="Xr" title="Xr" href="crypto_from_ed25519_public.html">crypto_from_ed25519_public(3monocypher)</a>. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">eddsa</var></dt> + <dd class="It-tag">The signing public key or private key to convert to a + X25519 public key or private key, respectively.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">x25519</var></dt> + <dd class="It-tag">The converted private key or public key.</dd> +</dl> +<div class="Pp"></div> +The arguments may overlap or point at the same buffer. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. They cannot fail. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange_public_key.html">crypto_key_exchange_public_key(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sign_public_key.html">crypto_sign_public_key(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_from_eddsa_private</b>() and + <b class="Fn" title="Fn">crypto_from_eddsa_public</b>() functions first + appeared in Monocypher 3.1.0. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +It is generally considered poor form to reuse the same key for different + purposes. While this conversion is technically safe, avoid these functions + nonetheless unless you are particularly resource-constrained or have some + other kind of hard requirement. It is otherwise an unnecessary risk + factor.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 25, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_hchacha20.html b/vendor/doc/html/crypto_hchacha20.html new file mode 100644 index 0000000..04177b6 --- /dev/null +++ b/vendor/doc/html/crypto_hchacha20.html @@ -0,0 +1,110 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_HCHACHA20(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_HCHACHA20(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_HCHACHA20(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_hchacha20</b> — + <span class="Nd" title="Nd">HChacha20 special-purpose hashing</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hchacha20</b>(<var class="Fa" title="Fa">uint8_t + out[32]</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t in[16]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<b class="Fn" title="Fn">crypto_hchacha20</b>() provides a not-so-cryptographic + hash. It may be used for some specific purposes, such as X25519 key + derivation, or XChacha20 initialisation. If in doubt, do not use directly. Use + <a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a> + instead. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">A sufficiently random key, such as the output of + <a class="Xr" title="Xr" href="crypto_x25519.html">crypto_x25519(3monocypher)</a>.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">in</var></dt> + <dd class="It-tag">The space reserved for the Chacha20 nonce and counter. It + does not have to be random.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">out</var></dt> + <dd class="It-tag">A cryptographically secure random number + <i class="Em" title="Em">if</i> there is enough entropy in + <var class="Fa" title="Fa">key</var>. X25519 shared secrets have enough + entropy.</dd> +</dl> +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +This function returns nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following example assumes the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Simple hash: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key[32]; /* Must have enough entropy */ +uint8_t in [16]; /* Does not have to be random */ +uint8_t out[32]; /* Will be random iff the above holds */ +arc4random_buf(key, 32); +crypto_hchacha20(out, key, in); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(key, 32); +crypto_wipe(in , 16); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_chacha20_encrypt.html">crypto_chacha20_encrypt(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +This function implements HChacha20. HChacha20 derives from Chacha20 the same way + HSalsa20 derives from Salsa20. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_hchacha20</b>() function first appeared in + Monocypher 0.1 as <b class="Fn" title="Fn">crypto_chacha20_H</b>(). It was + renamed to <b class="Fn" title="Fn">crypto_hchacha20</b>() in Monocypher + 3.0.0. +<h1 class="Sh" title="Sh" id="CAVEATS"><a class="selflink" href="#CAVEATS">CAVEATS</a></h1> +<b class="Sy" title="Sy">This is not a general-purpose cryptographic hash + function</b>.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 2, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_hidden_key_pair.html b/vendor/doc/html/crypto_hidden_key_pair.html new file mode 100644 index 0000000..bdbc6cb --- /dev/null +++ b/vendor/doc/html/crypto_hidden_key_pair.html @@ -0,0 +1,234 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_CURVE_TO_HIDDEN(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_CURVE_TO_HIDDEN(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_CURVE_TO_HIDDEN(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_curve_to_hidden</b>, + <b class="Nm" title="Nm">crypto_hidden_to_curve</b>, + <b class="Nm" title="Nm">crypto_hidden_key_pair</b> — + <span class="Nd" title="Nd">hiding of X25519 public keys</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_curve_to_hidden</b>(<var class="Fa" title="Fa">uint8_t + hidden[32]</var>, <var class="Fa" title="Fa">const uint8_t curve[32]</var>, + <var class="Fa" title="Fa">uint8_t tweak</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hidden_to_curve</b>(<var class="Fa" title="Fa">uint8_t + curve[32]</var>, <var class="Fa" title="Fa">const uint8_t hidden[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hidden_key_pair</b>(<var class="Fa" title="Fa">uint8_t + hidden[32]</var>, <var class="Fa" title="Fa">uint8_t secret_key[32]</var>, + <var class="Fa" title="Fa">uint8_t seed[32]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions allow obfuscating X25519 public keys by making them appear + effectively indistinguishable from random noise. This is of interest for key + exchange protocols that require indistinguishability from randomness, such as + padded uniform random blobs (PURBs). They are intended for ephemeral + (short-lived, possibly just one-time) X25519 keys, not for long-term public + keys. After an initial key exchange involving hidden keys, subsequent key + exchange messages should be encrypted instead; see, for example, the Noise + protocol. This is an <i class="Em" title="Em">advanced feature</i> – + unless you are implementing an protocol that requires indistinguishability of + all communications from random noise, consider + <a class="Xr" title="Xr" href="crypto_key_exchange_public_key.html">crypto_key_exchange_public_key(3monocypher)</a> + instead. +<div class="Pp"></div> +For understanding what these functions do, it is important to note that a + “public key” in this context refers to a + <i class="Em" title="Em">point on Curve25519</i>. This also means that these + functions are not compatible with + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a> + and related functions. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_curve_to_hidden</b>() takes a public key + <var class="Fa" title="Fa">curve</var> and a + <var class="Fa" title="Fa">tweak</var>, hiding the public key it so that it is + effectively indistinguishable from random noise. Note that only + <a class="Xr" title="Xr" href="crypto_x25519_dirty_fast.html">crypto_x25519_dirty_fast(3monocypher)</a> + or + <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a> + can generate a suitable public key; the + <a class="Xr" title="Xr" href="crypto_x25519.html">crypto_x25519(3monocypher)</a> + function is insufficient. The <var class="Fa" title="Fa">tweak</var> must be + chosen at random. Even then, this operation <i class="Em" title="Em">may</i> + fail: Not all curve points are capable of being hidden. In this case, + <b class="Fn" title="Fn">crypto_curve_to_hidden</b>() must be tried again with + a new key pair; the <var class="Fa" title="Fa">tweak</var> does not need to be + changed. On average, two attempts are needed. Once a suitable public key has + been found, <b class="Fn" title="Fn">crypto_curve_to_hidden</b>() always + succeeds for it. Given the same values for + <var class="Fa" title="Fa">tweak</var> and + <var class="Fa" title="Fa">curve</var>, + <b class="Fn" title="Fn">crypto_curve_to_hidden</b>() yields the same output + value <var class="Fa" title="Fa">hidden</var>. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_hidden_to_curve</b>() performs the inverse + operation: It decodes a hidden point to a curve point on Curve25519. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_hidden_key_pair</b>() is a convenience function + that generates a secret key and its corresponding public key, which is + effectively indistinguishable from random noise, from a random seed. + <i class="Em" title="Em">The execution time of this function is + unpredictable</i> because it may take many failures until a key pair could be + generated successfully. <b class="Fn" title="Fn">crypto_hidden_key_pair</b>() + uses + <a class="Xr" title="Xr" href="crypto_x25519_dirty_fast.html">crypto_x25519_dirty_fast(3monocypher)</a> + internally; if code size is an important concern, its functionality can be + replicated with + <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a> + instead. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">curve</var></dt> + <dd class="It-tag">A point on the curve, which is a Curve25519 public key + generated with either + <a class="Xr" title="Xr" href="crypto_x25519_dirty_fast.html">crypto_x25519_dirty_fast(3monocypher)</a> + or + <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a>.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hidden</var></dt> + <dd class="It-tag">The hidden encoding of a point on the curve which is + effectively indistinguishable from random.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">secret_key</var></dt> + <dd class="It-tag">The secret key that was generated from the given + <var class="Fa" title="Fa">seed</var>.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">seed</var></dt> + <dd class="It-tag">A 32-byte random number from which to derive a key pair. + See <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about generating random bytes (use the operating system's random + number generator). The <var class="Fa" title="Fa">seed</var> is wiped + automatically.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">tweak</var></dt> + <dd class="It-tag">A 1-byte random number, which influences the final output + of <b class="Fn" title="Fn">crypto_curve_to_hidden</b>().</dd> +</dl> +<div class="Pp"></div> +The <var class="Fa" title="Fa">hidden</var> and + <var class="Fa" title="Fa">curve</var> arguments may overlap or point at the + same buffer. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_curve_to_hidden</b>() returns 0 on success, -1 + if the given <var class="Fa" title="Fa">curve</var> argument is unsuitable for + hiding. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_hidden_to_curve</b>() and + <b class="Fn" title="Fn">crypto_hidden_key_pair</b>() return nothing; they + cannot fail. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +Generate a key pair manually using + <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a> + instead of its fast variant: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t sk [32]; /* Secret key output */ +uint8_t pk [32]; /* Hidden public key output */ +uint8_t tweak; /* Random tweak input */ +arc4random_buf(&tweak, 1); +for (;;) { + arc4random_buf(sk, 32); + crypto_x25519_dirty_small(pk, sk); + if (crypto_curve_to_hidden(pk, pk, tweak) == 0) + break; +} +/* Now save the secret key and send the hidden public key. */ +</pre> +</div> +<div class="Pp"></div> +Performing a key exchange with the other party's public key having been hidden: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hidden_pk [32]; /* Their hidden public key */ +uint8_t their_pk [32]; /* Their unhidden public key */ +uint8_t your_sk [32]; /* Your secret key */ +uint8_t shared_key[32]; /* Shared session key */ +crypto_hidden_to_curve(their_pk, hidden_pk); +crypto_key_exchange(shared_key, your_sk, their_pk); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(your_sk, 32); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_x25519.html">crypto_x25519(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement the Elligator 2 mapping for Curve25519. This mapping + is incompatible with both the hash-to-curve Internet draft and the + implementation of Elligator 2 in libsodium. Elligator 2 was described in: + <cite class="Rs" title="Rs"><span class="RsA">Daniel J. Bernstein</span>, + <span class="RsA">Mike Hamburg</span>, <span class="RsA">Anna Krasnova</span>, + and <span class="RsA">Tanja Lange</span>, <span class="RsT">Elligator: + Elliptic-curve points indistinguishable from uniform random strings</span>, + <i class="RsI">Association for Computing Machinery</i>, <i class="RsJ">CCS + '13: Proceedings of the 2013 ACM SIGSAC conference on Computer & + communications security</i>, <span class="RsP">pp. 967–980</span>, + <span class="RsD">2013</span>.</cite> +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_curve_to_hidden</b>(), + <b class="Fn" title="Fn">crypto_hidden_to_curve</b>(), and + <b class="Fn" title="Fn">crypto_hidden_key_pair</b>() functions first appeared + in Monocypher 3.1.0. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +The secret keys for the public keys fed into + <b class="Fn" title="Fn">crypto_curve_to_hidden</b>() + <b class="Sy" title="Sy">must be chosen randomly</b>, rather than + deterministically. Otherwise, the timing information given by the required + number of retries also leaks information on the secret keys. +<div class="Pp"></div> +These functions <i class="Em" title="Em">help</i> build highly + difficult-to-analyze protocols, but are insufficient by themselves: Other + metadata, such as the amount of bytes sent in a packet or the size of the + 32-byte random-looking string that represents the curve point itself, can be + very strong indicators of the use of cryptography. Consider using appropriate + padding algorithms, such as PADME, and obscure other metadata as much as + possible.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_hidden_to_curve.html b/vendor/doc/html/crypto_hidden_to_curve.html new file mode 100644 index 0000000..bdbc6cb --- /dev/null +++ b/vendor/doc/html/crypto_hidden_to_curve.html @@ -0,0 +1,234 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_CURVE_TO_HIDDEN(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_CURVE_TO_HIDDEN(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_CURVE_TO_HIDDEN(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_curve_to_hidden</b>, + <b class="Nm" title="Nm">crypto_hidden_to_curve</b>, + <b class="Nm" title="Nm">crypto_hidden_key_pair</b> — + <span class="Nd" title="Nd">hiding of X25519 public keys</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_curve_to_hidden</b>(<var class="Fa" title="Fa">uint8_t + hidden[32]</var>, <var class="Fa" title="Fa">const uint8_t curve[32]</var>, + <var class="Fa" title="Fa">uint8_t tweak</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hidden_to_curve</b>(<var class="Fa" title="Fa">uint8_t + curve[32]</var>, <var class="Fa" title="Fa">const uint8_t hidden[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hidden_key_pair</b>(<var class="Fa" title="Fa">uint8_t + hidden[32]</var>, <var class="Fa" title="Fa">uint8_t secret_key[32]</var>, + <var class="Fa" title="Fa">uint8_t seed[32]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions allow obfuscating X25519 public keys by making them appear + effectively indistinguishable from random noise. This is of interest for key + exchange protocols that require indistinguishability from randomness, such as + padded uniform random blobs (PURBs). They are intended for ephemeral + (short-lived, possibly just one-time) X25519 keys, not for long-term public + keys. After an initial key exchange involving hidden keys, subsequent key + exchange messages should be encrypted instead; see, for example, the Noise + protocol. This is an <i class="Em" title="Em">advanced feature</i> – + unless you are implementing an protocol that requires indistinguishability of + all communications from random noise, consider + <a class="Xr" title="Xr" href="crypto_key_exchange_public_key.html">crypto_key_exchange_public_key(3monocypher)</a> + instead. +<div class="Pp"></div> +For understanding what these functions do, it is important to note that a + “public key” in this context refers to a + <i class="Em" title="Em">point on Curve25519</i>. This also means that these + functions are not compatible with + <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a> + and related functions. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_curve_to_hidden</b>() takes a public key + <var class="Fa" title="Fa">curve</var> and a + <var class="Fa" title="Fa">tweak</var>, hiding the public key it so that it is + effectively indistinguishable from random noise. Note that only + <a class="Xr" title="Xr" href="crypto_x25519_dirty_fast.html">crypto_x25519_dirty_fast(3monocypher)</a> + or + <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a> + can generate a suitable public key; the + <a class="Xr" title="Xr" href="crypto_x25519.html">crypto_x25519(3monocypher)</a> + function is insufficient. The <var class="Fa" title="Fa">tweak</var> must be + chosen at random. Even then, this operation <i class="Em" title="Em">may</i> + fail: Not all curve points are capable of being hidden. In this case, + <b class="Fn" title="Fn">crypto_curve_to_hidden</b>() must be tried again with + a new key pair; the <var class="Fa" title="Fa">tweak</var> does not need to be + changed. On average, two attempts are needed. Once a suitable public key has + been found, <b class="Fn" title="Fn">crypto_curve_to_hidden</b>() always + succeeds for it. Given the same values for + <var class="Fa" title="Fa">tweak</var> and + <var class="Fa" title="Fa">curve</var>, + <b class="Fn" title="Fn">crypto_curve_to_hidden</b>() yields the same output + value <var class="Fa" title="Fa">hidden</var>. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_hidden_to_curve</b>() performs the inverse + operation: It decodes a hidden point to a curve point on Curve25519. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_hidden_key_pair</b>() is a convenience function + that generates a secret key and its corresponding public key, which is + effectively indistinguishable from random noise, from a random seed. + <i class="Em" title="Em">The execution time of this function is + unpredictable</i> because it may take many failures until a key pair could be + generated successfully. <b class="Fn" title="Fn">crypto_hidden_key_pair</b>() + uses + <a class="Xr" title="Xr" href="crypto_x25519_dirty_fast.html">crypto_x25519_dirty_fast(3monocypher)</a> + internally; if code size is an important concern, its functionality can be + replicated with + <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a> + instead. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">curve</var></dt> + <dd class="It-tag">A point on the curve, which is a Curve25519 public key + generated with either + <a class="Xr" title="Xr" href="crypto_x25519_dirty_fast.html">crypto_x25519_dirty_fast(3monocypher)</a> + or + <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a>.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hidden</var></dt> + <dd class="It-tag">The hidden encoding of a point on the curve which is + effectively indistinguishable from random.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">secret_key</var></dt> + <dd class="It-tag">The secret key that was generated from the given + <var class="Fa" title="Fa">seed</var>.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">seed</var></dt> + <dd class="It-tag">A 32-byte random number from which to derive a key pair. + See <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about generating random bytes (use the operating system's random + number generator). The <var class="Fa" title="Fa">seed</var> is wiped + automatically.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">tweak</var></dt> + <dd class="It-tag">A 1-byte random number, which influences the final output + of <b class="Fn" title="Fn">crypto_curve_to_hidden</b>().</dd> +</dl> +<div class="Pp"></div> +The <var class="Fa" title="Fa">hidden</var> and + <var class="Fa" title="Fa">curve</var> arguments may overlap or point at the + same buffer. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_curve_to_hidden</b>() returns 0 on success, -1 + if the given <var class="Fa" title="Fa">curve</var> argument is unsuitable for + hiding. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_hidden_to_curve</b>() and + <b class="Fn" title="Fn">crypto_hidden_key_pair</b>() return nothing; they + cannot fail. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +Generate a key pair manually using + <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a> + instead of its fast variant: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t sk [32]; /* Secret key output */ +uint8_t pk [32]; /* Hidden public key output */ +uint8_t tweak; /* Random tweak input */ +arc4random_buf(&tweak, 1); +for (;;) { + arc4random_buf(sk, 32); + crypto_x25519_dirty_small(pk, sk); + if (crypto_curve_to_hidden(pk, pk, tweak) == 0) + break; +} +/* Now save the secret key and send the hidden public key. */ +</pre> +</div> +<div class="Pp"></div> +Performing a key exchange with the other party's public key having been hidden: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hidden_pk [32]; /* Their hidden public key */ +uint8_t their_pk [32]; /* Their unhidden public key */ +uint8_t your_sk [32]; /* Your secret key */ +uint8_t shared_key[32]; /* Shared session key */ +crypto_hidden_to_curve(their_pk, hidden_pk); +crypto_key_exchange(shared_key, your_sk, their_pk); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(your_sk, 32); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_x25519.html">crypto_x25519(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement the Elligator 2 mapping for Curve25519. This mapping + is incompatible with both the hash-to-curve Internet draft and the + implementation of Elligator 2 in libsodium. Elligator 2 was described in: + <cite class="Rs" title="Rs"><span class="RsA">Daniel J. Bernstein</span>, + <span class="RsA">Mike Hamburg</span>, <span class="RsA">Anna Krasnova</span>, + and <span class="RsA">Tanja Lange</span>, <span class="RsT">Elligator: + Elliptic-curve points indistinguishable from uniform random strings</span>, + <i class="RsI">Association for Computing Machinery</i>, <i class="RsJ">CCS + '13: Proceedings of the 2013 ACM SIGSAC conference on Computer & + communications security</i>, <span class="RsP">pp. 967–980</span>, + <span class="RsD">2013</span>.</cite> +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_curve_to_hidden</b>(), + <b class="Fn" title="Fn">crypto_hidden_to_curve</b>(), and + <b class="Fn" title="Fn">crypto_hidden_key_pair</b>() functions first appeared + in Monocypher 3.1.0. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +The secret keys for the public keys fed into + <b class="Fn" title="Fn">crypto_curve_to_hidden</b>() + <b class="Sy" title="Sy">must be chosen randomly</b>, rather than + deterministically. Otherwise, the timing information given by the required + number of retries also leaks information on the secret keys. +<div class="Pp"></div> +These functions <i class="Em" title="Em">help</i> build highly + difficult-to-analyze protocols, but are insufficient by themselves: Other + metadata, such as the amount of bytes sent in a packet or the size of the + 32-byte random-looking string that represents the curve point itself, can be + very strong indicators of the use of cryptography. Consider using appropriate + padding algorithms, such as PADME, and obscure other metadata as much as + possible.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_hmac_sha512.html b/vendor/doc/html/crypto_hmac_sha512.html new file mode 100644 index 0000000..3d92390 --- /dev/null +++ b/vendor/doc/html/crypto_hmac_sha512.html @@ -0,0 +1,196 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_HMAC_SHA512(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_HMAC_SHA512(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_HMAC_SHA512(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_hmac_sha512</b>, + <b class="Nm" title="Nm">crypto_hmac_sha512_init</b>, + <b class="Nm" title="Nm">crypto_hmac_sha512_update</b>, + <b class="Nm" title="Nm">crypto_hmac_sha512_final</b> — + <span class="Nd" title="Nd">cryptographic hash-based message authentication + code with SHA-512</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher-ed25519.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hmac_sha512</b>(<var class="Fa" title="Fa">uint8_t + hmac[64]</var>, <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>, + <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hmac_sha512_final</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t hmac[64]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +HMAC with SHA-512 is a cryptographically secure message authentication code + (MAC), provided to enable compatibility with other cryptographic systems. It + is generally recommended to use + <a class="Xr" title="Xr" href="crypto_blake2b_general.html">crypto_blake2b_general(3monocypher)</a> + instead, as it performs faster on x86_64 CPUs. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hmac</var></dt> + <dd class="It-tag">The output MAC, which is always 64 bytes long.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">Some secret key. One cannot predict the final hash without + it. Users may want to wipe the key with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + once they are done with it.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">key</var>, in bytes. + 32 is a good default. Keys longer than 128 bytes will be reduced to 64 + bytes by hashing the key with SHA-512.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message</var></dt> + <dd class="It-tag">The message to compute the HMAC for. May overlap with + <var class="Fa" title="Fa">hmac</var>. May be + <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">message_size</var> is 0.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">message</var>, in + bytes.</dd> +</dl> +<div class="Pp"></div> +An incremental interface is provided. It is useful for handling streams of data + or large files without using too much memory. This interface uses three steps: +<ul class="Bl-bullet"> + <li class="It-bullet">initialisation with + <b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(), which sets up a + context with the hashing parameters;</li> + <li class="It-bullet">update with + <b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), which hashes the + message chunk by chunk, and keep the intermediary result in the + context;</li> + <li class="It-bullet">and finalisation with + <b class="Fn" title="Fn">crypto_hmac_sha512_final</b>(), which produces + the final hash. The + <var class="Ft" title="Ft">crypto_hmac_sha512_ctx</var> is automatically + wiped upon finalisation.</li> +</ul> +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_hmac_sha512</b>() is a convenience function that + performs <b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(), + <b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), and + <b class="Fn" title="Fn">crypto_hmac_sha512_final</b>(). +<div class="Pp"></div> +MACs may be truncated safely down to at most 16 bytes; the + <a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a>, + and + <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a> + functions can be used to to compare (possibly truncated) MACs. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Computing a message authentication code all at once: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [64]; /* Output hash (between 1 and 64 bytes) */ +uint8_t key [32]; /* Key (at least 1 byte) */ +uint8_t message[10] = "Lorem ipsu"; /* Message to authenticate */ +arc4random_buf(key, 32); +crypto_hmac_sha512(hash, key, 32, message, 500); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(message, 500); +crypto_wipe(key, 32); +</pre> +</div> +<div class="Pp"></div> +Computing a message authentication code incrementally: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [64]; /* Output hash (between 1 and 64 bytes) */ +uint8_t key [32]; /* Key (at least 1 byte) */ +uint8_t message[500] = {1}; /* Message to authenticate */ +crypto_hmac_sha512_ctx ctx; +arc4random_buf(key, 32); +crypto_hmac_sha512_init(&ctx, key, 32); +/* Wipe the key */ +crypto_wipe(key, 32); +for (size_t i = 0; i < 500; i += 100) { + crypto_hmac_sha512_update(&ctx, message + i, 100); + /* Wipe secrets if they are no longer needed */ + crypto_wipe(message + i, 100); +} +crypto_hmac_sha512_final(&ctx, hash); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_poly1305.html">crypto_poly1305(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement HMAC with SHA-512. HMAC and SHA-512 itself are + described in RFC 6234; SHA-512 is also described in the Federal Information + Processing Standard (FIPS) 180-4; HMAC is also described in FIPS 198-1. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_hmac_sha512</b>(), + <b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(), + <b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), and + <b class="Fn" title="Fn">crypto_hmac_sha512_final</b>() functions first + appeared in Monocypher 3.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 2, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_hmac_sha512_final.html b/vendor/doc/html/crypto_hmac_sha512_final.html new file mode 100644 index 0000000..3d92390 --- /dev/null +++ b/vendor/doc/html/crypto_hmac_sha512_final.html @@ -0,0 +1,196 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_HMAC_SHA512(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_HMAC_SHA512(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_HMAC_SHA512(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_hmac_sha512</b>, + <b class="Nm" title="Nm">crypto_hmac_sha512_init</b>, + <b class="Nm" title="Nm">crypto_hmac_sha512_update</b>, + <b class="Nm" title="Nm">crypto_hmac_sha512_final</b> — + <span class="Nd" title="Nd">cryptographic hash-based message authentication + code with SHA-512</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher-ed25519.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hmac_sha512</b>(<var class="Fa" title="Fa">uint8_t + hmac[64]</var>, <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>, + <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hmac_sha512_final</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t hmac[64]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +HMAC with SHA-512 is a cryptographically secure message authentication code + (MAC), provided to enable compatibility with other cryptographic systems. It + is generally recommended to use + <a class="Xr" title="Xr" href="crypto_blake2b_general.html">crypto_blake2b_general(3monocypher)</a> + instead, as it performs faster on x86_64 CPUs. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hmac</var></dt> + <dd class="It-tag">The output MAC, which is always 64 bytes long.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">Some secret key. One cannot predict the final hash without + it. Users may want to wipe the key with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + once they are done with it.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">key</var>, in bytes. + 32 is a good default. Keys longer than 128 bytes will be reduced to 64 + bytes by hashing the key with SHA-512.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message</var></dt> + <dd class="It-tag">The message to compute the HMAC for. May overlap with + <var class="Fa" title="Fa">hmac</var>. May be + <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">message_size</var> is 0.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">message</var>, in + bytes.</dd> +</dl> +<div class="Pp"></div> +An incremental interface is provided. It is useful for handling streams of data + or large files without using too much memory. This interface uses three steps: +<ul class="Bl-bullet"> + <li class="It-bullet">initialisation with + <b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(), which sets up a + context with the hashing parameters;</li> + <li class="It-bullet">update with + <b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), which hashes the + message chunk by chunk, and keep the intermediary result in the + context;</li> + <li class="It-bullet">and finalisation with + <b class="Fn" title="Fn">crypto_hmac_sha512_final</b>(), which produces + the final hash. The + <var class="Ft" title="Ft">crypto_hmac_sha512_ctx</var> is automatically + wiped upon finalisation.</li> +</ul> +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_hmac_sha512</b>() is a convenience function that + performs <b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(), + <b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), and + <b class="Fn" title="Fn">crypto_hmac_sha512_final</b>(). +<div class="Pp"></div> +MACs may be truncated safely down to at most 16 bytes; the + <a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a>, + and + <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a> + functions can be used to to compare (possibly truncated) MACs. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Computing a message authentication code all at once: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [64]; /* Output hash (between 1 and 64 bytes) */ +uint8_t key [32]; /* Key (at least 1 byte) */ +uint8_t message[10] = "Lorem ipsu"; /* Message to authenticate */ +arc4random_buf(key, 32); +crypto_hmac_sha512(hash, key, 32, message, 500); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(message, 500); +crypto_wipe(key, 32); +</pre> +</div> +<div class="Pp"></div> +Computing a message authentication code incrementally: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [64]; /* Output hash (between 1 and 64 bytes) */ +uint8_t key [32]; /* Key (at least 1 byte) */ +uint8_t message[500] = {1}; /* Message to authenticate */ +crypto_hmac_sha512_ctx ctx; +arc4random_buf(key, 32); +crypto_hmac_sha512_init(&ctx, key, 32); +/* Wipe the key */ +crypto_wipe(key, 32); +for (size_t i = 0; i < 500; i += 100) { + crypto_hmac_sha512_update(&ctx, message + i, 100); + /* Wipe secrets if they are no longer needed */ + crypto_wipe(message + i, 100); +} +crypto_hmac_sha512_final(&ctx, hash); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_poly1305.html">crypto_poly1305(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement HMAC with SHA-512. HMAC and SHA-512 itself are + described in RFC 6234; SHA-512 is also described in the Federal Information + Processing Standard (FIPS) 180-4; HMAC is also described in FIPS 198-1. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_hmac_sha512</b>(), + <b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(), + <b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), and + <b class="Fn" title="Fn">crypto_hmac_sha512_final</b>() functions first + appeared in Monocypher 3.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 2, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_hmac_sha512_init.html b/vendor/doc/html/crypto_hmac_sha512_init.html new file mode 100644 index 0000000..3d92390 --- /dev/null +++ b/vendor/doc/html/crypto_hmac_sha512_init.html @@ -0,0 +1,196 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_HMAC_SHA512(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_HMAC_SHA512(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_HMAC_SHA512(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_hmac_sha512</b>, + <b class="Nm" title="Nm">crypto_hmac_sha512_init</b>, + <b class="Nm" title="Nm">crypto_hmac_sha512_update</b>, + <b class="Nm" title="Nm">crypto_hmac_sha512_final</b> — + <span class="Nd" title="Nd">cryptographic hash-based message authentication + code with SHA-512</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher-ed25519.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hmac_sha512</b>(<var class="Fa" title="Fa">uint8_t + hmac[64]</var>, <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>, + <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hmac_sha512_final</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t hmac[64]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +HMAC with SHA-512 is a cryptographically secure message authentication code + (MAC), provided to enable compatibility with other cryptographic systems. It + is generally recommended to use + <a class="Xr" title="Xr" href="crypto_blake2b_general.html">crypto_blake2b_general(3monocypher)</a> + instead, as it performs faster on x86_64 CPUs. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hmac</var></dt> + <dd class="It-tag">The output MAC, which is always 64 bytes long.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">Some secret key. One cannot predict the final hash without + it. Users may want to wipe the key with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + once they are done with it.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">key</var>, in bytes. + 32 is a good default. Keys longer than 128 bytes will be reduced to 64 + bytes by hashing the key with SHA-512.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message</var></dt> + <dd class="It-tag">The message to compute the HMAC for. May overlap with + <var class="Fa" title="Fa">hmac</var>. May be + <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">message_size</var> is 0.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">message</var>, in + bytes.</dd> +</dl> +<div class="Pp"></div> +An incremental interface is provided. It is useful for handling streams of data + or large files without using too much memory. This interface uses three steps: +<ul class="Bl-bullet"> + <li class="It-bullet">initialisation with + <b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(), which sets up a + context with the hashing parameters;</li> + <li class="It-bullet">update with + <b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), which hashes the + message chunk by chunk, and keep the intermediary result in the + context;</li> + <li class="It-bullet">and finalisation with + <b class="Fn" title="Fn">crypto_hmac_sha512_final</b>(), which produces + the final hash. The + <var class="Ft" title="Ft">crypto_hmac_sha512_ctx</var> is automatically + wiped upon finalisation.</li> +</ul> +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_hmac_sha512</b>() is a convenience function that + performs <b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(), + <b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), and + <b class="Fn" title="Fn">crypto_hmac_sha512_final</b>(). +<div class="Pp"></div> +MACs may be truncated safely down to at most 16 bytes; the + <a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a>, + and + <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a> + functions can be used to to compare (possibly truncated) MACs. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Computing a message authentication code all at once: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [64]; /* Output hash (between 1 and 64 bytes) */ +uint8_t key [32]; /* Key (at least 1 byte) */ +uint8_t message[10] = "Lorem ipsu"; /* Message to authenticate */ +arc4random_buf(key, 32); +crypto_hmac_sha512(hash, key, 32, message, 500); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(message, 500); +crypto_wipe(key, 32); +</pre> +</div> +<div class="Pp"></div> +Computing a message authentication code incrementally: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [64]; /* Output hash (between 1 and 64 bytes) */ +uint8_t key [32]; /* Key (at least 1 byte) */ +uint8_t message[500] = {1}; /* Message to authenticate */ +crypto_hmac_sha512_ctx ctx; +arc4random_buf(key, 32); +crypto_hmac_sha512_init(&ctx, key, 32); +/* Wipe the key */ +crypto_wipe(key, 32); +for (size_t i = 0; i < 500; i += 100) { + crypto_hmac_sha512_update(&ctx, message + i, 100); + /* Wipe secrets if they are no longer needed */ + crypto_wipe(message + i, 100); +} +crypto_hmac_sha512_final(&ctx, hash); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_poly1305.html">crypto_poly1305(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement HMAC with SHA-512. HMAC and SHA-512 itself are + described in RFC 6234; SHA-512 is also described in the Federal Information + Processing Standard (FIPS) 180-4; HMAC is also described in FIPS 198-1. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_hmac_sha512</b>(), + <b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(), + <b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), and + <b class="Fn" title="Fn">crypto_hmac_sha512_final</b>() functions first + appeared in Monocypher 3.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 2, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_hmac_sha512_update.html b/vendor/doc/html/crypto_hmac_sha512_update.html new file mode 100644 index 0000000..3d92390 --- /dev/null +++ b/vendor/doc/html/crypto_hmac_sha512_update.html @@ -0,0 +1,196 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_HMAC_SHA512(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_HMAC_SHA512(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_HMAC_SHA512(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_hmac_sha512</b>, + <b class="Nm" title="Nm">crypto_hmac_sha512_init</b>, + <b class="Nm" title="Nm">crypto_hmac_sha512_update</b>, + <b class="Nm" title="Nm">crypto_hmac_sha512_final</b> — + <span class="Nd" title="Nd">cryptographic hash-based message authentication + code with SHA-512</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher-ed25519.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hmac_sha512</b>(<var class="Fa" title="Fa">uint8_t + hmac[64]</var>, <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>, + <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *key</var>, + <var class="Fa" title="Fa">size_t key_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>, + <var class="Fa" title="Fa">size_t message_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_hmac_sha512_final</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t hmac[64]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +HMAC with SHA-512 is a cryptographically secure message authentication code + (MAC), provided to enable compatibility with other cryptographic systems. It + is generally recommended to use + <a class="Xr" title="Xr" href="crypto_blake2b_general.html">crypto_blake2b_general(3monocypher)</a> + instead, as it performs faster on x86_64 CPUs. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">hmac</var></dt> + <dd class="It-tag">The output MAC, which is always 64 bytes long.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">Some secret key. One cannot predict the final hash without + it. Users may want to wipe the key with + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a> + once they are done with it.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">key</var>, in bytes. + 32 is a good default. Keys longer than 128 bytes will be reduced to 64 + bytes by hashing the key with SHA-512.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message</var></dt> + <dd class="It-tag">The message to compute the HMAC for. May overlap with + <var class="Fa" title="Fa">hmac</var>. May be + <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">message_size</var> is 0.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">message_size</var></dt> + <dd class="It-tag">Length of <var class="Fa" title="Fa">message</var>, in + bytes.</dd> +</dl> +<div class="Pp"></div> +An incremental interface is provided. It is useful for handling streams of data + or large files without using too much memory. This interface uses three steps: +<ul class="Bl-bullet"> + <li class="It-bullet">initialisation with + <b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(), which sets up a + context with the hashing parameters;</li> + <li class="It-bullet">update with + <b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), which hashes the + message chunk by chunk, and keep the intermediary result in the + context;</li> + <li class="It-bullet">and finalisation with + <b class="Fn" title="Fn">crypto_hmac_sha512_final</b>(), which produces + the final hash. The + <var class="Ft" title="Ft">crypto_hmac_sha512_ctx</var> is automatically + wiped upon finalisation.</li> +</ul> +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_hmac_sha512</b>() is a convenience function that + performs <b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(), + <b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), and + <b class="Fn" title="Fn">crypto_hmac_sha512_final</b>(). +<div class="Pp"></div> +MACs may be truncated safely down to at most 16 bytes; the + <a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a>, + and + <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a> + functions can be used to to compare (possibly truncated) MACs. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +These functions return nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Computing a message authentication code all at once: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [64]; /* Output hash (between 1 and 64 bytes) */ +uint8_t key [32]; /* Key (at least 1 byte) */ +uint8_t message[10] = "Lorem ipsu"; /* Message to authenticate */ +arc4random_buf(key, 32); +crypto_hmac_sha512(hash, key, 32, message, 500); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(message, 500); +crypto_wipe(key, 32); +</pre> +</div> +<div class="Pp"></div> +Computing a message authentication code incrementally: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t hash [64]; /* Output hash (between 1 and 64 bytes) */ +uint8_t key [32]; /* Key (at least 1 byte) */ +uint8_t message[500] = {1}; /* Message to authenticate */ +crypto_hmac_sha512_ctx ctx; +arc4random_buf(key, 32); +crypto_hmac_sha512_init(&ctx, key, 32); +/* Wipe the key */ +crypto_wipe(key, 32); +for (size_t i = 0; i < 500; i += 100) { + crypto_hmac_sha512_update(&ctx, message + i, 100); + /* Wipe secrets if they are no longer needed */ + crypto_wipe(message + i, 100); +} +crypto_hmac_sha512_final(&ctx, hash); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_poly1305.html">crypto_poly1305(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement HMAC with SHA-512. HMAC and SHA-512 itself are + described in RFC 6234; SHA-512 is also described in the Federal Information + Processing Standard (FIPS) 180-4; HMAC is also described in FIPS 198-1. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_hmac_sha512</b>(), + <b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(), + <b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), and + <b class="Fn" title="Fn">crypto_hmac_sha512_final</b>() functions first + appeared in Monocypher 3.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 2, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_ietf_chacha20.html b/vendor/doc/html/crypto_ietf_chacha20.html new file mode 100644 index 0000000..0dfd1c9 --- /dev/null +++ b/vendor/doc/html/crypto_ietf_chacha20.html @@ -0,0 +1,96 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_IETF_CHACHA20(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_IETF_CHACHA20(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_IETF_CHACHA20(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_ietf_chacha20</b>, + <b class="Nm" title="Nm">crypto_ietf_chacha20_ctr</b> — + <span class="Nd" title="Nd">IETF Chacha20 encryption functions</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ietf_chacha20</b>(<var class="Fa" title="Fa">uint8_t + *cipher_text</var>, <var class="Fa" title="Fa">const uint8_t + *plain_text</var>, <var class="Fa" title="Fa">size_t text_size</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[12]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ietf_chacha20_ctr</b>(<var class="Fa" title="Fa">uint8_t + *cipher_text</var>, <var class="Fa" title="Fa">const uint8_t + *plain_text</var>, <var class="Fa" title="Fa">size_t text_size</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[12]</var>, + <var class="Fa" title="Fa">const uint32_t ctr</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions provide an interface for the Chacha20 encryption primitive as + specified by the IETF in RFC 8439. They are provided strictly for + compatibility with existing systems or strict standards compliance. New + programs are strongly encouraged to use + <a class="Xr" title="Xr" href="crypto_xchacha20.html">crypto_xchacha20(3monocypher)</a> + instead. +<div class="Pp"></div> +Chacha20 is a low-level primitive. Consider using authenticated encryption, + implemented by + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>. +<div class="Pp"></div> +The <b class="Fn" title="Fn">crypto_ietf_chacha20</b>() and + <b class="Fn" title="Fn">crypto_ietf_chacha20_ctr</b>() functions behave the + same as + <a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20</a> and + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr</a>, + respectively, but use differently-sized nonce and counter values. The nonce + encompasses 12 bytes and the counter is correspondingly reduced to 4 bytes. + The short counter limits a single pair of key and nonce to 256 GiB of data. A + nonce of 12 bytes is <i class="Em" title="Em">just barely too short</i> to be + safely chosen at random; use a message counter instead. RFC 8439 also permits + linear feedback shift registers to generate nonces. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_ietf_chacha20</b>() returns nothing. + <b class="Fn" title="Fn">crypto_ietf_chacha20_ctr</b>() functions return the + next <var class="Fa" title="Fa">ctr</var> to use with the same key and nonce + values; this is always <var class="Fa" title="Fa">text_size</var> divided by + 64; plus one if there was a remainder. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement Chacha20 as described in RFC 8439. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +<b class="Fn" title="Fn">crypto_ietf_chacha20</b>() and + <b class="Fn" title="Fn">crypto_ietf_chacha20_ctr</b>() were added in + Monocypher 3.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_ietf_chacha20_ctr.html b/vendor/doc/html/crypto_ietf_chacha20_ctr.html new file mode 100644 index 0000000..0dfd1c9 --- /dev/null +++ b/vendor/doc/html/crypto_ietf_chacha20_ctr.html @@ -0,0 +1,96 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_IETF_CHACHA20(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_IETF_CHACHA20(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_IETF_CHACHA20(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_ietf_chacha20</b>, + <b class="Nm" title="Nm">crypto_ietf_chacha20_ctr</b> — + <span class="Nd" title="Nd">IETF Chacha20 encryption functions</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ietf_chacha20</b>(<var class="Fa" title="Fa">uint8_t + *cipher_text</var>, <var class="Fa" title="Fa">const uint8_t + *plain_text</var>, <var class="Fa" title="Fa">size_t text_size</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[12]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_ietf_chacha20_ctr</b>(<var class="Fa" title="Fa">uint8_t + *cipher_text</var>, <var class="Fa" title="Fa">const uint8_t + *plain_text</var>, <var class="Fa" title="Fa">size_t text_size</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[12]</var>, + <var class="Fa" title="Fa">const uint32_t ctr</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions provide an interface for the Chacha20 encryption primitive as + specified by the IETF in RFC 8439. They are provided strictly for + compatibility with existing systems or strict standards compliance. New + programs are strongly encouraged to use + <a class="Xr" title="Xr" href="crypto_xchacha20.html">crypto_xchacha20(3monocypher)</a> + instead. +<div class="Pp"></div> +Chacha20 is a low-level primitive. Consider using authenticated encryption, + implemented by + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>. +<div class="Pp"></div> +The <b class="Fn" title="Fn">crypto_ietf_chacha20</b>() and + <b class="Fn" title="Fn">crypto_ietf_chacha20_ctr</b>() functions behave the + same as + <a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20</a> and + <a class="Xr" title="Xr" href="crypto_chacha20_ctr.html">crypto_chacha20_ctr</a>, + respectively, but use differently-sized nonce and counter values. The nonce + encompasses 12 bytes and the counter is correspondingly reduced to 4 bytes. + The short counter limits a single pair of key and nonce to 256 GiB of data. A + nonce of 12 bytes is <i class="Em" title="Em">just barely too short</i> to be + safely chosen at random; use a message counter instead. RFC 8439 also permits + linear feedback shift registers to generate nonces. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_ietf_chacha20</b>() returns nothing. + <b class="Fn" title="Fn">crypto_ietf_chacha20_ctr</b>() functions return the + next <var class="Fa" title="Fa">ctr</var> to use with the same key and nonce + values; this is always <var class="Fa" title="Fa">text_size</var> divided by + 64; plus one if there was a remainder. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_chacha20.html">crypto_chacha20(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement Chacha20 as described in RFC 8439. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +<b class="Fn" title="Fn">crypto_ietf_chacha20</b>() and + <b class="Fn" title="Fn">crypto_ietf_chacha20_ctr</b>() were added in + Monocypher 3.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_key_exchange.html b/vendor/doc/html/crypto_key_exchange.html new file mode 100644 index 0000000..dd5a314 --- /dev/null +++ b/vendor/doc/html/crypto_key_exchange.html @@ -0,0 +1,164 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_KEY_EXCHANGE(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_KEY_EXCHANGE(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_KEY_EXCHANGE(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_key_exchange</b>, + <b class="Nm" title="Nm">crypto_key_exchange_public_key</b> — + <span class="Nd" title="Nd">Elliptic Curve Diffie-Hellman key exchange</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_key_exchange</b>(<var class="Fa" title="Fa">uint8_t + shared_key[32]</var>, <var class="Fa" title="Fa">const uint8_t + your_secret_key[32]</var>, <var class="Fa" title="Fa">const uint8_t + their_public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_key_exchange_public_key</b>(<var class="Fa" title="Fa">uint8_t + your_public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t + your_secret_key[32]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<b class="Fn" title="Fn">crypto_key_exchange</b>() computes a shared key with + your secret key and their public key. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_key_exchange_public_key</b>() deterministically + computes the public key from a random secret key. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">shared_key</var></dt> + <dd class="It-tag">The shared secret, known only to those who know a relevant + secret key (yours or theirs). It is cryptographically random, and suitable + for use with the + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a> + family of functions.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">your_secret_key</var></dt> + <dd class="It-tag">A 32-byte random number, known only to you. See + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about generating random bytes (use the operating system's random + number generator).</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">their_public_key</var></dt> + <dd class="It-tag">The public key of the other party.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">your_public_key</var></dt> + <dd class="It-tag">Your public key, generated from + <var class="Fa" title="Fa">your_secret_key</var> with + <b class="Fn" title="Fn">crypto_key_exchange_public_key</b>().</dd> +</dl> +<div class="Pp"></div> +<var class="Fa" title="Fa">shared_key</var> and + <var class="Fa" title="Fa">your_secret_key</var> may overlap if the secret is + no longer required. +<div class="Pp"></div> +Some poorly designed protocols require to test for “contributory” + behaviour, which ensures that no untrusted party forces the shared secret to a + known constant. Protocols should instead be designed in such a way that no + such check is necessary, namely by authenticating the other party or + exchanging keys over a trusted channel. +<div class="Pp"></div> +Do not use the same secret key for both key exchanges and signatures. The public + keys are different, and revealing both may leak information. If there really + is no room to store or derive two different secret keys, consider generating a + key pair for signatures and then converting it with + <a class="Xr" title="Xr" href="crypto_from_eddsa_private.html">crypto_from_eddsa_private(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_from_eddsa_public.html">crypto_from_eddsa_public(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_key_exchange</b>() and + <b class="Fn" title="Fn">crypto_key_exchange_public_key</b>() return nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Generate a public key from a randomly generated secret key: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t sk[32]; /* Random secret key */ +uint8_t pk[32]; /* Public key */ +arc4random_buf(sk, 32); +crypto_key_exchange_public_key(pk, sk); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(sk, 32); +</pre> +</div> +<div class="Pp"></div> +Generate a shared, symmetric key with your secret key and their public key. (The + other party will generate the same shared key with your public key and their + secret key.) +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t their_pk [32]; /* Their public key */ +uint8_t your_sk [32]; /* Your secret key */ +uint8_t shared_key[32]; /* Shared session key */ +crypto_key_exchange(shared_key, your_sk, their_pk); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(your_sk, 32); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement X25519, described in RFC 7748. + <b class="Fn" title="Fn">crypto_key_exchange</b>() uses HChacha20 as well. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_key_exchange</b>() function first appeared + in Monocypher 0.2. The + <b class="Fn" title="Fn">crypto_key_exchange_public_key</b>() macro alias + first appeared in Monocypher 1.1.0. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +If either of the long term secret keys leaks, it may compromise + <i class="Em" title="Em">all past messages</i>. This can be avoided by using + protocols that provide forward secrecy, such as the X3DH key agreement + protocol. +<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION + DETAILS</a></h1> +<b class="Fn" title="Fn">crypto_key_exchange_public_key</b>() is an alias to + <a class="Xr" title="Xr" href="crypto_x25519_public_key.html">crypto_x25519_public_key(3monocypher)</a>.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_key_exchange_public_key.html b/vendor/doc/html/crypto_key_exchange_public_key.html new file mode 100644 index 0000000..dd5a314 --- /dev/null +++ b/vendor/doc/html/crypto_key_exchange_public_key.html @@ -0,0 +1,164 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_KEY_EXCHANGE(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_KEY_EXCHANGE(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_KEY_EXCHANGE(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_key_exchange</b>, + <b class="Nm" title="Nm">crypto_key_exchange_public_key</b> — + <span class="Nd" title="Nd">Elliptic Curve Diffie-Hellman key exchange</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_key_exchange</b>(<var class="Fa" title="Fa">uint8_t + shared_key[32]</var>, <var class="Fa" title="Fa">const uint8_t + your_secret_key[32]</var>, <var class="Fa" title="Fa">const uint8_t + their_public_key[32]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_key_exchange_public_key</b>(<var class="Fa" title="Fa">uint8_t + your_public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t + your_secret_key[32]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<b class="Fn" title="Fn">crypto_key_exchange</b>() computes a shared key with + your secret key and their public key. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_key_exchange_public_key</b>() deterministically + computes the public key from a random secret key. +<div class="Pp"></div> +The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">shared_key</var></dt> + <dd class="It-tag">The shared secret, known only to those who know a relevant + secret key (yours or theirs). It is cryptographically random, and suitable + for use with the + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a> + family of functions.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">your_secret_key</var></dt> + <dd class="It-tag">A 32-byte random number, known only to you. See + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about generating random bytes (use the operating system's random + number generator).</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">their_public_key</var></dt> + <dd class="It-tag">The public key of the other party.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">your_public_key</var></dt> + <dd class="It-tag">Your public key, generated from + <var class="Fa" title="Fa">your_secret_key</var> with + <b class="Fn" title="Fn">crypto_key_exchange_public_key</b>().</dd> +</dl> +<div class="Pp"></div> +<var class="Fa" title="Fa">shared_key</var> and + <var class="Fa" title="Fa">your_secret_key</var> may overlap if the secret is + no longer required. +<div class="Pp"></div> +Some poorly designed protocols require to test for “contributory” + behaviour, which ensures that no untrusted party forces the shared secret to a + known constant. Protocols should instead be designed in such a way that no + such check is necessary, namely by authenticating the other party or + exchanging keys over a trusted channel. +<div class="Pp"></div> +Do not use the same secret key for both key exchanges and signatures. The public + keys are different, and revealing both may leak information. If there really + is no room to store or derive two different secret keys, consider generating a + key pair for signatures and then converting it with + <a class="Xr" title="Xr" href="crypto_from_eddsa_private.html">crypto_from_eddsa_private(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_from_eddsa_public.html">crypto_from_eddsa_public(3monocypher)</a>. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_key_exchange</b>() and + <b class="Fn" title="Fn">crypto_key_exchange_public_key</b>() return nothing. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Generate a public key from a randomly generated secret key: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t sk[32]; /* Random secret key */ +uint8_t pk[32]; /* Public key */ +arc4random_buf(sk, 32); +crypto_key_exchange_public_key(pk, sk); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(sk, 32); +</pre> +</div> +<div class="Pp"></div> +Generate a shared, symmetric key with your secret key and their public key. (The + other party will generate the same shared key with your public key and their + secret key.) +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t their_pk [32]; /* Their public key */ +uint8_t your_sk [32]; /* Your secret key */ +uint8_t shared_key[32]; /* Shared session key */ +crypto_key_exchange(shared_key, your_sk, their_pk); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(your_sk, 32); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement X25519, described in RFC 7748. + <b class="Fn" title="Fn">crypto_key_exchange</b>() uses HChacha20 as well. +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_key_exchange</b>() function first appeared + in Monocypher 0.2. The + <b class="Fn" title="Fn">crypto_key_exchange_public_key</b>() macro alias + first appeared in Monocypher 1.1.0. +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +If either of the long term secret keys leaks, it may compromise + <i class="Em" title="Em">all past messages</i>. This can be avoided by using + protocols that provide forward secrecy, such as the X3DH key agreement + protocol. +<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION + DETAILS</a></h1> +<b class="Fn" title="Fn">crypto_key_exchange_public_key</b>() is an alias to + <a class="Xr" title="Xr" href="crypto_x25519_public_key.html">crypto_x25519_public_key(3monocypher)</a>.</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_lock.html b/vendor/doc/html/crypto_lock.html new file mode 100644 index 0000000..921c60e --- /dev/null +++ b/vendor/doc/html/crypto_lock.html @@ -0,0 +1,299 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_LOCK(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_LOCK(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_LOCK(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_lock_aead</b>, + <b class="Nm" title="Nm">crypto_unlock_aead</b>, + <b class="Nm" title="Nm">crypto_lock</b>, + <b class="Nm" title="Nm">crypto_unlock</b> — + <span class="Nd" title="Nd">authenticated encryption with additional + data</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock</b>(<var class="Fa" title="Fa">uint8_t + mac[16]</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock</b>(<var class="Fa" title="Fa">uint8_t + *plain_text</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">const uint8_t mac[16]</var>, + <var class="Fa" title="Fa">const uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_aead</b>(<var class="Fa" title="Fa">uint8_t + mac[16]</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_aead</b>(<var class="Fa" title="Fa">uint8_t + *plain_text</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">const uint8_t mac[16]</var>, + <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>, + <var class="Fa" title="Fa">const uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<b class="Fn" title="Fn">crypto_lock</b>() encrypts and authenticates a + plaintext. It can be decrypted by + <b class="Fn" title="Fn">crypto_unlock</b>(). The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">A 32-byte session key, shared between the sender and the + recipient. It must be secret and random. Different methods can be used to + produce and exchange this key, such as Diffie-Hellman key exchange, + password key derivation (the password must be communicated on a secure + channel), or even meeting physically. See + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a> + for key exchange, and + <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a> + for password key derivation.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">nonce</var></dt> + <dd class="It-tag">A 24-byte number, used only once with any given session + key. It does not need to be secret or random, but it does have to be + unique. <i class="Em" title="Em">Never</i> use the same nonce twice with + the same key. This would reveal the XOR of 2 different messages, which + allows decryption and forgeries. The easiest (and recommended) way to + generate this nonce is to select it at random. See + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> about + random number generation (use your operating system's random number + generator).</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">mac</var></dt> + <dd class="It-tag">A 16-byte <i class="Em" title="Em">message authentication + code</i> (MAC), that can only be produced by someone who knows the session + key. This guarantee cannot be upheld if a nonce has been reused with the + session key, because doing so allows the attacker to learn the + authentication key associated with that nonce. The MAC is intended to be + sent along with the ciphertext.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">plain_text</var></dt> + <dd class="It-tag">The secret message. Its contents will be kept hidden from + attackers. Its length however, will <i class="Em" title="Em">not</i>. Be + careful when combining encryption with compression. See + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + details.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">cipher_text</var></dt> + <dd class="It-tag">The encrypted message.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">text_size</var></dt> + <dd class="It-tag">Length of both <var class="Fa" title="Fa">plain_text + and</var> <var class="Fa" title="Fa">cipher_text</var>, in bytes.</dd> +</dl> +<div class="Pp"></div> +The <var class="Fa" title="Fa">cipher_text</var> and + <var class="Fa" title="Fa">plain_text</var> arguments may point to the same + buffer for in-place encryption. Otherwise, the buffers they point to must not + overlap. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_unlock</b>() first checks the integrity of an + encrypted message. If it has been corrupted, + <b class="Fn" title="Fn">crypto_unlock</b>() returns -1 immediately. + Otherwise, it decrypts the message, then returns zero. + <i class="Em" title="Em">Always check the return value</i>. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_lock_aead</b>() and + <b class="Fn" title="Fn">crypto_unlock_aead</b>() are variants of + <b class="Fn" title="Fn">crypto_lock</b>() and + <b class="Fn" title="Fn">crypto_unlock</b>(), permitting additional data. + Additional data is authenticated, but <i class="Em" title="Em">not</i> + encrypted. This is used to authenticate relevant data that cannot be + encrypted. The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">ad</var></dt> + <dd class="It-tag">Additional data to authenticate. It will not be encrypted. + May be <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">ad_size</var> is zero. Setting + <var class="Fa" title="Fa">ad_size</var> to zero yields the same results + as <b class="Fn" title="Fn">crypto_lock</b>() and + <b class="Fn" title="Fn">crypto_unlock</b>().</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">ad_size</var></dt> + <dd class="It-tag">Length of the additional data, in bytes.</dd> +</dl> +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_lock</b>() and + <b class="Fn" title="Fn">crypto_lock_aead</b>() return nothing. + <b class="Fn" title="Fn">crypto_unlock</b>() and + <b class="Fn" title="Fn">crypto_unlock_aead</b>() return 0 on success or -1 if + the message was corrupted (i.e. <var class="Fa" title="Fa">mac</var> + mismatched the combination of <var class="Fa" title="Fa">key</var>, + <var class="Fa" title="Fa">nonce</var>, <var class="Fa" title="Fa">ad</var> + and <var class="Fa" title="Fa">cipher_text</var>). Corruption can be caused by + transmission errors, programmer error, or an attacker's interference. + <var class="Fa" title="Fa">plain_text</var> does not need to be wiped if the + decryption fails. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Encryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key [32]; /* Random, secret session key */ +uint8_t nonce [24]; /* Use only once per key */ +uint8_t plain_text [12] = "Lorem ipsum"; /* Secret message */ +uint8_t mac [16]; /* Message authentication code */ +uint8_t cipher_text[12]; /* Encrypted message */ +arc4random_buf(key, 32); +arc4random_buf(nonce, 24); +crypto_lock(mac, cipher_text, key, nonce, plain_text, + sizeof(plain_text)); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(plain_text, 12); +crypto_wipe(key, 32); +/* Transmit cipher_text, nonce, and mac over the network, + * store them in a file, etc. + */ +</pre> +</div> +<div class="Pp"></div> +To decrypt the above: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key [32]; /* Same as the above */ +uint8_t nonce [24]; /* Same as the above */ +const uint8_t cipher_text[12]; /* Encrypted message */ +const uint8_t mac [16]; /* Received along with text */ +uint8_t plain_text [12]; /* Secret message */ +if (crypto_unlock(plain_text, key, nonce, mac, cipher_text, 12)) { + /* The message is corrupted. + * Wipe key if it is no longer needed, + * and abort the decryption. + */ + crypto_wipe(key, 32); +} else { + /* ...do something with the decrypted text here... */ + /* Finally, wipe secrets if they are no longer needed */ + crypto_wipe(plain_text, 12); + crypto_wipe(key, 32); +} +</pre> +</div> +<div class="Pp"></div> +In-place encryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key [32]; /* Random, secret session key */ +uint8_t nonce[24]; /* Use only once per key */ +uint8_t text [12] = "Lorem ipsum"; /* Secret message */ +uint8_t mac [16]; /* Message authentication code */ +arc4random_buf(key, 32); +arc4random_buf(nonce, 24); +crypto_lock(mac, text, key, nonce, text, 12); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(key, 32); +/* Transmit cipher_text, nonce, and mac over the network, + * store them in a file, etc. + */ +</pre> +</div> +<div class="Pp"></div> +In-place decryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key [32]; /* Same as the above */ +const uint8_t nonce[24]; /* Same as the above */ +const uint8_t mac [16]; /* Received from along with text */ +uint8_t text [12]; /* Message to decrypt */ +if (crypto_unlock(text, key, nonce, mac, text, 12)) { + /* The message is corrupted. + * Wipe key if it is no longer needed, + * and abort the decryption. + */ + crypto_wipe(key, 32); +} else { + /* ...do something with the decrypted text here... */ + /* Finally, wipe secrets if they are no longer needed */ + crypto_wipe(text, 12); + crypto_wipe(key, 32); +} +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement RFC 8439, with XChacha20 instead of Chacha20. + XChacha20 derives from Chacha20 the same way XSalsa20 derives from Salsa20, + and benefits from the same security reduction (proven secure as long as + Chacha20 itself is secure). +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_lock</b>() and + <b class="Fn" title="Fn">crypto_unlock</b>() functions first appeared in + Monocypher 0.1. <b class="Fn" title="Fn">crypto_lock_aead</b>() and + <b class="Fn" title="Fn">crypto_unlock_aead</b>() were introduced in + Monocypher 1.1.0. In Monocypher 2.0.0, the underlying algorithms for these + functions were changed from a custom XChacha20/Poly1305 construction to an + implementation of RFC 7539 (now RFC 8439) with XChacha20 instead of Chacha20. + The <b class="Fn" title="Fn">crypto_lock_encrypt</b>() and + <b class="Fn" title="Fn">crypto_lock_auth</b>() functions were removed in + Monocypher 2.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">February 29, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_lock_aead.html b/vendor/doc/html/crypto_lock_aead.html new file mode 100644 index 0000000..921c60e --- /dev/null +++ b/vendor/doc/html/crypto_lock_aead.html @@ -0,0 +1,299 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_LOCK(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_LOCK(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_LOCK(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_lock_aead</b>, + <b class="Nm" title="Nm">crypto_unlock_aead</b>, + <b class="Nm" title="Nm">crypto_lock</b>, + <b class="Nm" title="Nm">crypto_unlock</b> — + <span class="Nd" title="Nd">authenticated encryption with additional + data</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock</b>(<var class="Fa" title="Fa">uint8_t + mac[16]</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock</b>(<var class="Fa" title="Fa">uint8_t + *plain_text</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">const uint8_t mac[16]</var>, + <var class="Fa" title="Fa">const uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_aead</b>(<var class="Fa" title="Fa">uint8_t + mac[16]</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_aead</b>(<var class="Fa" title="Fa">uint8_t + *plain_text</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>, + <var class="Fa" title="Fa">const uint8_t mac[16]</var>, + <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>, + <var class="Fa" title="Fa">const uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<b class="Fn" title="Fn">crypto_lock</b>() encrypts and authenticates a + plaintext. It can be decrypted by + <b class="Fn" title="Fn">crypto_unlock</b>(). The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt> + <dd class="It-tag">A 32-byte session key, shared between the sender and the + recipient. It must be secret and random. Different methods can be used to + produce and exchange this key, such as Diffie-Hellman key exchange, + password key derivation (the password must be communicated on a secure + channel), or even meeting physically. See + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a> + for key exchange, and + <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a> + for password key derivation.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">nonce</var></dt> + <dd class="It-tag">A 24-byte number, used only once with any given session + key. It does not need to be secret or random, but it does have to be + unique. <i class="Em" title="Em">Never</i> use the same nonce twice with + the same key. This would reveal the XOR of 2 different messages, which + allows decryption and forgeries. The easiest (and recommended) way to + generate this nonce is to select it at random. See + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> about + random number generation (use your operating system's random number + generator).</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">mac</var></dt> + <dd class="It-tag">A 16-byte <i class="Em" title="Em">message authentication + code</i> (MAC), that can only be produced by someone who knows the session + key. This guarantee cannot be upheld if a nonce has been reused with the + session key, because doing so allows the attacker to learn the + authentication key associated with that nonce. The MAC is intended to be + sent along with the ciphertext.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">plain_text</var></dt> + <dd class="It-tag">The secret message. Its contents will be kept hidden from + attackers. Its length however, will <i class="Em" title="Em">not</i>. Be + careful when combining encryption with compression. See + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + details.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">cipher_text</var></dt> + <dd class="It-tag">The encrypted message.</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">text_size</var></dt> + <dd class="It-tag">Length of both <var class="Fa" title="Fa">plain_text + and</var> <var class="Fa" title="Fa">cipher_text</var>, in bytes.</dd> +</dl> +<div class="Pp"></div> +The <var class="Fa" title="Fa">cipher_text</var> and + <var class="Fa" title="Fa">plain_text</var> arguments may point to the same + buffer for in-place encryption. Otherwise, the buffers they point to must not + overlap. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_unlock</b>() first checks the integrity of an + encrypted message. If it has been corrupted, + <b class="Fn" title="Fn">crypto_unlock</b>() returns -1 immediately. + Otherwise, it decrypts the message, then returns zero. + <i class="Em" title="Em">Always check the return value</i>. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_lock_aead</b>() and + <b class="Fn" title="Fn">crypto_unlock_aead</b>() are variants of + <b class="Fn" title="Fn">crypto_lock</b>() and + <b class="Fn" title="Fn">crypto_unlock</b>(), permitting additional data. + Additional data is authenticated, but <i class="Em" title="Em">not</i> + encrypted. This is used to authenticate relevant data that cannot be + encrypted. The arguments are: +<dl class="Bl-tag"> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">ad</var></dt> + <dd class="It-tag">Additional data to authenticate. It will not be encrypted. + May be <code class="Dv" title="Dv">NULL</code> if + <var class="Fa" title="Fa">ad_size</var> is zero. Setting + <var class="Fa" title="Fa">ad_size</var> to zero yields the same results + as <b class="Fn" title="Fn">crypto_lock</b>() and + <b class="Fn" title="Fn">crypto_unlock</b>().</dd> + <dt class="It-tag"> </dt> + <dd class="It-tag"> </dd> + <dt class="It-tag"><var class="Fa" title="Fa">ad_size</var></dt> + <dd class="It-tag">Length of the additional data, in bytes.</dd> +</dl> +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_lock</b>() and + <b class="Fn" title="Fn">crypto_lock_aead</b>() return nothing. + <b class="Fn" title="Fn">crypto_unlock</b>() and + <b class="Fn" title="Fn">crypto_unlock_aead</b>() return 0 on success or -1 if + the message was corrupted (i.e. <var class="Fa" title="Fa">mac</var> + mismatched the combination of <var class="Fa" title="Fa">key</var>, + <var class="Fa" title="Fa">nonce</var>, <var class="Fa" title="Fa">ad</var> + and <var class="Fa" title="Fa">cipher_text</var>). Corruption can be caused by + transmission errors, programmer error, or an attacker's interference. + <var class="Fa" title="Fa">plain_text</var> does not need to be wiped if the + decryption fails. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +The following examples assume the existence of + <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer + with cryptographically secure random bytes. If + <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system, + see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for + advice about how to generate cryptographically secure random bytes. +<div class="Pp"></div> +Encryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key [32]; /* Random, secret session key */ +uint8_t nonce [24]; /* Use only once per key */ +uint8_t plain_text [12] = "Lorem ipsum"; /* Secret message */ +uint8_t mac [16]; /* Message authentication code */ +uint8_t cipher_text[12]; /* Encrypted message */ +arc4random_buf(key, 32); +arc4random_buf(nonce, 24); +crypto_lock(mac, cipher_text, key, nonce, plain_text, + sizeof(plain_text)); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(plain_text, 12); +crypto_wipe(key, 32); +/* Transmit cipher_text, nonce, and mac over the network, + * store them in a file, etc. + */ +</pre> +</div> +<div class="Pp"></div> +To decrypt the above: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key [32]; /* Same as the above */ +uint8_t nonce [24]; /* Same as the above */ +const uint8_t cipher_text[12]; /* Encrypted message */ +const uint8_t mac [16]; /* Received along with text */ +uint8_t plain_text [12]; /* Secret message */ +if (crypto_unlock(plain_text, key, nonce, mac, cipher_text, 12)) { + /* The message is corrupted. + * Wipe key if it is no longer needed, + * and abort the decryption. + */ + crypto_wipe(key, 32); +} else { + /* ...do something with the decrypted text here... */ + /* Finally, wipe secrets if they are no longer needed */ + crypto_wipe(plain_text, 12); + crypto_wipe(key, 32); +} +</pre> +</div> +<div class="Pp"></div> +In-place encryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key [32]; /* Random, secret session key */ +uint8_t nonce[24]; /* Use only once per key */ +uint8_t text [12] = "Lorem ipsum"; /* Secret message */ +uint8_t mac [16]; /* Message authentication code */ +arc4random_buf(key, 32); +arc4random_buf(nonce, 24); +crypto_lock(mac, text, key, nonce, text, 12); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(key, 32); +/* Transmit cipher_text, nonce, and mac over the network, + * store them in a file, etc. + */ +</pre> +</div> +<div class="Pp"></div> +In-place decryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +uint8_t key [32]; /* Same as the above */ +const uint8_t nonce[24]; /* Same as the above */ +const uint8_t mac [16]; /* Received from along with text */ +uint8_t text [12]; /* Message to decrypt */ +if (crypto_unlock(text, key, nonce, mac, text, 12)) { + /* The message is corrupted. + * Wipe key if it is no longer needed, + * and abort the decryption. + */ + crypto_wipe(key, 32); +} else { + /* ...do something with the decrypted text here... */ + /* Finally, wipe secrets if they are no longer needed */ + crypto_wipe(text, 12); + crypto_wipe(key, 32); +} +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement RFC 8439, with XChacha20 instead of Chacha20. + XChacha20 derives from Chacha20 the same way XSalsa20 derives from Salsa20, + and benefits from the same security reduction (proven secure as long as + Chacha20 itself is secure). +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_lock</b>() and + <b class="Fn" title="Fn">crypto_unlock</b>() functions first appeared in + Monocypher 0.1. <b class="Fn" title="Fn">crypto_lock_aead</b>() and + <b class="Fn" title="Fn">crypto_unlock_aead</b>() were introduced in + Monocypher 1.1.0. In Monocypher 2.0.0, the underlying algorithms for these + functions were changed from a custom XChacha20/Poly1305 construction to an + implementation of RFC 7539 (now RFC 8439) with XChacha20 instead of Chacha20. + The <b class="Fn" title="Fn">crypto_lock_encrypt</b>() and + <b class="Fn" title="Fn">crypto_lock_auth</b>() functions were removed in + Monocypher 2.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">February 29, 2020</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_lock_aead_auth.html b/vendor/doc/html/crypto_lock_aead_auth.html new file mode 100644 index 0000000..fd6c688 --- /dev/null +++ b/vendor/doc/html/crypto_lock_aead_auth.html @@ -0,0 +1,307 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_LOCK_INIT(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_LOCK_INIT(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_LOCK_INIT(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_lock_init</b>, + <b class="Nm" title="Nm">crypto_lock_aead_auth</b>, + <b class="Nm" title="Nm">crypto_lock_update</b>, + <b class="Nm" title="Nm">crypto_lock_final</b>, + <b class="Nm" title="Nm">crypto_unlock_init</b>, + <b class="Nm" title="Nm">crypto_unlock_aead_auth</b>, + <b class="Nm" title="Nm">crypto_unlock_update</b>, + <b class="Nm" title="Nm">crypto_unlock_final</b>, + <b class="Nm" title="Nm">crypto_lock_auth</b>, + <b class="Nm" title="Nm">crypto_lock_encrypt</b> — + <span class="Nd" title="Nd">incremental authenticated encryption with + additional data</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_init</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_aead_auth</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_update</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_final</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t mac[16]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_init</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_aead_auth</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_update</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *plain_text</var>, + <var class="Fa" title="Fa">const uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_final</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t mac[16]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_auth</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_encrypt</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions are variants of + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_aead_lock.html">crypto_aead_lock(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_aead_unlock.html">crypto_aead_unlock(3monocypher)</a>. + Prefer those simpler functions if possible. +<div class="Pp"></div> +This incremental interface can be used to encrypt and decrypt messages too large + to fit in a single buffer. The arguments are the same as described for the + direct interface described in + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>. +<div class="Pp"></div> +Encryption requires four steps: +<ul class="Bl-bullet"> + <li class="It-bullet">Initialise a context with + <b class="Fn" title="Fn">crypto_lock_init</b>().</li> + <li class="It-bullet">Authenticate additional data, if any, with + <b class="Fn" title="Fn">crypto_lock_aead_auth</b>().</li> + <li class="It-bullet">Encrypt and authenticate some data with + <b class="Fn" title="Fn">crypto_lock_update</b>().</li> + <li class="It-bullet">Generate the MAC with + <b class="Fn" title="Fn">crypto_lock_final</b>().</li> +</ul> +<div class="Pp"></div> +Decryption also requires four steps: +<ul class="Bl-bullet"> + <li class="It-bullet">Initialise a context with + <b class="Fn" title="Fn">crypto_unlock_init</b>().</li> + <li class="It-bullet">Verify additional data, if any, with + <b class="Fn" title="Fn">crypto_unlock_aead_auth</b>().</li> + <li class="It-bullet">Decrypt and verify some data with + <b class="Fn" title="Fn">crypto_unlock_update</b>().</li> + <li class="It-bullet">Verify the MAC with + <b class="Fn" title="Fn">crypto_unlock_final</b>().</li> +</ul> +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_lock_encrypt</b>() encrypts or decrypts data + <i class="Em" title="Em">without authenticating it</i>. It is meant as a + building block. Used with <b class="Fn" title="Fn">crypto_lock_auth</b>(), it + enables various AEAD constructions. Most users do not need either of them. + Prefer <b class="Fn" title="Fn">crypto_lock_update</b>() and + <b class="Fn" title="Fn">crypto_unlock_update</b>() instead. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_lock_init</b>(), + <b class="Fn" title="Fn">crypto_unlock_init</b>(), + <b class="Fn" title="Fn">crypto_lock_auth</b>(), + <b class="Fn" title="Fn">crypto_lock_encrypt</b>(), + <b class="Fn" title="Fn">crypto_lock_aead_auth</b>(), + <b class="Fn" title="Fn">crypto_unlock_aead_auth</b>(), + <b class="Fn" title="Fn">crypto_lock_update</b>(), + <b class="Fn" title="Fn">crypto_unlock_update</b>(), and + <b class="Fn" title="Fn">crypto_lock_final</b>() return nothing. They cannot + fail. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_unlock_final</b>() returns 0 on success or -1 if + the message was corrupted. Corruption can be caused by transmission errors, + programmer error, or an attacker's interference. + <i class="Em" title="Em">Always check the return value</i>. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +Encryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [ 32]; /* Session key */ +const uint8_t nonce [ 32]; /* Unique per session key */ +const uint8_t ad [500]; /* Optional additional data */ +const uint8_t plain_text [500]; /* Secret message */ +uint8_t cipher_text[500]; /* Encrypted message */ +uint8_t mac [ 16]; /* Message authentication code */ + +/* Set up initial context */ +crypto_lock_ctx ctx; +crypto_lock_init(&ctx, key, nonce); +/* Wipe the key if it is no longer needed */ +crypto_wipe(key, 32); + +/* Authenticate additional data */ +for (size_t i = 0; i < 500; i += 100) { + crypto_lock_aead_auth(&ctx, ad + i, 100); +} + +/* Encrypt message */ +for (size_t i = 0; i < 500; i += 100) { + crypto_lock_update(&ctx, cipher_text + i, plain_text + i, 100); + /* Wipe the secret message if it is no longer needed */ + crypto_wipe(plain_text + i, 100); +} + +/* Produce the MAC */ +crypto_lock_final(&ctx, mac); +</pre> +</div> +<div class="Pp"></div> +To decrypt the above: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [ 32]; /* Session key */ +const uint8_t nonce [ 32]; /* Unique per session key */ +const uint8_t mac [ 16]; /* Transmitted MAC */ +const uint8_t ad [500]; /* Optional additional data */ +const uint8_t cipher_text[500]; /* Encrypted message */ +uint8_t plain_text [500]; /* Secret message */ + +/* Set up initial context */ +crypto_unlock_ctx ctx; +crypto_unlock_init(&ctx, key, nonce); +/* Wipe the key if it is no longer needed */ +crypto_wipe(key, 32); + +/* Verify additional data */ +for (size_t i = 0; i < 500; i += 100) { + crypto_unlock_aead_auth(&ctx, ad + i, 100); +} + +/* Decrypt message */ +for (size_t i = 0; i < 500; i += 100) { + crypto_unlock_update(&ctx, plain_text + i, cipher_text + i, 100); +} + +/* Check the MAC */ +if (crypto_unlock_final(&ctx, mac)) { + /* Corrupted message, abort processing */ +} else { + /* Genuine message */ +} + +/* Wipe the secret message if it is no longer needed */ +crypto_wipe(plain_text, 500); +</pre> +</div> +<div class="Pp"></div> +In-place encryption without additional data: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [ 32]; /* Session key */ +const uint8_t nonce [ 32]; /* Unique per session key */ +uint8_t text [500]; /* Message */ +uint8_t mac [ 16]; /* Message authentication code */ + +/* Set up initial context */ +crypto_lock_ctx ctx; +crypto_lock_init(&ctx, key, nonce); +/* Wipe the key if it is no longer needed */ +crypto_wipe(key, 32); + +/* Encrypt message */ +for (size_t i = 0; i < 500; i += 100) { + crypto_lock_update(&ctx, text + i, text + i, 100); +} + +/* Produce the MAC */ +crypto_lock_final(&ctx, mac); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_aead_lock.html">crypto_aead_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_aead_unlock.html">crypto_aead_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement the XChacha20 (encryption) and Poly1305 (MAC) + primitives. Chacha20 and Poly1305 are described in RFC 7539. XChacha20 derives + from Chacha20 the same way XSalsa20 derives from Salsa20, and benefits from + the same security reduction (proven secure as long as Chacha20 itself is + secure). +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +Messages are not verified until the call to + <b class="Fn" title="Fn">crypto_unlock_final</b>(). Make sure to call it and + check the return value <i class="Em" title="Em">before</i> processing the + message. Messages may be stored before they are verified, but they cannot be + trusted. Processing untrusted messages increases the attack surface of the + system. Doing so securely is hard. Do not process messages before calling + <b class="Fn" title="Fn">crypto_unlock_final</b>(). +<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION + DETAILS</a></h1> +<ul class="Bl-bullet"> + <li class="It-bullet"><var class="Vt" title="Vt">crypto_unlock_ctx</var> is an + alias to <var class="Vt" title="Vt">crypto_lock_ctx</var>.</li> + <li class="It-bullet"><b class="Fn" title="Fn">crypto_unlock_init</b>() is an + alias to <b class="Fn" title="Fn">crypto_lock_init</b>().</li> + <li class="It-bullet"><b class="Fn" title="Fn">crypto_lock_aead_auth</b>() and + <b class="Fn" title="Fn">crypto_unlock_aead_auth</b>() are aliases to + <b class="Fn" title="Fn">crypto_lock_auth</b>().</li> +</ul> +<div class="Pp"></div> +The incremental interface is roughly three times slower than the direct + interface at identifying corrupted messages. This is because the incremental + interface works in a single pass and has to interleave decryption and + verification. Users who expect a high corruption rate may want to avoid + it.</div> +<table class="foot"> + <tr> + <td class="foot-date">December 28, 2017</td> + <td class="foot-os">Linux 4.4.0-116-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_lock_auth.html b/vendor/doc/html/crypto_lock_auth.html new file mode 100644 index 0000000..fd6c688 --- /dev/null +++ b/vendor/doc/html/crypto_lock_auth.html @@ -0,0 +1,307 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_LOCK_INIT(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_LOCK_INIT(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_LOCK_INIT(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_lock_init</b>, + <b class="Nm" title="Nm">crypto_lock_aead_auth</b>, + <b class="Nm" title="Nm">crypto_lock_update</b>, + <b class="Nm" title="Nm">crypto_lock_final</b>, + <b class="Nm" title="Nm">crypto_unlock_init</b>, + <b class="Nm" title="Nm">crypto_unlock_aead_auth</b>, + <b class="Nm" title="Nm">crypto_unlock_update</b>, + <b class="Nm" title="Nm">crypto_unlock_final</b>, + <b class="Nm" title="Nm">crypto_lock_auth</b>, + <b class="Nm" title="Nm">crypto_lock_encrypt</b> — + <span class="Nd" title="Nd">incremental authenticated encryption with + additional data</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_init</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_aead_auth</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_update</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_final</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t mac[16]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_init</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_aead_auth</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_update</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *plain_text</var>, + <var class="Fa" title="Fa">const uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_final</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t mac[16]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_auth</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_encrypt</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions are variants of + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_aead_lock.html">crypto_aead_lock(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_aead_unlock.html">crypto_aead_unlock(3monocypher)</a>. + Prefer those simpler functions if possible. +<div class="Pp"></div> +This incremental interface can be used to encrypt and decrypt messages too large + to fit in a single buffer. The arguments are the same as described for the + direct interface described in + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>. +<div class="Pp"></div> +Encryption requires four steps: +<ul class="Bl-bullet"> + <li class="It-bullet">Initialise a context with + <b class="Fn" title="Fn">crypto_lock_init</b>().</li> + <li class="It-bullet">Authenticate additional data, if any, with + <b class="Fn" title="Fn">crypto_lock_aead_auth</b>().</li> + <li class="It-bullet">Encrypt and authenticate some data with + <b class="Fn" title="Fn">crypto_lock_update</b>().</li> + <li class="It-bullet">Generate the MAC with + <b class="Fn" title="Fn">crypto_lock_final</b>().</li> +</ul> +<div class="Pp"></div> +Decryption also requires four steps: +<ul class="Bl-bullet"> + <li class="It-bullet">Initialise a context with + <b class="Fn" title="Fn">crypto_unlock_init</b>().</li> + <li class="It-bullet">Verify additional data, if any, with + <b class="Fn" title="Fn">crypto_unlock_aead_auth</b>().</li> + <li class="It-bullet">Decrypt and verify some data with + <b class="Fn" title="Fn">crypto_unlock_update</b>().</li> + <li class="It-bullet">Verify the MAC with + <b class="Fn" title="Fn">crypto_unlock_final</b>().</li> +</ul> +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_lock_encrypt</b>() encrypts or decrypts data + <i class="Em" title="Em">without authenticating it</i>. It is meant as a + building block. Used with <b class="Fn" title="Fn">crypto_lock_auth</b>(), it + enables various AEAD constructions. Most users do not need either of them. + Prefer <b class="Fn" title="Fn">crypto_lock_update</b>() and + <b class="Fn" title="Fn">crypto_unlock_update</b>() instead. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_lock_init</b>(), + <b class="Fn" title="Fn">crypto_unlock_init</b>(), + <b class="Fn" title="Fn">crypto_lock_auth</b>(), + <b class="Fn" title="Fn">crypto_lock_encrypt</b>(), + <b class="Fn" title="Fn">crypto_lock_aead_auth</b>(), + <b class="Fn" title="Fn">crypto_unlock_aead_auth</b>(), + <b class="Fn" title="Fn">crypto_lock_update</b>(), + <b class="Fn" title="Fn">crypto_unlock_update</b>(), and + <b class="Fn" title="Fn">crypto_lock_final</b>() return nothing. They cannot + fail. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_unlock_final</b>() returns 0 on success or -1 if + the message was corrupted. Corruption can be caused by transmission errors, + programmer error, or an attacker's interference. + <i class="Em" title="Em">Always check the return value</i>. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +Encryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [ 32]; /* Session key */ +const uint8_t nonce [ 32]; /* Unique per session key */ +const uint8_t ad [500]; /* Optional additional data */ +const uint8_t plain_text [500]; /* Secret message */ +uint8_t cipher_text[500]; /* Encrypted message */ +uint8_t mac [ 16]; /* Message authentication code */ + +/* Set up initial context */ +crypto_lock_ctx ctx; +crypto_lock_init(&ctx, key, nonce); +/* Wipe the key if it is no longer needed */ +crypto_wipe(key, 32); + +/* Authenticate additional data */ +for (size_t i = 0; i < 500; i += 100) { + crypto_lock_aead_auth(&ctx, ad + i, 100); +} + +/* Encrypt message */ +for (size_t i = 0; i < 500; i += 100) { + crypto_lock_update(&ctx, cipher_text + i, plain_text + i, 100); + /* Wipe the secret message if it is no longer needed */ + crypto_wipe(plain_text + i, 100); +} + +/* Produce the MAC */ +crypto_lock_final(&ctx, mac); +</pre> +</div> +<div class="Pp"></div> +To decrypt the above: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [ 32]; /* Session key */ +const uint8_t nonce [ 32]; /* Unique per session key */ +const uint8_t mac [ 16]; /* Transmitted MAC */ +const uint8_t ad [500]; /* Optional additional data */ +const uint8_t cipher_text[500]; /* Encrypted message */ +uint8_t plain_text [500]; /* Secret message */ + +/* Set up initial context */ +crypto_unlock_ctx ctx; +crypto_unlock_init(&ctx, key, nonce); +/* Wipe the key if it is no longer needed */ +crypto_wipe(key, 32); + +/* Verify additional data */ +for (size_t i = 0; i < 500; i += 100) { + crypto_unlock_aead_auth(&ctx, ad + i, 100); +} + +/* Decrypt message */ +for (size_t i = 0; i < 500; i += 100) { + crypto_unlock_update(&ctx, plain_text + i, cipher_text + i, 100); +} + +/* Check the MAC */ +if (crypto_unlock_final(&ctx, mac)) { + /* Corrupted message, abort processing */ +} else { + /* Genuine message */ +} + +/* Wipe the secret message if it is no longer needed */ +crypto_wipe(plain_text, 500); +</pre> +</div> +<div class="Pp"></div> +In-place encryption without additional data: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [ 32]; /* Session key */ +const uint8_t nonce [ 32]; /* Unique per session key */ +uint8_t text [500]; /* Message */ +uint8_t mac [ 16]; /* Message authentication code */ + +/* Set up initial context */ +crypto_lock_ctx ctx; +crypto_lock_init(&ctx, key, nonce); +/* Wipe the key if it is no longer needed */ +crypto_wipe(key, 32); + +/* Encrypt message */ +for (size_t i = 0; i < 500; i += 100) { + crypto_lock_update(&ctx, text + i, text + i, 100); +} + +/* Produce the MAC */ +crypto_lock_final(&ctx, mac); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_aead_lock.html">crypto_aead_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_aead_unlock.html">crypto_aead_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement the XChacha20 (encryption) and Poly1305 (MAC) + primitives. Chacha20 and Poly1305 are described in RFC 7539. XChacha20 derives + from Chacha20 the same way XSalsa20 derives from Salsa20, and benefits from + the same security reduction (proven secure as long as Chacha20 itself is + secure). +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +Messages are not verified until the call to + <b class="Fn" title="Fn">crypto_unlock_final</b>(). Make sure to call it and + check the return value <i class="Em" title="Em">before</i> processing the + message. Messages may be stored before they are verified, but they cannot be + trusted. Processing untrusted messages increases the attack surface of the + system. Doing so securely is hard. Do not process messages before calling + <b class="Fn" title="Fn">crypto_unlock_final</b>(). +<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION + DETAILS</a></h1> +<ul class="Bl-bullet"> + <li class="It-bullet"><var class="Vt" title="Vt">crypto_unlock_ctx</var> is an + alias to <var class="Vt" title="Vt">crypto_lock_ctx</var>.</li> + <li class="It-bullet"><b class="Fn" title="Fn">crypto_unlock_init</b>() is an + alias to <b class="Fn" title="Fn">crypto_lock_init</b>().</li> + <li class="It-bullet"><b class="Fn" title="Fn">crypto_lock_aead_auth</b>() and + <b class="Fn" title="Fn">crypto_unlock_aead_auth</b>() are aliases to + <b class="Fn" title="Fn">crypto_lock_auth</b>().</li> +</ul> +<div class="Pp"></div> +The incremental interface is roughly three times slower than the direct + interface at identifying corrupted messages. This is because the incremental + interface works in a single pass and has to interleave decryption and + verification. Users who expect a high corruption rate may want to avoid + it.</div> +<table class="foot"> + <tr> + <td class="foot-date">December 28, 2017</td> + <td class="foot-os">Linux 4.4.0-116-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_lock_auth_ad.html b/vendor/doc/html/crypto_lock_auth_ad.html new file mode 100644 index 0000000..312c542 --- /dev/null +++ b/vendor/doc/html/crypto_lock_auth_ad.html @@ -0,0 +1,172 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_LOCK_INIT(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_LOCK_INIT(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_LOCK_INIT(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_lock_init</b>, + <b class="Nm" title="Nm">crypto_lock_auth_ad</b>, + <b class="Nm" title="Nm">crypto_lock_auth_message</b>, + <b class="Nm" title="Nm">crypto_lock_update</b>, + <b class="Nm" title="Nm">crypto_lock_final</b>, + <b class="Nm" title="Nm">crypto_unlock_init</b>, + <b class="Nm" title="Nm">crypto_unlock_auth_ad</b>, + <b class="Nm" title="Nm">crypto_unlock_auth_message</b>, + <b class="Nm" title="Nm">crypto_unlock_update</b>, + <b class="Nm" title="Nm">crypto_unlock_final</b> — + <span class="Nd" title="Nd">incremental authenticated encryption with + additional data</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_init</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_auth_ad</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_auth_message</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_update</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_final</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t mac[16]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_init</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_auth_ad</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_auth_message</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_update</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *plain_text</var>, + <var class="Fa" title="Fa">const uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_final</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t mac[16]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions were variants of + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_unlock_aead.html">crypto_unlock_aead(3monocypher)</a>. + They are deprecated in favor of those simpler functions. +<div class="Pp"></div> +Change your protocol so that it does not rely on the removed functions, namely + by splitting the data into chunks that you can individually use + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a> + on. +<div class="Pp"></div> +For files in particular, you may alternatively (and suboptimally) attempt to use + <b class="Fn" title="Fn">mmap</b>() (on *NIX) or + <b class="Fn" title="Fn">MapViewOfFile</b>() (on Windows) and pass the files + as mapped memory into + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a> + instead. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_lock_init</b>(), + <b class="Fn" title="Fn">crypto_unlock_init</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_lock_update</b>(), + <b class="Fn" title="Fn">crypto_unlock_update</b>(), and + <b class="Fn" title="Fn">crypto_lock_final</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_unlock_final</b>() returns 0 on success or -1 if + the message was corrupted. Corruption can be caused by transmission errors, + programmer error, or an attacker's interference. + <i class="Em" title="Em">Always check the return value</i>. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock_aead.html">crypto_unlock_aead(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_lock_init</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_lock_update</b>(), + <b class="Fn" title="Fn">crypto_lock_final</b>(), + <b class="Fn" title="Fn">crypto_unlock_init</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_unlock_update</b>(), and + <b class="Fn" title="Fn">crypto_unlock_final</b>() functions first appeared in + Monocypher 1.1.0. <b class="Fn" title="Fn">crypto_lock_aead_auth</b>() and + <b class="Fn" title="Fn">crypto_unlock_aead_auth</b>() were renamed to + <b class="Fn" title="Fn">crypto_lock_auth_ad</b>() and + <b class="Fn" title="Fn">crypto_unlock_auth_ad</b>() respectively in + Monocypher 2.0.0. They were deprecated in Monocypher 3.0.0 and will be removed + in Monocypher 4.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">December 12, 2019</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_lock_auth_message.html b/vendor/doc/html/crypto_lock_auth_message.html new file mode 100644 index 0000000..312c542 --- /dev/null +++ b/vendor/doc/html/crypto_lock_auth_message.html @@ -0,0 +1,172 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_LOCK_INIT(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_LOCK_INIT(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_LOCK_INIT(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_lock_init</b>, + <b class="Nm" title="Nm">crypto_lock_auth_ad</b>, + <b class="Nm" title="Nm">crypto_lock_auth_message</b>, + <b class="Nm" title="Nm">crypto_lock_update</b>, + <b class="Nm" title="Nm">crypto_lock_final</b>, + <b class="Nm" title="Nm">crypto_unlock_init</b>, + <b class="Nm" title="Nm">crypto_unlock_auth_ad</b>, + <b class="Nm" title="Nm">crypto_unlock_auth_message</b>, + <b class="Nm" title="Nm">crypto_unlock_update</b>, + <b class="Nm" title="Nm">crypto_unlock_final</b> — + <span class="Nd" title="Nd">incremental authenticated encryption with + additional data</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_init</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_auth_ad</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_auth_message</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_update</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_final</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t mac[16]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_init</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_auth_ad</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_auth_message</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_update</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *plain_text</var>, + <var class="Fa" title="Fa">const uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_final</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t mac[16]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions were variants of + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_unlock_aead.html">crypto_unlock_aead(3monocypher)</a>. + They are deprecated in favor of those simpler functions. +<div class="Pp"></div> +Change your protocol so that it does not rely on the removed functions, namely + by splitting the data into chunks that you can individually use + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a> + on. +<div class="Pp"></div> +For files in particular, you may alternatively (and suboptimally) attempt to use + <b class="Fn" title="Fn">mmap</b>() (on *NIX) or + <b class="Fn" title="Fn">MapViewOfFile</b>() (on Windows) and pass the files + as mapped memory into + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a> + instead. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_lock_init</b>(), + <b class="Fn" title="Fn">crypto_unlock_init</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_lock_update</b>(), + <b class="Fn" title="Fn">crypto_unlock_update</b>(), and + <b class="Fn" title="Fn">crypto_lock_final</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_unlock_final</b>() returns 0 on success or -1 if + the message was corrupted. Corruption can be caused by transmission errors, + programmer error, or an attacker's interference. + <i class="Em" title="Em">Always check the return value</i>. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock_aead.html">crypto_unlock_aead(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_lock_init</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_lock_update</b>(), + <b class="Fn" title="Fn">crypto_lock_final</b>(), + <b class="Fn" title="Fn">crypto_unlock_init</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_unlock_update</b>(), and + <b class="Fn" title="Fn">crypto_unlock_final</b>() functions first appeared in + Monocypher 1.1.0. <b class="Fn" title="Fn">crypto_lock_aead_auth</b>() and + <b class="Fn" title="Fn">crypto_unlock_aead_auth</b>() were renamed to + <b class="Fn" title="Fn">crypto_lock_auth_ad</b>() and + <b class="Fn" title="Fn">crypto_unlock_auth_ad</b>() respectively in + Monocypher 2.0.0. They were deprecated in Monocypher 3.0.0 and will be removed + in Monocypher 4.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">December 12, 2019</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_lock_encrypt.html b/vendor/doc/html/crypto_lock_encrypt.html new file mode 100644 index 0000000..fd6c688 --- /dev/null +++ b/vendor/doc/html/crypto_lock_encrypt.html @@ -0,0 +1,307 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_LOCK_INIT(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_LOCK_INIT(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_LOCK_INIT(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_lock_init</b>, + <b class="Nm" title="Nm">crypto_lock_aead_auth</b>, + <b class="Nm" title="Nm">crypto_lock_update</b>, + <b class="Nm" title="Nm">crypto_lock_final</b>, + <b class="Nm" title="Nm">crypto_unlock_init</b>, + <b class="Nm" title="Nm">crypto_unlock_aead_auth</b>, + <b class="Nm" title="Nm">crypto_unlock_update</b>, + <b class="Nm" title="Nm">crypto_unlock_final</b>, + <b class="Nm" title="Nm">crypto_lock_auth</b>, + <b class="Nm" title="Nm">crypto_lock_encrypt</b> — + <span class="Nd" title="Nd">incremental authenticated encryption with + additional data</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_init</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_aead_auth</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_update</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_final</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t mac[16]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_init</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_aead_auth</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_update</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *plain_text</var>, + <var class="Fa" title="Fa">const uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_final</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t mac[16]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_auth</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_encrypt</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions are variants of + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_aead_lock.html">crypto_aead_lock(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_aead_unlock.html">crypto_aead_unlock(3monocypher)</a>. + Prefer those simpler functions if possible. +<div class="Pp"></div> +This incremental interface can be used to encrypt and decrypt messages too large + to fit in a single buffer. The arguments are the same as described for the + direct interface described in + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>. +<div class="Pp"></div> +Encryption requires four steps: +<ul class="Bl-bullet"> + <li class="It-bullet">Initialise a context with + <b class="Fn" title="Fn">crypto_lock_init</b>().</li> + <li class="It-bullet">Authenticate additional data, if any, with + <b class="Fn" title="Fn">crypto_lock_aead_auth</b>().</li> + <li class="It-bullet">Encrypt and authenticate some data with + <b class="Fn" title="Fn">crypto_lock_update</b>().</li> + <li class="It-bullet">Generate the MAC with + <b class="Fn" title="Fn">crypto_lock_final</b>().</li> +</ul> +<div class="Pp"></div> +Decryption also requires four steps: +<ul class="Bl-bullet"> + <li class="It-bullet">Initialise a context with + <b class="Fn" title="Fn">crypto_unlock_init</b>().</li> + <li class="It-bullet">Verify additional data, if any, with + <b class="Fn" title="Fn">crypto_unlock_aead_auth</b>().</li> + <li class="It-bullet">Decrypt and verify some data with + <b class="Fn" title="Fn">crypto_unlock_update</b>().</li> + <li class="It-bullet">Verify the MAC with + <b class="Fn" title="Fn">crypto_unlock_final</b>().</li> +</ul> +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_lock_encrypt</b>() encrypts or decrypts data + <i class="Em" title="Em">without authenticating it</i>. It is meant as a + building block. Used with <b class="Fn" title="Fn">crypto_lock_auth</b>(), it + enables various AEAD constructions. Most users do not need either of them. + Prefer <b class="Fn" title="Fn">crypto_lock_update</b>() and + <b class="Fn" title="Fn">crypto_unlock_update</b>() instead. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_lock_init</b>(), + <b class="Fn" title="Fn">crypto_unlock_init</b>(), + <b class="Fn" title="Fn">crypto_lock_auth</b>(), + <b class="Fn" title="Fn">crypto_lock_encrypt</b>(), + <b class="Fn" title="Fn">crypto_lock_aead_auth</b>(), + <b class="Fn" title="Fn">crypto_unlock_aead_auth</b>(), + <b class="Fn" title="Fn">crypto_lock_update</b>(), + <b class="Fn" title="Fn">crypto_unlock_update</b>(), and + <b class="Fn" title="Fn">crypto_lock_final</b>() return nothing. They cannot + fail. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_unlock_final</b>() returns 0 on success or -1 if + the message was corrupted. Corruption can be caused by transmission errors, + programmer error, or an attacker's interference. + <i class="Em" title="Em">Always check the return value</i>. +<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1> +Encryption: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [ 32]; /* Session key */ +const uint8_t nonce [ 32]; /* Unique per session key */ +const uint8_t ad [500]; /* Optional additional data */ +const uint8_t plain_text [500]; /* Secret message */ +uint8_t cipher_text[500]; /* Encrypted message */ +uint8_t mac [ 16]; /* Message authentication code */ + +/* Set up initial context */ +crypto_lock_ctx ctx; +crypto_lock_init(&ctx, key, nonce); +/* Wipe the key if it is no longer needed */ +crypto_wipe(key, 32); + +/* Authenticate additional data */ +for (size_t i = 0; i < 500; i += 100) { + crypto_lock_aead_auth(&ctx, ad + i, 100); +} + +/* Encrypt message */ +for (size_t i = 0; i < 500; i += 100) { + crypto_lock_update(&ctx, cipher_text + i, plain_text + i, 100); + /* Wipe the secret message if it is no longer needed */ + crypto_wipe(plain_text + i, 100); +} + +/* Produce the MAC */ +crypto_lock_final(&ctx, mac); +</pre> +</div> +<div class="Pp"></div> +To decrypt the above: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [ 32]; /* Session key */ +const uint8_t nonce [ 32]; /* Unique per session key */ +const uint8_t mac [ 16]; /* Transmitted MAC */ +const uint8_t ad [500]; /* Optional additional data */ +const uint8_t cipher_text[500]; /* Encrypted message */ +uint8_t plain_text [500]; /* Secret message */ + +/* Set up initial context */ +crypto_unlock_ctx ctx; +crypto_unlock_init(&ctx, key, nonce); +/* Wipe the key if it is no longer needed */ +crypto_wipe(key, 32); + +/* Verify additional data */ +for (size_t i = 0; i < 500; i += 100) { + crypto_unlock_aead_auth(&ctx, ad + i, 100); +} + +/* Decrypt message */ +for (size_t i = 0; i < 500; i += 100) { + crypto_unlock_update(&ctx, plain_text + i, cipher_text + i, 100); +} + +/* Check the MAC */ +if (crypto_unlock_final(&ctx, mac)) { + /* Corrupted message, abort processing */ +} else { + /* Genuine message */ +} + +/* Wipe the secret message if it is no longer needed */ +crypto_wipe(plain_text, 500); +</pre> +</div> +<div class="Pp"></div> +In-place encryption without additional data: +<div class="Pp"></div> +<div class="Bd" style="margin-left: 5.00ex;"> +<pre class="Li"> +const uint8_t key [ 32]; /* Session key */ +const uint8_t nonce [ 32]; /* Unique per session key */ +uint8_t text [500]; /* Message */ +uint8_t mac [ 16]; /* Message authentication code */ + +/* Set up initial context */ +crypto_lock_ctx ctx; +crypto_lock_init(&ctx, key, nonce); +/* Wipe the key if it is no longer needed */ +crypto_wipe(key, 32); + +/* Encrypt message */ +for (size_t i = 0; i < 500; i += 100) { + crypto_lock_update(&ctx, text + i, text + i, 100); +} + +/* Produce the MAC */ +crypto_lock_final(&ctx, mac); +</pre> +</div> +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_aead_lock.html">crypto_aead_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_aead_unlock.html">crypto_aead_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1> +These functions implement the XChacha20 (encryption) and Poly1305 (MAC) + primitives. Chacha20 and Poly1305 are described in RFC 7539. XChacha20 derives + from Chacha20 the same way XSalsa20 derives from Salsa20, and benefits from + the same security reduction (proven secure as long as Chacha20 itself is + secure). +<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +Messages are not verified until the call to + <b class="Fn" title="Fn">crypto_unlock_final</b>(). Make sure to call it and + check the return value <i class="Em" title="Em">before</i> processing the + message. Messages may be stored before they are verified, but they cannot be + trusted. Processing untrusted messages increases the attack surface of the + system. Doing so securely is hard. Do not process messages before calling + <b class="Fn" title="Fn">crypto_unlock_final</b>(). +<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION + DETAILS</a></h1> +<ul class="Bl-bullet"> + <li class="It-bullet"><var class="Vt" title="Vt">crypto_unlock_ctx</var> is an + alias to <var class="Vt" title="Vt">crypto_lock_ctx</var>.</li> + <li class="It-bullet"><b class="Fn" title="Fn">crypto_unlock_init</b>() is an + alias to <b class="Fn" title="Fn">crypto_lock_init</b>().</li> + <li class="It-bullet"><b class="Fn" title="Fn">crypto_lock_aead_auth</b>() and + <b class="Fn" title="Fn">crypto_unlock_aead_auth</b>() are aliases to + <b class="Fn" title="Fn">crypto_lock_auth</b>().</li> +</ul> +<div class="Pp"></div> +The incremental interface is roughly three times slower than the direct + interface at identifying corrupted messages. This is because the incremental + interface works in a single pass and has to interleave decryption and + verification. Users who expect a high corruption rate may want to avoid + it.</div> +<table class="foot"> + <tr> + <td class="foot-date">December 28, 2017</td> + <td class="foot-os">Linux 4.4.0-116-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_lock_final.html b/vendor/doc/html/crypto_lock_final.html new file mode 100644 index 0000000..312c542 --- /dev/null +++ b/vendor/doc/html/crypto_lock_final.html @@ -0,0 +1,172 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_LOCK_INIT(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_LOCK_INIT(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_LOCK_INIT(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_lock_init</b>, + <b class="Nm" title="Nm">crypto_lock_auth_ad</b>, + <b class="Nm" title="Nm">crypto_lock_auth_message</b>, + <b class="Nm" title="Nm">crypto_lock_update</b>, + <b class="Nm" title="Nm">crypto_lock_final</b>, + <b class="Nm" title="Nm">crypto_unlock_init</b>, + <b class="Nm" title="Nm">crypto_unlock_auth_ad</b>, + <b class="Nm" title="Nm">crypto_unlock_auth_message</b>, + <b class="Nm" title="Nm">crypto_unlock_update</b>, + <b class="Nm" title="Nm">crypto_unlock_final</b> — + <span class="Nd" title="Nd">incremental authenticated encryption with + additional data</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_init</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_auth_ad</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_auth_message</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_update</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_final</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t mac[16]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_init</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_auth_ad</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_auth_message</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_update</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *plain_text</var>, + <var class="Fa" title="Fa">const uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_final</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t mac[16]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions were variants of + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_unlock_aead.html">crypto_unlock_aead(3monocypher)</a>. + They are deprecated in favor of those simpler functions. +<div class="Pp"></div> +Change your protocol so that it does not rely on the removed functions, namely + by splitting the data into chunks that you can individually use + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a> + on. +<div class="Pp"></div> +For files in particular, you may alternatively (and suboptimally) attempt to use + <b class="Fn" title="Fn">mmap</b>() (on *NIX) or + <b class="Fn" title="Fn">MapViewOfFile</b>() (on Windows) and pass the files + as mapped memory into + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a> + instead. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_lock_init</b>(), + <b class="Fn" title="Fn">crypto_unlock_init</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_lock_update</b>(), + <b class="Fn" title="Fn">crypto_unlock_update</b>(), and + <b class="Fn" title="Fn">crypto_lock_final</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_unlock_final</b>() returns 0 on success or -1 if + the message was corrupted. Corruption can be caused by transmission errors, + programmer error, or an attacker's interference. + <i class="Em" title="Em">Always check the return value</i>. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock_aead.html">crypto_unlock_aead(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_lock_init</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_lock_update</b>(), + <b class="Fn" title="Fn">crypto_lock_final</b>(), + <b class="Fn" title="Fn">crypto_unlock_init</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_unlock_update</b>(), and + <b class="Fn" title="Fn">crypto_unlock_final</b>() functions first appeared in + Monocypher 1.1.0. <b class="Fn" title="Fn">crypto_lock_aead_auth</b>() and + <b class="Fn" title="Fn">crypto_unlock_aead_auth</b>() were renamed to + <b class="Fn" title="Fn">crypto_lock_auth_ad</b>() and + <b class="Fn" title="Fn">crypto_unlock_auth_ad</b>() respectively in + Monocypher 2.0.0. They were deprecated in Monocypher 3.0.0 and will be removed + in Monocypher 4.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">December 12, 2019</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_lock_init.html b/vendor/doc/html/crypto_lock_init.html new file mode 100644 index 0000000..312c542 --- /dev/null +++ b/vendor/doc/html/crypto_lock_init.html @@ -0,0 +1,172 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_LOCK_INIT(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_LOCK_INIT(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_LOCK_INIT(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_lock_init</b>, + <b class="Nm" title="Nm">crypto_lock_auth_ad</b>, + <b class="Nm" title="Nm">crypto_lock_auth_message</b>, + <b class="Nm" title="Nm">crypto_lock_update</b>, + <b class="Nm" title="Nm">crypto_lock_final</b>, + <b class="Nm" title="Nm">crypto_unlock_init</b>, + <b class="Nm" title="Nm">crypto_unlock_auth_ad</b>, + <b class="Nm" title="Nm">crypto_unlock_auth_message</b>, + <b class="Nm" title="Nm">crypto_unlock_update</b>, + <b class="Nm" title="Nm">crypto_unlock_final</b> — + <span class="Nd" title="Nd">incremental authenticated encryption with + additional data</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_init</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_auth_ad</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_auth_message</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_update</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_final</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t mac[16]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_init</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_auth_ad</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_auth_message</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_update</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *plain_text</var>, + <var class="Fa" title="Fa">const uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_final</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t mac[16]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions were variants of + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_unlock_aead.html">crypto_unlock_aead(3monocypher)</a>. + They are deprecated in favor of those simpler functions. +<div class="Pp"></div> +Change your protocol so that it does not rely on the removed functions, namely + by splitting the data into chunks that you can individually use + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a> + on. +<div class="Pp"></div> +For files in particular, you may alternatively (and suboptimally) attempt to use + <b class="Fn" title="Fn">mmap</b>() (on *NIX) or + <b class="Fn" title="Fn">MapViewOfFile</b>() (on Windows) and pass the files + as mapped memory into + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a> + instead. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_lock_init</b>(), + <b class="Fn" title="Fn">crypto_unlock_init</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_lock_update</b>(), + <b class="Fn" title="Fn">crypto_unlock_update</b>(), and + <b class="Fn" title="Fn">crypto_lock_final</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_unlock_final</b>() returns 0 on success or -1 if + the message was corrupted. Corruption can be caused by transmission errors, + programmer error, or an attacker's interference. + <i class="Em" title="Em">Always check the return value</i>. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock_aead.html">crypto_unlock_aead(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_lock_init</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_lock_update</b>(), + <b class="Fn" title="Fn">crypto_lock_final</b>(), + <b class="Fn" title="Fn">crypto_unlock_init</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_unlock_update</b>(), and + <b class="Fn" title="Fn">crypto_unlock_final</b>() functions first appeared in + Monocypher 1.1.0. <b class="Fn" title="Fn">crypto_lock_aead_auth</b>() and + <b class="Fn" title="Fn">crypto_unlock_aead_auth</b>() were renamed to + <b class="Fn" title="Fn">crypto_lock_auth_ad</b>() and + <b class="Fn" title="Fn">crypto_unlock_auth_ad</b>() respectively in + Monocypher 2.0.0. They were deprecated in Monocypher 3.0.0 and will be removed + in Monocypher 4.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">December 12, 2019</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_lock_update.html b/vendor/doc/html/crypto_lock_update.html new file mode 100644 index 0000000..312c542 --- /dev/null +++ b/vendor/doc/html/crypto_lock_update.html @@ -0,0 +1,172 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_LOCK_INIT(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_LOCK_INIT(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_LOCK_INIT(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +<b class="Nm" title="Nm">crypto_lock_init</b>, + <b class="Nm" title="Nm">crypto_lock_auth_ad</b>, + <b class="Nm" title="Nm">crypto_lock_auth_message</b>, + <b class="Nm" title="Nm">crypto_lock_update</b>, + <b class="Nm" title="Nm">crypto_lock_final</b>, + <b class="Nm" title="Nm">crypto_unlock_init</b>, + <b class="Nm" title="Nm">crypto_unlock_auth_ad</b>, + <b class="Nm" title="Nm">crypto_unlock_auth_message</b>, + <b class="Nm" title="Nm">crypto_unlock_update</b>, + <b class="Nm" title="Nm">crypto_unlock_final</b> — + <span class="Nd" title="Nd">incremental authenticated encryption with + additional data</span> +<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<b class="In" title="In">#include + <<a class="In" title="In">monocypher.h</a>></b> +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_init</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_auth_ad</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_auth_message</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_update</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_lock_final</b>(<var class="Fa" title="Fa">crypto_lock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t mac[16]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_init</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>, + <var class="Fa" title="Fa">const uint8_t nonce[24]</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_auth_ad</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *ad</var>, + <var class="Fa" title="Fa">size_t ad_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_auth_message</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t *plain_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">void</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_update</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">uint8_t *plain_text</var>, + <var class="Fa" title="Fa">const uint8_t *cipher_text</var>, + <var class="Fa" title="Fa">size_t text_size</var>); +<div class="Pp"></div> +<var class="Ft" title="Ft">int</var> +<br/> +<b class="Fn" title="Fn">crypto_unlock_final</b>(<var class="Fa" title="Fa">crypto_unlock_ctx + *ctx</var>, <var class="Fa" title="Fa">const uint8_t mac[16]</var>); +<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1> +These functions were variants of + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_unlock_aead.html">crypto_unlock_aead(3monocypher)</a>. + They are deprecated in favor of those simpler functions. +<div class="Pp"></div> +Change your protocol so that it does not rely on the removed functions, namely + by splitting the data into chunks that you can individually use + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a> + on. +<div class="Pp"></div> +For files in particular, you may alternatively (and suboptimally) attempt to use + <b class="Fn" title="Fn">mmap</b>() (on *NIX) or + <b class="Fn" title="Fn">MapViewOfFile</b>() (on Windows) and pass the files + as mapped memory into + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a> + and + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a> + instead. +<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<b class="Fn" title="Fn">crypto_lock_init</b>(), + <b class="Fn" title="Fn">crypto_unlock_init</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_lock_update</b>(), + <b class="Fn" title="Fn">crypto_unlock_update</b>(), and + <b class="Fn" title="Fn">crypto_lock_final</b>() return nothing. +<div class="Pp"></div> +<b class="Fn" title="Fn">crypto_unlock_final</b>() returns 0 on success or -1 if + the message was corrupted. Corruption can be caused by transmission errors, + programmer error, or an attacker's interference. + <i class="Em" title="Em">Always check the return value</i>. +<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock.html">crypto_unlock(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_unlock_aead.html">crypto_unlock_aead(3monocypher)</a>, + <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>, + <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> +<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1> +The <b class="Fn" title="Fn">crypto_lock_init</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_lock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_lock_update</b>(), + <b class="Fn" title="Fn">crypto_lock_final</b>(), + <b class="Fn" title="Fn">crypto_unlock_init</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_ad</b>(), + <b class="Fn" title="Fn">crypto_unlock_auth_message</b>(), + <b class="Fn" title="Fn">crypto_unlock_update</b>(), and + <b class="Fn" title="Fn">crypto_unlock_final</b>() functions first appeared in + Monocypher 1.1.0. <b class="Fn" title="Fn">crypto_lock_aead_auth</b>() and + <b class="Fn" title="Fn">crypto_unlock_aead_auth</b>() were renamed to + <b class="Fn" title="Fn">crypto_lock_auth_ad</b>() and + <b class="Fn" title="Fn">crypto_unlock_auth_ad</b>() respectively in + Monocypher 2.0.0. They were deprecated in Monocypher 3.0.0 and will be removed + in Monocypher 4.0.0.</div> +<table class="foot"> + <tr> + <td class="foot-date">December 12, 2019</td> + <td class="foot-os">Linux 4.15.0-106-generic</td> + </tr> +</table> +</body> +</html> diff --git a/vendor/doc/html/crypto_memcmp.html b/vendor/doc/html/crypto_memcmp.html new file mode 100644 index 0000000..b6ab9ef --- /dev/null +++ b/vendor/doc/html/crypto_memcmp.html @@ -0,0 +1,67 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + div.Pp { margin: 1ex 0ex; } + </style> + <link rel="stylesheet" href="style.css" type="text/css" media="all"/> + <title>CRYPTO_MEMCMP(3MONOCYPHER)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">CRYPTO_MEMCMP(3MONOCYPHER)</td> + <td class="head-vol">3MONOCYPHER</td> + <td class="head-rtitle">CRYPTO_MEMCMP(3MONOCYPHER)</td> + </tr> +</table> +<div class="manual-text"> +<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1> +& |