FOLDER=monocypher-$VERSION
TARBALL=$FOLDER.tar
-# Generate documentation for users who don't have mandoc
-doc/man2html.sh
+# Generate documentation
+doc/doc_gen.sh
# Delete the destination folder just to make sure everything is clean.
# May be needed if we unpack the tarball in place for testing purposes,
See
.Xr crypto_x25519 3monocypher
for a building block for a key exchange protocol and
-.Xr crypto_argon2i 3monocypher
+.Xr crypto_argon2 3monocypher
for password-based key derivation.
.It Fa nonce
A 24-byte number, used only once with any given session key.
first initialise a context with
.Fn crypto_aead_init_x ,
then encrypt each chunk with
-.Fn crypto_aead_write.
+.Fn crypto_aead_write .
The receiving end will initialise its own context with
.Fn crypto_aead_init_x ,
then decrypt each chunk with
-.Fn crypto_aead_read.
+.Fn crypto_aead_read .
.Pp
Just like
.Fn crypto_aead_unlock ,
.Fa hash ,
in bytes.
This argument should be set to 32 or 64 for compatibility with the
-.Fn crypto_verify*
+.Xr crypto_verify32 3monocypher
+or
+.Xr crypto_verify64 3monocypher
constant time comparison functions.
.It Fa work_area
Temporary buffer for the algorithm, allocated by the caller.
.Fa config.nb_blocks
× 1024 bytes big and suitably aligned for 64-bit integers.
If you are not sure how to allocate that buffer, just use
-.Fn malloc .
+.Xr malloc 3.
.Pp
The work area is automatically wiped by
.Fn crypto_argon2 .
}
.Ed
.Sh SEE ALSO
-.Xr crypto_lock 3monocypher ,
+.Xr crypto_aead_lock 3monocypher ,
.Xr crypto_verify16 3monocypher ,
.Xr crypto_wipe 3monocypher ,
.Xr intro 3monocypher
Note that BLAKE2b itself is not suitable for hashing passwords and
deriving keys from them;
use the
-.Xr crypto_argon2i 3monocypher
+.Xr crypto_argon2 3monocypher
family of functions for that purpose instead.
.Pp
While BLAKE2b is immune to length extension attacks,
.Ed
.Sh SEE ALSO
.Xr crypto_x25519 3monocypher ,
-.Xr crypto_lock 3monocypher ,
+.Xr crypto_aead_lock 3monocypher ,
.Xr intro 3monocypher
.Sh STANDARDS
These functions implement BLAKE2b, described in RFC 7693.
it is important to artificially slow down attackers by using
computationally difficult hashing algorithms.
Monocypher therefore provides
-.Xr crypto_argon2i 3monocypher
+.Xr crypto_argon2 3monocypher
for password hashing and deriving keys from passwords.
.Sh IMPLEMENTATION DETAILS
The core loop is unrolled by default.
.Pp
ChaCha20 is a low-level primitive.
Consider using authenticated encryption, implemented by
-.Xr crypto_lock 3monocypher .
+.Xr crypto_aead_lock 3monocypher .
.Pp
The arguments are:
.Bl -tag -width Ds
crypto_wipe(in , 16);
.Ed
.Sh SEE ALSO
-.Xr crypto_lock 3monocypher ,
+.Xr crypto_aead_lock 3monocypher ,
.Xr crypto_wipe 3monocypher ,
.Xr intro 3monocypher
.Sh STANDARDS
authenticated encryption; see
.Xr crypto_blake2b 3monocypher
and
-.Xr crypto_lock 3monocypher .
+.Xr crypto_aead_lock 3monocypher .
.Ss Nonce reuse
Repeating a nonce with the same key exposes the XOR of two or more
plaintext messages, effectively destroying confidentiality.
.Sh NAME
.Nm crypto_ed25519_sign ,
.Nm crypto_ed25519_check ,
-.Nm crypto_ed25519_public_key
+.Nm crypto_ed25519_key_pair
+.Nm crypto_ed25519_ph_sign
+.Nm crypto_ed25519_ph_check
.Nd public key signatures
.Sh SYNOPSIS
.In monocypher-ed25519.h
.Pp
The arguments and security considerations are the same as those
described in
-.Xr crypto_sign 3monocypher .
+.Xr crypto_eddsa_sign 3monocypher .
.Pp
.Fn crypto_ed25519_ph_sign
and
then process the resulting
.Fa message_hash .
.Sh RETURN VALUES
-.Fn crypto_ed25519_public_key ,
+.Fn crypto_ed25519_key_pair ,
.Fn crypto_ed25519_sign ,
and
.Fn crypto_ed25519_ph_sign
.Sh SEE ALSO
.Xr crypto_eddsa_sign 3monocypher ,
.Xr crypto_x25519 3monocypher ,
-.Xr crypto_lock 3monocypher ,
+.Xr crypto_aead_lock 3monocypher ,
.Xr crypto_sha512 3monocypher ,
.Xr intro 3monocypher
.Sh STANDARDS
.Dt CRYPTO_SIGN 3MONOCYPHER
.Os
.Sh NAME
-.Nm crypto_sign ,
-.Nm crypto_check ,
-.Nm crypto_sign_public_key
+.Nm crypto_eddsa_sign
+.Nm crypto_eddsa_check
+.Nm crypto_eddsa_key_pair
+.Nm crypto_eddsa_to_x25519
+.Nm crypto_eddsa_trim_scalar
+.Nm crypto_eddsa_reduce
+.Nm crypto_eddsa_mul_add
+.Nm crypto_eddsa_scalarbase
+.Nm crypto_eddsa_check_equation
.Nd public key signatures
.Sh SYNOPSIS
.In monocypher.h
and
.Fn crypto_eddsa_check
provide EdDSA public key signatures and verification.
-.Fn crypto_sign_key_pair
+.Fn crypto_eddsa_key_pair
computes the private and public keys from a random seed.
The arguments are:
.Bl -tag -width Ds
.It Fa seed
Random seed, freshly generated and used only once.
It is automatically wiped by
-.Fn crypto_sign_key_pair .
+.Fn crypto_eddsa_key_pair .
See
.Xr intro 3monocypher
about random number generation (use your operating system's random
in this context refers to a
.Em point on Curve25519 .
This also means that these functions are not compatible with
-.Xr crypto_sign 3monocypher
+.Xr crypto_eddsa_sign 3monocypher
and related functions.
.Pp
.Fn crypto_elligator_rev
.Pp
Poly1305 is a low-level primitive.
Consider using authenticated encryption, implemented by
-.Xr crypto_lock 3monocypher .
+.Xr crypto_aead_lock 3monocypher .
.Pp
The arguments are:
.Bl -tag -width Ds
.Ed
.Sh SEE ALSO
.Xr crypto_blake2b 3monocypher ,
-.Xr crypto_lock 3monocypher ,
+.Xr crypto_aead_lock 3monocypher ,
.Xr crypto_verify16 3monocypher ,
.Xr intro 3monocypher
.Sh STANDARDS
Poly1305 is difficult to use correctly.
Do not use it unless you are absolutely sure what you are doing.
Use authenticated encryption instead; see
-.Xr crypto_lock 3monocypher .
+.Xr crypto_aead_lock 3monocypher .
If you are certain you do not want encryption, refer to
.Xr crypto_blake2b 3monocypher
on how to use BLAKE2b to generate message authentication codes.
.Em rest
of the stream to encrypt your message.
This is the approach used by
-.Xr crypto_lock_aead 3monocypher .
+.Xr crypto_aead_lock 3monocypher .
.Ss Protection against side channels
Use
.Xr crypto_verify16 3monocypher
Note that SHA-512 itself is not suitable for hashing passwords and
deriving keys from them;
use the
-.Xr crypto_argon2i 3monocypher
+.Xr crypto_argon2 3monocypher
family of functions for that purpose instead.
.Pp
SHA-512 is
.Ed
.Sh SEE ALSO
.Xr crypto_blake2b 3monocypher ,
-.Xr crypto_lock 3monocypher ,
+.Xr crypto_aead_lock 3monocypher ,
.Xr crypto_poly1305 3monocypher ,
.Xr intro 3monocypher
.Sh STANDARDS
it is important to artificially slow down attackers by using especially
computationally difficult hashing algorithms.
Monocypher therefore provides
-.Xr crypto_argon2i 3monocypher
+.Xr crypto_argon2 3monocypher
for password hashing and deriving keys from passwords.
.Pp
While HKDF and HMAC are proper key derivation functions (KDF),
Cryptographic operations often require comparison of secrets or values
derived from secrets.
Standard comparison functions like
-.Fn memcmp
+.Xr memcmp 3
tend to exit when they find the first difference, leaking information
through timing differences.
.Pp
.Fa b .
.Pp
When in doubt, prefer these functions over
-.Fn memcmp .
+.Xr memcmp 3 .
.Sh RETURN VALUES
These functions return 0 if the two memory chunks are the same and -1
otherwise.
Monocypher will wipe its context structs when finalizing an operation
such as signing or decrypting.
When using direct interfaces like
-.Xr crypto_lock 3monocypher ,
+.Xr crypto_aead_lock 3monocypher ,
these context structs are invisible to you.
However, they are exposed in incremental interfaces like
.Xr crypto_blake2b_init 3monocypher .
.Fn crypto_x25519_dirty_fast
uses multiple large temporary variables and functions that are
normally used internally for
-.Xr crypto_sign 3monocypher .
+.Xr crypto_eddsa_sign 3monocypher .
Accordingly, it uses both more stack memory and more code
(unless the signing code is already compiled in elsewhere).
.Fn crypto_x25519_dirty_small
--- /dev/null
+#! /bin/env python3
+
+# This file 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.
+#
+# SPDX-License-Identifier: BSD-2-Clause OR CC0-1.0
+#
+# ------------------------------------------------------------------------
+#
+# Copyright (c) 2023, Loup Vaillant
+# 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.
+#
+# ------------------------------------------------------------------------
+#
+# Written in 2023 by Loup Vaillant
+#
+# To the extent possible under law, the author(s) have dedicated all copyright
+# and related neighboring rights to this software to the public domain
+# worldwide. This software is distributed without any warranty.
+#
+# You should have received a copy of the CC0 Public Domain Dedication along
+# with this software. If not, see
+# <https://creativecommons.org/publicdomain/zero/1.0/>
+
+import sys
+
+def map_prepend(s, l):
+ return [s + ": " + x for x in l]
+
+def extract(lines, start='', sub=''):
+ return [line.split(' ')[1].strip()
+ for line in lines
+ if (line.startswith(start) and line.__contains__(sub))]
+
+def without(item, list):
+ return [x for x in list if x != item]
+
+def check_inside(lines, all_functions):
+ errors = []
+
+ no_history = []
+ in_history = False
+ for line in lines:
+ if line.startswith('.Sh HISTORY'): in_history = True
+ elif line.startswith('.Sh') : in_history = False
+ if not in_history : no_history.append(line)
+
+ nm = extract(no_history, '.Nm')
+ fo = extract(no_history, '.Fo')
+ fn = extract(no_history, '.Fn')
+ fn = without('arc4random_buf', sorted(set(fn)))
+
+ dupes_nm = sorted(set([x for x in nm if nm.count(x) > 1]))
+ dupes_fo = sorted(set([x for x in fo if fo.count(x) > 1]))
+
+ only_fo = [x for x in fo if nm .count(x) == 0]
+ only_nm = [x for x in nm if fo .count(x) == 0]
+ only_fn = [x for x in fn if fo .count(x) == 0]
+ no_src = [x for x in fn if all_functions.count(x) == 0]
+
+ if len(dupes_nm) > 0: errors.append('Duplicates in .Nm: ' + str(dupes_nm))
+ if len(dupes_fo) > 0: errors.append('Duplicates in .Fo: ' + str(dupes_fo))
+ if len(only_fo) > 0: errors.append('Missing in .Nm: ' + str(only_fo))
+ if len(only_nm) > 0: errors.append('Only in .Nm: ' + str(only_nm))
+ if len(only_fn) > 0: errors.append('Only in .Fn: ' + str(only_fn))
+ if len(no_src) > 0: errors.append('Not in sources: ' + str(no_src))
+
+ return errors
+
+def check_xr(lines, all_nm):
+ errors = []
+ xr = sorted(set(extract(lines, '.Xr', '3monocypher')))
+ dead_xr = [x for x in xr if all_nm.count(x) == 0]
+ if len(dead_xr) > 0:
+ errors.append('Dead .Xr: ' + str(dead_xr))
+ return errors
+
+# Every line from every doc file
+all_lines = {}
+for file_name in sys.argv[1:]:
+ name = file_name.split('.')[0]
+ with open(file_name) as file:
+ all_lines[name] = file.readlines()
+
+# All .Nm (to spot .Xr dead references)
+all_nm = []
+for lines in all_lines.values():
+ all_nm += extract(lines, '.Nm')
+
+# All functions from source files
+all_functions = [x.strip()for x in sys.stdin.readlines()]
+
+# Errors
+errors = []
+for name, lines in all_lines.items():
+ if name != "intro": # skip internal checks for the intro page
+ errors += map_prepend(name, check_inside(lines, all_functions))
+ errors += map_prepend(name, check_xr(lines, all_nm))
+
+# Undocumented functions
+undocumented = [x for x in all_functions if all_nm.count(x) == 0]
+if len(undocumented) > 0:
+ errors.append('Undocumented functions: ' + str(undocumented))
+
+# Print any error, then exit accordingly
+if len(errors) != 0:
+ for e in errors:
+ print(e)
+ exit(1)
mkdir -p html
cp style.css html/
+cat ../src/monocypher.h ../src/optional/monocypher-ed25519.h |\
+ egrep -v "^(//|\}| | |extern)" |\
+ grep crypto_ |\
+ sed 's|[a-z0-9_]* *\([a-z0-9_]*\).*|\1|' |\
+ ./doc_check.py *.3monocypher
+
for source in $(find . -name "*.3monocypher" | sed 's|^\./||' | sort)
do
name=$(echo "$source" | sed 's/.3monocypher//')
It provides functions for authenticated encryption, hashing, password
hashing and key derivation, key exchange, and public key signatures.
.Ss Authenticated encryption
-.Xr crypto_lock 3monocypher
+.Xr crypto_aead_lock 3monocypher
and
-.Xr crypto_unlock 3monocypher
+.Xr crypto_aead_unlock 3monocypher
use the ChaCha20 cipher and the Poly1305 one-time authenticator.
.Pp
ChaCha20 is a stream cipher based on a cryptographic hash function.
It is very fast and very simple.
.Pp
For specialised needs,
-.Xr crypto_chacha20 3monocypher
+.Xr crypto_chacha20_djb 3monocypher
and
.Xr crypto_poly1305 3monocypher
are available to implement constructions involving them.
Whenever possible,
-.Xr crypto_lock 3monocypher
+.Xr crypto_aead_lock 3monocypher
should be preferred, however.
.Ss Hashing
.Xr crypto_blake2b 3monocypher
It is immune to length extension attacks and provides a keyed mode
that makes it a safe, easy to use authenticator.
.Ss Password hashing and key derivation
-.Xr crypto_argon2i 3monocypher
+.Xr crypto_argon2 3monocypher
implements the Argon2i resource intensive hash algorithm,
which can be used to hash passwords for storage and to derive keys
from passwords.
.Pp
For specialised protocols that require indistinguishability from random
noise,
-.Xr crypto_curve_to_hidden 3monocypher
+.Xr crypto_elligator_rev 3monocypher
gives the option to disguise ephemeral (one-time use) X25519 public keys
as random noise.
.Ss Public key signatures
-.Xr crypto_sign 3monocypher
+.Xr crypto_eddsa_sign 3monocypher
and
-.Xr crypto_check 3monocypher
+.Xr crypto_eddsa_check 3monocypher
implement EdDSA, with Curve25519 and BLAKE2b.
This is the same as the more famous Ed25519, with SHA-512 replaced by
the faster and more secure BLAKE2b.
It is meant to erase secrets when they are no longer needed, to reduce
the chances of leaks.
.Ss Optional code
-If Monocypher was compiled and installed with
-.Dv USE_ED25519 ,
+If Monocypher was compiled and installed with the provided makefile,
SHA-512 functions become available as well.
See
.Xr crypto_ed25519_sign 3monocypher ,
-.Xr crypto_ed25519_sign_init_first_pass 3monocypher ,
-.Xr crypto_sha512 3monocypher ,
and
-.Xr crypto_hmac_sha512 3monocypher .
+.Xr crypto_sha512 3monocypher .
.Sh SEE ALSO
-.Xr crypto_argon2i 3monocypher ,
-.Xr crypto_argon2i_general 3monocypher ,
+.Xr crypto_aead_init_djb 3monocypher ,
+.Xr crypto_aead_init_ietf 3monocypher ,
+.Xr crypto_aead_init_x 3monocypher ,
+.Xr crypto_aead_lock 3monocypher ,
+.Xr crypto_aead_read 3monocypher ,
+.Xr crypto_aead_unlock 3monocypher ,
+.Xr crypto_aead_write 3monocypher ,
+.Xr crypto_argon2 3monocypher ,
.Xr crypto_blake2b 3monocypher ,
.Xr crypto_blake2b_final 3monocypher ,
-.Xr crypto_blake2b_general 3monocypher ,
-.Xr crypto_blake2b_general_init 3monocypher ,
.Xr crypto_blake2b_init 3monocypher ,
+.Xr crypto_blake2b_keyed 3monocypher ,
+.Xr crypto_blake2b_keyed_init 3monocypher ,
.Xr crypto_blake2b_update 3monocypher ,
-.Xr crypto_chacha20 3monocypher ,
-.Xr crypto_chacha20_ctr 3monocypher ,
-.Xr crypto_check 3monocypher ,
-.Xr crypto_curve_to_hidden 3monocypher ,
-.Xr crypto_from_eddsa_private 3monocypher ,
-.Xr crypto_from_eddsa_public 3monocypher ,
-.Xr crypto_hchacha20 3monocypher ,
-.Xr crypto_hidden_key_pair 3monocypher ,
-.Xr crypto_hidden_to_curve 3monocypher ,
-.Xr crypto_ietf_chacha20 3monocypher ,
-.Xr crypto_ietf_chacha20_ctr 3monocypher ,
-.Xr crypto_lock 3monocypher ,
-.Xr crypto_lock_aead 3monocypher ,
+.Xr crypto_chacha20_djb 3monocypher ,
+.Xr crypto_chacha20_h 3monocypher ,
+.Xr crypto_chacha20_ietf 3monocypher ,
+.Xr crypto_chacha20_x 3monocypher ,
+.Xr crypto_eddsa_check 3monocypher ,
+.Xr crypto_eddsa_check_equation 3monocypher ,
+.Xr crypto_eddsa_key_pair 3monocypher ,
+.Xr crypto_eddsa_mul_add 3monocypher ,
+.Xr crypto_eddsa_reduce 3monocypher ,
+.Xr crypto_eddsa_scalarbase 3monocypher ,
+.Xr crypto_eddsa_sign 3monocypher ,
+.Xr crypto_eddsa_to_x25519 3monocypher ,
+.Xr crypto_eddsa_trim_scalar 3monocypher ,
+.Xr crypto_elligator_key_pair 3monocypher ,
+.Xr crypto_elligator_map 3monocypher ,
+.Xr crypto_elligator_rev 3monocypher ,
.Xr crypto_poly1305 3monocypher ,
.Xr crypto_poly1305_final 3monocypher ,
.Xr crypto_poly1305_init 3monocypher ,
.Xr crypto_poly1305_update 3monocypher ,
-.Xr crypto_sign 3monocypher ,
-.Xr crypto_sign_public_key 3monocypher ,
-.Xr crypto_unlock 3monocypher ,
-.Xr crypto_unlock_aead 3monocypher ,
.Xr crypto_verify16 3monocypher ,
.Xr crypto_verify32 3monocypher ,
.Xr crypto_verify64 3monocypher ,
.Xr crypto_x25519_dirty_small 3monocypher ,
.Xr crypto_x25519_inverse 3monocypher ,
.Xr crypto_x25519_public_key 3monocypher ,
-.Xr crypto_xchacha20 3monocypher ,
-.Xr crypto_xchacha20_ctr 3monocypher
+.Xr crypto_x25519_to_eddsa 3monocypher
.Ss Optional code
-.Xr crypto_from_ed25519_private 3monocypher ,
-.Xr crypto_from_ed25519_public 3monocypher ,
.Xr crypto_ed25519_check 3monocypher ,
-.Xr crypto_ed25519_public_key 3monocypher ,
+.Xr crypto_ed25519_key_pair 3monocypher ,
+.Xr crypto_ed25519_ph_check 3monocypher ,
+.Xr crypto_ed25519_ph_sign 3monocypher ,
.Xr crypto_ed25519_sign 3monocypher ,
-.Xr crypto_hmac_sha512 3monocypher ,
-.Xr crypto_hmac_sha512_init 3monocypher ,
-.Xr crypto_hmac_sha512_update 3monocypher ,
-.Xr crypto_hmac_sha512_final 3monocypher
.Xr crypto_sha512 3monocypher ,
+.Xr crypto_sha512_final 3monocypher ,
+.Xr crypto_sha512_hkdf 3monocypher ,
+.Xr crypto_sha512_hkdf_expand 3monocypher ,
+.Xr crypto_sha512_hmac 3monocypher ,
+.Xr crypto_sha512_hmac_final 3monocypher ,
+.Xr crypto_sha512_hmac_init 3monocypher ,
+.Xr crypto_sha512_hmac_update 3monocypher ,
.Xr crypto_sha512_init 3monocypher ,
-.Xr crypto_sha512_update 3monocypher ,
-.Xr crypto_sha512_final 3monocypher
+.Xr crypto_sha512_update 3monocypher
.Sh SECURITY CONSIDERATIONS
Using cryptography securely is difficult.
Flaws that never manifest under normal use might be exploited by a
void crypto_sha512(uint8_t hash[64],
const uint8_t *message, size_t message_size);
-
// SHA 512 HMAC
// ------------
void crypto_sha512_hmac_init(crypto_sha512_hmac_ctx *ctx,
projects / Monocypher.git / commitdiff