chiark - git - mdw - catacomb/blob - mgf.h

   1 /* -*-c-*-
   2  *
   3  * $Id: mgf.h,v 1.2 2004/04/08 01:36:15 mdw Exp $
   4  *
   5  * The MGF mask generation function
   6  *
   7  * (c) 2000 Straylight/Edgeware
   8  */
   9
  10 /*----- Licensing notice --------------------------------------------------*
  11  *
  12  * This file is part of Catacomb.
  13  *
  14  * Catacomb is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU Library General Public License as
  16  * published by the Free Software Foundation; either version 2 of the
  17  * License, or (at your option) any later version.
  18  *
  19  * Catacomb is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU Library General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU Library General Public
  25  * License along with Catacomb; if not, write to the Free
  26  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  27  * MA 02111-1307, USA.
  28  */
  29
  30 /*----- Notes on the MGF-1 mask generating function -----------------------*
  31  *
  32  * The idea of a mask-generating function is that given an input of arbitrary
  33  * size, it can emit a pseudorandom output `mask' of arbitrary size.  This is
  34  * used in PKCS#1 OAEP (RFC2437).  My recommendation would be to use a decent
  35  * stream cipher instead, like RC4 or SEAL.  MGF-1 isn't very fast.
  36  */
  37
  38 #ifndef CATACOMB_MGF_H
  39 #define CATACOMB_MGF_H
  40
  41 #ifdef __cplusplus
  42   extern "C" {
  43 #endif
  44
  45 /*----- Header files ------------------------------------------------------*/
  46
  47 #include <mLib/bits.h>
  48
  49 #ifndef CATACOMB_GCIPHER_H
  50 #  include "gcipher.h"
  51 #endif
  52
  53 #ifndef CATACOMB_GRAND_H
  54 #  include "grand.h"
  55 #endif
  56
  57 /*----- Macros ------------------------------------------------------------*/
  58
  59 #define MGF_DECL(PRE, pre)                                              \
  60                                                                         \
  61 /* --- An MGF generation context --- */                                 \
  62                                                                         \
  63 typedef struct pre##_mgfctx {                                           \
  64   pre##_ctx k;                          /* Underlying key context */    \
  65   uint32 c;                             /* Counter */                   \
  66   octet buf[PRE##_HASHSZ];              /* Output buffer */             \
  67   size_t bsz;                           /* Size of buffered data */     \
  68 } pre##_mgfctx;                                                         \
  69                                                                         \
  70 /* --- Other useful constants --- */                                    \
  71                                                                         \
  72 extern const octet pre##_mgfkeysz[];                                    \
  73                                                                         \
  74 /* --- @pre_mgfkeybegin@, @pre_mgfkeyadd@ --- *                         \
  75  *                                                                      \
  76  * Arguments:   @pre_mgfctx *k@ = pointer to context to initialize      \
  77  *              @const void *p@ = pointer to data to contribute         \
  78  *              @size_t sz@ = size of data to contribute                \
  79  *                                                                      \
  80  * Returns:     ---                                                     \
  81  *                                                                      \
  82  * Use:         A multi-step keying procedure for initializing an MGF   \
  83  *              context.  The data is contributed to a hashing context  \
  84  *              which is then used for mask generation.  If you only    \
  85  *              have a fixed buffer, you can save a lot of effort by    \
  86  *              simply calling @pre_mgfinit@.                           \
  87  */                                                                     \
  88                                                                         \
  89 extern void pre##_mgfkeybegin(pre##_mgfctx */*k*/);                     \
  90 extern void pre##_mgfkeyadd(pre##_mgfctx */*k*/,                        \
  91                             const void */*p*/, size_t /*sz*/);          \
  92                                                                         \
  93 /* ---- @pre_mgfinit@ --- *                                             \
  94  *                                                                      \
  95  * Arguments:   @pre_mgfctx *k@ = pointer to context to initialize      \
  96  *              @const void *p@ = pointer to data to contribute         \
  97  *              @size_t sz@ = size of data to contribute                \
  98  *                                                                      \
  99  * Returns:     ---                                                     \
 100  *                                                                      \
 101  * Use:         A simpler interface to initialization if all of your    \
 102  *              keying material is in one place.                        \
 103  */                                                                     \
 104                                                                         \
 105 extern void pre##_mgfinit(pre##_mgfctx */*k*/,                          \
 106                           const void */*p*/, size_t /*sz*/);            \
 107                                                                         \
 108 /* --- @pre_mgfencrypt@ --- *                                           \
 109  *                                                                      \
 110  * Arguments:   @pre_mgfctx *k@ = pointer to masking context            \
 111  *              @const void *s@ = pointer to source buffer              \
 112  *              @void *d@ = pointer to destination buffer               \
 113  *              @size_t sz@ = size of buffers                           \
 114  *                                                                      \
 115  * Returns:     ---                                                     \
 116  *                                                                      \
 117  * Use:         Outputs pseudorandom data, or masks an input buffer.    \
 118  *                                                                      \
 119  *              If @s@ is nonzero, the source material is exclusive-    \
 120  *              orred with the generated mask.  If @d@ is zero, the     \
 121  *              generator is simply spun around for a while, which      \
 122  *              isn't very useful.                                      \
 123  */                                                                     \
 124                                                                         \
 125 extern void pre##_mgfencrypt(pre##_mgfctx */*k*/, const void */*s*/,    \
 126                              void */*d*/, size_t /*sz*/);               \
 127                                                                         \
 128 /* --- @pre_mgfsetindex@ --- *                                          \
 129  *                                                                      \
 130  * Arguments:   @pre_mgfctx *k@ = pointer to masking context            \
 131  *              @uint32 *c@ = new index to set                          \
 132  *                                                                      \
 133  * Returns:     ---                                                     \
 134  *                                                                      \
 135  * Use:         Sets a new index.  This may be used to step around the  \
 136  *              output stream in a rather crude way.                    \
 137  */                                                                     \
 138                                                                         \
 139 extern void pre##_mgfsetindex(pre##_mgfctx */*k*/, uint32 /*c*/);       \
 140                                                                         \
 141 /* --- @pre_mgfrand@ --- *                                              \
 142  *                                                                      \
 143  * Arguments:   @const void *k@ = pointer to key material               \
 144  *              @size_t sz@ = size of key material                      \
 145  *                                                                      \
 146  * Returns:     Pointer to a generic random number generator instance.  \
 147  *                                                                      \
 148  * Use:         Creates a random number interface wrapper around an     \
 149  *              MGF-1-mode hash function.                               \
 150  */                                                                     \
 151                                                                         \
 152 extern grand *pre##_mgfrand(const void */*k*/, size_t /*sz*/);          \
 153                                                                         \
 154 /* --- Generic cipher interface --- */                                  \
 155                                                                         \
 156 extern const gccipher pre##_mgf;
 157
 158 /*----- That's all, folks -------------------------------------------------*/
 159
 160 #ifdef __cplusplus
 161   }
 162 #endif
 163
 164 #endif