1CRYPTO_SIGN(3MONOCYPHER)             LOCAL            CRYPTO_SIGN(3MONOCYPHER)
2

NAME

4     crypto_sign, crypto_check, crypto_sign_public_key — public key signatures
5

SYNOPSIS

7     #include <monocypher.h>
8
9     void
10     crypto_sign_public_key(uint8_t public_key[32],
11         const uint8_t secret_key[32]);
12
13     void
14     crypto_sign(uint8_t signature[64], const uint8_t secret_key[32],
15         const uint8_t public_key[32], const uint8_t *message,
16         size_t message_size);
17
18     int
19     crypto_check(const uint8_t signature[64], const uint8_t public_key[32],
20         const uint8_t *message, size_t message_size);
21

DESCRIPTION

23     crypto_sign() and crypto_check() provide EdDSA public key signatures and
24     verification.
25
26     The arguments are:
27
28     signature
29             The signature.
30
31     secret_key
32             A 32-byte random number, known only to you.  See
33             intro(3monocypher) about random number generation (use your oper‐
34             ating system's random number generator).  Do not use the same
35             private key for both signatures and key exchanges.  The public
36             keys are different, and revealing both may leak information.
37
38     public_key
39             The public key, generated from secret_key with
40             crypto_sign_public_key().
41
42     message
43             Message to sign.
44
45     message_size
46             Length of message, in bytes.
47
48     signature and message may overlap.
49
50     crypto_sign_public_key() computes the public key of the specified secret
51     key.
52
53     crypto_sign() signs a message with secret_key.  The public key is op‐
54     tional, and will be recomputed if not provided.  This recomputation dou‐
55     bles the execution time.
56
57     crypto_check() checks that a given signature is genuine.  Meaning, only
58     someone who had the private key could have signed the message.  It does
59     not run in constant time.  It does not have to in most threat models, be‐
60     cause nothing is secret: everyone knows the public key, and the signature
61     and message are rarely secret.  If the message needs to be secret, use
62     crypto_key_exchange(3monocypher) and crypto_lock_aead(3monocypher) in‐
63     stead.
64
65     An incremental interface is available; see
66     crypto_sign_init_first_pass(3monocypher).
67

RETURN VALUES

69     crypto_sign_public_key() and crypto_sign() return nothing.
70
71     crypto_check() returns 0 for legitimate messages and -1 for forgeries.
72

EXAMPLES

74     The following examples assume the existence of arc4random_buf(), which
75     fills the given buffer with cryptographically secure random bytes.  If
76     arc4random_buf() does not exist on your system, see intro(3monocypher)
77     for advice about how to generate cryptographically secure random bytes.
78
79     Generate a public key from a random secret key:
80
81           uint8_t       sk[32]; /* Random secret key   */
82           uint8_t       pk[32]; /* Matching public key */
83           arc4random_buf(sk, 32);
84           crypto_sign_public_key(pk, sk);
85           /* Wipe the secret key if it is no longer needed */
86           crypto_wipe(sk, 32);
87
88     Sign a message:
89
90           uint8_t       sk       [32]; /* Secret key from above          */
91           const uint8_t pk       [32]; /* Matching public key            */
92           const uint8_t message  [11] = "Lorem ipsu"; /* Message to sign */
93           uint8_t       signature[64];
94           crypto_sign(signature, sk, pk, message, 10);
95           /* Wipe the secret key if it is no longer needed */
96           crypto_wipe(sk, 32);
97
98     Check the above:
99
100           const uint8_t pk       [32]; /* Their public key              */
101           const uint8_t message  [11] = "Lorem ipsu"; /* Signed message */
102           const uint8_t signature[64]; /* Signature to check            */
103           if (crypto_check(signature, pk, message, 10)) {
104               /* Message is corrupted, abort processing */
105           } else {
106               /* Message is genuine */
107           }
108

SEE ALSO

110     crypto_blake2b(3monocypher), crypto_key_exchange(3monocypher),
111     crypto_lock(3monocypher), intro(3monocypher)
112

STANDARDS

114     These functions implement PureEdDSA with Curve25519 and Blake2b, as de‐
115     scribed in RFC 8032.  This is the same as Ed25519, with Blake2b instead
116     of SHA-512.
117

HISTORY

119     The crypto_sign(), crypto_check(), and crypto_sign_public_key() functions
120     appeared in Monocypher 0.2.
121
122     Starting with Monocypher 2.0.5, modified signatures abusing the inherent
123     signature malleability property of EdDSA now cause a non-zero return
124     value of crypto_check(); in prior versions, such signatures would be ac‐
125     cepted.
126
127     A critical security vulnerability that caused all-zero signatures to be
128     accepted was introduced in Monocypher 0.3; it was fixed in Monocypher
129     1.1.1 and 2.0.4.
130

SECURITY CONSIDERATIONS

132   Signature malleability
133     Signature malleability is the ability of an attacker to produce a valid
134     signature with knowledge of only an existing signature and the public
135     key.  That is, given a message, a signature and a public key, an attacker
136     could generate a new signature for the same message that is valid under
137     the same public key.  Monocypher prevents signature malleability by only
138     accepting signatures in canonical form.
139
140     On the other hand, EdDSA signatures are not unique like cryptographic
141     hashes.  The signing procedure is deterministic by specification and
142     crypto_sign() follows this specification.  However, someone with the pri‐
143     vate key can generate arbitrarily many valid, canonical, different signa‐
144     tures of the same message.  Because of this, never assume that signatures
145     are unique.
146
147   Fault injection and power analysis
148     Fault injection (also known as glitching) and power analysis may be used
149     to manipulate the resulting signature and recover the secret key in some
150     cases.  This requires hardware access.  If attackers are expected to have
151     such access and have the relevant equipment, you may try use the incre‐
152     mental interface provided by crypto_sign_init_first_pass(3monocypher) to
153     mitigate the side channel attacks.  Note that there may still be other
154     power-related side channels (such as if the CPU leaks information when an
155     operation overflows a register) that must be considered.
156
157BSD                           September 26, 2020                           BSD
Impressum