From: Loup Vaillant Date: Sat, 27 Jan 2018 18:54:44 +0000 (+0100) Subject: Documented aliases X-Git-Url: https://git.codecow.com/?a=commitdiff_plain;h=9d5bc4317325645f8fc49735c574063c3c3facdc;p=Monocypher.git Documented aliases Related to #80 --- diff --git a/doc/man/man3/crypto_key_exchange.3monocypher b/doc/man/man3/crypto_key_exchange.3monocypher index a35bf8f..734d9d2 100644 --- a/doc/man/man3/crypto_key_exchange.3monocypher +++ b/doc/man/man3/crypto_key_exchange.3monocypher @@ -3,7 +3,7 @@ .Os .Sh NAME .Nm crypto_key_exchange , -.Nm crypto_x25519_public_key +.Nm crypto_key_exchange_public_key .Nd Elliptic Curve Diffie-Hellman key exchange .Sh SYNOPSIS .In monocypher.h @@ -14,7 +14,7 @@ .Fa "const uint8_t their_public_key[32]" .Fc .Ft void -.Fo crypto_x25519_public_key +.Fo crypto_key_exchange_public_key .Fa "uint8_t your_public_key[32]" .Fa "const uint8_t your_secret_key[32]" .Fc @@ -22,7 +22,7 @@ .Fn crypto_key_exchange computes a shared key with your secret key and their public key. .Pp -.Fn crypto_x25519_public_key +.Fn crypto_key_exchange_public_key deterministically computes the public key from a random secret key. .Pp The arguments are: @@ -47,7 +47,7 @@ The public key of the other party. Your public key, generated from .Fa your_secret_key with -.Fn crypto_x25519_public_key . +.Fn crypto_key_exchange_public_key . .El .Sh RETURN VALUES Some public keys force the shared key to a known constant. @@ -56,7 +56,7 @@ returns -1 if it detects such a public key, otherwise it returns 0. This never happens with legitimate public keys, but if the ones you process are not known to be trustworthy, check the return value. .Pp -.Fn crypto_x25519_public_key +.Fn crypto_key_exchange_public_key returns nothing. It cannot fail. .Sh EXAMPLES @@ -64,7 +64,7 @@ Generate a public key from a randomly generated secret key: .Bd -literal -offset indent const uint8_t sk[32]; /* Random secret key */ uint8_t pk[32]; /* Public key */ -crypto_x25519_public_key(pk, sk); +crypto_key_exchange_public_key(pk, sk); /* Wipe secrets if they are no longer needed */ crypto_wipe(sk, 32); .Ed @@ -96,3 +96,7 @@ If either of the long term secret keys leaks, it may compromise .Em all past messages . This can be avoided by using protocols that provide forward secrecy, such as the Double Ratchet Algorithm. +.Sh IMPLEMENTATION DETAILS +.Fn crypto_key_exchange_public_key +is an alias to +.Xr crypto_x25519_public_key 3monocypher . diff --git a/doc/man/man3/crypto_key_exchange_public_key.3monocypher b/doc/man/man3/crypto_key_exchange_public_key.3monocypher new file mode 120000 index 0000000..ff1529a --- /dev/null +++ b/doc/man/man3/crypto_key_exchange_public_key.3monocypher @@ -0,0 +1 @@ +crypto_key_exchange.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_lock_aead_auth.3monocypher b/doc/man/man3/crypto_lock_aead_auth.3monocypher new file mode 120000 index 0000000..c5b4453 --- /dev/null +++ b/doc/man/man3/crypto_lock_aead_auth.3monocypher @@ -0,0 +1 @@ +crypto_lock_init.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_lock_init.3monocypher b/doc/man/man3/crypto_lock_init.3monocypher index c9371c4..98cdbf6 100644 --- a/doc/man/man3/crypto_lock_init.3monocypher +++ b/doc/man/man3/crypto_lock_init.3monocypher @@ -3,12 +3,15 @@ .Os .Sh NAME .Nm crypto_lock_init , -.Nm crypto_lock_auth , -.Nm crypto_lock_encrypt , +.Nm crypto_lock_aead_auth , .Nm crypto_lock_update , .Nm crypto_lock_final , +.Nm crypto_unlock_init , +.Nm crypto_unlock_aead_auth , .Nm crypto_unlock_update , -.Nm crypto_unlock_final +.Nm crypto_unlock_final , +.Nm crypto_lock_auth , +.Nm crypto_lock_encrypt .Nd incremental authenticated encryption with additional data .Sh SYNOPSIS .In monocypher.h @@ -19,7 +22,7 @@ .Fa "const uint8_t nonce[24]" .Fc .Ft void -.Fo crypto_lock_auth +.Fo crypto_lock_aead_auth .Fa "crypto_lock_ctx *ctx" .Fa "const uint8_t *ad" .Fa "size_t ad_size" @@ -37,18 +40,36 @@ .Fa "uint8_t mac[16]" .Fc .Ft void +.Fo crypto_unlock_init +.Fa "crypto_unlock_ctx *ctx" +.Fa "const uint8_t key[32]" +.Fa "const uint8_t nonce[24]" +.Fc +.Ft void +.Fo crypto_unlock_aead_auth +.Fa "crypto_unlock_ctx *ctx" +.Fa "const uint8_t *ad" +.Fa "size_t ad_size" +.Fc +.Ft void .Fo crypto_unlock_update -.Fa "crypto_lock_ctx *ctx" +.Fa "crypto_unlock_ctx *ctx" .Fa "uint8_t *plain_text" .Fa "const uint8_t *cipher_text" .Fa "size_t text_size" .Fc .Ft int .Fo crypto_unlock_final -.Fa "crypto_lock_ctx *ctx" +.Fa "crypto_unlock_ctx *ctx" .Fa "const uint8_t mac[16]" .Fc .Ft void +.Fo crypto_lock_auth +.Fa "crypto_lock_ctx *ctx" +.Fa "const uint8_t *ad" +.Fa "size_t ad_size" +.Fc +.Ft void .Fo crypto_lock_encrypt .Fa "crypto_lock_ctx *ctx" .Fa "uint8_t *cipher_text" @@ -77,7 +98,7 @@ Initialise a context with .Fn crypto_lock_init . .It Authenticate additional data, if any, with -.Fn crypto_lock_auth . +.Fn crypto_lock_aead_auth . .It Encrypt and authenticate some data with .Fn crypto_lock_update . @@ -90,10 +111,10 @@ Decryption also requires four steps: .Bl -bullet .It Initialise a context with -.Fn crypto_lock_init . +.Fn crypto_unlock_init . .It Verify additional data, if any, with -.Fn crypto_lock_auth . +.Fn crypto_unlock_aead_auth . .It Decrypt and verify some data with .Fn crypto_unlock_update . @@ -109,7 +130,7 @@ It is meant as a building block. Used with .Fn crypto_lock_auth , it enables various AEAD constructions. -Most users do not need it. +Most users do not need either of them. Prefer .Fn crypto_lock_update and @@ -117,9 +138,13 @@ and instead. .Sh RETURN VALUES .Fn crypto_lock_init , +.Fn crypto_unlock_init , .Fn crypto_lock_auth , .Fn crypto_lock_encrypt , +.Fn crypto_lock_aead_auth , +.Fn crypto_unlock_aead_auth , .Fn crypto_lock_update , +.Fn crypto_unlock_update , and .Fn crypto_lock_final return nothing. @@ -148,7 +173,7 @@ crypto_wipe(key, 32); /* Authenticate additional data */ for (size_t i = 0; i < 500; i += 100) { - crypto_lock_auth(&ctx, ad + i, 100); + crypto_lock_aead_auth(&ctx, ad + i, 100); } /* Encrypt message */ @@ -172,14 +197,14 @@ const uint8_t cipher_text[500]; /* Encrypted message */ uint8_t plain_text [500]; /* Secret message */ /* Set up initial context */ -crypto_lock_ctx ctx; -crypto_lock_init(&ctx, key, nonce); +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_lock_auth(&ctx, ad + i, 100); + crypto_unlock_aead_auth(&ctx, ad + i, 100); } /* Decrypt message */ @@ -248,6 +273,23 @@ Doing so securely is hard. Do not process messages before calling .Fn crypto_unlock_final . .Sh IMPLEMENTATION DETAILS +.Bl -bullet +.It +.Vt crypto_unlock_ctx +is an alias to +.Vt crypto_lock_ctx . +.It +.Fn crypto_unlock_init +is an alias to +.Fn crypto_lock_init . +.It +.Fn crypto_lock_aead_auth +and +.Fn crypto_unlock_aead_auth +are aliases to +.Fn crypto_lock_auth . +.El +.Pp 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 diff --git a/doc/man/man3/crypto_unlock_aead_auth.3monocypher b/doc/man/man3/crypto_unlock_aead_auth.3monocypher new file mode 120000 index 0000000..c5b4453 --- /dev/null +++ b/doc/man/man3/crypto_unlock_aead_auth.3monocypher @@ -0,0 +1 @@ +crypto_lock_init.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_unlock_init.3monocypher b/doc/man/man3/crypto_unlock_init.3monocypher new file mode 120000 index 0000000..c5b4453 --- /dev/null +++ b/doc/man/man3/crypto_unlock_init.3monocypher @@ -0,0 +1 @@ +crypto_lock_init.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_x25519.3monocypher b/doc/man/man3/crypto_x25519.3monocypher index 065878a..48028f9 100644 --- a/doc/man/man3/crypto_x25519.3monocypher +++ b/doc/man/man3/crypto_x25519.3monocypher @@ -2,7 +2,8 @@ .Dt CRYPTO_X25519 3MONOCYPHER .Os .Sh NAME -.Nm crypto_x25519 +.Nm crypto_x25519 , +.Nm crypto_x25519_public_key .Nd X25519 key exchange .Sh SYNOPSIS .In monocypher.h @@ -12,6 +13,11 @@ .Fa "const uint8_t your_secret_key[32]" .Fa "const uint8_t their_public_key[32]" .Fc +.Ft void +.Fo crypto_x25519_public_key +.Fa "uint8_t your_public_key[32]" +.Fa "const uint8_t your_secret_key[32]" +.Fc .Sh DESCRIPTION .Fn crypto_x25519 computes a shared secret with @@ -20,9 +26,14 @@ and .Fa their_public_key . It is a low-level primitive. Users should use -.Xr crypto_key_exchange 3monocypher +.Xr crypto_key_exchange 3monocypher . unless they have a specific reason not to. .Pp +.Fn crypto_x25519_public_key +is the same as +.Xr crypto_key_exchange_public_key 3monocypher +It deterministically computes the public key from a random secret key. +.Pp The arguments are: .Bl -tag -width Ds .It Fa raw_shared_secret @@ -86,7 +97,7 @@ such as the Double Ratchet Algorithm. 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's not fully +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).