chiark - git - mdw - secnet/blob - ed25519.h

   1 /* -*-c-*-
   2  *
   3  * The Ed25519 signature scheme
   4  *
   5  * (c) 2017 Straylight/Edgeware
   6  */
   7
   8 /*----- Licensing notice --------------------------------------------------*
   9  *
  10  * This file is part of secnet.
  11  * See README for full list of copyright holders.
  12  *
  13  * secnet is free software; you can redistribute it and/or modify it
  14  * under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version d of the License, or
  16  * (at your option) any later version.
  17  *
  18  * secnet is distributed in the hope that it will be useful, but
  19  * WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21  * General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * version 3 along with secnet; if not, see
  25  * https://www.gnu.org/licenses/gpl.html.
  26  *
  27  * This file was originally part of Catacomb, but has been automatically
  28  * modified for incorporation into secnet: see `import-catacomb-crypto'
  29  * for details.
  30  *
  31  * Catacomb is free software; you can redistribute it and/or modify
  32  * it under the terms of the GNU Library General Public License as
  33  * published by the Free Software Foundation; either version 2 of the
  34  * License, or (at your option) any later version.
  35  *
  36  * Catacomb is distributed in the hope that it will be useful,
  37  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  38  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  39  * GNU Library General Public License for more details.
  40  *
  41  * You should have received a copy of the GNU Library General Public
  42  * License along with Catacomb; if not, write to the Free
  43  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  44  * MA 02111-1307, USA.
  45  */
  46
  47 #ifndef CATACOMB_ED25519_H
  48 #define CATACOMB_ED25519_H
  49
  50 #ifdef __cplusplus
  51   extern "C" {
  52 #endif
  53
  54 /*----- Notes on the Ed25519 signature scheme -----------------------------*
  55  *
  56  * This is Ed25519, as described in Daniel J. Bernstein, Neils Duif, Tanja
  57  * Lange, Peter Schwabe, and Bo-Yin Yang, `High-speed high-security
  58  * signatures', CHES 2011, https://ed25519.cr.yp.to/ed25519-20110926.pdf
  59  *
  60  * Specifically, this code implements `PureEdDSA', according to the
  61  * definition in Daniel J. Bernstein, Simon Josefsson, Tanja Lange, Peter
  62  * Schwabe, and Bo-Yin Yang, `EdDSA for more curves',
  63  * https://ed25519.cr.yp.to/eddsa-20150704.pdf.  HashEdEDSA can be
  64  * implemented easily by presenting a hash of a message to the functions
  65  * here, as the message to be signed or verified.
  66  *
  67  * It also implements `Ed25519ctx' and `Ed25519ph' as described in RFC8032,
  68  * though in the latter case it assumes that you've already done the hashing
  69  * and have provided the hash as the `message' input.
  70  */
  71
  72 /*----- Header files ------------------------------------------------------*/
  73
  74 #include "fake-mLib-bits.h"
  75
  76 /*----- Important constants -----------------------------------------------*/
  77
  78 #define ED25519_KEYSZ 32u
  79 #define ED25519_PUBSZ 32u
  80 #define ED25519_SIGSZ 64u
  81
  82 #define ED25519_MAXPERSOSZ 255u
  83
  84 /*----- Functions provided ------------------------------------------------*/
  85
  86 /* --- @ed25519_pubkey@ --- *
  87  *
  88  * Arguments:   @octet K[ED25519_PUBSZ]@ = where to put the public key
  89  *              @const void *k@ = private key
  90  *              @size_t ksz@ = length of private key
  91  *
  92  * Returns:     ---
  93  *
  94  * Use:         Derives the public key from a private key.
  95  */
  96
  97 extern void ed25519_pubkey(octet /*K*/[ED25519_PUBSZ],
  98                            const void */*k*/, size_t /*ksz*/);
  99
 100 /* --- @ed25519_sign@, @ed25519ctx_sign@ --- *
 101  *
 102  * Arguments:   @octet sig[ED25519_SIGSZ]@ = where to put the signature
 103  *              @const void *k@ = private key
 104  *              @size_t ksz@ = length of private key
 105  *              @const octet K[ED25519_PUBSZ]@ = public key
 106  *              @int phflag@ = whether the `message' has been hashed already
 107  *              @const void *p@ = personalization string
 108  *              @size_t psz@ = length of personalization string
 109  *              @const void *m@ = message to sign
 110  *              @size_t msz@ = length of message
 111  *
 112  * Returns:     ---
 113  *
 114  * Use:         Signs a message.
 115  *
 116  *              In @ed25519ctx_sign@, if @phflag@ is @-1@ then you get plain
 117  *              old Ed25519: the personalization string pointer @p@ will be
 118  *              ignored.  If @phflag > 0@ then the `message' @m@ should be a
 119  *              SHA512 hash of the actual message.
 120  */
 121
 122 extern void ed25519ctx_sign(octet /*sig*/[ED25519_SIGSZ],
 123                             const void */*k*/, size_t /*ksz*/,
 124                             const octet /*K*/[ED25519_PUBSZ],
 125                             int /*phflag*/,
 126                             const void */*p*/, size_t /*psz*/,
 127                             const void */*m*/, size_t /*msz*/);
 128
 129 extern void ed25519_sign(octet /*sig*/[ED25519_SIGSZ],
 130                          const void */*k*/, size_t /*ksz*/,
 131                          const octet /*K*/[ED25519_PUBSZ],
 132                          const void */*m*/, size_t /*msz*/);
 133
 134 /* --- @ed25519_verify@, @ed25519ctx_verify@ --- *
 135  *
 136  * Arguments:   @const octet K[ED25519_PUBSZ]@ = public key
 137  *              @int phflag@ = whether the `message' has been hashed already
 138  *              @const void *p@ = personalization string
 139  *              @size_t psz@ = length of personalization string
 140  *              @const void *m@ = message to sign
 141  *              @size_t msz@ = length of message
 142  *              @const octet sig[ED25519_SIGSZ]@ = signature
 143  *
 144  * Returns:     Zero if OK, negative on failure.
 145  *
 146  * Use:         Verify a signature.
 147  *
 148  *              In @ed25519ctx_verify@, if @phflag@ is @-1@ then you get
 149  *              plain old Ed25519: the personalization string pointer @p@
 150  *              will be ignored.  If @phflag > 0@ then the `message' @m@
 151  *              should be a SHA512 hash of the actual message.
 152  */
 153
 154 extern int ed25519ctx_verify(const octet /*K*/[ED25519_PUBSZ],
 155                              int /*phflag*/,
 156                              const void */*p*/, size_t /*psz*/,
 157                              const void */*m*/, size_t /*msz*/,
 158                              const octet /*sig*/[ED25519_SIGSZ]);
 159
 160 extern int ed25519_verify(const octet /*K*/[ED25519_PUBSZ],
 161                           const void */*m*/, size_t /*msz*/,
 162                           const octet /*sig*/[ED25519_SIGSZ]);
 163
 164 /*----- That's all, folks -------------------------------------------------*/
 165
 166 #ifdef __cplusplus
 167   }
 168 #endif
 169
 170 #endif