initial commit
This commit is contained in:
commit
5a8953b7ea
|
|
@ -0,0 +1,5 @@
|
|||
.clang-format
|
||||
compile_commands.json
|
||||
/epic_drm
|
||||
/client
|
||||
*.o
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
.PHONY: all clean
|
||||
|
||||
all: epic_drm client
|
||||
|
||||
epic_drm: epic_drm.c monocypher-3.1.1/lib/monocypher.o
|
||||
gcc -g -Wall -Wextra -std=gnu11 -pipe -o $@ -Imonocypher-3.1.1/src -lpthread -lrt $< \
|
||||
monocypher-3.1.1/lib/monocypher.o
|
||||
|
||||
client: client.c
|
||||
gcc -O3 -Wall -Wextra -std=gnu11 -pipe -o $@ -lpthread -lrt $<
|
||||
|
||||
monocypher-3.1.1/lib/monocypher.o:
|
||||
cd monocypher-3.1.1 && $(MAKE) lib/monocypher.o
|
||||
|
||||
clean:
|
||||
$(RM) epic_drm client
|
||||
cd monocypher-3.1.1 && $(MAKE) clean
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
#include <stdio.h>
|
||||
#include <sys/random.h>
|
||||
|
||||
#include "epic_drm.h"
|
||||
|
||||
#define log(what) printf("[epic_drm] " what "\n")
|
||||
#define logf(what, ...) printf("[epic_drm] " what "\n", __VA_ARGS__)
|
||||
|
||||
int main() {
|
||||
// perform a basic interaction with epic_drm
|
||||
log("opening drm");
|
||||
int shm = shm_open(SHM_NAME, O_RDWR, 0);
|
||||
struct command_channel* chan = mmap(NULL, SHM_SIZE, PROT_READ | PROT_WRITE, MAP_SHARED, shm, 0);
|
||||
|
||||
log("sending get_cmd");
|
||||
chan->command = GET_CMD;
|
||||
sem_post(&chan->sem_c2s);
|
||||
sem_wait(&chan->sem_s2c);
|
||||
logf("result: %s", chan->command == SUCCESS ? "success" : "error");
|
||||
|
||||
log("data");
|
||||
for (size_t i = 0; i < 64; i++) {
|
||||
uint8_t b = ((uint8_t*) &chan->data)[i];
|
||||
printf("%02x ", b);
|
||||
if (i % 16 == 15) {
|
||||
printf("\n");
|
||||
}
|
||||
}
|
||||
printf("...\n");
|
||||
|
||||
log("sending execute_cmd");
|
||||
chan->command = EXECUTE_CMD;
|
||||
sem_post(&chan->sem_c2s);
|
||||
sem_wait(&chan->sem_s2c);
|
||||
logf("result: %s", chan->command == SUCCESS ? "success" : "error");
|
||||
|
||||
log("done");
|
||||
}
|
||||
|
|
@ -0,0 +1,73 @@
|
|||
#include <stdbool.h>
|
||||
#include <stdio.h>
|
||||
#include <string.h>
|
||||
#include <sys/random.h>
|
||||
|
||||
#include <monocypher.h>
|
||||
#include "epic_drm.h"
|
||||
|
||||
#define log(what) printf("[epic_drm] " what "\n")
|
||||
|
||||
/**
|
||||
* sends a protected command to the client
|
||||
*/
|
||||
void get_cmd(struct command_channel* chan, const uint8_t* key) {
|
||||
log("sending encrypted DRM command");
|
||||
uint8_t cmd[CMD_SIZE] = "echo 'sharks'";
|
||||
getrandom(chan->data.nonce, 24, 0);
|
||||
crypto_lock(chan->data.mac, chan->data.exec_cmd, key, chan->data.nonce, cmd, CMD_SIZE);
|
||||
chan->command = SUCCESS;
|
||||
}
|
||||
|
||||
/**
|
||||
* unprotects and executes data from the client
|
||||
*/
|
||||
void execute_cmd(struct command_channel* chan, const uint8_t* key) {
|
||||
log("decrypting command");
|
||||
uint8_t cmd[CMD_SIZE];
|
||||
int res = crypto_unlock(cmd, key, chan->data.nonce, chan->data.mac, chan->data.exec_cmd, CMD_SIZE);
|
||||
if (res != 0) {
|
||||
log("decryption error");
|
||||
chan->command = ERROR;
|
||||
} else {
|
||||
log("executing command");
|
||||
system((const char*)cmd);
|
||||
chan->command = SUCCESS;
|
||||
}
|
||||
}
|
||||
|
||||
int main() {
|
||||
// create random key
|
||||
uint8_t key[16];
|
||||
log("generating random key");
|
||||
getrandom(key, sizeof(key), 0);
|
||||
|
||||
// initialize memory
|
||||
log("opening shm");
|
||||
shm_unlink(SHM_NAME);
|
||||
int shm = shm_open(SHM_NAME, O_RDWR | O_CREAT | O_EXCL, 0644);
|
||||
ftruncate(shm, SHM_SIZE);
|
||||
struct command_channel* chan = mmap(NULL, SHM_SIZE, PROT_READ | PROT_WRITE, MAP_SHARED, shm, 0);
|
||||
|
||||
sem_init(&chan->sem_c2s, 1, 0);
|
||||
sem_init(&chan->sem_s2c, 1, 0);
|
||||
|
||||
// process commands
|
||||
log("ready");
|
||||
while (true) {
|
||||
sem_wait(&chan->sem_c2s);
|
||||
|
||||
switch (chan->command) {
|
||||
case GET_CMD:
|
||||
get_cmd(chan, key);
|
||||
break;
|
||||
case EXECUTE_CMD:
|
||||
execute_cmd(chan, key);
|
||||
break;
|
||||
default:
|
||||
log("unexpected command");
|
||||
}
|
||||
|
||||
sem_post(&chan->sem_s2c);
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
#pragma once
|
||||
#include <fcntl.h>
|
||||
#include <semaphore.h>
|
||||
#include <stdbool.h>
|
||||
#include <stdint.h>
|
||||
#include <stdlib.h>
|
||||
#include <sys/mman.h>
|
||||
#include <sys/stat.h>
|
||||
#include <unistd.h>
|
||||
|
||||
#define SHM_NAME "epic_drm"
|
||||
#define CMD_SIZE (1024 * 1024)
|
||||
#define SHM_SIZE (CMD_SIZE + 128)
|
||||
|
||||
|
||||
/**
|
||||
* a struct describing the contents of the shared memory used to interact with epic_drm
|
||||
*/
|
||||
struct command_channel {
|
||||
sem_t sem_c2s;
|
||||
sem_t sem_s2c;
|
||||
|
||||
enum { GET_CMD, EXECUTE_CMD, SUCCESS, ERROR } command;
|
||||
|
||||
struct {
|
||||
uint8_t nonce[24];
|
||||
uint8_t exec_cmd[CMD_SIZE];
|
||||
uint8_t mac[16];
|
||||
} data;
|
||||
};
|
||||
|
|
@ -0,0 +1,58 @@
|
|||
Designers
|
||||
---------
|
||||
|
||||
- **Chacha20:** Daniel J. Bernstein.
|
||||
- **Poly1305:** Daniel J. Bernstein.
|
||||
- **Blake2:** Jean-Philippe Aumasson, Christian Winnerlein, Samuel Neves,
|
||||
and Zooko Wilcox-O'Hearn
|
||||
- **Argon2:** Alex Biryukov, Daniel Dinu, and Dmitry Khovratovich
|
||||
- **X25519:** Daniel J. Bernstein
|
||||
- **EdDSA:** Daniel J. Bernstein, Bo-Yin Yang, Niels Duif, Peter
|
||||
Schwabe, and Tanja Lange
|
||||
|
||||
Implementors
|
||||
------------
|
||||
|
||||
- **Chacha20:** Loup Vaillant, implemented from spec.
|
||||
- **Poly1305:** Loup Vaillant, implemented from spec.
|
||||
- **Blake2b:** Loup Vaillant, implemented from spec.
|
||||
- **Argon2i:** Loup Vaillant, implemented from spec.
|
||||
- **X25519:** Daniel J. Bernstein, taken and packaged from SUPERCOP
|
||||
ref10.
|
||||
- **EdDSA:** Loup Vaillant, with bits and pieces from SUPERCOP ref10
|
||||
and TweetNaCl.
|
||||
|
||||
Test suite
|
||||
----------
|
||||
|
||||
Designed and implemented by Loup Vaillant, using _libsodium_ (by many
|
||||
authors), and _ed25519-donna_ (by Andrew Moon —floodyberry).
|
||||
|
||||
Manual
|
||||
------
|
||||
|
||||
Loup Vaillant, Fabio Scotoni, and Michael Savage.
|
||||
|
||||
- Loup Vaillant did a first draft.
|
||||
- Fabio Scotoni rewrote the manual into proper man pages (and
|
||||
substantially changed it in the process).
|
||||
- Michael Savage did extensive editing and proofreading.
|
||||
|
||||
Thanks
|
||||
------
|
||||
|
||||
Fabio Scotoni provided much needed advice about testing, interface,
|
||||
packaging, and the general direction of the whole project. He also
|
||||
redesigned monocypher.org style sheets.
|
||||
|
||||
Mike Pechkin and André Maroneze found bugs in earlier versions of
|
||||
Monocypher.
|
||||
|
||||
Andrew Moon clarified carry propagation in modular arithmetic, and
|
||||
provided advice and code that significantly simplified and improved
|
||||
Elligator2 mappings.
|
||||
|
||||
Mike Hamburg explained comb algorithms, including the signed
|
||||
all-bits-set comb described in his 2012 paper, Fast and compact
|
||||
elliptic-curve cryptography. This made EdDSA signatures over twice as
|
||||
fast.
|
||||
|
|
@ -0,0 +1,225 @@
|
|||
3.1.1
|
||||
-----
|
||||
2020/06/15
|
||||
|
||||
- Various documentation fixes.
|
||||
- Fixed various compiler warnings.
|
||||
- Fixed some integer overflows (16-bit platforms only).
|
||||
|
||||
|
||||
3.1.0
|
||||
-----
|
||||
2020/04/03
|
||||
|
||||
- Added Elligator 2 mappings (hash to curve, curve to hash).
|
||||
- Added OPRF support (with scalar inversion).
|
||||
- Added Edwards25519 -> Curve25519 conversions
|
||||
|
||||
|
||||
3.0.0
|
||||
-----
|
||||
2020/01/19
|
||||
|
||||
- Deprecated the incremental AEAD interface.
|
||||
- Deprecated the incremental Chacha20, added a direct interface.
|
||||
- Added IETF Chacha20 (96-bit nonce), as described in RFC 8439.
|
||||
- Moved deprecated interfaces to a separate `src/deprecated` folder.
|
||||
- Removed the `ED25519_SHA512` preprocessor flag.
|
||||
- `crypto_x25519()` and `crypto_key_exchange()` now return `void`.
|
||||
- Added a custom hash interface to EdDSA. Several instances of EdDSA
|
||||
can share the same binary.
|
||||
- Added optional support for HMAC SHA-512
|
||||
- Moved all SHA-512 operations to `src/optional/monocypher-ed25519.(h|c)`
|
||||
- Optional support for Ed25519 no longer requires a preprocessor flag.
|
||||
Add `src/optional/monocypher-ed25519.(h|c)` to your project instead.
|
||||
|
||||
|
||||
2.0.6
|
||||
-----
|
||||
2019/10/21
|
||||
|
||||
- Added the `BLAKE2_NO_UNROLLING` preprocessor definition. Activating it
|
||||
makes the binary about 5KB smaller, and speeds up processing times on
|
||||
many embedded processors.
|
||||
- Reduced the stack usage of signature verification by about
|
||||
40%. Signature verification now fits in smaller machines.
|
||||
- Fixed many implicit casts warnings.
|
||||
- Fixed the manual here and there.
|
||||
- Lots of small nitpicks.
|
||||
|
||||
|
||||
2.0.5
|
||||
-----
|
||||
2018/08/23
|
||||
|
||||
- Faster EdDSA signatures and verification. Like, 4 times as fast.
|
||||
|
||||
|
||||
2.0.4
|
||||
-----
|
||||
2018/06/24
|
||||
|
||||
- Corrected a critical vulnerability in EdDSA, where crypto_check() was
|
||||
accepting invalid signatures. (Found by Mike Pechkin.) The current
|
||||
fix removes a buggy optimisation, effectively halving the performance
|
||||
of EdDSA.
|
||||
- The test suite no longer tries to allocate zero bytes (some platforms
|
||||
fail such an allocation).
|
||||
|
||||
2.0.3
|
||||
-----
|
||||
2018/06/16
|
||||
|
||||
- Corrected undefined behaviour in Blake2b
|
||||
- Improved the test suite (faster, better coverage)
|
||||
|
||||
2.0.2
|
||||
-----
|
||||
2018/04/23
|
||||
|
||||
- Corrected a couple failures to wipe secret buffers.
|
||||
- Corrected a bug that prevented compilation in Ed25519 mode.
|
||||
- Adjusted the number of test vectors in the test suite.
|
||||
- Improved tests for incremental interfaces.
|
||||
- Replaced the GNU all permissive licence by a public domain dedication
|
||||
(Creative Commons CC-0). The BSD licence remains as a fallback.
|
||||
|
||||
2.0.1
|
||||
-----
|
||||
2018/03/07
|
||||
|
||||
- Followed a systematic pattern for the loading code of symmetric
|
||||
crypto. It is now easier to review.
|
||||
- Tweaked Poly1305 code to make it easier to prove correct.
|
||||
|
||||
2.0.0
|
||||
-----
|
||||
2018/02/14
|
||||
|
||||
- Changed the authenticated encryption format. It now conforms to
|
||||
RFC 7539, with one exception: it uses XChacha20 initialisation instead
|
||||
of the IETF version of Chacha20. This new format conforms to
|
||||
Libsodium's `crypto_aead_xchacha20poly1305_ietf_encrypt`.
|
||||
- Removed `crypto_lock_encrypt()` and `crypto_lock_auth()`.
|
||||
- Renamed `crypto_lock_aead_auth()` to `crypto_lock_auth_ad()`.
|
||||
- Renamed `crypto_unlock_aead_auth()` to `crypto_unlock_auth_ad()`.
|
||||
- Added `crypto_lock_auth_message()` and `crypto_unlock_auth_message()`
|
||||
- Renamed `crypto_aead_lock` to `crypto_lock_aead`;
|
||||
- Renamed `crypto_aead_unlock` to `crypto_unlock_aead`;
|
||||
|
||||
The format change facilitates optimisation by aligning data to block
|
||||
boundaries. The API changes increase consistency.
|
||||
|
||||
1.1.0
|
||||
-----
|
||||
2018/02/06
|
||||
|
||||
- Rewrote the manual into proper man pages.
|
||||
- Added incremental interfaces for authenticated encryption and
|
||||
signatures.
|
||||
- A couple breaking API changes, easily fixed by renaming the affected
|
||||
functions.
|
||||
|
||||
1.0.1
|
||||
-----
|
||||
2017/07/23
|
||||
|
||||
- Optimised the loading and unloading code of the symmetric crypto
|
||||
(Blake2b, sha512, Chacha20, and Poly1305).
|
||||
- Fused self contained tests together for easier analysis with Frama-C
|
||||
and the TIS interpreter.
|
||||
|
||||
1.0
|
||||
---
|
||||
2017/07/18
|
||||
|
||||
- Renamed `crypto_chacha20_Xinit` to `crypto_chacha20_x_init`, for
|
||||
consistency reasons (snake case everywhere).
|
||||
- Fixed signed integer overflow detected by UBSan.
|
||||
- Doubled the speed of EdDSA by performing the scalar product in
|
||||
Montgomery space.
|
||||
|
||||
0.8
|
||||
---
|
||||
2017/07/06
|
||||
|
||||
- Added about a hundred lines of code to improve performance of public
|
||||
key cryptography. Diffie-Hellman is now 20% faster than before.
|
||||
(The effects are less pronounces for EdDSA).
|
||||
- Added random self-consistency tests.
|
||||
- Added a speed benchmark against libsodium.
|
||||
|
||||
0.7
|
||||
---
|
||||
2017/06/07
|
||||
|
||||
- Slightly changed the authenticated encryption API. Functions are
|
||||
now all in "detached" mode. The reason is better support for
|
||||
authenticated encryption _without_ additional data.
|
||||
- Rewrote Blake2b from spec, so it can use the same licence as
|
||||
everything else.
|
||||
- Added random tests that compare Monocypher with libsodium and
|
||||
ed25519-donna.
|
||||
- Added explicit support for Frama-C analysis (this doesn't affect the
|
||||
source code)
|
||||
|
||||
0.6
|
||||
---
|
||||
2017/03/17
|
||||
|
||||
- Fixed incorrect poly1305 output on empty messages. (Found by Mike
|
||||
Pechkin.)
|
||||
|
||||
0.5
|
||||
---
|
||||
2017/03/10
|
||||
|
||||
- Fixed many undefined behaviours in curve25519, that occur whenever
|
||||
we perform a left shift on a signed negative integer. It doesn't
|
||||
affect the generated code, but you never know. (Found with Frama-C
|
||||
by André Maroneze.)
|
||||
|
||||
Fun fact: TweetNaCl and ref10 have the same bug. Libsodium have
|
||||
corrected the issue, though.
|
||||
|
||||
For those who don't comprehend the magnitude of this madness, the
|
||||
expression `-1 << 3` is undefined in C. This is explained in
|
||||
section 6.5.7(§4) of the C11 standard.
|
||||
|
||||
0.4
|
||||
---
|
||||
2017/03/09
|
||||
|
||||
- Fixed critical bug causing Argon2i to fail whenever it uses more
|
||||
than 512 blocks. It was reading uninitialised memory, and the
|
||||
results were incorrect. (Found by Mike Pechkin.)
|
||||
- Fixed an undefined behaviour in curve25519 (`fe_tobytes()`). It was
|
||||
accessing uninitialised memory, before throwing it away. It didn't
|
||||
affect the compiled code nor the results, but you never know.
|
||||
(Found with [Frama-C](http://frama-c.com) by André Maroneze.)
|
||||
|
||||
0.3
|
||||
---
|
||||
2017/02/27
|
||||
|
||||
- Got the invariants of poly1305 right, put them in the comments.
|
||||
There was no bug, but that was lucky (turned out the IETF test
|
||||
vectors were designed to trigger the bugs I was afraid of).
|
||||
- Simplified poly1305 finalisation (replaced conditional subtraction
|
||||
by a carry propagation).
|
||||
- Made a few cosmetic changes here and there.
|
||||
|
||||
0.2
|
||||
---
|
||||
????/??/??
|
||||
|
||||
- Public interface significantly reworked. Removed redundant, hard to
|
||||
mess up constructions.
|
||||
- Added AEAD.
|
||||
- Sped up curve25519 by a factor of more than 6 (switched to ref10
|
||||
arithmetic)
|
||||
- Added various test vectors, completed the consistency tests.
|
||||
|
||||
0.1
|
||||
---
|
||||
2016/??/??
|
||||
|
|
@ -0,0 +1,173 @@
|
|||
Monocypher as a whole is dual-licensed. Choose whichever licence you
|
||||
want from the two licences listed below.
|
||||
|
||||
The first licence is a regular 2-clause BSD licence. The second licence
|
||||
is the CC-0 from Creative Commons. It is intended to release Monocypher
|
||||
to the public domain. The BSD licence serves as a fallback option.
|
||||
|
||||
See the individual files for specific information about who contributed
|
||||
to what file during which years. See below for special notes.
|
||||
|
||||
Licence 1 (2-clause BSD)
|
||||
------------------------
|
||||
|
||||
Copyright (c) 2017-2020, Loup Vaillant
|
||||
Copyright (c) 2017-2019, Michael Savage
|
||||
Copyright (c) 2017-2020, Fabio Scotoni
|
||||
All rights reserved.
|
||||
|
||||
Redistribution and use in source and binary forms, with or without
|
||||
modification, are permitted provided that the following conditions are
|
||||
met:
|
||||
|
||||
1. Redistributions of source code must retain the above copyright
|
||||
notice, this list of conditions and the following disclaimer.
|
||||
|
||||
2. Redistributions in binary form must reproduce the above copyright
|
||||
notice, this list of conditions and the following disclaimer in the
|
||||
documentation and/or other materials provided with the
|
||||
distribution.
|
||||
|
||||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
||||
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
||||
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
||||
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
||||
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
||||
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
||||
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||||
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||||
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||||
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
|
||||
Licence 2 (CC-0)
|
||||
----------------
|
||||
|
||||
> CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
|
||||
> LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
|
||||
> ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
|
||||
> INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
|
||||
> REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
|
||||
> PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
|
||||
> THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
|
||||
> HEREUNDER.
|
||||
|
||||
### Statement of Purpose
|
||||
|
||||
The laws of most jurisdictions throughout the world automatically confer
|
||||
exclusive Copyright and Related Rights (defined below) upon the creator
|
||||
and subsequent owner(s) (each and all, an "owner") of an original work
|
||||
of authorship and/or a database (each, a "Work").
|
||||
|
||||
Certain owners wish to permanently relinquish those rights to a Work for
|
||||
the purpose of contributing to a commons of creative, cultural and
|
||||
scientific works ("Commons") that the public can reliably and without
|
||||
fear of later claims of infringement build upon, modify, incorporate in
|
||||
other works, reuse and redistribute as freely as possible in any form
|
||||
whatsoever and for any purposes, including without limitation commercial
|
||||
purposes. These owners may contribute to the Commons to promote the
|
||||
ideal of a free culture and the further production of creative, cultural
|
||||
and scientific works, or to gain reputation or greater distribution for
|
||||
their Work in part through the use and efforts of others.
|
||||
|
||||
For these and/or other purposes and motivations, and without any
|
||||
expectation of additional consideration or compensation, the person
|
||||
associating CC0 with a Work (the "Affirmer"), to the extent that he or
|
||||
she is an owner of Copyright and Related Rights in the Work, voluntarily
|
||||
elects to apply CC0 to the Work and publicly distribute the Work under
|
||||
its terms, with knowledge of his or her Copyright and Related Rights in
|
||||
the Work and the meaning and intended legal effect of CC0 on those
|
||||
rights.
|
||||
|
||||
1. **Copyright and Related Rights.** A Work made available under CC0 may
|
||||
be protected by copyright and related or neighboring rights
|
||||
("Copyright and Related Rights"). Copyright and Related Rights
|
||||
include, but are not limited to, the following:
|
||||
|
||||
- the right to reproduce, adapt, distribute, perform, display,
|
||||
communicate, and translate a Work;
|
||||
- moral rights retained by the original author(s) and/or
|
||||
performer(s); publicity and privacy rights pertaining to a person's
|
||||
image or likeness depicted in a Work;
|
||||
- rights protecting against unfair competition in regards to a Work,
|
||||
subject to the limitations in paragraph 4(a), below;
|
||||
- rights protecting the extraction, dissemination, use and reuse of
|
||||
data in a Work;
|
||||
- database rights (such as those arising under Directive 96/9/EC of
|
||||
the European Parliament and of the Council of 11 March 1996 on the
|
||||
legal protection of databases, and under any national
|
||||
implementation thereof, including any amended or successor version
|
||||
of such directive); and
|
||||
- other similar, equivalent or corresponding rights throughout the
|
||||
world based on applicable law or treaty, and any national
|
||||
implementations thereof.
|
||||
|
||||
2. **Waiver.** To the greatest extent permitted by, but not in
|
||||
contravention of, applicable law, Affirmer hereby overtly, fully,
|
||||
permanently, irrevocably and unconditionally waives, abandons, and
|
||||
surrenders all of Affirmer's Copyright and Related Rights and
|
||||
associated claims and causes of action, whether now known or unknown
|
||||
(including existing as well as future claims and causes of action),
|
||||
in the Work (i) in all territories worldwide, (ii) for the maximum
|
||||
duration provided by applicable law or treaty (including future time
|
||||
extensions), (iii) in any current or future medium and for any number
|
||||
of copies, and (iv) for any purpose whatsoever, including without
|
||||
limitation commercial, advertising or promotional purposes (the
|
||||
"Waiver"). Affirmer makes the Waiver for the benefit of each member
|
||||
of the public at large and to the detriment of Affirmer's heirs and
|
||||
successors, fully intending that such Waiver shall not be subject to
|
||||
revocation, rescission, cancellation, termination, or any other legal
|
||||
or equitable action to disrupt the quiet enjoyment of the Work by the
|
||||
public as contemplated by Affirmer's express Statement of Purpose.
|
||||
|
||||
3. **Public License Fallback.** Should any part of the Waiver for any
|
||||
reason be judged legally invalid or ineffective under applicable law,
|
||||
then the Waiver shall be preserved to the maximum extent permitted
|
||||
taking into account Affirmer's express Statement of Purpose. In
|
||||
addition, to the extent the Waiver is so judged Affirmer hereby
|
||||
grants to each affected person a royalty-free, non transferable, non
|
||||
sublicensable, non exclusive, irrevocable and unconditional license
|
||||
to exercise Affirmer's Copyright and Related Rights in the Work (i)
|
||||
in all territories worldwide, (ii) for the maximum duration provided
|
||||
by applicable law or treaty (including future time extensions), (iii)
|
||||
in any current or future medium and for any number of copies, and
|
||||
(iv) for any purpose whatsoever, including without limitation
|
||||
commercial, advertising or promotional purposes (the "License"). The
|
||||
License shall be deemed effective as of the date CC0 was applied by
|
||||
Affirmer to the Work. Should any part of the License for any reason
|
||||
be judged legally invalid or ineffective under applicable law, such
|
||||
partial invalidity or ineffectiveness shall not invalidate the
|
||||
remainder of the License, and in such case Affirmer hereby affirms
|
||||
that he or she will not (i) exercise any of his or her remaining
|
||||
Copyright and Related Rights in the Work or (ii) assert any
|
||||
associated claims and causes of action with respect to the Work, in
|
||||
either case contrary to Affirmer's express Statement of Purpose.
|
||||
|
||||
4. **Limitations and Disclaimers.**
|
||||
|
||||
- No trademark or patent rights held by Affirmer are waived,
|
||||
abandoned, surrendered, licensed or otherwise affected by this
|
||||
document.
|
||||
- Affirmer offers the Work as-is and makes no representations or
|
||||
warranties of any kind concerning the Work, express, implied,
|
||||
statutory or otherwise, including without limitation warranties of
|
||||
title, merchantability, fitness for a particular purpose, non
|
||||
infringement, or the absence of latent or other defects, accuracy,
|
||||
or the present or absence of errors, whether or not discoverable,
|
||||
all to the greatest extent permissible under applicable law.
|
||||
- Affirmer disclaims responsibility for clearing rights of other
|
||||
persons that may apply to the Work or any use thereof, including
|
||||
without limitation any person's Copyright and Related Rights in the
|
||||
Work. Further, Affirmer disclaims responsibility for obtaining any
|
||||
necessary consents, permissions or other rights required for any
|
||||
use of the Work.
|
||||
- Affirmer understands and acknowledges that Creative Commons is not
|
||||
a party to this document and has no duty or obligation with respect
|
||||
to this CC0 or use of the Work.
|
||||
|
||||
Special notes
|
||||
-------------
|
||||
|
||||
The files in `tests/externals/` were placed in the public domain by
|
||||
their respective authors. See the `AUTHORS.md` files in each directory.
|
||||
|
|
@ -0,0 +1,172 @@
|
|||
Monocypher
|
||||
----------
|
||||
|
||||
Monocypher is an easy to use, easy to deploy, auditable crypto library
|
||||
written in portable C. It approaches the size of [TweetNaCl][] and the
|
||||
speed of [Libsodium][].
|
||||
|
||||
[Official site.](https://monocypher.org/)
|
||||
[Official releases.](https://monocypher.org/download/)
|
||||
|
||||
[Libsodium]: https://libsodium.org
|
||||
[TweetNaCl]: https://tweetnacl.cr.yp.to/
|
||||
|
||||
Manual
|
||||
------
|
||||
|
||||
The manual can be found at https://monocypher.org/manual/, and in the
|
||||
`doc/` folder.
|
||||
|
||||
The `doc/man/` folder contains the man pages. You can install them in
|
||||
your system by running `make install-doc`. Official releases also have a
|
||||
`doc/html/` folder with an html version.
|
||||
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
### Option 1: grab the sources
|
||||
|
||||
The easiest way to use Monocypher is to include `src/monocypher.h` and
|
||||
`src/monocypher.c` directly into your project. They compile as C (since
|
||||
C99) and C++ (since C++98).
|
||||
|
||||
|
||||
### Option 2: grab the library
|
||||
|
||||
Run `make`, then grab the `src/monocypher.h` header and either the
|
||||
`lib/libmonocypher.a` or `lib/libmonocypher.so` library. The default
|
||||
compiler is `gcc -std=gnu99`, and the default flags are `-pedantic -Wall
|
||||
-Wextra -O3 -march=native`. If they don't work on your platform, you
|
||||
can change them like this:
|
||||
|
||||
$ make CC="clang -std=c99" CFLAGS="-O2"
|
||||
|
||||
### Option 3: install it on your system
|
||||
|
||||
The following should work on most UNIX systems:
|
||||
|
||||
$ make install
|
||||
|
||||
This will install Monocypher in `/usr/local/` by default. Libraries
|
||||
will go to `/usr/local/lib/`, the header in `/usr/local/include/`, and
|
||||
the man pages in `/usr/local/share/man/man3`. You can change those
|
||||
defaults with the `PREFIX` and `DESTDIR` variables thus:
|
||||
|
||||
$ make install PREFIX="/opt"
|
||||
|
||||
Once installed, you can use `pkg-config` to compile and link your
|
||||
program. For instance, if you have a one file C project that uses
|
||||
Monocypher, you can compile it thus:
|
||||
|
||||
$ gcc -o myProgram myProgram.c \
|
||||
$(pkg-config monocypher --cflags) \
|
||||
$(pkg-config monocypher --libs)
|
||||
|
||||
The `cflags` line gives the include path for monocypher.h, and the
|
||||
`libs` line provides the link path and option required to find
|
||||
`libmonocypher.a` (or `libmonocypher.so`).
|
||||
|
||||
|
||||
Test suite
|
||||
----------
|
||||
|
||||
$ make test
|
||||
|
||||
It should display a nice printout of all the tests, all starting with
|
||||
"OK". If you see "FAILURE" anywhere, something has gone very wrong
|
||||
somewhere.
|
||||
|
||||
*Do not* use Monocypher without running those tests at least once.
|
||||
|
||||
The same test suite can be run under Clang sanitisers and Valgrind, and
|
||||
be checked for code coverage:
|
||||
|
||||
$ tests/test.sh
|
||||
$ tests/coverage.sh
|
||||
|
||||
|
||||
### Serious auditing
|
||||
|
||||
The code may be analysed more formally with [Frama-c][] and the
|
||||
[TIS interpreter][TIS]. To analyse the code with Frama-c, run:
|
||||
|
||||
$ tests/formal-analysis.sh
|
||||
$ tests/frama-c.sh
|
||||
|
||||
This will have Frama-c parse, and analyse the code, then launch a GUI.
|
||||
You must have Frama-c installed. See `frama-c.sh` for the recommended
|
||||
settings. To run the code under the TIS interpreter, run
|
||||
|
||||
$ tests/formal-analysis.sh
|
||||
$ tis-interpreter.sh --cc -Dvolatile= tests/formal-analysis/*.c
|
||||
|
||||
Notes:
|
||||
|
||||
- `tis-interpreter.sh` is part of TIS. If it is not in your path,
|
||||
adjust the command accordingly.
|
||||
|
||||
- The TIS interpreter sometimes fails to evaluate correct programs when
|
||||
they use the `volatile` keyword (which is only used as an attempt to
|
||||
prevent dead store elimination for memory wipes). The `-cc
|
||||
-Dvolatile=` option works around that bug by ignoring `volatile`
|
||||
altogether.
|
||||
|
||||
[Frama-c]:https://frama-c.com/
|
||||
[TIS]: https://trust-in-soft.com/tis-interpreter/
|
||||
|
||||
|
||||
Speed benchmark
|
||||
---------------
|
||||
|
||||
$ make speed
|
||||
|
||||
This will give you an idea how fast Monocypher is on your machine. Make
|
||||
sure you run it on the target platform if performance is a concern. If
|
||||
Monocypher is too slow, try Libsodium. If you're not sure, you can
|
||||
always switch later.
|
||||
|
||||
|
||||
Note: the speed benchmark currently requires the POSIX
|
||||
`clock_gettime()` function.
|
||||
|
||||
There are similar benchmarks for Libsodium, TweetNaCl, LibHydrogen, and
|
||||
c25519:
|
||||
|
||||
$ make speed-sodium
|
||||
$ make speed-tweetnacl
|
||||
$ make speed-hydrogen
|
||||
$ make speed-c25519
|
||||
|
||||
(The `speed-hydrogen` target assumes it has pkg-config installed. Try
|
||||
`make pkg-config-libhydrogen` as root if it is not.)
|
||||
|
||||
You can also adjust the optimisation options for Monocypher, TweetNaCl,
|
||||
and c25519 (the default is `-O3 march=native`):
|
||||
|
||||
$ make speed CFLAGS="-O2"
|
||||
$ make speed-tweetnacl CFLAGS="-O2"
|
||||
|
||||
|
||||
Customisation
|
||||
-------------
|
||||
|
||||
Monocypher has optional compatibility with Ed25519. To have that, add
|
||||
`monocypher-ed25519.h` and `monocypher-ed25519.c` provided in
|
||||
`src/optional` to your project. If you're using the makefile, define
|
||||
the `USE_ED25519` variable to link it to monocypher.a and monocypher.so:
|
||||
|
||||
$ make USE_ED25519=true
|
||||
|
||||
Monocypher also has the `BLAKE2_NO_UNROLLING` preprocessor flag, which
|
||||
is activated by compiling monocypher.c with the `-DBLAKE2_NO_UNROLLING`
|
||||
option.
|
||||
|
||||
The `-DBLAKE2_NO_UNROLLING` option is a performance tweak. By default,
|
||||
Monocypher unrolls the Blake2b inner loop, because doing so is over 25%
|
||||
faster on modern processors. Some embedded processors however, run the
|
||||
unrolled loop _slower_ (possibly because of the cost of fetching 5KB of
|
||||
additional code). If you're using an embedded platform, try this
|
||||
option. The binary will be about 5KB smaller, and in some cases faster.
|
||||
|
||||
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
<b class="Nm" title="Nm">crypto_memcmp</b>,
|
||||
<b class="Nm" title="Nm">crypto_zerocmp</b> —
|
||||
<span class="Nd" title="Nd">deprecated timing-safe data comparisons</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_memcmp</b>(<var class="Fa" title="Fa">const
|
||||
uint8_t *p1</var>, <var class="Fa" title="Fa">const uint8_t *p2</var>,
|
||||
<var class="Fa" title="Fa">size_t n</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">int</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_zerocmp</b>(<var class="Fa" title="Fa">const
|
||||
uint8_t *p</var>, <var class="Fa" title="Fa">size_t n</var>);
|
||||
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||
<b class="Fn" title="Fn">crypto_memcmp</b>() and
|
||||
<b class="Fn" title="Fn">crypto_zerocmp</b>() were meant to provide
|
||||
timing-safe data comparison. They have been removed from Monocypher because
|
||||
they could not uphold those guarantees when compiled with
|
||||
<b class="Fl" title="Fl">-O3</b> on common compilers. 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>
|
||||
and
|
||||
<a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a>
|
||||
instead.
|
||||
<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_verify16.html">crypto_verify16(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_memcmp</b>() function first appeared in
|
||||
Monocypher 0.1. <b class="Fn" title="Fn">crypto_zerocmp</b>() was introduced
|
||||
in Monocypher 0.6. These functions were removed in Monocypher 1.1.0.</div>
|
||||
<table class="foot">
|
||||
<tr>
|
||||
<td class="foot-date">December 28, 2017</td>
|
||||
<td class="foot-os">Linux 4.15.0-65-generic</td>
|
||||
</tr>
|
||||
</table>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,241 @@
|
|||
<!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_POLY1305(3MONOCYPHER)</title>
|
||||
</head>
|
||||
<body>
|
||||
<table class="head">
|
||||
<tr>
|
||||
<td class="head-ltitle">CRYPTO_POLY1305(3MONOCYPHER)</td>
|
||||
<td class="head-vol">3MONOCYPHER</td>
|
||||
<td class="head-rtitle">CRYPTO_POLY1305(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_poly1305</b>,
|
||||
<b class="Nm" title="Nm">crypto_poly1305_init</b>,
|
||||
<b class="Nm" title="Nm">crypto_poly1305_update</b>,
|
||||
<b class="Nm" title="Nm">crypto_poly1305_final</b> —
|
||||
<span class="Nd" title="Nd">Poly1305 one-time message authentication
|
||||
codes</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_poly1305</b>(<var class="Fa" title="Fa">uint8_t
|
||||
mac[16]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>,
|
||||
<var class="Fa" title="Fa">size_t message_size</var>,
|
||||
<var class="Fa" title="Fa">const uint8_t key[32]</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">void</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_poly1305_init</b>(<var class="Fa" title="Fa">crypto_poly1305_ctx
|
||||
*ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">void</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_poly1305_update</b>(<var class="Fa" title="Fa">crypto_poly1305_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_poly1305_final</b>(<var class="Fa" title="Fa">crypto_poly1305_ctx
|
||||
*ctx</var>, <var class="Fa" title="Fa">uint8_t mac[16]</var>);
|
||||
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||
Poly1305 is a one-time message authentication code. “One-time”
|
||||
means the authentication key can be used only once.
|
||||
<b class="Sy" title="Sy">This makes Poly1305 easy to misuse</b>. On the other
|
||||
hand, Poly1305 is fast, and provably secure if used correctly.
|
||||
<div class="Pp"></div>
|
||||
Poly1305 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">mac</var></dt>
|
||||
<dd class="It-tag">The 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">The secret authentication key. Use only once per message.
|
||||
Do not use the session key to authenticate messages. It should be wiped
|
||||
with
|
||||
<a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>
|
||||
after use.</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 authenticate. May overlap with the
|
||||
<var class="Fa" title="Fa">mac</var> argument.</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>
|
||||
<b class="Fn" title="Fn">crypto_poly1305</b>() produces a message authentication
|
||||
code for the given message and authentication key. To verify the integrity of
|
||||
a message, use
|
||||
<a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>
|
||||
to compare the received MAC to the output
|
||||
<var class="Fa" title="Fa">mac</var>.
|
||||
<h2 class="Ss" title="Ss" id="Incremental_interface"><a class="selflink" href="#Incremental_interface">Incremental
|
||||
interface</a></h2>
|
||||
<b class="Fn" title="Fn">crypto_poly1305_init</b>() initialises a context.
|
||||
<var class="Fa" title="Fa">key</var> should be wiped once the context is
|
||||
initialised. Then, <b class="Fn" title="Fn">crypto_poly1305_update</b>()
|
||||
authenticates the message chunk by chunk. Once the message is entirely
|
||||
processed, <b class="Fn" title="Fn">crypto_poly1305_final</b>() yields the
|
||||
message authentication code.
|
||||
<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>
|
||||
To authenticate a message:
|
||||
<div class="Pp"></div>
|
||||
<div class="Bd" style="margin-left: 5.00ex;">
|
||||
<pre class="Li">
|
||||
const uint8_t msg[ 5] = "Lorem"; /* Message to authenticate */
|
||||
uint8_t key[32]; /* Random secret key (use only once) */
|
||||
uint8_t mac[16]; /* Message authentication code (MAC) */
|
||||
arc4random_buf(key, 32);
|
||||
crypto_poly1305(mac, msg, 5, key);
|
||||
/* Wipe the key */
|
||||
crypto_wipe(key, 32);
|
||||
</pre>
|
||||
</div>
|
||||
<div class="Pp"></div>
|
||||
To verify the above message:
|
||||
<div class="Pp"></div>
|
||||
<div class="Bd" style="margin-left: 5.00ex;">
|
||||
<pre class="Li">
|
||||
const uint8_t msg [ 5] = "Lorem"; /* Message to verify */
|
||||
uint8_t key [32]; /* The above key */
|
||||
const uint8_t mac [16]; /* The above MAC */
|
||||
uint8_t real_mac[16]; /* The actual MAC */
|
||||
crypto_poly1305(real_mac, msg, 5, key);
|
||||
/* Wipe the key */
|
||||
crypto_wipe(key, 32);
|
||||
if (crypto_verify16(mac, real_mac)) {
|
||||
/* Corrupted message, abort processing */
|
||||
} else {
|
||||
/* Genuine message */
|
||||
}
|
||||
/* The real mac is secret. Wipe it */
|
||||
crypto_wipe(real_mac, 16);
|
||||
</pre>
|
||||
</div>
|
||||
<div class="Pp"></div>
|
||||
Incremental authentication:
|
||||
<div class="Pp"></div>
|
||||
<div class="Bd" style="margin-left: 5.00ex;">
|
||||
<pre class="Li">
|
||||
const uint8_t msg[500]= {1}; /* Message to authenticate */
|
||||
uint8_t key[ 32]; /* Random secret key (use only once) */
|
||||
uint8_t mac[ 16]; /* Message authentication code (MAC) */
|
||||
crypto_poly1305_ctx ctx;
|
||||
arc4random_buf(key, 32);
|
||||
crypto_poly1305_init(&ctx, key);
|
||||
/* Wipe the key */
|
||||
crypto_wipe(key, 32);
|
||||
for (int i = 0; i < 500; i += 100) {
|
||||
crypto_poly1305_update(&ctx, msg, 100);
|
||||
}
|
||||
crypto_poly1305_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_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_verify16.html">crypto_verify16(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 Poly1305, described in RFC 8439.
|
||||
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
|
||||
The <b class="Fn" title="Fn">crypto_poly1305_init</b>(),
|
||||
<b class="Fn" title="Fn">crypto_poly1305_update</b>(), and
|
||||
<b class="Fn" title="Fn">crypto_poly1305_final</b>() functions first appeared
|
||||
in Monocypher 0.1. <b class="Fn" title="Fn">crypto_poly1305</b>() 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>
|
||||
Poly1305 is difficult to use correctly. Do not use it unless you are absolutely
|
||||
sure what you are doing. Use authenticated encryption instead; see
|
||||
<a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>.
|
||||
If you are certain you do not want encryption, refer to
|
||||
<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>
|
||||
on how to use Blake2b to generate message authentication codes.
|
||||
<h2 class="Ss" title="Ss" id="Authentication_key_requirements"><a class="selflink" href="#Authentication_key_requirements">Authentication
|
||||
key requirements</a></h2>
|
||||
Poly1305 is a <i class="Em" title="Em">one-time</i> authenticator. This puts
|
||||
rather stringent constraints on the authentication key:
|
||||
<ul class="Bl-bullet">
|
||||
<li class="It-bullet">Any given key must be used only once. Using the same key
|
||||
for two different messages reveals it to the attacker. Do not use the
|
||||
session key, or it will void all security.</li>
|
||||
<li class="It-bullet">Authentication keys must be random, and independent from
|
||||
each other. Do not use non-random nonces. Do not use related keys. Use
|
||||
fresh, unpredictable, uniformly distributed random numbers.</li>
|
||||
<li class="It-bullet">The key must be transmitted to the recipient without
|
||||
revealing it to the attacker. Somehow.</li>
|
||||
</ul>
|
||||
<div class="Pp"></div>
|
||||
The only practical source for the authentication key is a chunk of the
|
||||
encryption stream used to encrypt the message. That chunk must be
|
||||
<i class="Em" title="Em">dedicated</i> to the authentication key: if it is
|
||||
reused to encrypt the message itself, the attacker may recover that chunk by
|
||||
guessing the message, then forge arbitrary messages.
|
||||
<div class="Pp"></div>
|
||||
To get this right, you need a session key, a <i class="Em" title="Em">unique</i>
|
||||
nonce, and a stream cipher. Generate a stream with the session key and nonce.
|
||||
Take the first 32 bytes of that stream as your authentication key, then use
|
||||
the <i class="Em" title="Em">rest</i> of the stream to encrypt your message.
|
||||
This is the approach used by
|
||||
<a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(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>
|
||||
Use
|
||||
<a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>
|
||||
to compare message authentication codes. Avoid standard buffer comparison
|
||||
functions. They may not run in constant time, enabling an attacker to exploit
|
||||
timing attacks to recover the MAC.
|
||||
<div class="Pp"></div>
|
||||
The authentication key should be wiped with
|
||||
<a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>
|
||||
after use.
|
||||
<div class="Pp"></div>
|
||||
The incremental interface automatically wipes its context when finished so users
|
||||
do not need to do it themselves.</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>
|
||||
|
|
@ -0,0 +1,241 @@
|
|||
<!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_POLY1305(3MONOCYPHER)</title>
|
||||
</head>
|
||||
<body>
|
||||
<table class="head">
|
||||
<tr>
|
||||
<td class="head-ltitle">CRYPTO_POLY1305(3MONOCYPHER)</td>
|
||||
<td class="head-vol">3MONOCYPHER</td>
|
||||
<td class="head-rtitle">CRYPTO_POLY1305(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_poly1305</b>,
|
||||
<b class="Nm" title="Nm">crypto_poly1305_init</b>,
|
||||
<b class="Nm" title="Nm">crypto_poly1305_update</b>,
|
||||
<b class="Nm" title="Nm">crypto_poly1305_final</b> —
|
||||
<span class="Nd" title="Nd">Poly1305 one-time message authentication
|
||||
codes</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_poly1305</b>(<var class="Fa" title="Fa">uint8_t
|
||||
mac[16]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>,
|
||||
<var class="Fa" title="Fa">size_t message_size</var>,
|
||||
<var class="Fa" title="Fa">const uint8_t key[32]</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">void</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_poly1305_init</b>(<var class="Fa" title="Fa">crypto_poly1305_ctx
|
||||
*ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">void</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_poly1305_update</b>(<var class="Fa" title="Fa">crypto_poly1305_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_poly1305_final</b>(<var class="Fa" title="Fa">crypto_poly1305_ctx
|
||||
*ctx</var>, <var class="Fa" title="Fa">uint8_t mac[16]</var>);
|
||||
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||
Poly1305 is a one-time message authentication code. “One-time”
|
||||
means the authentication key can be used only once.
|
||||
<b class="Sy" title="Sy">This makes Poly1305 easy to misuse</b>. On the other
|
||||
hand, Poly1305 is fast, and provably secure if used correctly.
|
||||
<div class="Pp"></div>
|
||||
Poly1305 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">mac</var></dt>
|
||||
<dd class="It-tag">The 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">The secret authentication key. Use only once per message.
|
||||
Do not use the session key to authenticate messages. It should be wiped
|
||||
with
|
||||
<a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>
|
||||
after use.</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 authenticate. May overlap with the
|
||||
<var class="Fa" title="Fa">mac</var> argument.</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>
|
||||
<b class="Fn" title="Fn">crypto_poly1305</b>() produces a message authentication
|
||||
code for the given message and authentication key. To verify the integrity of
|
||||
a message, use
|
||||
<a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>
|
||||
to compare the received MAC to the output
|
||||
<var class="Fa" title="Fa">mac</var>.
|
||||
<h2 class="Ss" title="Ss" id="Incremental_interface"><a class="selflink" href="#Incremental_interface">Incremental
|
||||
interface</a></h2>
|
||||
<b class="Fn" title="Fn">crypto_poly1305_init</b>() initialises a context.
|
||||
<var class="Fa" title="Fa">key</var> should be wiped once the context is
|
||||
initialised. Then, <b class="Fn" title="Fn">crypto_poly1305_update</b>()
|
||||
authenticates the message chunk by chunk. Once the message is entirely
|
||||
processed, <b class="Fn" title="Fn">crypto_poly1305_final</b>() yields the
|
||||
message authentication code.
|
||||
<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>
|
||||
To authenticate a message:
|
||||
<div class="Pp"></div>
|
||||
<div class="Bd" style="margin-left: 5.00ex;">
|
||||
<pre class="Li">
|
||||
const uint8_t msg[ 5] = "Lorem"; /* Message to authenticate */
|
||||
uint8_t key[32]; /* Random secret key (use only once) */
|
||||
uint8_t mac[16]; /* Message authentication code (MAC) */
|
||||
arc4random_buf(key, 32);
|
||||
crypto_poly1305(mac, msg, 5, key);
|
||||
/* Wipe the key */
|
||||
crypto_wipe(key, 32);
|
||||
</pre>
|
||||
</div>
|
||||
<div class="Pp"></div>
|
||||
To verify the above message:
|
||||
<div class="Pp"></div>
|
||||
<div class="Bd" style="margin-left: 5.00ex;">
|
||||
<pre class="Li">
|
||||
const uint8_t msg [ 5] = "Lorem"; /* Message to verify */
|
||||
uint8_t key [32]; /* The above key */
|
||||
const uint8_t mac [16]; /* The above MAC */
|
||||
uint8_t real_mac[16]; /* The actual MAC */
|
||||
crypto_poly1305(real_mac, msg, 5, key);
|
||||
/* Wipe the key */
|
||||
crypto_wipe(key, 32);
|
||||
if (crypto_verify16(mac, real_mac)) {
|
||||
/* Corrupted message, abort processing */
|
||||
} else {
|
||||
/* Genuine message */
|
||||
}
|
||||
/* The real mac is secret. Wipe it */
|
||||
crypto_wipe(real_mac, 16);
|
||||
</pre>
|
||||
</div>
|
||||
<div class="Pp"></div>
|
||||
Incremental authentication:
|
||||
<div class="Pp"></div>
|
||||
<div class="Bd" style="margin-left: 5.00ex;">
|
||||
<pre class="Li">
|
||||
const uint8_t msg[500]= {1}; /* Message to authenticate */
|
||||
uint8_t key[ 32]; /* Random secret key (use only once) */
|
||||
uint8_t mac[ 16]; /* Message authentication code (MAC) */
|
||||
crypto_poly1305_ctx ctx;
|
||||
arc4random_buf(key, 32);
|
||||
crypto_poly1305_init(&ctx, key);
|
||||
/* Wipe the key */
|
||||
crypto_wipe(key, 32);
|
||||
for (int i = 0; i < 500; i += 100) {
|
||||
crypto_poly1305_update(&ctx, msg, 100);
|
||||
}
|
||||
crypto_poly1305_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_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_verify16.html">crypto_verify16(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 Poly1305, described in RFC 8439.
|
||||
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
|
||||
The <b class="Fn" title="Fn">crypto_poly1305_init</b>(),
|
||||
<b class="Fn" title="Fn">crypto_poly1305_update</b>(), and
|
||||
<b class="Fn" title="Fn">crypto_poly1305_final</b>() functions first appeared
|
||||
in Monocypher 0.1. <b class="Fn" title="Fn">crypto_poly1305</b>() 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>
|
||||
Poly1305 is difficult to use correctly. Do not use it unless you are absolutely
|
||||
sure what you are doing. Use authenticated encryption instead; see
|
||||
<a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>.
|
||||
If you are certain you do not want encryption, refer to
|
||||
<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>
|
||||
on how to use Blake2b to generate message authentication codes.
|
||||
<h2 class="Ss" title="Ss" id="Authentication_key_requirements"><a class="selflink" href="#Authentication_key_requirements">Authentication
|
||||
key requirements</a></h2>
|
||||
Poly1305 is a <i class="Em" title="Em">one-time</i> authenticator. This puts
|
||||
rather stringent constraints on the authentication key:
|
||||
<ul class="Bl-bullet">
|
||||
<li class="It-bullet">Any given key must be used only once. Using the same key
|
||||
for two different messages reveals it to the attacker. Do not use the
|
||||
session key, or it will void all security.</li>
|
||||
<li class="It-bullet">Authentication keys must be random, and independent from
|
||||
each other. Do not use non-random nonces. Do not use related keys. Use
|
||||
fresh, unpredictable, uniformly distributed random numbers.</li>
|
||||
<li class="It-bullet">The key must be transmitted to the recipient without
|
||||
revealing it to the attacker. Somehow.</li>
|
||||
</ul>
|
||||
<div class="Pp"></div>
|
||||
The only practical source for the authentication key is a chunk of the
|
||||
encryption stream used to encrypt the message. That chunk must be
|
||||
<i class="Em" title="Em">dedicated</i> to the authentication key: if it is
|
||||
reused to encrypt the message itself, the attacker may recover that chunk by
|
||||
guessing the message, then forge arbitrary messages.
|
||||
<div class="Pp"></div>
|
||||
To get this right, you need a session key, a <i class="Em" title="Em">unique</i>
|
||||
nonce, and a stream cipher. Generate a stream with the session key and nonce.
|
||||
Take the first 32 bytes of that stream as your authentication key, then use
|
||||
the <i class="Em" title="Em">rest</i> of the stream to encrypt your message.
|
||||
This is the approach used by
|
||||
<a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(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>
|
||||
Use
|
||||
<a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>
|
||||
to compare message authentication codes. Avoid standard buffer comparison
|
||||
functions. They may not run in constant time, enabling an attacker to exploit
|
||||
timing attacks to recover the MAC.
|
||||
<div class="Pp"></div>
|
||||
The authentication key should be wiped with
|
||||
<a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>
|
||||
after use.
|
||||
<div class="Pp"></div>
|
||||
The incremental interface automatically wipes its context when finished so users
|
||||
do not need to do it themselves.</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>
|
||||
|
|
@ -0,0 +1,241 @@
|
|||
<!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_POLY1305(3MONOCYPHER)</title>
|
||||
</head>
|
||||
<body>
|
||||
<table class="head">
|
||||
<tr>
|
||||
<td class="head-ltitle">CRYPTO_POLY1305(3MONOCYPHER)</td>
|
||||
<td class="head-vol">3MONOCYPHER</td>
|
||||
<td class="head-rtitle">CRYPTO_POLY1305(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_poly1305</b>,
|
||||
<b class="Nm" title="Nm">crypto_poly1305_init</b>,
|
||||
<b class="Nm" title="Nm">crypto_poly1305_update</b>,
|
||||
<b class="Nm" title="Nm">crypto_poly1305_final</b> —
|
||||
<span class="Nd" title="Nd">Poly1305 one-time message authentication
|
||||
codes</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_poly1305</b>(<var class="Fa" title="Fa">uint8_t
|
||||
mac[16]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>,
|
||||
<var class="Fa" title="Fa">size_t message_size</var>,
|
||||
<var class="Fa" title="Fa">const uint8_t key[32]</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">void</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_poly1305_init</b>(<var class="Fa" title="Fa">crypto_poly1305_ctx
|
||||
*ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">void</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_poly1305_update</b>(<var class="Fa" title="Fa">crypto_poly1305_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_poly1305_final</b>(<var class="Fa" title="Fa">crypto_poly1305_ctx
|
||||
*ctx</var>, <var class="Fa" title="Fa">uint8_t mac[16]</var>);
|
||||
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||
Poly1305 is a one-time message authentication code. “One-time”
|
||||
means the authentication key can be used only once.
|
||||
<b class="Sy" title="Sy">This makes Poly1305 easy to misuse</b>. On the other
|
||||
hand, Poly1305 is fast, and provably secure if used correctly.
|
||||
<div class="Pp"></div>
|
||||
Poly1305 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">mac</var></dt>
|
||||
<dd class="It-tag">The 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">The secret authentication key. Use only once per message.
|
||||
Do not use the session key to authenticate messages. It should be wiped
|
||||
with
|
||||
<a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>
|
||||
after use.</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 authenticate. May overlap with the
|
||||
<var class="Fa" title="Fa">mac</var> argument.</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>
|
||||
<b class="Fn" title="Fn">crypto_poly1305</b>() produces a message authentication
|
||||
code for the given message and authentication key. To verify the integrity of
|
||||
a message, use
|
||||
<a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>
|
||||
to compare the received MAC to the output
|
||||
<var class="Fa" title="Fa">mac</var>.
|
||||
<h2 class="Ss" title="Ss" id="Incremental_interface"><a class="selflink" href="#Incremental_interface">Incremental
|
||||
interface</a></h2>
|
||||
<b class="Fn" title="Fn">crypto_poly1305_init</b>() initialises a context.
|
||||
<var class="Fa" title="Fa">key</var> should be wiped once the context is
|
||||
initialised. Then, <b class="Fn" title="Fn">crypto_poly1305_update</b>()
|
||||
authenticates the message chunk by chunk. Once the message is entirely
|
||||
processed, <b class="Fn" title="Fn">crypto_poly1305_final</b>() yields the
|
||||
message authentication code.
|
||||
<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>
|
||||
To authenticate a message:
|
||||
<div class="Pp"></div>
|
||||
<div class="Bd" style="margin-left: 5.00ex;">
|
||||
<pre class="Li">
|
||||
const uint8_t msg[ 5] = "Lorem"; /* Message to authenticate */
|
||||
uint8_t key[32]; /* Random secret key (use only once) */
|
||||
uint8_t mac[16]; /* Message authentication code (MAC) */
|
||||
arc4random_buf(key, 32);
|
||||
crypto_poly1305(mac, msg, 5, key);
|
||||
/* Wipe the key */
|
||||
crypto_wipe(key, 32);
|
||||
</pre>
|
||||
</div>
|
||||
<div class="Pp"></div>
|
||||
To verify the above message:
|
||||
<div class="Pp"></div>
|
||||
<div class="Bd" style="margin-left: 5.00ex;">
|
||||
<pre class="Li">
|
||||
const uint8_t msg [ 5] = "Lorem"; /* Message to verify */
|
||||
uint8_t key [32]; /* The above key */
|
||||
const uint8_t mac [16]; /* The above MAC */
|
||||
uint8_t real_mac[16]; /* The actual MAC */
|
||||
crypto_poly1305(real_mac, msg, 5, key);
|
||||
/* Wipe the key */
|
||||
crypto_wipe(key, 32);
|
||||
if (crypto_verify16(mac, real_mac)) {
|
||||
/* Corrupted message, abort processing */
|
||||
} else {
|
||||
/* Genuine message */
|
||||
}
|
||||
/* The real mac is secret. Wipe it */
|
||||
crypto_wipe(real_mac, 16);
|
||||
</pre>
|
||||
</div>
|
||||
<div class="Pp"></div>
|
||||
Incremental authentication:
|
||||
<div class="Pp"></div>
|
||||
<div class="Bd" style="margin-left: 5.00ex;">
|
||||
<pre class="Li">
|
||||
const uint8_t msg[500]= {1}; /* Message to authenticate */
|
||||
uint8_t key[ 32]; /* Random secret key (use only once) */
|
||||
uint8_t mac[ 16]; /* Message authentication code (MAC) */
|
||||
crypto_poly1305_ctx ctx;
|
||||
arc4random_buf(key, 32);
|
||||
crypto_poly1305_init(&ctx, key);
|
||||
/* Wipe the key */
|
||||
crypto_wipe(key, 32);
|
||||
for (int i = 0; i < 500; i += 100) {
|
||||
crypto_poly1305_update(&ctx, msg, 100);
|
||||
}
|
||||
crypto_poly1305_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_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_verify16.html">crypto_verify16(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 Poly1305, described in RFC 8439.
|
||||
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
|
||||
The <b class="Fn" title="Fn">crypto_poly1305_init</b>(),
|
||||
<b class="Fn" title="Fn">crypto_poly1305_update</b>(), and
|
||||
<b class="Fn" title="Fn">crypto_poly1305_final</b>() functions first appeared
|
||||
in Monocypher 0.1. <b class="Fn" title="Fn">crypto_poly1305</b>() 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>
|
||||
Poly1305 is difficult to use correctly. Do not use it unless you are absolutely
|
||||
sure what you are doing. Use authenticated encryption instead; see
|
||||
<a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>.
|
||||
If you are certain you do not want encryption, refer to
|
||||
<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>
|
||||
on how to use Blake2b to generate message authentication codes.
|
||||
<h2 class="Ss" title="Ss" id="Authentication_key_requirements"><a class="selflink" href="#Authentication_key_requirements">Authentication
|
||||
key requirements</a></h2>
|
||||
Poly1305 is a <i class="Em" title="Em">one-time</i> authenticator. This puts
|
||||
rather stringent constraints on the authentication key:
|
||||
<ul class="Bl-bullet">
|
||||
<li class="It-bullet">Any given key must be used only once. Using the same key
|
||||
for two different messages reveals it to the attacker. Do not use the
|
||||
session key, or it will void all security.</li>
|
||||
<li class="It-bullet">Authentication keys must be random, and independent from
|
||||
each other. Do not use non-random nonces. Do not use related keys. Use
|
||||
fresh, unpredictable, uniformly distributed random numbers.</li>
|
||||
<li class="It-bullet">The key must be transmitted to the recipient without
|
||||
revealing it to the attacker. Somehow.</li>
|
||||
</ul>
|
||||
<div class="Pp"></div>
|
||||
The only practical source for the authentication key is a chunk of the
|
||||
encryption stream used to encrypt the message. That chunk must be
|
||||
<i class="Em" title="Em">dedicated</i> to the authentication key: if it is
|
||||
reused to encrypt the message itself, the attacker may recover that chunk by
|
||||
guessing the message, then forge arbitrary messages.
|
||||
<div class="Pp"></div>
|
||||
To get this right, you need a session key, a <i class="Em" title="Em">unique</i>
|
||||
nonce, and a stream cipher. Generate a stream with the session key and nonce.
|
||||
Take the first 32 bytes of that stream as your authentication key, then use
|
||||
the <i class="Em" title="Em">rest</i> of the stream to encrypt your message.
|
||||
This is the approach used by
|
||||
<a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(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>
|
||||
Use
|
||||
<a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>
|
||||
to compare message authentication codes. Avoid standard buffer comparison
|
||||
functions. They may not run in constant time, enabling an attacker to exploit
|
||||
timing attacks to recover the MAC.
|
||||
<div class="Pp"></div>
|
||||
The authentication key should be wiped with
|
||||
<a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>
|
||||
after use.
|
||||
<div class="Pp"></div>
|
||||
The incremental interface automatically wipes its context when finished so users
|
||||
do not need to do it themselves.</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>
|
||||
|
|
@ -0,0 +1,241 @@
|
|||
<!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_POLY1305(3MONOCYPHER)</title>
|
||||
</head>
|
||||
<body>
|
||||
<table class="head">
|
||||
<tr>
|
||||
<td class="head-ltitle">CRYPTO_POLY1305(3MONOCYPHER)</td>
|
||||
<td class="head-vol">3MONOCYPHER</td>
|
||||
<td class="head-rtitle">CRYPTO_POLY1305(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_poly1305</b>,
|
||||
<b class="Nm" title="Nm">crypto_poly1305_init</b>,
|
||||
<b class="Nm" title="Nm">crypto_poly1305_update</b>,
|
||||
<b class="Nm" title="Nm">crypto_poly1305_final</b> —
|
||||
<span class="Nd" title="Nd">Poly1305 one-time message authentication
|
||||
codes</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_poly1305</b>(<var class="Fa" title="Fa">uint8_t
|
||||
mac[16]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>,
|
||||
<var class="Fa" title="Fa">size_t message_size</var>,
|
||||
<var class="Fa" title="Fa">const uint8_t key[32]</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">void</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_poly1305_init</b>(<var class="Fa" title="Fa">crypto_poly1305_ctx
|
||||
*ctx</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">void</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_poly1305_update</b>(<var class="Fa" title="Fa">crypto_poly1305_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_poly1305_final</b>(<var class="Fa" title="Fa">crypto_poly1305_ctx
|
||||
*ctx</var>, <var class="Fa" title="Fa">uint8_t mac[16]</var>);
|
||||
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||
Poly1305 is a one-time message authentication code. “One-time”
|
||||
means the authentication key can be used only once.
|
||||
<b class="Sy" title="Sy">This makes Poly1305 easy to misuse</b>. On the other
|
||||
hand, Poly1305 is fast, and provably secure if used correctly.
|
||||
<div class="Pp"></div>
|
||||
Poly1305 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">mac</var></dt>
|
||||
<dd class="It-tag">The 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">The secret authentication key. Use only once per message.
|
||||
Do not use the session key to authenticate messages. It should be wiped
|
||||
with
|
||||
<a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>
|
||||
after use.</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 authenticate. May overlap with the
|
||||
<var class="Fa" title="Fa">mac</var> argument.</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>
|
||||
<b class="Fn" title="Fn">crypto_poly1305</b>() produces a message authentication
|
||||
code for the given message and authentication key. To verify the integrity of
|
||||
a message, use
|
||||
<a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>
|
||||
to compare the received MAC to the output
|
||||
<var class="Fa" title="Fa">mac</var>.
|
||||
<h2 class="Ss" title="Ss" id="Incremental_interface"><a class="selflink" href="#Incremental_interface">Incremental
|
||||
interface</a></h2>
|
||||
<b class="Fn" title="Fn">crypto_poly1305_init</b>() initialises a context.
|
||||
<var class="Fa" title="Fa">key</var> should be wiped once the context is
|
||||
initialised. Then, <b class="Fn" title="Fn">crypto_poly1305_update</b>()
|
||||
authenticates the message chunk by chunk. Once the message is entirely
|
||||
processed, <b class="Fn" title="Fn">crypto_poly1305_final</b>() yields the
|
||||
message authentication code.
|
||||
<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>
|
||||
To authenticate a message:
|
||||
<div class="Pp"></div>
|
||||
<div class="Bd" style="margin-left: 5.00ex;">
|
||||
<pre class="Li">
|
||||
const uint8_t msg[ 5] = "Lorem"; /* Message to authenticate */
|
||||
uint8_t key[32]; /* Random secret key (use only once) */
|
||||
uint8_t mac[16]; /* Message authentication code (MAC) */
|
||||
arc4random_buf(key, 32);
|
||||
crypto_poly1305(mac, msg, 5, key);
|
||||
/* Wipe the key */
|
||||
crypto_wipe(key, 32);
|
||||
</pre>
|
||||
</div>
|
||||
<div class="Pp"></div>
|
||||
To verify the above message:
|
||||
<div class="Pp"></div>
|
||||
<div class="Bd" style="margin-left: 5.00ex;">
|
||||
<pre class="Li">
|
||||
const uint8_t msg [ 5] = "Lorem"; /* Message to verify */
|
||||
uint8_t key [32]; /* The above key */
|
||||
const uint8_t mac [16]; /* The above MAC */
|
||||
uint8_t real_mac[16]; /* The actual MAC */
|
||||
crypto_poly1305(real_mac, msg, 5, key);
|
||||
/* Wipe the key */
|
||||
crypto_wipe(key, 32);
|
||||
if (crypto_verify16(mac, real_mac)) {
|
||||
/* Corrupted message, abort processing */
|
||||
} else {
|
||||
/* Genuine message */
|
||||
}
|
||||
/* The real mac is secret. Wipe it */
|
||||
crypto_wipe(real_mac, 16);
|
||||
</pre>
|
||||
</div>
|
||||
<div class="Pp"></div>
|
||||
Incremental authentication:
|
||||
<div class="Pp"></div>
|
||||
<div class="Bd" style="margin-left: 5.00ex;">
|
||||
<pre class="Li">
|
||||
const uint8_t msg[500]= {1}; /* Message to authenticate */
|
||||
uint8_t key[ 32]; /* Random secret key (use only once) */
|
||||
uint8_t mac[ 16]; /* Message authentication code (MAC) */
|
||||
crypto_poly1305_ctx ctx;
|
||||
arc4random_buf(key, 32);
|
||||
crypto_poly1305_init(&ctx, key);
|
||||
/* Wipe the key */
|
||||
crypto_wipe(key, 32);
|
||||
for (int i = 0; i < 500; i += 100) {
|
||||
crypto_poly1305_update(&ctx, msg, 100);
|
||||
}
|
||||
crypto_poly1305_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_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_verify16.html">crypto_verify16(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 Poly1305, described in RFC 8439.
|
||||
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
|
||||
The <b class="Fn" title="Fn">crypto_poly1305_init</b>(),
|
||||
<b class="Fn" title="Fn">crypto_poly1305_update</b>(), and
|
||||
<b class="Fn" title="Fn">crypto_poly1305_final</b>() functions first appeared
|
||||
in Monocypher 0.1. <b class="Fn" title="Fn">crypto_poly1305</b>() 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>
|
||||
Poly1305 is difficult to use correctly. Do not use it unless you are absolutely
|
||||
sure what you are doing. Use authenticated encryption instead; see
|
||||
<a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>.
|
||||
If you are certain you do not want encryption, refer to
|
||||
<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>
|
||||
on how to use Blake2b to generate message authentication codes.
|
||||
<h2 class="Ss" title="Ss" id="Authentication_key_requirements"><a class="selflink" href="#Authentication_key_requirements">Authentication
|
||||
key requirements</a></h2>
|
||||
Poly1305 is a <i class="Em" title="Em">one-time</i> authenticator. This puts
|
||||
rather stringent constraints on the authentication key:
|
||||
<ul class="Bl-bullet">
|
||||
<li class="It-bullet">Any given key must be used only once. Using the same key
|
||||
for two different messages reveals it to the attacker. Do not use the
|
||||
session key, or it will void all security.</li>
|
||||
<li class="It-bullet">Authentication keys must be random, and independent from
|
||||
each other. Do not use non-random nonces. Do not use related keys. Use
|
||||
fresh, unpredictable, uniformly distributed random numbers.</li>
|
||||
<li class="It-bullet">The key must be transmitted to the recipient without
|
||||
revealing it to the attacker. Somehow.</li>
|
||||
</ul>
|
||||
<div class="Pp"></div>
|
||||
The only practical source for the authentication key is a chunk of the
|
||||
encryption stream used to encrypt the message. That chunk must be
|
||||
<i class="Em" title="Em">dedicated</i> to the authentication key: if it is
|
||||
reused to encrypt the message itself, the attacker may recover that chunk by
|
||||
guessing the message, then forge arbitrary messages.
|
||||
<div class="Pp"></div>
|
||||
To get this right, you need a session key, a <i class="Em" title="Em">unique</i>
|
||||
nonce, and a stream cipher. Generate a stream with the session key and nonce.
|
||||
Take the first 32 bytes of that stream as your authentication key, then use
|
||||
the <i class="Em" title="Em">rest</i> of the stream to encrypt your message.
|
||||
This is the approach used by
|
||||
<a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(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>
|
||||
Use
|
||||
<a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>
|
||||
to compare message authentication codes. Avoid standard buffer comparison
|
||||
functions. They may not run in constant time, enabling an attacker to exploit
|
||||
timing attacks to recover the MAC.
|
||||
<div class="Pp"></div>
|
||||
The authentication key should be wiped with
|
||||
<a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>
|
||||
after use.
|
||||
<div class="Pp"></div>
|
||||
The incremental interface automatically wipes its context when finished so users
|
||||
do not need to do it themselves.</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>
|
||||
|
|
@ -0,0 +1,179 @@
|
|||
<!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_SHA512(3MONOCYPHER)</title>
|
||||
</head>
|
||||
<body>
|
||||
<table class="head">
|
||||
<tr>
|
||||
<td class="head-ltitle">CRYPTO_SHA512(3MONOCYPHER)</td>
|
||||
<td class="head-vol">3MONOCYPHER</td>
|
||||
<td class="head-rtitle">CRYPTO_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_sha512</b>,
|
||||
<b class="Nm" title="Nm">crypto_sha512_init</b>,
|
||||
<b class="Nm" title="Nm">crypto_sha512_update</b>,
|
||||
<b class="Nm" title="Nm">crypto_sha512_final</b> —
|
||||
<span class="Nd" title="Nd">cryptographic hashing with the SHA-512
|
||||
algorithm</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_sha512</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_sha512_init</b>(<var class="Fa" title="Fa">crypto_sha512_ctx
|
||||
*ctx</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">void</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_sha512_update</b>(<var class="Fa" title="Fa">crypto_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_sha512_final</b>(<var class="Fa" title="Fa">crypto_sha512_ctx
|
||||
*ctx</var>, <var class="Fa" title="Fa">uint8_t hash[64]</var>);
|
||||
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||
SHA-512 is a cryptographically secure hash, provided to enable compatibility
|
||||
with other cryptographic systems. It is generally recommended to use
|
||||
<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>
|
||||
instead, as it both performs faster on x86_64 CPUs and lacks many of the
|
||||
pitfalls of SHA-512.
|
||||
<div class="Pp"></div>
|
||||
Note that SHA-512 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>
|
||||
SHA-512 is <i class="Em" title="Em">vulnerable to length extension attacks</i>;
|
||||
using it as a message authentication code (MAC) algorithm or keyed hash
|
||||
requires precautions. The
|
||||
<a class="Xr" title="Xr" href="crypto_hmac_sha512.html">crypto_hmac_sha512(3monocypher)</a>
|
||||
family of functions provides HMAC with SHA-512. Use
|
||||
<a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a>
|
||||
to compare MACs created this way.
|
||||
<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, 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">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>
|
||||
<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_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_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_sha512_final</b>(), which produces the
|
||||
final hash. The <var class="Ft" title="Ft">crypto_sha512_ctx</var> is
|
||||
automatically wiped upon finalisation.</li>
|
||||
</ul>
|
||||
<div class="Pp"></div>
|
||||
<b class="Fn" title="Fn">crypto_sha512</b>() is a convenience function that
|
||||
performs <b class="Fn" title="Fn">crypto_sha512_init</b>(),
|
||||
<b class="Fn" title="Fn">crypto_sha512_update</b>(), and
|
||||
<b class="Fn" title="Fn">crypto_sha512_final</b>().
|
||||
<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>
|
||||
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_sha512(hash, message, 12);
|
||||
</pre>
|
||||
</div>
|
||||
<div class="Pp"></div>
|
||||
Hashing a message incrementally:
|
||||
<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_sha512_ctx ctx;
|
||||
crypto_sha512_init(&ctx);
|
||||
for (size_t i = 0; i < 500; i += 100) {
|
||||
crypto_sha512_update(&ctx, message + i, 100);
|
||||
}
|
||||
crypto_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_hmac_sha512.html">crypto_hmac_sha512(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 SHA-512, described in RFC 6234 and the Federal
|
||||
Information Processing Standard (FIPS) 180-4.
|
||||
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
|
||||
The <b class="Fn" title="Fn">crypto_sha512</b>(),
|
||||
<b class="Fn" title="Fn">crypto_sha512_init</b>(),
|
||||
<b class="Fn" title="Fn">crypto_sha512_update</b>(), and
|
||||
<b class="Fn" title="Fn">crypto_sha512_final</b>() functions first appeared in
|
||||
Monocypher 0.3; they were not intended for use outside Monocypher itself and
|
||||
thus undocumented. They became part of the official API in Monocypher 3.0.0.
|
||||
<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY
|
||||
CONSIDERATIONS</a></h1>
|
||||
SHA-512 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">February 5, 2020</td>
|
||||
<td class="foot-os">Linux 4.15.0-106-generic</td>
|
||||
</tr>
|
||||
</table>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,179 @@
|
|||
<!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_SHA512(3MONOCYPHER)</title>
|
||||
</head>
|
||||
<body>
|
||||
<table class="head">
|
||||
<tr>
|
||||
<td class="head-ltitle">CRYPTO_SHA512(3MONOCYPHER)</td>
|
||||
<td class="head-vol">3MONOCYPHER</td>
|
||||
<td class="head-rtitle">CRYPTO_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_sha512</b>,
|
||||
<b class="Nm" title="Nm">crypto_sha512_init</b>,
|
||||
<b class="Nm" title="Nm">crypto_sha512_update</b>,
|
||||
<b class="Nm" title="Nm">crypto_sha512_final</b> —
|
||||
<span class="Nd" title="Nd">cryptographic hashing with the SHA-512
|
||||
algorithm</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_sha512</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_sha512_init</b>(<var class="Fa" title="Fa">crypto_sha512_ctx
|
||||
*ctx</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">void</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_sha512_update</b>(<var class="Fa" title="Fa">crypto_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_sha512_final</b>(<var class="Fa" title="Fa">crypto_sha512_ctx
|
||||
*ctx</var>, <var class="Fa" title="Fa">uint8_t hash[64]</var>);
|
||||
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||
SHA-512 is a cryptographically secure hash, provided to enable compatibility
|
||||
with other cryptographic systems. It is generally recommended to use
|
||||
<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>
|
||||
instead, as it both performs faster on x86_64 CPUs and lacks many of the
|
||||
pitfalls of SHA-512.
|
||||
<div class="Pp"></div>
|
||||
Note that SHA-512 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>
|
||||
SHA-512 is <i class="Em" title="Em">vulnerable to length extension attacks</i>;
|
||||
using it as a message authentication code (MAC) algorithm or keyed hash
|
||||
requires precautions. The
|
||||
<a class="Xr" title="Xr" href="crypto_hmac_sha512.html">crypto_hmac_sha512(3monocypher)</a>
|
||||
family of functions provides HMAC with SHA-512. Use
|
||||
<a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a>
|
||||
to compare MACs created this way.
|
||||
<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, 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">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>
|
||||
<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_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_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_sha512_final</b>(), which produces the
|
||||
final hash. The <var class="Ft" title="Ft">crypto_sha512_ctx</var> is
|
||||
automatically wiped upon finalisation.</li>
|
||||
</ul>
|
||||
<div class="Pp"></div>
|
||||
<b class="Fn" title="Fn">crypto_sha512</b>() is a convenience function that
|
||||
performs <b class="Fn" title="Fn">crypto_sha512_init</b>(),
|
||||
<b class="Fn" title="Fn">crypto_sha512_update</b>(), and
|
||||
<b class="Fn" title="Fn">crypto_sha512_final</b>().
|
||||
<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>
|
||||
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_sha512(hash, message, 12);
|
||||
</pre>
|
||||
</div>
|
||||
<div class="Pp"></div>
|
||||
Hashing a message incrementally:
|
||||
<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_sha512_ctx ctx;
|
||||
crypto_sha512_init(&ctx);
|
||||
for (size_t i = 0; i < 500; i += 100) {
|
||||
crypto_sha512_update(&ctx, message + i, 100);
|
||||
}
|
||||
crypto_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_hmac_sha512.html">crypto_hmac_sha512(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 SHA-512, described in RFC 6234 and the Federal
|
||||
Information Processing Standard (FIPS) 180-4.
|
||||
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
|
||||
The <b class="Fn" title="Fn">crypto_sha512</b>(),
|
||||
<b class="Fn" title="Fn">crypto_sha512_init</b>(),
|
||||
<b class="Fn" title="Fn">crypto_sha512_update</b>(), and
|
||||
<b class="Fn" title="Fn">crypto_sha512_final</b>() functions first appeared in
|
||||
Monocypher 0.3; they were not intended for use outside Monocypher itself and
|
||||
thus undocumented. They became part of the official API in Monocypher 3.0.0.
|
||||
<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY
|
||||
CONSIDERATIONS</a></h1>
|
||||
SHA-512 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">February 5, 2020</td>
|
||||
<td class="foot-os">Linux 4.15.0-106-generic</td>
|
||||
</tr>
|
||||
</table>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,179 @@
|
|||
<!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_SHA512(3MONOCYPHER)</title>
|
||||
</head>
|
||||
<body>
|
||||
<table class="head">
|
||||
<tr>
|
||||
<td class="head-ltitle">CRYPTO_SHA512(3MONOCYPHER)</td>
|
||||
<td class="head-vol">3MONOCYPHER</td>
|
||||
<td class="head-rtitle">CRYPTO_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_sha512</b>,
|
||||
<b class="Nm" title="Nm">crypto_sha512_init</b>,
|
||||
<b class="Nm" title="Nm">crypto_sha512_update</b>,
|
||||
<b class="Nm" title="Nm">crypto_sha512_final</b> —
|
||||
<span class="Nd" title="Nd">cryptographic hashing with the SHA-512
|
||||
algorithm</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_sha512</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_sha512_init</b>(<var class="Fa" title="Fa">crypto_sha512_ctx
|
||||
*ctx</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">void</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_sha512_update</b>(<var class="Fa" title="Fa">crypto_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_sha512_final</b>(<var class="Fa" title="Fa">crypto_sha512_ctx
|
||||
*ctx</var>, <var class="Fa" title="Fa">uint8_t hash[64]</var>);
|
||||
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||
SHA-512 is a cryptographically secure hash, provided to enable compatibility
|
||||
with other cryptographic systems. It is generally recommended to use
|
||||
<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>
|
||||
instead, as it both performs faster on x86_64 CPUs and lacks many of the
|
||||
pitfalls of SHA-512.
|
||||
<div class="Pp"></div>
|
||||
Note that SHA-512 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>
|
||||
SHA-512 is <i class="Em" title="Em">vulnerable to length extension attacks</i>;
|
||||
using it as a message authentication code (MAC) algorithm or keyed hash
|
||||
requires precautions. The
|
||||
<a class="Xr" title="Xr" href="crypto_hmac_sha512.html">crypto_hmac_sha512(3monocypher)</a>
|
||||
family of functions provides HMAC with SHA-512. Use
|
||||
<a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a>
|
||||
to compare MACs created this way.
|
||||
<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, 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">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>
|
||||
<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_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_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_sha512_final</b>(), which produces the
|
||||
final hash. The <var class="Ft" title="Ft">crypto_sha512_ctx</var> is
|
||||
automatically wiped upon finalisation.</li>
|
||||
</ul>
|
||||
<div class="Pp"></div>
|
||||
<b class="Fn" title="Fn">crypto_sha512</b>() is a convenience function that
|
||||
performs <b class="Fn" title="Fn">crypto_sha512_init</b>(),
|
||||
<b class="Fn" title="Fn">crypto_sha512_update</b>(), and
|
||||
<b class="Fn" title="Fn">crypto_sha512_final</b>().
|
||||
<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>
|
||||
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_sha512(hash, message, 12);
|
||||
</pre>
|
||||
</div>
|
||||
<div class="Pp"></div>
|
||||
Hashing a message incrementally:
|
||||
<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_sha512_ctx ctx;
|
||||
crypto_sha512_init(&ctx);
|
||||
for (size_t i = 0; i < 500; i += 100) {
|
||||
crypto_sha512_update(&ctx, message + i, 100);
|
||||
}
|
||||
crypto_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_hmac_sha512.html">crypto_hmac_sha512(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 SHA-512, described in RFC 6234 and the Federal
|
||||
Information Processing Standard (FIPS) 180-4.
|
||||
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
|
||||
The <b class="Fn" title="Fn">crypto_sha512</b>(),
|
||||
<b class="Fn" title="Fn">crypto_sha512_init</b>(),
|
||||
<b class="Fn" title="Fn">crypto_sha512_update</b>(), and
|
||||
<b class="Fn" title="Fn">crypto_sha512_final</b>() functions first appeared in
|
||||
Monocypher 0.3; they were not intended for use outside Monocypher itself and
|
||||
thus undocumented. They became part of the official API in Monocypher 3.0.0.
|
||||
<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY
|
||||
CONSIDERATIONS</a></h1>
|
||||
SHA-512 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">February 5, 2020</td>
|
||||
<td class="foot-os">Linux 4.15.0-106-generic</td>
|
||||
</tr>
|
||||
</table>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,179 @@
|
|||
<!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_SHA512(3MONOCYPHER)</title>
|
||||
</head>
|
||||
<body>
|
||||
<table class="head">
|
||||
<tr>
|
||||
<td class="head-ltitle">CRYPTO_SHA512(3MONOCYPHER)</td>
|
||||
<td class="head-vol">3MONOCYPHER</td>
|
||||
<td class="head-rtitle">CRYPTO_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_sha512</b>,
|
||||
<b class="Nm" title="Nm">crypto_sha512_init</b>,
|
||||
<b class="Nm" title="Nm">crypto_sha512_update</b>,
|
||||
<b class="Nm" title="Nm">crypto_sha512_final</b> —
|
||||
<span class="Nd" title="Nd">cryptographic hashing with the SHA-512
|
||||
algorithm</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_sha512</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_sha512_init</b>(<var class="Fa" title="Fa">crypto_sha512_ctx
|
||||
*ctx</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">void</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_sha512_update</b>(<var class="Fa" title="Fa">crypto_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_sha512_final</b>(<var class="Fa" title="Fa">crypto_sha512_ctx
|
||||
*ctx</var>, <var class="Fa" title="Fa">uint8_t hash[64]</var>);
|
||||
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||
SHA-512 is a cryptographically secure hash, provided to enable compatibility
|
||||
with other cryptographic systems. It is generally recommended to use
|
||||
<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>
|
||||
instead, as it both performs faster on x86_64 CPUs and lacks many of the
|
||||
pitfalls of SHA-512.
|
||||
<div class="Pp"></div>
|
||||
Note that SHA-512 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>
|
||||
SHA-512 is <i class="Em" title="Em">vulnerable to length extension attacks</i>;
|
||||
using it as a message authentication code (MAC) algorithm or keyed hash
|
||||
requires precautions. The
|
||||
<a class="Xr" title="Xr" href="crypto_hmac_sha512.html">crypto_hmac_sha512(3monocypher)</a>
|
||||
family of functions provides HMAC with SHA-512. Use
|
||||
<a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a>
|
||||
to compare MACs created this way.
|
||||
<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, 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">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>
|
||||
<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_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_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_sha512_final</b>(), which produces the
|
||||
final hash. The <var class="Ft" title="Ft">crypto_sha512_ctx</var> is
|
||||
automatically wiped upon finalisation.</li>
|
||||
</ul>
|
||||
<div class="Pp"></div>
|
||||
<b class="Fn" title="Fn">crypto_sha512</b>() is a convenience function that
|
||||
performs <b class="Fn" title="Fn">crypto_sha512_init</b>(),
|
||||
<b class="Fn" title="Fn">crypto_sha512_update</b>(), and
|
||||
<b class="Fn" title="Fn">crypto_sha512_final</b>().
|
||||
<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>
|
||||
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_sha512(hash, message, 12);
|
||||
</pre>
|
||||
</div>
|
||||
<div class="Pp"></div>
|
||||
Hashing a message incrementally:
|
||||
<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_sha512_ctx ctx;
|
||||
crypto_sha512_init(&ctx);
|
||||
for (size_t i = 0; i < 500; i += 100) {
|
||||
crypto_sha512_update(&ctx, message + i, 100);
|
||||
}
|
||||
crypto_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_hmac_sha512.html">crypto_hmac_sha512(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 SHA-512, described in RFC 6234 and the Federal
|
||||
Information Processing Standard (FIPS) 180-4.
|
||||
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
|
||||
The <b class="Fn" title="Fn">crypto_sha512</b>(),
|
||||
<b class="Fn" title="Fn">crypto_sha512_init</b>(),
|
||||
<b class="Fn" title="Fn">crypto_sha512_update</b>(), and
|
||||
<b class="Fn" title="Fn">crypto_sha512_final</b>() functions first appeared in
|
||||
Monocypher 0.3; they were not intended for use outside Monocypher itself and
|
||||
thus undocumented. They became part of the official API in Monocypher 3.0.0.
|
||||
<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY
|
||||
CONSIDERATIONS</a></h1>
|
||||
SHA-512 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">February 5, 2020</td>
|
||||
<td class="foot-os">Linux 4.15.0-106-generic</td>
|
||||
</tr>
|
||||
</table>
|
||||
</body>
|
||||
</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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -0,0 +1,92 @@
|
|||
<!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_VERIFY16(3MONOCYPHER)</title>
|
||||
</head>
|
||||
<body>
|
||||
<table class="head">
|
||||
<tr>
|
||||
<td class="head-ltitle">CRYPTO_VERIFY16(3MONOCYPHER)</td>
|
||||
<td class="head-vol">3MONOCYPHER</td>
|
||||
<td class="head-rtitle">CRYPTO_VERIFY16(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_verify16</b>,
|
||||
<b class="Nm" title="Nm">crypto_verify32</b>,
|
||||
<b class="Nm" title="Nm">crypto_verify64</b> —
|
||||
<span class="Nd" title="Nd">timing-safe data comparison</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_verify16</b>(<var class="Fa" title="Fa">const
|
||||
uint8_t a[16]</var>, <var class="Fa" title="Fa">const uint8_t b[16]</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">int</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_verify32</b>(<var class="Fa" title="Fa">const
|
||||
uint8_t a[32]</var>, <var class="Fa" title="Fa">const uint8_t b[32]</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">int</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_verify64</b>(<var class="Fa" title="Fa">const
|
||||
uint8_t a[64]</var>, <var class="Fa" title="Fa">const uint8_t b[64]</var>);
|
||||
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||
Cryptographic operations often require comparison of secrets or values derived
|
||||
from secrets. Standard comparison functions like
|
||||
<b class="Fn" title="Fn">memcmp</b>() tend to exit when they find the first
|
||||
difference, leaking information through timing differences.
|
||||
<div class="Pp"></div>
|
||||
As an example, say a message authentication code (MAC) is sent over the network
|
||||
along with a message, but the correct MAC is secret. If the attacker attempts
|
||||
a forgery, one does not want to reveal “your MAC is wrong,
|
||||
<i class="Em" title="Em">and it took 384 microseconds to tell</i>”. If
|
||||
the next attempt takes 462 microseconds instead, it tells the attacker they
|
||||
just guessed a byte correctly. That way, an attacker can derive the correct
|
||||
MAC byte by byte, and successfully forge a message. This has lead to practical
|
||||
attacks in the past.
|
||||
<div class="Pp"></div>
|
||||
To avoid such catastrophic failure,
|
||||
<b class="Fn" title="Fn">crypto_verify16</b>(),
|
||||
<b class="Fn" title="Fn">crypto_verify32</b>() and
|
||||
<b class="Fn" title="Fn">crypto_verify64</b>() provide comparison functions
|
||||
whose timing is independent from the content of their input. They compare the
|
||||
first 16, 32, or 64 bytes of the two byte arrays
|
||||
<var class="Fa" title="Fa">a</var> and <var class="Fa" title="Fa">b</var>.
|
||||
<div class="Pp"></div>
|
||||
When in doubt, prefer these functions over
|
||||
<b class="Fn" title="Fn">memcmp</b>().
|
||||
<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN
|
||||
VALUES</a></h1>
|
||||
These functions return 0 if the two memory chunks are the same, -1 otherwise.
|
||||
<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE
|
||||
ALSO</a></h1>
|
||||
<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_verify16</b>(),
|
||||
<b class="Fn" title="Fn">crypto_verify32</b>(),
|
||||
<b class="Fn" title="Fn">crypto_verify64</b>() functions first appeared in
|
||||
Monocypher 1.1.0. They replaced the
|
||||
<b class="Fn" title="Fn">crypto_memcmp</b>() and
|
||||
<b class="Fn" title="Fn">crypto_zerocmp</b>() functions that were present
|
||||
until Monocypher 1.0.1.</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>
|
||||
|
|
@ -0,0 +1,92 @@
|
|||
<!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_VERIFY16(3MONOCYPHER)</title>
|
||||
</head>
|
||||
<body>
|
||||
<table class="head">
|
||||
<tr>
|
||||
<td class="head-ltitle">CRYPTO_VERIFY16(3MONOCYPHER)</td>
|
||||
<td class="head-vol">3MONOCYPHER</td>
|
||||
<td class="head-rtitle">CRYPTO_VERIFY16(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_verify16</b>,
|
||||
<b class="Nm" title="Nm">crypto_verify32</b>,
|
||||
<b class="Nm" title="Nm">crypto_verify64</b> —
|
||||
<span class="Nd" title="Nd">timing-safe data comparison</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_verify16</b>(<var class="Fa" title="Fa">const
|
||||
uint8_t a[16]</var>, <var class="Fa" title="Fa">const uint8_t b[16]</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">int</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_verify32</b>(<var class="Fa" title="Fa">const
|
||||
uint8_t a[32]</var>, <var class="Fa" title="Fa">const uint8_t b[32]</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">int</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_verify64</b>(<var class="Fa" title="Fa">const
|
||||
uint8_t a[64]</var>, <var class="Fa" title="Fa">const uint8_t b[64]</var>);
|
||||
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||
Cryptographic operations often require comparison of secrets or values derived
|
||||
from secrets. Standard comparison functions like
|
||||
<b class="Fn" title="Fn">memcmp</b>() tend to exit when they find the first
|
||||
difference, leaking information through timing differences.
|
||||
<div class="Pp"></div>
|
||||
As an example, say a message authentication code (MAC) is sent over the network
|
||||
along with a message, but the correct MAC is secret. If the attacker attempts
|
||||
a forgery, one does not want to reveal “your MAC is wrong,
|
||||
<i class="Em" title="Em">and it took 384 microseconds to tell</i>”. If
|
||||
the next attempt takes 462 microseconds instead, it tells the attacker they
|
||||
just guessed a byte correctly. That way, an attacker can derive the correct
|
||||
MAC byte by byte, and successfully forge a message. This has lead to practical
|
||||
attacks in the past.
|
||||
<div class="Pp"></div>
|
||||
To avoid such catastrophic failure,
|
||||
<b class="Fn" title="Fn">crypto_verify16</b>(),
|
||||
<b class="Fn" title="Fn">crypto_verify32</b>() and
|
||||
<b class="Fn" title="Fn">crypto_verify64</b>() provide comparison functions
|
||||
whose timing is independent from the content of their input. They compare the
|
||||
first 16, 32, or 64 bytes of the two byte arrays
|
||||
<var class="Fa" title="Fa">a</var> and <var class="Fa" title="Fa">b</var>.
|
||||
<div class="Pp"></div>
|
||||
When in doubt, prefer these functions over
|
||||
<b class="Fn" title="Fn">memcmp</b>().
|
||||
<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN
|
||||
VALUES</a></h1>
|
||||
These functions return 0 if the two memory chunks are the same, -1 otherwise.
|
||||
<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE
|
||||
ALSO</a></h1>
|
||||
<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_verify16</b>(),
|
||||
<b class="Fn" title="Fn">crypto_verify32</b>(),
|
||||
<b class="Fn" title="Fn">crypto_verify64</b>() functions first appeared in
|
||||
Monocypher 1.1.0. They replaced the
|
||||
<b class="Fn" title="Fn">crypto_memcmp</b>() and
|
||||
<b class="Fn" title="Fn">crypto_zerocmp</b>() functions that were present
|
||||
until Monocypher 1.0.1.</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>
|
||||
|
|
@ -0,0 +1,92 @@
|
|||
<!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_VERIFY16(3MONOCYPHER)</title>
|
||||
</head>
|
||||
<body>
|
||||
<table class="head">
|
||||
<tr>
|
||||
<td class="head-ltitle">CRYPTO_VERIFY16(3MONOCYPHER)</td>
|
||||
<td class="head-vol">3MONOCYPHER</td>
|
||||
<td class="head-rtitle">CRYPTO_VERIFY16(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_verify16</b>,
|
||||
<b class="Nm" title="Nm">crypto_verify32</b>,
|
||||
<b class="Nm" title="Nm">crypto_verify64</b> —
|
||||
<span class="Nd" title="Nd">timing-safe data comparison</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_verify16</b>(<var class="Fa" title="Fa">const
|
||||
uint8_t a[16]</var>, <var class="Fa" title="Fa">const uint8_t b[16]</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">int</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_verify32</b>(<var class="Fa" title="Fa">const
|
||||
uint8_t a[32]</var>, <var class="Fa" title="Fa">const uint8_t b[32]</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">int</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_verify64</b>(<var class="Fa" title="Fa">const
|
||||
uint8_t a[64]</var>, <var class="Fa" title="Fa">const uint8_t b[64]</var>);
|
||||
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||
Cryptographic operations often require comparison of secrets or values derived
|
||||
from secrets. Standard comparison functions like
|
||||
<b class="Fn" title="Fn">memcmp</b>() tend to exit when they find the first
|
||||
difference, leaking information through timing differences.
|
||||
<div class="Pp"></div>
|
||||
As an example, say a message authentication code (MAC) is sent over the network
|
||||
along with a message, but the correct MAC is secret. If the attacker attempts
|
||||
a forgery, one does not want to reveal “your MAC is wrong,
|
||||
<i class="Em" title="Em">and it took 384 microseconds to tell</i>”. If
|
||||
the next attempt takes 462 microseconds instead, it tells the attacker they
|
||||
just guessed a byte correctly. That way, an attacker can derive the correct
|
||||
MAC byte by byte, and successfully forge a message. This has lead to practical
|
||||
attacks in the past.
|
||||
<div class="Pp"></div>
|
||||
To avoid such catastrophic failure,
|
||||
<b class="Fn" title="Fn">crypto_verify16</b>(),
|
||||
<b class="Fn" title="Fn">crypto_verify32</b>() and
|
||||
<b class="Fn" title="Fn">crypto_verify64</b>() provide comparison functions
|
||||
whose timing is independent from the content of their input. They compare the
|
||||
first 16, 32, or 64 bytes of the two byte arrays
|
||||
<var class="Fa" title="Fa">a</var> and <var class="Fa" title="Fa">b</var>.
|
||||
<div class="Pp"></div>
|
||||
When in doubt, prefer these functions over
|
||||
<b class="Fn" title="Fn">memcmp</b>().
|
||||
<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN
|
||||
VALUES</a></h1>
|
||||
These functions return 0 if the two memory chunks are the same, -1 otherwise.
|
||||
<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE
|
||||
ALSO</a></h1>
|
||||
<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_verify16</b>(),
|
||||
<b class="Fn" title="Fn">crypto_verify32</b>(),
|
||||
<b class="Fn" title="Fn">crypto_verify64</b>() functions first appeared in
|
||||
Monocypher 1.1.0. They replaced the
|
||||
<b class="Fn" title="Fn">crypto_memcmp</b>() and
|
||||
<b class="Fn" title="Fn">crypto_zerocmp</b>() functions that were present
|
||||
until Monocypher 1.0.1.</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>
|
||||
|
|
@ -0,0 +1,86 @@
|
|||
<!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_WIPE(3MONOCYPHER)</title>
|
||||
</head>
|
||||
<body>
|
||||
<table class="head">
|
||||
<tr>
|
||||
<td class="head-ltitle">CRYPTO_WIPE(3MONOCYPHER)</td>
|
||||
<td class="head-vol">3MONOCYPHER</td>
|
||||
<td class="head-rtitle">CRYPTO_WIPE(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_wipe</b> —
|
||||
<span class="Nd" title="Nd">wipe data from memory</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_wipe</b>(<var class="Fa" title="Fa">void
|
||||
*secret</var>, <var class="Fa" title="Fa">size_t secret_size</var>);
|
||||
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||
<b class="Fn" title="Fn">crypto_wipe</b>() securely erases sensitive data in
|
||||
memory.
|
||||
<div class="Pp"></div>
|
||||
Sensitive data (such as cryptographic keys or secret plaintexts) should be
|
||||
erased from memory as early as possible, to minimise the window in which it
|
||||
can be leaked. Standard functions like memset and bzero are not safe to use,
|
||||
as the compiler may decide they have no effect and optimise them out.
|
||||
<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">secret</var></dt>
|
||||
<dd class="It-tag">The buffer to erase.</dd>
|
||||
<dt class="It-tag"> </dt>
|
||||
<dd class="It-tag"> </dd>
|
||||
<dt class="It-tag"><var class="Fa" title="Fa">secret_size</var></dt>
|
||||
<dd class="It-tag">The number of bytes to erase from the buffer. Normally this
|
||||
is the size of the entire buffer.</dd>
|
||||
</dl>
|
||||
<div class="Pp"></div>
|
||||
Monocypher will wipe its context structs when finalizing an operation such as
|
||||
signing or decrypting. When using direct interfaces like
|
||||
<a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>,
|
||||
these context structs are invisible to you. They are exposed in incremental
|
||||
interfaces like
|
||||
<a class="Xr" title="Xr" href="crypto_blake2b_init.html">crypto_blake2b_init(3monocypher)</a>.
|
||||
The original key buffer does not get automatically wiped. When using
|
||||
incremental interfaces, you may want to wipe the original key buffers
|
||||
immediately after calling the respective init function.
|
||||
<div class="Pp"></div>
|
||||
Using <b class="Fn" title="Fn">crypto_wipe</b>() alone may not suffice for
|
||||
security. It is recommended to lock down relevant memory regions as well.
|
||||
Refer to <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for
|
||||
instructions on how to lock down memory on common operating systems.
|
||||
<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="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE
|
||||
ALSO</a></h1>
|
||||
<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_wipe</b>() function first appeared in
|
||||
Monocypher 1.1.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>
|
||||
|
|
@ -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_X25519(3MONOCYPHER)</title>
|
||||
</head>
|
||||
<body>
|
||||
<table class="head">
|
||||
<tr>
|
||||
<td class="head-ltitle">CRYPTO_X25519(3MONOCYPHER)</td>
|
||||
<td class="head-vol">3MONOCYPHER</td>
|
||||
<td class="head-rtitle">CRYPTO_X25519(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_x25519</b>,
|
||||
<b class="Nm" title="Nm">crypto_x25519_public_key</b> —
|
||||
<span class="Nd" title="Nd">X25519 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_x25519</b>(<var class="Fa" title="Fa">uint8_t
|
||||
raw_shared_secret[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_x25519_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_x25519</b>() computes a shared secret with
|
||||
<var class="Fa" title="Fa">your_secret_key</var> and
|
||||
<var class="Fa" title="Fa">their_public_key</var>. It is a low-level
|
||||
primitive. Use
|
||||
<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>
|
||||
unless you have a specific reason not to.
|
||||
<div class="Pp"></div>
|
||||
<b class="Fn" title="Fn">crypto_x25519_public_key</b>() is the same as
|
||||
<a class="Xr" title="Xr" href="crypto_key_exchange_public_key.html">crypto_key_exchange_public_key(3monocypher)</a>.
|
||||
It 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">raw_shared_secret</var></dt>
|
||||
<dd class="It-tag">The shared secret, known only to those who know a relevant
|
||||
secret key (yours or theirs). It is not cryptographically random. Do not
|
||||
use it directly as a key. Hash it with
|
||||
<a class="Xr" title="Xr" href="crypto_chacha20_H.html">crypto_chacha20_H(3monocypher)</a>
|
||||
or
|
||||
<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>
|
||||
first.</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 secret random number. 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.
|
||||
<div class="Pp"></div>
|
||||
<var class="Fa" title="Fa">raw_shared_secret</var> and
|
||||
<var class="Fa" title="Fa">your_secret_key</var> may overlap if your
|
||||
secret is no longer required.</dd>
|
||||
</dl>
|
||||
<div class="Pp"></div>
|
||||
Some protocols, such as some password-authenticated key exchange (PAKE)
|
||||
protocols and oblivious pseudo-random functions (OPRF), may require
|
||||
“contributory” behaviour, which ensures that no untrusted party
|
||||
forces the shared secret to a known constant. If a protocol requires
|
||||
contributory behaviour, compare the output of
|
||||
<b class="Fn" title="Fn">crypto_x25519</b>() to an all-zero buffer using
|
||||
<a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a>;
|
||||
abort the protocol if the output and the all-zero buffer are equal.
|
||||
<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_x25519</b>() and
|
||||
<b class="Fn" title="Fn">crypto_x25519_public_key</b>() 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>
|
||||
Generate a pair of shared keys with your secret key and their public key. (This
|
||||
can help nonce management for full duplex communications.)
|
||||
<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_secret[32]; /* Shared secret (NOT a key) */
|
||||
arc4random_buf(your_sk, 32);
|
||||
crypto_x25519(shared_secret, your_sk, their_pk);
|
||||
/* Wipe secrets if they are no longer needed */
|
||||
crypto_wipe(your_sk, 32);
|
||||
|
||||
uint8_t shared_keys[64]; /* Two shared session keys */
|
||||
crypto_blake2b(shared_keys, shared_secret, 32);
|
||||
const uint8_t *key_1 = shared_keys; /* Shared key 1 */
|
||||
const uint8_t *key_2 = shared_keys + 32; /* Shared key 2 */
|
||||
/* Wipe secrets if they are no longer needed */
|
||||
crypto_wipe(shared_secret, 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="intro.html">intro(3monocypher)</a>
|
||||
<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1>
|
||||
This function implements X25519, described in RFC 7748.
|
||||
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
|
||||
The <b class="Fn" title="Fn">crypto_x25519</b>(), and
|
||||
<b class="Fn" title="Fn">crypto_x25519_public_key</b>() functions first
|
||||
appeared in Monocypher 0.1.
|
||||
<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>
|
||||
The most significant bit of the public key is systematically ignored. It is not
|
||||
needed because every public key should be smaller than 2^255-19, which fits in
|
||||
255 bits. If another implementation of X25519 gives you a key that is not
|
||||
fully reduced and has its high bit set, the computation will fail. On the
|
||||
other hand, it also means you may use this bit for other purposes (such as
|
||||
parity flipping for Ed25519 compatibility).</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>
|
||||
|
|
@ -0,0 +1,102 @@
|
|||
<!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_X25519_DIRTY_FAST(3monocypher)</title>
|
||||
</head>
|
||||
<body>
|
||||
<table class="head">
|
||||
<tr>
|
||||
<td class="head-ltitle">CRYPTO_X25519_DIRTY_FAST(3monocypher)</td>
|
||||
<td class="head-vol">3monocypher</td>
|
||||
<td class="head-rtitle">CRYPTO_X25519_DIRTY_FAST(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_x25519_dirty_fast</b>,
|
||||
<b class="Nm" title="Nm">crypto_x25519_dirty_small</b> —
|
||||
<span class="Nd" title="Nd">generation of Curve25519 points with a low-order
|
||||
component</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_x25519_dirty_fast</b>(<var class="Fa" title="Fa">uint8_t
|
||||
pk[32]</var>, <var class="Fa" title="Fa">const uint8_t sk[32]</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">void</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_x25519_dirty_small</b>(<var class="Fa" title="Fa">uint8_t
|
||||
pk[32]</var>, <var class="Fa" title="Fa">const uint8_t sk[32]</var>);
|
||||
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||
These functions are used in public key generation for
|
||||
<a class="Xr" title="Xr" href="crypto_curve_to_hidden.html">crypto_curve_to_hidden(3monocypher)</a>.
|
||||
<b class="Sy" title="Sy">This is a highly advanced feature</b>; unless you are
|
||||
reading this because you were referred here from
|
||||
<a class="Xr" title="Xr" href="crypto_curve_to_hidden.html">crypto_curve_to_hidden(3monocypher)</a>,
|
||||
<b class="Sy" title="Sy">you likely have no reason to be using these
|
||||
functions</b> and are probably looking for
|
||||
<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>
|
||||
or
|
||||
<a class="Xr" title="Xr" href="crypto_x25519.html">crypto_x25519(3monocypher)</a>
|
||||
instead. Expect elliptic curve jargon on this page.
|
||||
<div class="Pp"></div>
|
||||
Both functions generate a Curve25519 public key
|
||||
<var class="Fa" title="Fa">pk</var> from the given secret key
|
||||
<var class="Fa" title="Fa">sk</var>; the public keys are on the
|
||||
<i class="Em" title="Em">whole</i> curve, rather than just the main
|
||||
prime-order subgroup. Both do the same with different code size and memory
|
||||
characteristics: <b class="Fn" title="Fn">crypto_x25519_dirty_fast</b>() uses
|
||||
multiple large temporary variables and uses functions that are normally used
|
||||
internally for
|
||||
<a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>;
|
||||
accordingly, it uses both more memory (for the temporary variables) and more
|
||||
code size (unless the signing code is already compiled in elsewhere).
|
||||
<b class="Fn" title="Fn">crypto_x25519_dirty_small</b>() yields the same
|
||||
result, but does so using less code and memory at a large performance penalty
|
||||
compared to <b class="Fn" title="Fn">crypto_x25519_dirty_fast</b>().
|
||||
<div class="Pp"></div>
|
||||
The resulting public keys are to be used with
|
||||
<a class="Xr" title="Xr" href="crypto_x25519.html">crypto_x25519(3monocypher)</a>
|
||||
or
|
||||
<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>,
|
||||
which clear the cofactor.
|
||||
<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN
|
||||
VALUES</a></h1>
|
||||
These functions have no return value. 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_curve_to_hidden.html">crypto_curve_to_hidden(3monocypher)</a>,
|
||||
<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_x25519_public_key.html">crypto_x25519_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_x25519_dirty_fast</b>() and
|
||||
<b class="Fn" title="Fn">crypto_x25519_dirty_small</b>() functions first
|
||||
appeared in Monocypher 3.1.0.
|
||||
<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION
|
||||
DETAILS</a></h1>
|
||||
The slow variant is approximately an entire two times slower than the fast
|
||||
variant. When considering that, on average, two calls to this function will be
|
||||
required for obtaining a valid key pair for
|
||||
<a class="Xr" title="Xr" href="crypto_curve_to_hidden.html">crypto_curve_to_hidden(3monocypher)</a>,
|
||||
this adds up to an <i class="Em" title="Em">average</i> effective slowdown for
|
||||
key pair generation of a factor of four.</div>
|
||||
<table class="foot">
|
||||
<tr>
|
||||
<td class="foot-date">March 24, 2020</td>
|
||||
<td class="foot-os">Linux 4.15.0-106-generic</td>
|
||||
</tr>
|
||||
</table>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,102 @@
|
|||
<!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_X25519_DIRTY_FAST(3monocypher)</title>
|
||||
</head>
|
||||
<body>
|
||||
<table class="head">
|
||||
<tr>
|
||||
<td class="head-ltitle">CRYPTO_X25519_DIRTY_FAST(3monocypher)</td>
|
||||
<td class="head-vol">3monocypher</td>
|
||||
<td class="head-rtitle">CRYPTO_X25519_DIRTY_FAST(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_x25519_dirty_fast</b>,
|
||||
<b class="Nm" title="Nm">crypto_x25519_dirty_small</b> —
|
||||
<span class="Nd" title="Nd">generation of Curve25519 points with a low-order
|
||||
component</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_x25519_dirty_fast</b>(<var class="Fa" title="Fa">uint8_t
|
||||
pk[32]</var>, <var class="Fa" title="Fa">const uint8_t sk[32]</var>);
|
||||
<div class="Pp"></div>
|
||||
<var class="Ft" title="Ft">void</var>
|
||||
<br/>
|
||||
<b class="Fn" title="Fn">crypto_x25519_dirty_small</b>(<var class="Fa" title="Fa">uint8_t
|
||||
pk[32]</var>, <var class="Fa" title="Fa">const uint8_t sk[32]</var>);
|
||||
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||||
These functions are used in public key generation for
|
||||
<a class="Xr" title="Xr" href="crypto_curve_to_hidden.html">crypto_curve_to_hidden(3monocypher)</a>.
|
||||
<b class="Sy" title="Sy">This is a highly advanced feature</b>; unless you are
|
||||
reading this because you were referred here from
|
||||
<a class="Xr" title="Xr" href="crypto_curve_to_hidden.html">crypto_curve_to_hidden(3monocypher)</a>,
|
||||
<b class="Sy" title="Sy">you likely have no reason to be using these
|
||||
functions</b> and are probably looking for
|
||||
<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>
|
||||
or
|
||||
<a class="Xr" title="Xr" href="crypto_x25519.html">crypto_x25519(3monocypher)</a>
|
||||
instead. Expect elliptic curve jargon on this page.
|
||||
<div class="Pp"></div>
|
||||
Both functions generate a Curve25519 public key
|
||||
<var class="Fa" title="Fa">pk</var> from the given secret key
|
||||
<var class="Fa" title="Fa">sk</var>; the public keys are on the
|
||||
<i class="Em" title="Em">whole</i> curve, rather than just the main
|
||||
prime-order subgroup. Both do the same with different code size and memory
|
||||
characteristics: <b class="Fn" title="Fn">crypto_x25519_dirty_fast</b>() uses
|
||||
multiple large temporary variables and uses functions that are normally used
|
||||
internally for
|
||||
<a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>;
|
||||
accordingly, it uses both more memory (for the temporary variables) and more
|
||||
code size (unless the signing code is already compiled in elsewhere).
|
||||
<b class="Fn" title="Fn">crypto_x25519_dirty_small</b>() yields the same
|
||||
result, but does so using less code and memory at a large performance penalty
|
||||
compared to <b class="Fn" title="Fn">crypto_x25519_dirty_fast</b>().
|
||||
<div class="Pp"></div>
|
||||
The resulting public keys are to be used with
|
||||
<a class="Xr" title="Xr" href="crypto_x25519.html">crypto_x25519(3monocypher)</a>
|
||||
or
|
||||
<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>,
|
||||
which clear the cofactor.
|
||||
<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN
|
||||
VALUES</a></h1>
|
||||
These functions have no return value. 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_curve_to_hidden.html">crypto_curve_to_hidden(3monocypher)</a>,
|
||||
<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_x25519_public_key.html">crypto_x25519_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_x25519_dirty_fast</b>() and
|
||||
<b class="Fn" title="Fn">crypto_x25519_dirty_small</b>() functions first
|
||||
appeared in Monocypher 3.1.0.
|
||||
<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION
|
||||
DETAILS</a></h1>
|
||||
The slow variant is approximately an entire two times slower than the fast
|
||||
variant. When considering that, on average, two calls to this function will be
|
||||
required for obtaining a valid key pair for
|
||||
<a class="Xr" title="Xr" href="crypto_curve_to_hidden.html">crypto_curve_to_hidden(3monocypher)</a>,
|
||||
this adds up to an <i class="Em" title="Em">average</i> effective slowdown for
|
||||
key pair generation of a factor of four.</div>
|
||||
<table class="foot">
|
||||
<tr>
|
||||
<td class="foot-date">March 24, 2020</td>
|
||||
<td class="foot-os">Linux 4.15.0-106-generic</td>
|
||||
</tr>
|
||||
</table>
|
||||
</body>
|
||||
</html>
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue