+++ /dev/null
-.Dd August 25, 2017
-.Dt CRYPTO_AEAD_LOCK 3MONOCYPHER
-.Os
-.Sh NAME
-.Nm crypto_aead_lock ,
-.Nm crypto_aead_unlock
-.Nd authenticated encryption with additional data
-.Sh SYNOPSIS
-.In monocypher.h
-.Ft void
-.Fo crypto_aead_lock
-.Fa "uint8_t mac[16]"
-.Fa "uint8_t *cipher_text"
-.Fa "const uint8_t key[32]"
-.Fa "const uint8_t nonce[24]"
-.Fa "const uint8_t *ad"
-.Fa "size_t ad_size"
-.Fa "const uint8_t *plain_text"
-.Fa "size_t text_size"
-.Fc
-.Ft int
-.Fo crypto_aead_unlock
-.Fa "uint8_t *plain_text"
-.Fa "const uint8_t key[32]"
-.Fa "const uint8_t nonce[24]"
-.Fa "const uint8_t mac[16]"
-.Fa "const uint8_t *ad"
-.Fa "size_t ad_size"
-.Fa "const uint8_t *cipher_text"
-.Fa "size_t text_size"
-.Fc
-.Sh DESCRIPTION
-These functions are variants of
-.Xr crypto_lock 3monocypher
-and
-.Xr crypto_unlock 3monocypher ,
-permitting additional data.
-Additional data is authenticated, but
-.Em not
-encrypted.
-.Pp
-.Bf Em
-Note: using these functions is discouraged:
-if the data you are transmitting is worth authenticating, it is probably
-worth encrypting as well.
-Do so if you can, using
-.Xr crypto_lock 3monocypher
-and
-.Xr crypto_unlock 3monocypher .
-.Ef
-.Pp
-If you must send unencrypted data, remember that you cannot trust
-unauthenticated data,
-.Em including the length of the additional data .
-If you transmit that length over the wire, you must authenticate it.
-(The easiest way to do so is to append that length to the additional
-data before you call
-.Fn crypto_aead_lock
-or
-.Fn crypto_aead_unlock ) .
-Otherwise, an attacker could provide a false length, effectively moving
-the boundary between the additional data and the ciphertext or possibly
-causing buffer overflows.
-If however the length of the additional data is implicit (fixed size)
-or self-contained (such as length appending or null termination), you do
-not need to authenticate it explicitly.
-.Pp
-The
-.Fn crypto_aead_lock
-function encrypts and authenticates a plaintext and authenticates
-additional data.
-It can be decrypted by the
-.Fn crypto_aead_unlock
-function.
-Arguments that are already documented in
-.Xr crypto_lock 3monocypher
-will not be repeated here.
-The arguments are:
-.Bl -tag -width Ds
-.It Fa ad
-additional data.
-This can be any arbitrary byte sequence.
-It will not be encrypted.
-.It Fa ad_size
-length of the additional data.
-.El
-.Pp
-If
-.Fa ad
-is
-.Dv NULL
-and
-.Fa ad_size
-is zero, these functions behave like
-.Xr crypto_lock 3monocypher
-and
-.Xr crypto_unlock 3monocypher .
-This can be useful if your protocol somehow requires you to
-send unencrypted data.
-.Pp
-Unlocking proceeds in two steps: first, we authenticate the ciphertext
-and additional data with the provided MAC.
-If it has been corrupted, the
-.Fn crypto_aead_unlock
-function returns immediately,
-without decrypting the message.
-If the message is genuine, the
-.Fn crypto_aead_unlock
-function decrypts the ciphertext.
-.Em Always check the return value .
-.Sh RETURN VALUES
-The
-.Fn crypto_aead_lock
-function returns nothing.
-It cannot fail.
-The
-.Fn crypto_aead_unlock
-function returns 0 on success or -1 if the message was corrupted (i.e.
-.Fa mac
-mismatched the combination of
-.Fa key ,
-.Fa nonce ,
-.Fa ad
-and
-.Fa cipher_text ) .
-Corruption can happen because of transmission errors, programmer error
-(e.g. failed to parse the protocol properly and thus supplied only part
-of the expected
-.Fa ad
-or
-.Fa cipher_text )
-or an attacker's interference.
-.Sh SEE ALSO
-.Xr crypto_key_exchange 3monocypher ,
-.Xr crypto_lock 3monocypher ,
-.Xr crypto_unlock 3monocypher ,
-.Xr intro 3monocypher
-.Sh IMPLEMENTATION DETAILS
-These functions do not authenticate the length themselves for
-simplicity, compatibility, and efficiency reasons:
-most of the time, the length of the additional data is either fixed or
-self-contained, and thus outside of attacker control.
-It also makes them compatible with
-.Xr crypto_lock 3monocypher
-and
-.Xr crypto_unlock 3monocypher
-when the size of the additional data is zero, and simplifies the
-implementation.
--- /dev/null
+crypto_lock.3monocypher
\ No newline at end of file
-crypto_aead_lock.3monocypher
\ No newline at end of file
+crypto_lock.3monocypher
\ No newline at end of file
.It Fa hash_size
the length of the output
.Fa hash .
+Because only fixed-length functions for constant-time comparison of
+hashes are available, it is recommended to set this argument to either
+16, 32 or 64.
.It Fa work_area
The address of a work area for the algorithm.
It must be big enough to hold
All pointer arguments may overlap.
.Pp
Use
-.Xr crypto_memcmp 3monocypher
+.Xr crypto_verify16 3monocypher ,
+.Xr crypto_verify32 3monocypher
+or
+.Xr crypto_verify64 3monocypher
to compare password hashes to prevent timing attacks, which are feasible
against the weakest passwords.
.Pp
.Ed
.Sh SEE ALSO
.Xr crypto_lock 3monocypher ,
-.Xr crypto_memcmp 3monocypher ,
+.Xr crypto_verify16 3monocypher ,
.Xr intro 3monocypher
.Sh CAVEATS
Any deviation from the specified input and output length ranges results
if
.Fa key_size
is 0.
+This can be used to create a message authentication code (MAC).
+Use the
+.Xr crypto_verify16 3monocypher ,
+.Xr crypto_verify32 3monocypher
+or the
+.Xr crypto_verify64 3monocypher
+function to compare MACs created this way.
+Choose
+.Fa hash_size
+appropriately for the verification functions.
.It Fa key_size
length of the
.Fa key .
--- /dev/null
+crypto_sign_init_first_pass.3monocypher
\ No newline at end of file
--- /dev/null
+crypto_sign_init_first_pass.3monocypher
\ No newline at end of file
--- /dev/null
+crypto_sign_init_first_pass.3monocypher
\ No newline at end of file
.Dt CRYPTO_LOCK 3MONOCYPHER
.Os
.Sh NAME
+.Nm crypto_aead_lock ,
+.Nm crypto_aead_unlock ,
.Nm crypto_lock ,
.Nm crypto_unlock
-.Nd authenticated encryption
+.Nd authenticated encryption (optionally with additional data)
.Sh SYNOPSIS
.In monocypher.h
.Ft void
.Fa "size_t text_size"
.Fc
.Ft void
-.Fo crypto_lock_init
-.Fa "crypto_lock_ctx *ctx"
+.Fo crypto_aead_lock
+.Fa "uint8_t mac[16]"
+.Fa "uint8_t *cipher_text"
.Fa "const uint8_t key[32]"
.Fa "const uint8_t nonce[24]"
-.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_update
-.Fa "crypto_lock_ctx *ctx"
-.Fa "uint8_t *cipher_text"
.Fa "const uint8_t *plain_text"
.Fa "size_t text_size"
.Fc
-.Ft void
-.Fo crypto_lock_final
-.Fa "crypto_lock_ctx *ctx"
-.Fa "uint8_t mac[16]"
-.Fc
-.Ft void
-.Fo crypto_unlock_update
-.Fa "crypto_lock_ctx *ctx"
+.Ft int
+.Fo crypto_aead_unlock
.Fa "uint8_t *plain_text"
+.Fa "const uint8_t key[32]"
+.Fa "const uint8_t nonce[24]"
+.Fa "const uint8_t mac[16]"
+.Fa "const uint8_t *ad"
+.Fa "size_t ad_size"
.Fa "const uint8_t *cipher_text"
.Fa "size_t text_size"
.Fc
-.Ft int
-.Fo crypto_unlock_final
-.Fa "crypto_lock_ctx *ctx"
-.Fa "const uint8_t mac[16]"
-.Fc
.Sh DESCRIPTION
Encryption makes your messages unreadable to eavesdroppers.
Authentication ascertain the origin and integrity of the messages you
legitimate, but actually come from an attacker).
A clever attacker may even leverage forgeries to steal your secrets.
Always authenticate your messages.
-.Ss Direct interface
+.Pp
The
.Fn crypto_lock
function encrypts and authenticates a plaintext.
.Fn crypto_aead_unlock
function decrypts the ciphertext.
.Em Always check the return value .
-.Ss Incremental interface
-The incremental interface allows to split up decryption and
-authentication of larger messages too large to fit into a single buffer
-or to handle individual pieces of data located in different buffers.
+.\" AEAD
.Pp
-The arguments are the same as described for the direct interface.
-It instead uses three steps:
-.Bl -bullet
-.It
-initialisation, where we set up a context for encryption/decryption and
-authentication;
-.It
-update, where we encrypt/decrypt and incrementally generate the MAC;
-.It
-final, where we generate/check the MAC.
-.El
+The
+.Fn crypto_aead_lock
+and
+.Fn crypto_aead_unlock
+functions are variants of
+.Fn crypto_lock
+and
+.Fn crypto_unlock ,
+permitting additional data.
+Additional data is authenticated, but
+.Em not
+encrypted.
.Pp
-Because the incremental interface interleaves both encryption and
-authentication,
-.Sy a message with a mismatched MAC is three times slower
-to process than when using the direct interface.
-The direct interface checks the MAC first and only then proceeds to
-decrypt.
-If you expect to frequently encounter messages whose MAC mismatches,
-especially large messages, you may want to forgo the incremental
-interface for a different approach.
+.Bf Em
+Note: using these functions is discouraged:
+if the data you are transmitting is worth authenticating, it is probably
+worth encrypting as well.
+Do so if you can, using
+.Fn crypto_lock
+and
+.Fn crypto_unlock .
+.Ef
+.Pp
+If you must send unencrypted data, remember that you cannot trust
+unauthenticated data,
+.Em including the length of the additional data .
+If you transmit that length over the wire, you must authenticate it.
+(The easiest way to do so is to append that length to the additional
+data before you call
+.Fn crypto_aead_lock
+or
+.Fn crypto_aead_unlock ) .
+Otherwise, an attacker could provide a false length, effectively moving
+the boundary between the additional data and the ciphertext or possibly
+causing buffer overflows.
+If however the length of the additional data is implicit (fixed size)
+or self-contained (such as length appending or null termination), you do
+not need to authenticate it explicitly.
.Pp
-.Sy Both encryption and decryption
-are initialized with
-.Fn crypto_lock_init .
-If you need to authenticate data without encrypting like with
-.Xr crypto_aead_lock 3monocypher ,
-plaintext data can be authenticated with
-.Fn crypto_lock_auth .
-Calls to
-.Fn crypto_lock_auth
-.Em can
-be interleaved with calls to
-.Fn crypto_lock_update
+The
+.Fn crypto_aead_lock
+function encrypts and authenticates a plaintext and authenticates
+additional data.
+It can be decrypted by the
+.Fn crypto_aead_unlock
+function.
+Arguments that are already documented above will not be repeated here.
+The arguments are:
+.Bl -tag -width Ds
+.It Fa ad
+additional data.
+This can be any arbitrary byte sequence.
+It will not be encrypted.
+.It Fa ad_size
+length of the additional data.
+.El
+.Pp
+If
+.Fa ad
+is
+.Dv NULL
+and
+.Fa ad_size
+is zero, these functions behave like
+.Xr crypto_lock 3monocypher
and
-.Fn crypto_unlock_update .
+.Xr crypto_unlock 3monocypher .
+This can be useful if your protocol somehow requires you to
+send unencrypted data.
.Pp
-.Sy For encryption,
-.Fn crypto_lock_update
-authenticates and encrypts the data;
-.Fn crypto_lock_final
-generates the MAC.
-.Sy For decryption ,
-.Fn crypto_unlock_update
-authenticates and decrypts the data;
-.Fn crypto_unlock_final
-checks the MAC.
+Unlocking proceeds in two steps: first, we authenticate the ciphertext
+and additional data with the provided MAC.
+If it has been corrupted, the
+.Fn crypto_aead_unlock
+function returns immediately,
+without decrypting the message.
+If the message is genuine, the
+.Fn crypto_aead_unlock
+function decrypts the ciphertext.
.Em Always check the return value .
+.Pp
+An incremental interface is available; see
+.Xr crypto_lock_init 3monocypher .
.Sh RETURN VALUES
The
-.Fn crypto_lock ,
-.Fn crypto_lock_init ,
-.Fn crypto_lock_auth ,
-.Fn crypto_lock_update ,
+.Fn crypto_lock
and
-.Fn crypto_lock_final
+.Fn crypto_aead_lock
functions return nothing.
They cannot fail.
-.Pp
The
.Fn crypto_unlock
and
-.Fn crypto_unlock_final
+.Fn crypto_aead_unlock
functions return 0 on success or -1 if the message was corrupted
(i.e.
.Fa mac
mismatched the combination of
.Fa key ,
-.Fa nonce
+.Fa nonce ,
+.Fa ad
and
.Fa cipher_text ) .
Corruption can happen because of transmission errors, programmer error
.Fa cipher_text )
or an attacker's interference.
.Sh EXAMPLES
-.Ss Direct interface
Encryption:
.Bd -literal -offset indent
uint8_t key[32], nonce[24];
*/
}
.Ed
-.Ss Incremental interface
-Useful for decrypting huge inputs.
-This time, decryption is performed regardless of whether the message
-is corrupted or not.
-This may be relevant if you expect a high rate of corrupted messages.
-.Pp
-Encryption:
-.Bd -literal -offset indent
-/* Prepare the key, nonce, and input */
-
-/* First, initialise the context */
-crypto_lock_ctx ctx;
-crypto_lock_init(&ctx, key, nonce);
-
-/* Second, authenticate the additional data, if any. */
-crypto_lock_auth(&ctx, ad1, ad_size1);
-crypto_lock_auth(&ctx, ad2, ad_size2);
-crypto_lock_auth(&ctx, ad3, ad_size3);
-
-/* Third, encrypt the plain text */
-crypto_lock_update(&ctx, cipher1, plain1, text_size1);
-crypto_lock_update(&ctx, cipher2, plain2, text_size2);
-crypto_lock_update(&ctx, cipher3, plain2, text_size3);
-
-/* Finally, compute the authentication code */
-crypto_lock_final (&ctx, mac);
-.Ed
-.Pp
-Make sure you authenticate the additional data before you begin the
-encryption, or the mac won't be compatible with the direct interface.
-.Pp
-To decrypt the above:
-.Bd -literal -offset indent
-/* First, initialise the context.
- * Use the key and nonce that were used for encryption.
- */
-crypto_lock_ctx ctx;
-crypto_lock_init(&ctx, key, nonce);
-
-/* Second, authenticate the additional data, if any. */
-crypto_lock_auth(&ctx, ad1, ad_size1);
-crypto_lock_auth(&ctx, ad2, ad_size2);
-crypto_lock_auth(&ctx, ad3, ad_size3);
-
-/* Third, decrypt the cipher text */
-crypto_unlock_update(&ctx, re_plain1, cipher1, text_size1);
-crypto_unlock_update(&ctx, re_plain2, cipher2, text_size2);
-crypto_unlock_update(&ctx, re_plain3, cipher3, text_size3);
-
-/* Finally, check the authentication code */
-if (crypto_unlock_final(&ctx, mac2)) {
- /* Message corrupted. */
-} else {
- /* Decryption went well. */
-}
-.Ed
-.Pp
-To authenticate without decrypting at all:
-.Bd -literal -offset indent
-/* First, initialise the context.
- * Use the key and nonce that were used for encryption.
- */
-crypto_lock_ctx ctx;
-crypto_lock_init(&ctx, key, nonce);
-
-/* Second, authenticate the additional data, if any. */
-crypto_lock_auth(&ctx, ad1, ad_size1);
-crypto_lock_auth(&ctx, ad2, ad_size2);
-crypto_lock_auth(&ctx, ad3, ad_size3);
-
-/* Third, authenticate the cipher text */
-crypto_lock_auth(&ctx, re_plain1, cipher1, text_size1);
-crypto_lock_auth(&ctx, re_plain2, cipher2, text_size2);
-crypto_lock_auth(&ctx, re_plain3, cipher3, text_size3);
-
-/* Finally, check the authentication code */
-if (crypto_unlock_final(&ctx, mac2)) {
- /* Message corrupted. */
-} else {
- /* Message authentic. */
-}
-.Ed
.Sh SEE ALSO
-.Xr crypto_aead_lock 3monocypher ,
-.Xr crypto_aead_unlock 3monocypher ,
.Xr crypto_key_exchange 3monocypher ,
+.Xr crypto_lock_init 3monocypher ,
.Xr intro 3monocypher
.Sh IMPLEMENTATION DETAILS
These functions implement the XChacha20 (encryption) and Poly1305 (MAC)
primitives.
+.Pp
+The
+.Fn crypto_aead_lock
+and
+.Fn crypto_aead_unlock
+functions do not authenticate the length themselves for simplicity,
+compatibility, and efficiency reasons:
+most of the time, the length of the additional data is either fixed or
+self-contained, and thus outside of attacker control.
+It also makes them compatible with
+.Fn crypto_lock
+and
+.Fn crypto_unlock
+when the size of the additional data is zero, and simplifies the
+implementation.
-crypto_lock.3monocypher
\ No newline at end of file
+crypto_lock_init.3monocypher
\ No newline at end of file
--- /dev/null
+crypto_lock_init.3monocypher
\ No newline at end of file
-crypto_lock.3monocypher
\ No newline at end of file
+crypto_lock_init.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_lock.3monocypher
\ No newline at end of file
--- /dev/null
+.Dd October 14, 2017
+.Dt CRYPTO_LOCK_INIT 3MONOCYPHER
+.Os
+.Sh NAME
+.Nm crypto_lock_init ,
+.Nm crypto_lock_auth ,
+.Nm crypto_lock_encrypt ,
+.Nm crypto_lock_update ,
+.Nm crypto_lock_final ,
+.Nm crypto_unlock_update ,
+.Nm crypto_unlock_final
+.Nd incremental authenticated encryption with authenticated data
+.Sh SYNOPSIS
+.In monocypher.h
+.Ft void
+.Fo crypto_lock_init
+.Fa "crypto_lock_ctx *ctx"
+.Fa "const uint8_t key[32]"
+.Fa "const uint8_t nonce[24]"
+.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_update
+.Fa "crypto_lock_ctx *ctx"
+.Fa "uint8_t *cipher_text"
+.Fa "const uint8_t *plain_text"
+.Fa "size_t text_size"
+.Fc
+.Ft void
+.Fo crypto_lock_final
+.Fa "crypto_lock_ctx *ctx"
+.Fa "uint8_t mac[16]"
+.Fc
+.Ft void
+.Fo crypto_unlock_update
+.Fa "crypto_lock_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 "const uint8_t mac[16]"
+.Fc
+.Ft void
+.Fo crypto_lock_encrypt
+.Fa "crypto_lock_ctx *ctx"
+.Fa "uint8_t *cipher_text"
+.Fa "const uint8_t *plain_text"
+.Fa "size_t text_size"
+.Fc
+.Sh DESCRIPTION
+These functions are variants of
+.Xr crypto_lock 3monocypher ,
+.Xr crypto_unlock 3monocypher ,
+.Xr crypto_aead_lock 3monocypher
+and
+.Xr crypto_aead_unlock 3monocypher .
+Prefer those more simple functions if possible.
+.Pp
+This incremental interface allows splitting up decryption and
+authentication of larger messages too large to fit into a single buffer
+or to handle individual pieces of data located in different buffers.
+The arguments are the same as described for the direct interface on
+.Xr crypto_lock 3monocypher .
+.Pp
+This interface uses three steps:
+.Bl -bullet
+.It
+initialisation, where we set up a context for encryption/decryption and
+authentication;
+.It
+update, where we encrypt/decrypt and incrementally generate the MAC;
+.It
+final, where we generate/check the MAC.
+.El
+.Pp
+Because the incremental interface interleaves both encryption and
+authentication,
+.Sy a message with a mismatched MAC is three times slower
+to process than when using the direct interface.
+The direct interface checks the MAC first and only then proceeds to
+decrypt.
+If you expect to frequently encounter messages whose MAC mismatches,
+especially large messages, you may want to forgo the incremental
+interface for a different approach.
+.Pp
+.Sy Both encryption and decryption
+are initialized with
+.Fn crypto_lock_init .
+If you need to authenticate data without encrypting like with
+.Xr crypto_aead_lock 3monocypher ,
+plaintext data can be authenticated with
+.Fn crypto_lock_auth .
+Calls to
+.Fn crypto_lock_auth
+.Em can
+be interleaved with calls to
+.Fn crypto_lock_update
+and
+.Fn crypto_unlock_update .
+.Pp
+.Sy For encryption ,
+.Fn crypto_lock_update
+authenticates and encrypts the data;
+.Fn crypto_lock_final
+generates the MAC.
+.Sy For decryption ,
+.Fn crypto_unlock_update
+authenticates and decrypts the data;
+.Fn crypto_unlock_final
+checks the MAC.
+.Em Always check the return value .
+.Pp
+The
+.Fn crypto_lock_encrypt
+function encrypts or decrypts data
+.Em without authenticating it .
+You will likely not require this function unless you wish to implement
+most of the actual AEAD work yourself.
+The
+.Fn crypto_lock_update
+and
+.Fn crypto_unlock_update
+functions are convenience wrappers around
+the
+.Fn crypto_lock_encrypt
+and
+.Fn crypto_lock_auth
+functions.
+.Sh RETURN VALUES
+The
+.Fn crypto_lock_init ,
+.Fn crypto_lock_auth ,
+.Fn crypto_lock_encrypt ,
+.Fn crypto_lock_update ,
+and
+.Fn crypto_lock_final
+functions return nothing.
+They cannot fail.
+.Pp
+The
+.Fn crypto_unlock_final
+function returns 0 on success or -1 if the message was corrupted
+(i.e.
+.Fa mac
+mismatched the combination of
+.Fa key ,
+.Fa nonce ,
+.Fa mac
+and
+.Fa cipher_text ) .
+Corruption can happen because of transmission errors, programmer error
+(e.g. failed to parse the protocol properly and thus supplied only part
+of the expected
+.Fa cipher_text )
+or an attacker's interference.
+.Sh EXAMPLES
+Encryption:
+.Bd -literal -offset indent
+/* Prepare the key, nonce, and input */
+
+/* First, initialise the context */
+crypto_lock_ctx ctx;
+crypto_lock_init(&ctx, key, nonce);
+
+/* Second, authenticate the additional data, if any. */
+crypto_lock_auth(&ctx, ad1, ad_size1);
+crypto_lock_auth(&ctx, ad2, ad_size2);
+crypto_lock_auth(&ctx, ad3, ad_size3);
+
+/* Third, encrypt the plain text */
+crypto_lock_update(&ctx, cipher1, plain1, text_size1);
+crypto_lock_update(&ctx, cipher2, plain2, text_size2);
+crypto_lock_update(&ctx, cipher3, plain2, text_size3);
+
+/* Finally, compute the authentication code */
+crypto_lock_final (&ctx, mac);
+.Ed
+.Pp
+Make sure you authenticate the additional data before you begin the
+encryption, or the mac won't be compatible with the direct interface.
+.Pp
+To decrypt the above:
+.Bd -literal -offset indent
+/* First, initialise the context.
+ * Use the key and nonce that were used for encryption.
+ */
+crypto_lock_ctx ctx;
+crypto_lock_init(&ctx, key, nonce);
+
+/* Second, authenticate the additional data, if any. */
+crypto_lock_auth(&ctx, ad1, ad_size1);
+crypto_lock_auth(&ctx, ad2, ad_size2);
+crypto_lock_auth(&ctx, ad3, ad_size3);
+
+/* Third, decrypt the cipher text */
+crypto_unlock_update(&ctx, re_plain1, cipher1, text_size1);
+crypto_unlock_update(&ctx, re_plain2, cipher2, text_size2);
+crypto_unlock_update(&ctx, re_plain3, cipher3, text_size3);
+
+/* Finally, check the authentication code */
+if (crypto_unlock_final(&ctx, mac2)) {
+ /* Message corrupted. */
+} else {
+ /* Decryption went well. */
+}
+.Ed
+.Pp
+To authenticate without decrypting at all:
+.Bd -literal -offset indent
+/* First, initialise the context.
+ * Use the key and nonce that were used for encryption.
+ */
+crypto_lock_ctx ctx;
+crypto_lock_init(&ctx, key, nonce);
+
+/* Second, authenticate the additional data, if any. */
+crypto_lock_auth(&ctx, ad1, ad_size1);
+crypto_lock_auth(&ctx, ad2, ad_size2);
+crypto_lock_auth(&ctx, ad3, ad_size3);
+
+/* Third, authenticate the cipher text */
+crypto_lock_auth(&ctx, re_plain1, cipher1, text_size1);
+crypto_lock_auth(&ctx, re_plain2, cipher2, text_size2);
+crypto_lock_auth(&ctx, re_plain3, cipher3, text_size3);
+
+/* Finally, check the authentication code */
+if (crypto_unlock_final(&ctx, mac2)) {
+ /* Message corrupted. */
+} else {
+ /* Message authentic. */
+}
+.Ed
+.Sh SEE ALSO
+.Xr crypto_aead_lock 3monocypher ,
+.Xr crypto_aead_unlock 3monocypher ,
+.Xr crypto_key_exchange 3monocypher ,
+.Xr crypto_lock 3monocypher ,
+.Xr crypto_unlock 3monocypher ,
+.Xr intro 3monocypher
+.Sh IMPLEMENTATION DETAILS
+These functions implement the XChacha20 (encryption) and Poly1305 (MAC)
+primitives.
-crypto_lock.3monocypher
\ No newline at end of file
+crypto_lock_init.3monocypher
\ No newline at end of file
-.Dd August 25, 2017
+.Dd October 14, 2017
.Dt CRYPTO_MEMCMP 3MONOCYPHER
.Os
.Sh NAME
.Nm crypto_memcmp ,
.Nm crypto_zerocmp
-.Nd timing-safe data comparisons
+.Nd deprecated timing-safe data comparisons
.Sh SYNOPSIS
.In monocypher.h
.Ft int
.Ft int
.Fn crypto_zerocmp "const uint8_t *p" "size_t n"
.Sh DESCRIPTION
-In cryptography, we often need to compare secrets or values derived from
-secrets.
-A message authentication code for instance:
-while the MAC sent over the network along with a message is public, the
-true MAC is secret.
-If the attacker attempts a forgery, you do not want to state
-.Dq your MAC is wrong, Em and it took 384 microseconds to know .
-If the next attempt takes 462 microseconds instead, it gives away the
-fact that the attacker just got a few bytes right.
-That way, an attacker can derive the correct MAC.
-.Pp
-To avoid such catastrophe,
-.Fn crypto_memcmp
-and
-.Fn crypto_zerocmp
-provide comparison functions whose timing is independent from the
-context of their input.
-.Pp
The
.Fn crypto_memcmp
-function compares the first
-.Fa n
-bytes of the two byte arrays
-.Fa p1
and
-.Fa p2 .
-The
-.Fn crypto_zerocmp
-function compares the first
-.Fa n
-bytes of the byte array
-.Fa p1
-against zero.
-.Pp
-You should not need these functions if you use the high-level interface
-of Monocypher \(en just look at the return codes.
-But if you do have to compare secrets, make sure you use
-.Fn crypto_memcmp
-or
-.Fn crypto_zerocmp .
-If you are in doubt whether you need to use these functions, prefer
-these over
-.Fn memcmp .
-.Sh RETURN VALUES
-The
-.Fn crypto_memcmp
-function returns 0 if the two memory chunks are the same, -1 otherwise.
-The
.Fn crypto_zerocmp
-function returns 0 if all bytes of the memory chunk are zero, -1
-otherwise.
+functions were meant to provide timing-safe data comparison.
+They have been removed from Monocypher because they could not uphold
+those guarantees when compiled with
+.Fl O3
+on common compilers.
+Use
+.Xr crypto_verify16 3monocypher ,
+.Xr crypto_verify32 3monocypher
+and
+.Xr crypto_verify64 3monocypher
+instead.
.Sh SEE ALSO
+.Xr crypto_verify16 3monocypher ,
.Xr intro 3monocypher
function yields the message authentication code.
.Pp
Use
-.Xr crypto_memcmp 3monocypher
+.Xr crypto_verify16 3monocypher
to compare the MAC received to the output
.Fa mac .
.Sh RETURN VALUES
.Sh SEE ALSO
.Xr crypto_blake2b 3monocypher ,
.Xr crypto_lock 3monocypher ,
-.Xr crypto_memcmp 3monocypher ,
+.Xr crypto_verify16 3monocypher ,
.Xr intro 3monocypher
.Sh CAVEATS
Using Poly1305 correctly is very difficult.
.Fa message
arguments may overlap.
.Pp
-An incremental interface is not available.
-If you require an incremental interface, signing a hash of your data
-is an acceptable substitute; see
-.Xr crypto_blake2b_init 3monocypher
-for details about incrementally hashing data.
+An incremental interface is available; see
+.Xr crypto_sign_init_first_pass 3monocypher .
.Sh RETURN VALUES
The
.Fn crypto_sign_public_key
.Pp
The reason why there is a SHA-512 option at all is due to official test
vectors.
-.Pp
-There is no incremental interface because EdDSA requires the full
-message to be hashed twice in a way that makes parallel hashing
-impossible.
-Workarounds for providing an incremental interface would involve
-lowering the security guarantees of the underlying hash function or
-would introduce grave potential for misuse, likely leading to situations
-such as the Sony PlayStation EdDSA nonce randomization failure.
-For this reason, an incremental interface has not been provided.
--- /dev/null
+crypto_sign_init_first_pass.3monocypher
\ No newline at end of file
--- /dev/null
+.Dd October 14, 2017
+.Dt CRYPTO_SIGN_INIT_FIRST_PASS 3MONOCYPHER
+.Os
+.Sh NAME
+.Nm crypto_sign_init_first_pass ,
+.Nm crypto_sign_update ,
+.Nm crypto_sign_final ,
+.Nm crypto_sign_init_second_pass ,
+.Nm crypto_check_init ,
+.Nm crypto_check_update ,
+.Nm crypto_check_final
+.Nd incremental public key signatures
+.Sh SYNOPSIS
+.In monocypher.h
+.Ft void
+.Fo crypto_sign_init_first_pass
+.Fa "crypto_sign_ctx *ctx"
+.Fa "const uint8_t secret_key[32]"
+.Fa "const uint8_t public_key[32]"
+.Fc
+.Ft void
+.Fo crypto_sign_update
+.Fa "crypto_sign_ctx *ctx"
+.Fa "const uint8_t *message"
+.Fa "size_t message_size"
+.Fc
+.Ft void
+.Fo crypto_sign_final
+.Fa "crypto_sign_ctx *ctx"
+.Fa "uint8_t signature[64]"
+.Fc
+.Ft void
+.Fo crypto_sign_init_second_pass
+.Fa "crypto_sign_ctx *ctx"
+.Fc
+.Ft void
+.Fo crypto_check_init
+.Fa "crypto_check_ctx *ctx"
+.Fa "const uint8_t signature[64]"
+.Fa "const uint8_t public_key[32]"
+.Fc
+.Ft void
+.Fo crypto_check_update
+.Fa "crypto_check_ctx *ctx"
+.Fa "const uint8_t *message"
+.Fa "size_t message_size"
+.Fc
+.Ft int
+.Fo crypto_check_final
+.Fa "crypto_check_ctx *ctx"
+.Fc
+.Sh DESCRIPTION
+These functions are variants of
+.Xr crypto_sign 3monocypher
+and
+.Xr crypto_check 3monocypher .
+Prefer those more simple functions if possible.
+.Pp
+This incremental interface allows splitting up decryption and
+authentication of larger messages too large to fit into a single buffer
+or to handle individual pieces of data located in different buffers.
+The arguments are the same as described for the direct interface on
+.Xr crypto_sign 3monocypher .
+.Pp
+For signing, this interface uses
+.Em five
+steps:
+.Bl -bullet
+.It
+initialisation of the first pass, where a context for signing is set up;
+.It
+update, where the message is processed for the first time;
+.It
+initialisation of the second pass, where the result from the first pass
+is used to prepare the second pass;
+.It
+update, where the message is processed for the second time;
+.It
+final, where we generate/check the signature.
+.El
+.Pp
+For verification, this interface uses three steps:
+.Bl -bullet
+.It
+initialization, where a context for verification is set up;
+.It
+update, where the message is processed;
+.It
+final, where the signature is actually verified.
+.El
+.Pp
+Signatures made with this interface are compatible with the direct
+interface and vice-versa.
+.Sh RETURN VALUES
+The
+.Fn crypto_sign_init_first_pass ,
+.Fn crypto_sign_init_second_pass ,
+.Fn crypto_sign_update ,
+.Fn crypto_sign_final ,
+.Fn crypto_check_init
+and
+.Fn crypto_check_update
+functions return nothing.
+They cannot fail.
+.Pp
+The
+.Fn crypto_check_final
+function returns zero for legitimate messages and -1 for forgeries.
+.Sh EXAMPLES
+This example signs a random message and verifies the signature.
+.Bd -literal -offset indent
+uint8_t sk[32], pk[32], msg[128];
+
+/* ...randomly generate sk and msg here... */
+crypto_sign_public_key(pk, sk);
+
+/* Signing */
+uint8_t sig[64];
+crypto_sign_ctx sctx;
+crypto_sign_init_first_pass (&sctx, sk, pk);
+crypto_sign_update (&sctx, msg, sizeof(msg));
+crypto_sign_init_second_pass(&sctx);
+crypto_sign_update (&sctx, msg, sizeof(msg));
+crypto_sign_final (&sctx, sig);
+
+/* Verifying */
+crypto_check_ctx cctx;
+crypto_check_init (&cctx, sig, pk);
+crypto_check_update (&cctx, msg, sizeof(msg));
+int is_valid_sig = (crypto_check_final(&cctx) == 0);
+.Ed
+.Sh SEE ALSO
+.Xr crypto_blake2b 3monocypher ,
+.Xr crypto_key_exchange 3monocypher ,
+.Xr crypto_lock 3monocypher ,
+.Xr crypto_sign 3monocypher ,
+.Xr intro 3monocypher
+.Sh CAVEATS
+The same caveats as documented on
+.Xr crypto_sign 3monocypher
+apply.
+.Sh IMPLEMENTATION DETAILS
+These functions provide public key signatures with a variant of Ed25519,
+which uses Blake2b as the hash instead of SHA-512.
+.Pp
+Ed25519 is designed as a two-pass algorithm.
+See
+.Xr crypto_sign 3monocypher
+for other details.
--- /dev/null
+crypto_sign_init_first_pass.3monocypher
\ No newline at end of file
--- /dev/null
+crypto_sign_init_first_pass.3monocypher
\ No newline at end of file
-crypto_lock.3monocypher
\ No newline at end of file
+crypto_lock_init.3monocypher
\ No newline at end of file
-crypto_lock.3monocypher
\ No newline at end of file
+crypto_lock_init.3monocypher
\ No newline at end of file
--- /dev/null
+.Dd October 14, 2017
+.Dt CRYPTO_VERIFY16 3MONOCYPHER
+.Os
+.Sh NAME
+.Nm crypto_verify16 ,
+.Nm crypto_verify32 ,
+.Nm crypto_verify64
+.Nd timing-safe data comparison
+.Sh SYNOPSIS
+.In monocypher.h
+.Ft int
+.Fn crypto_verify16 "const uint8_t a[16]" "const uint8_t b[16]"
+.Ft int
+.Fn crypto_verify32 "const uint8_t a[32]" "const uint8_t b[32]"
+.Ft int
+.Fn crypto_verify64 "const uint8_t a[64]" "const uint8_t b[64]"
+.Sh DESCRIPTION
+Cryptographic operations often require comparison of secrets or values
+derived from secrets.
+Take for example a message authentication code (MAC).
+A MAC may be sent over the network along with a message.
+However, the correct MAC is secret.
+If the attacker attempts a forgery, you do not want to reveal
+.Dq your MAC is wrong, Em and it took 384 microseconds to tell .
+If the next attempt takes 462 microseconds instead, it gives away the
+fact that the attacker just guessed a few bytes correctly.
+That way, an attacker can derive the correct MAC.
+.Pp
+To avoid such catastrophic failure,
+the
+.Fn crypto_verify16 ,
+.Fn crypto_verify32
+and
+.Fn crypto_verify64
+functions provide comparison functions whose timing is independent from
+the context of their input.
+.Pp
+The
+.Fn crypto_verify16 ,
+.Fn crypto_verify32
+and
+.Fn crypto_verify64
+functions compare the first
+16, 32 and 64 bytes of the two byte arrays
+.Fa a
+and
+.Fa b ,
+respectively.
+.Pp
+You should not need these functions if you use the high-level interface
+of Monocypher \(en just look at the return codes.
+Some high-level functions in Monocypher nonetheless require manual
+constant-time comparison:
+.Bl -bullet
+.It
+.Xr crypto_argon2i 3monocypher
+when used for password storage.
+Comparing the input password hash with the one in the database must be
+constant-time.
+.It
+.Xr crypto_blake2b 3monocypher
+when used with the
+.Fa key
+argument to create a message authentication code.
+Comparing the local hash with a known good hash must be constant-time.
+.El
+.Pp
+Both of these functions allow you to specify output lengths that do not
+have an equivalent verification function.
+In this case, you may wish to allocate buffers larger than your output
+hash, zero them out, copy the hashes into the buffers and compare those
+buffers instead.
+.Pp
+If you are in doubt whether you need to use these functions, prefer
+these over
+.Fn memcmp .
+.Sh RETURN VALUES
+These functions return 0 if the two memory chunks are the same, -1
+otherwise.
+.Sh SEE ALSO
+.Xr intro 3monocypher
--- /dev/null
+crypto_verify16.3monocypher
\ No newline at end of file
--- /dev/null
+crypto_verify16.3monocypher
\ No newline at end of file
.Bl -tag -offset indent-two -width Ds
.It Xr crypto_lock 3monocypher
.It Xr crypto_unlock 3monocypher
+.El
+.It Authenticated encryption with additional data (AEAD)
+.Bl -tag -offset indent-two -width Ds
+.It Xr crypto_aead_lock 3monocypher
+.It Xr crypto_aead_unlock 3monocypher
.It Xr crypto_lock_init 3monocypher
.It Xr crypto_lock_auth 3monocypher
.It Xr crypto_lock_update 3monocypher
.It Xr crypto_lock_final 3monocypher
.It Xr crypto_unlock_update 3monocypher
.It Xr crypto_unlock_final 3monocypher
-.El
-.It Authenticated encryption with additional data (AEAD)
-.Bl -tag -offset indent-two -width Ds
-.It Xr crypto_aead_lock 3monocypher
-.It Xr crypto_aead_unlock 3monocypher
+.It Xr crypto_lock_encrypt 3monocypher
.El
.It (Elliptic Curve) Diffie-Hellman key exchange
.Bl -tag -offset indent-two -width Ds
.It Xr crypto_sign_public_key 3monocypher
.It Xr crypto_sign 3monocypher
.It Xr crypto_check 3monocypher
+.It Xr crypto_sign_init_first_pass 3monocypher
+.It Xr crypto_sign_update 3monocypher
+.It Xr crypto_sign_final 3monocypher
+.It Xr crypto_sign_init_second_pass 3monocypher
+.It Xr crypto_check_init 3monocypher
+.It Xr crypto_check_update 3monocypher
+.It Xr crypto_check_final 3monocypher
.El
.It Cryptographic hashing
.Bl -tag -offset indent-two -width Ds
.It Xr crypto_poly1305_update 3monocypher
.It Xr crypto_poly1305_final 3monocypher
.El
-.It Utility functions
+.It Comparison functions
.Bl -tag -offset indent-two -width Ds
-.It Xr crypto_memcmp 3monocypher
-.It Xr crypto_zerocmp 3monocypher
+.It Xr crypto_verify16 3monocypher
+.It Xr crypto_verify32 3monocypher
+.It Xr crypto_verify64 3monocypher
.El
.El
.Sh SEE ALSO
.Xr crypto_blake2b_general_init 3monocypher ,
.Xr crypto_blake2b_init 3monocypher ,
.Xr crypto_blake2b_update 3monocypher ,
-.Xr crypto_chacha20_H 3monocypher ,
.Xr crypto_chacha20_encrypt 3monocypher ,
+.Xr crypto_chacha20_H 3monocypher ,
.Xr crypto_chacha20_init 3monocypher ,
.Xr crypto_chacha20_set_ctr 3monocypher ,
.Xr crypto_chacha20_stream 3monocypher ,
.Xr crypto_chacha20_x_init 3monocypher ,
.Xr crypto_check 3monocypher ,
+.Xr crypto_check_final 3monocypher ,
+.Xr crypto_check_init 3monocypher ,
+.Xr crypto_check_update 3monocypher ,
.Xr crypto_key_exchange 3monocypher ,
.Xr crypto_lock 3monocypher ,
-.Xr crypto_memcmp 3monocypher ,
+.Xr crypto_lock_auth 3monocypher ,
+.Xr crypto_lock_encrypt 3monocypher ,
+.Xr crypto_lock_final 3monocypher ,
+.Xr crypto_lock_init 3monocypher ,
+.Xr crypto_lock_update 3monocypher ,
.Xr crypto_poly1305_auth 3monocypher ,
-.Xr crypto_poly1305_final 3monocypher
+.Xr crypto_poly1305_final 3monocypher ,
.Xr crypto_poly1305_init 3monocypher ,
.Xr crypto_poly1305_update 3monocypher ,
.Xr crypto_sign 3monocypher ,
+.Xr crypto_sign_final 3monocypher ,
+.Xr crypto_sign_init_first_pass 3monocypher ,
+.Xr crypto_sign_init_second_pass 3monocypher ,
.Xr crypto_sign_public_key 3monocypher ,
-.Xr crypto_unlock 3monocypher ,
+.Xr crypto_sign_update 3monocypher ,
+.Xr crypto_unlock 3monocypher 3monocypher ,
+.Xr crypto_unlock_update 3monocypher ,
+.Xr crypto_unlock_final 3monocypher ,
+.Xr crypto_verify16 3monocypher ,
+.Xr crypto_verify32 3monocypher ,
+.Xr crypto_verify64 3monocypher ,
.Xr crypto_x25519 3monocypher ,
-.Xr crypto_x25519_public_key 3monocypher ,
-.Xr crypto_zerocmp 3monocypher
+.Xr crypto_x25519_public_key 3monocypher
projects / Monocypher.git / commitdiff