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