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

   1 /*
   2  * x25519.h: Bernstein's X25519 key-exchange function
   3  */
   4 /*
   5  * This file is Free Software.  It has been modified to as part of its
   6  * incorporation into secnet.
   7  *
   8  * Copyright 2017 Mark Wooding
   9  *
  10  * You may redistribute this file and/or modify it under the terms of
  11  * the permissive licence shown below.
  12  *
  13  * You may redistribute secnet as a whole and/or modify it under the
  14  * terms of the GNU General Public License as published by the Free
  15  * Software Foundation; either version 3, or (at your option) any
  16  * later version.
  17  *
  18  * This program is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with this program; if not, see
  25  * https://www.gnu.org/licenses/gpl.html.
  26  */
  27 /*
  28  * Imported from Catacomb, and modified for Secnet (2017-04-30):
  29  *
  30  *   * Use `fake-mLib-bits.h' in place of the real <mLib/bits.h>.
  31  *
  32  *   * Strip out the key-management definitions.
  33  *
  34  * The file's original comment headers are preserved below.
  35  */
  36 /* -*-c-*-
  37  *
  38  * The X25519 key-agreement algorithm
  39  *
  40  * (c) 2017 Straylight/Edgeware
  41  */
  42
  43 /*----- Licensing notice --------------------------------------------------*
  44  *
  45  * This file is part of Catacomb.
  46  *
  47  * Catacomb is free software; you can redistribute it and/or modify
  48  * it under the terms of the GNU Library General Public License as
  49  * published by the Free Software Foundation; either version 2 of the
  50  * License, or (at your option) any later version.
  51  *
  52  * Catacomb is distributed in the hope that it will be useful,
  53  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  54  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  55  * GNU Library General Public License for more details.
  56  *
  57  * You should have received a copy of the GNU Library General Public
  58  * License along with Catacomb; if not, write to the Free
  59  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  60  * MA 02111-1307, USA.
  61  */
  62
  63 #ifndef CATACOMB_X25519_H
  64 #define CATACOMB_X25519_H
  65
  66 #ifdef __cplusplus
  67   extern "C" {
  68 #endif
  69
  70 /*----- Notes on the X25519 key-agreement algorithm -----------------------*
  71  *
  72  * This is X25519, as described in Daniel J. Bernstein, `Curve25519: new
  73  * Diffie--Hellman speed records', PKC 2006,
  74  * https://cr.yp.to/ecdh/curve25519-20060209.pdf
  75  *
  76  * Since then, the name `Curve25519' has shifted somewhat, to refer to the
  77  * specific elliptic curve used, and the x-coordinate Diffie--Hellman
  78  * operation is now named `X25519'.
  79  */
  80
  81 /*----- Header files ------------------------------------------------------*/
  82
  83 #include "fake-mLib-bits.h"
  84
  85 /*----- Important constants -----------------------------------------------*/
  86
  87 #define X25519_KEYSZ 32u
  88 #define X25519_PUBSZ 32u
  89 #define X25519_OUTSZ 32u
  90
  91 extern const octet x25519_base[32];
  92
  93 /*----- Functions provided ------------------------------------------------*/
  94
  95 /* --- @x25519@ --- *
  96  *
  97  * Arguments:   @octet zz[X25519_OUTSZ]@ = where to put the result
  98  *              @const octet k[X25519_KEYSZ]@ = pointer to private key
  99  *              @const octet qx[X25519_PUBSZ]@ = pointer to public value
 100  *
 101  * Returns:     ---
 102  *
 103  * Use:         Calculates X25519 of @k@ and @qx@.
 104  *
 105  *              Note that there is disagreement over whether the most
 106  *              significant bit of @qx@ (i.e., the value @qx[31]&0x80@)
 107  *              should be ignored or counted towards the represented value.
 108  *              Historically implementations respected the bit; later
 109  *              convention seems to be to ignore it.  This implementation
 110  *              honours the bit: a caller who wants to ignore the bit can
 111  *              easily clear it, while caller who wants to respect it has a
 112  *              difficult job if this function ignores it.
 113  */
 114
 115 extern void x25519(octet /*zz*/[X25519_OUTSZ],
 116                    const octet /*k*/[X25519_KEYSZ],
 117                    const octet /*qx*/[X25519_PUBSZ]);
 118
 119 /*----- That's all, folks -------------------------------------------------*/
 120
 121 #ifdef __cplusplus
 122   }
 123 #endif
 124
 125 #endif