chiark - git - mdw - catacomb/blob - base/ct.h

   1 /* -*-c-*-
   2  *
   3  * Constant-time operations
   4  *
   5  * (c) 2013 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_CT_H
  29 #define CATACOMB_CT_H
  30
  31 #ifdef __cplusplus
  32   extern "C" {
  33 #endif
  34
  35 /*----- Header files ------------------------------------------------------*/
  36
  37 #include <mLib/bits.h>
  38
  39 /*----- Miscellaneous constant-time utilities -----------------------------*/
  40
  41 /* --- @ct_inteq@ --- *
  42  *
  43  * Arguments:   @uint32 x, y@ = two 32-bit unsigned integers
  44  *
  45  * Returns:     One if @x@ and @y@ are equal, zero if they differ.
  46  *
  47  * Use:         Answers whether two integers are equal, in constant time.
  48  */
  49
  50 extern int ct_inteq(uint32 /*x*/, uint32 /*y*/);
  51
  52 /* --- @ct_intle@ --- *
  53  *
  54  * Arguments:   @uint32 x, y@ = two 32-bit unsigned integers
  55  *
  56  * Returns:     One if %$x \le y$%, zero if @x@ is greater.
  57  *
  58  * Use:         Answers whether two integers are ordered, in constant time.
  59  */
  60
  61 extern int ct_intle(uint32 /*x*/, uint32 /*y*/);
  62
  63 /* --- @ct_pick@ --- *
  64  *
  65  * Arguments:   @uint32 a@ = a switch, either zero or one
  66  *              @uint32 x0, x1@ = two 32-bit unsigned integers
  67  *
  68  * Returns:     @x0@ if @a@ is zero; @x1@ if @a@ is one.  Other values of @a@
  69  *              will give you unhelpful results.
  70  *
  71  * Use:         Picks one of two results according to a switch variable, in
  72  *              constant time.
  73  */
  74
  75 extern int ct_pick(uint32 /*a*/, uint32 /*x0*/, uint32 /*x1*/);
  76
  77 /* --- @ct_condcopy@ --- *
  78  *
  79  * Arguments:   @uint32 a@ = a switch, either zero or one
  80  *              @void *d@ = destination pointer
  81  *              @const void *s@ = source pointer
  82  *              @size_t n@ amount to copy
  83  *
  84  * Returns:     ---
  85  *
  86  * Use:         If @a@ is one then copy the @n@ bytes starting at @s@ to
  87  *              @d@; if @a@ is zero then leave @d@ unchanged (but it will
  88  *              still be written).  All of this is done in constant time.
  89  */
  90
  91 extern void ct_condcopy(uint32 /*a*/,
  92                         void */*d*/, const void */*s*/, size_t /*n*/);
  93
  94 /* --- @ct_memeq@ ---
  95  *
  96  * Arguments:   @const void *p, *q@ = two pointers to buffers
  97  *              @size_t n@ = the (common) size of the buffers
  98  *
  99  * Returns:     One if the two buffers are equal, zero if they aren't.
 100  *
 101  * Use:         Compares two chunks of memory, in constant time.
 102  */
 103
 104 extern int ct_memeq(const void */*p*/, const void */*q*/, size_t /*n*/);
 105
 106 /*----- Utilities for testing ---------------------------------------------*/
 107
 108 /* --- @ct_poison@ --- *
 109  *
 110  * Arguments:   @const void *p@ = pointer to a secret
 111  *              @size_t sz@ = size of the secret
 112  *
 113  * Returns:     ---
 114  *
 115  * Use:         Ordinarily, does nothing.  If the process is running under
 116  *              the control of Valgrind's `memcheck' utility, then mark the
 117  *              secret as `uninitialized', so that Valgrind warns about
 118  *              conditional execution or memory addressing based on the value
 119  *              of the secret.
 120  *
 121  *              Credit for this idea goes to Adam Langley, who described it
 122  *              in https://www.imperialviolet.org/2010/04/01/ctgrind.html,
 123  *              though this implementation doesn't require patching Valgrind.
 124  */
 125
 126 extern void ct_poison(const void */*p*/, size_t /*sz*/);
 127
 128 /* --- @ct_remedy@ --- *
 129  *
 130  * Arguments:   @const void *p@ = pointer to a secret
 131  *              @size_t sz@ = size of the secret
 132  *
 133  * Returns:     ---
 134  *
 135  * Use:         Ordinarily, does nothing.  If the process is running under
 136  *              the control of Valgrind's `memcheck' utility, then mark the
 137  *              secret as `initialized'.  This is intended to reverse the
 138  *              effect of @ct_poison@ so that a test program can verify
 139  *              function outputs wihtout Valgrind warning.
 140  */
 141
 142 extern void ct_remedy(const void */*p*/, size_t /*sz*/);
 143
 144 /*----- That's all, folks -------------------------------------------------*/
 145
 146 #ifdef __cplusplus
 147   }
 148 #endif
 149
 150 #endif