.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
.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
.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:
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.
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
.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
.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 .
.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
.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"
.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"
.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 .
.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 .
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
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.
/* 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 */
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 */
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
.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
.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
.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
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).
projects / Monocypher.git / commitdiff