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

   1 /* -*-c-*-
   2  *
   3  * $Id: mgf.h,v 1.1 2000/06/17 11:33:11 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 /*----- Revision history --------------------------------------------------*
  31  *
  32  * $Log: mgf.h,v $
  33  * Revision 1.1  2000/06/17 11:33:11  mdw
  34  * MGF-1 support, as defined in PKCS#1.
  35  *
  36  */
  37
  38 /*----- Notes on the MGF-1 mask generating function -----------------------*
  39  *
  40  * The idea of a mask-generating function is that given an input of arbitrary
  41  * size, it can emit a pseudorandom output `mask' of arbitrary size.  This is
  42  * used in PKCS#1 OAEP (RFC2437).  My recommendation would be to use a decent
  43  * stream cipher instead, like RC4 or SEAL.  MGF-1 isn't very fast.
  44  */
  45
  46 #ifndef CATACOMB_MGF_H
  47 #define CATACOMB_MGF_H
  48
  49 #ifdef __cplusplus
  50   extern "C" {
  51 #endif
  52
  53 /*----- Header files ------------------------------------------------------*/
  54
  55 #include <mLib/bits.h>
  56
  57 #ifndef CATACOMB_GCIPHER_H
  58 #  include "gcipher.h"
  59 #endif
  60
  61 #ifndef CATACOMB_GRAND_H
  62 #  include "grand.h"
  63 #endif
  64
  65 /*----- Macros ------------------------------------------------------------*/
  66
  67 #define MGF_DECL(PRE, pre)                                              \
  68                                                                         \
  69 /* --- An MGF generation context --- */                                 \
  70                                                                         \
  71 typedef struct pre##_mgfctx {                                           \
  72   pre##_ctx k;                          /* Underlying key context */    \
  73   uint32 c;                             /* Counter */                   \
  74   octet buf[PRE##_HASHSZ];              /* Output buffer */             \
  75   size_t bsz;                           /* Size of buffered data */     \
  76 } pre##_mgfctx;                                                         \
  77                                                                         \
  78 /* --- Other useful constants --- */                                    \
  79                                                                         \
  80 extern const octet pre##_mgfkeysz[];                                    \
  81                                                                         \
  82 /* --- @pre_mgfkeybegin@, @pre_mgfkeyadd@ --- *                         \
  83  *                                                                      \
  84  * Arguments:   @pre_mgfctx *k@ = pointer to context to initialize      \
  85  *              @const void *p@ = pointer to data to contribute         \
  86  *              @size_t sz@ = size of data to contribute                \
  87  *                                                                      \
  88  * Returns:     ---                                                     \
  89  *                                                                      \
  90  * Use:         A multi-step keying procedure for initializing an MGF   \
  91  *              context.  The data is contributed to a hashing context  \
  92  *              which is then used for mask generation.  If you only    \
  93  *              have a fixed buffer, you can save a lot of effort by    \
  94  *              simply calling @pre_mgfinit@.                           \
  95  */                                                                     \
  96                                                                         \
  97 extern void pre##_mgfkeybegin(pre##_mgfctx */*k*/);                     \
  98 extern void pre##_mgfkeyadd(pre##_mgfctx */*k*/,                        \
  99                             const void */*p*/, size_t /*sz*/);          \
 100                                                                         \
 101 /* ---- @pre_mgfinit@ --- *                                             \
 102  *                                                                      \
 103  * Arguments:   @pre_mgfctx *k@ = pointer to context to initialize      \
 104  *              @const void *p@ = pointer to data to contribute         \
 105  *              @size_t sz@ = size of data to contribute                \
 106  *                                                                      \
 107  * Returns:     ---                                                     \
 108  *                                                                      \
 109  * Use:         A simpler interface to initialization if all of your    \
 110  *              keying material is in one place.                        \
 111  */                                                                     \
 112                                                                         \
 113 extern void pre##_mgfinit(pre##_mgfctx */*k*/,                          \
 114                           const void */*p*/, size_t /*sz*/);            \
 115                                                                         \
 116 /* --- @pre_mgfencrypt@ --- *                                           \
 117  *                                                                      \
 118  * Arguments:   @pre_mgfctx *k@ = pointer to masking context            \
 119  *              @const void *s@ = pointer to source buffer              \
 120  *              @void *d@ = pointer to destination buffer               \
 121  *              @size_t sz@ = size of buffers                           \
 122  *                                                                      \
 123  * Returns:     ---                                                     \
 124  *                                                                      \
 125  * Use:         Outputs pseudorandom data, or masks an input buffer.    \
 126  *                                                                      \
 127  *              If @s@ is nonzero, the source material is exclusive-    \
 128  *              orred with the generated mask.  If @d@ is zero, the     \
 129  *              generator is simply spun around for a while, which      \
 130  *              isn't very useful.                                      \
 131  */                                                                     \
 132                                                                         \
 133 extern void pre##_mgfencrypt(pre##_mgfctx */*k*/, const void */*s*/,    \
 134                              void */*d*/, size_t /*sz*/);               \
 135                                                                         \
 136 /* --- @pre_mgfsetindex@ --- *                                          \
 137  *                                                                      \
 138  * Arguments:   @pre_mgfctx *k@ = pointer to masking context            \
 139  *              @uint32 *c@ = new index to set                          \
 140  *                                                                      \
 141  * Returns:     ---                                                     \
 142  *                                                                      \
 143  * Use:         Sets a new index.  This may be used to step around the  \
 144  *              output stream in a rather crude way.                    \
 145  */                                                                     \
 146                                                                         \
 147 extern void pre##_mgfsetindex(pre##_mgfctx */*k*/, uint32 /*c*/);       \
 148                                                                         \
 149 /* --- @pre_mgfrand@ --- *                                              \
 150  *                                                                      \
 151  * Arguments:   @const void *k@ = pointer to key material               \
 152  *              @size_t sz@ = size of key material                      \
 153  *                                                                      \
 154  * Returns:     Pointer to a generic random number generator instance.  \
 155  *                                                                      \
 156  * Use:         Creates a random number interface wrapper around an     \
 157  *              MGF-1-mode hash function.                               \
 158  */                                                                     \
 159                                                                         \
 160 extern grand *pre##_mgfrand(const void */*k*/, size_t /*sz*/);          \
 161                                                                         \
 162 /* --- Generic cipher interface --- */                                  \
 163                                                                         \
 164 extern const gccipher pre##_mgf;
 165
 166 /*----- That's all, folks -------------------------------------------------*/
 167
 168 #ifdef __cplusplus
 169   }
 170 #endif
 171
 172 #endif