sha3/sph_skein.h

   1 /* $Id: sph_skein.h 253 2011-06-07 18:33:10Z tp $ */
   2 /**
   3  * Skein interface. The Skein specification defines three main
   4  * functions, called Skein-256, Skein-512 and Skein-1024, which can be
   5  * further parameterized with an output length. For the SHA-3
   6  * competition, Skein-512 is used for output sizes of 224, 256, 384 and
   7  * 512 bits; this is what this code implements. Thus, we hereafter call
   8  * Skein-224, Skein-256, Skein-384 and Skein-512 what the Skein
   9  * specification defines as Skein-512-224, Skein-512-256, Skein-512-384
  10  * and Skein-512-512, respectively.
  11  *
  12  * ==========================(LICENSE BEGIN)============================
  13  *
  14  * Copyright (c) 2007-2010  Projet RNRT SAPHIR
  15  *
  16  * Permission is hereby granted, free of charge, to any person obtaining
  17  * a copy of this software and associated documentation files (the
  18  * "Software"), to deal in the Software without restriction, including
  19  * without limitation the rights to use, copy, modify, merge, publish,
  20  * distribute, sublicense, and/or sell copies of the Software, and to
  21  * permit persons to whom the Software is furnished to do so, subject to
  22  * the following conditions:
  23  *
  24  * The above copyright notice and this permission notice shall be
  25  * included in all copies or substantial portions of the Software.
  26  *
  27  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  28  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  29  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  30  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  31  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  32  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  33  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  34  *
  35  * ===========================(LICENSE END)=============================
  36  *
  37  * @file     sph_skein.h
  38  * @author   Thomas Pornin <[email protected]>
  39  */
  40
  41 #ifndef SPH_SKEIN_H__
  42 #define SPH_SKEIN_H__
  43
  44 #ifdef __cplusplus
  45 extern "C"{
  46 #endif
  47
  48 #include <stddef.h>
  49 #include "sph_types.h"
  50
  51 #if SPH_64
  52
  53 /**
  54  * Output size (in bits) for Skein-224.
  55  */
  56 #define SPH_SIZE_skein224   224
  57
  58 /**
  59  * Output size (in bits) for Skein-256.
  60  */
  61 #define SPH_SIZE_skein256   256
  62
  63 /**
  64  * Output size (in bits) for Skein-384.
  65  */
  66 #define SPH_SIZE_skein384   384
  67
  68 /**
  69  * Output size (in bits) for Skein-512.
  70  */
  71 #define SPH_SIZE_skein512   512
  72
  73 /**
  74  * This structure is a context for Skein computations (with a 384- or
  75  * 512-bit output): it contains the intermediate values and some data
  76  * from the last entered block. Once a Skein computation has been
  77  * performed, the context can be reused for another computation.
  78  *
  79  * The contents of this structure are private. A running Skein computation
  80  * can be cloned by copying the context (e.g. with a simple
  81  * <code>memcpy()</code>).
  82  */
  83 typedef struct {
  84 #ifndef DOXYGEN_IGNORE
  85         unsigned char buf[64];    /* first field, for alignment */
  86         size_t ptr;
  87         sph_u64 h0, h1, h2, h3, h4, h5, h6, h7;
  88         sph_u64 bcount;
  89 #endif
  90 } sph_skein_big_context;
  91
  92 /**
  93  * Type for a Skein-224 context (identical to the common "big" context).
  94  */
  95 typedef sph_skein_big_context sph_skein224_context;
  96
  97 /**
  98  * Type for a Skein-256 context (identical to the common "big" context).
  99  */
 100 typedef sph_skein_big_context sph_skein256_context;
 101
 102 /**
 103  * Type for a Skein-384 context (identical to the common "big" context).
 104  */
 105 typedef sph_skein_big_context sph_skein384_context;
 106
 107 /**
 108  * Type for a Skein-512 context (identical to the common "big" context).
 109  */
 110 typedef sph_skein_big_context sph_skein512_context;
 111
 112 /**
 113  * Initialize a Skein-224 context. This process performs no memory allocation.
 114  *
 115  * @param cc   the Skein-224 context (pointer to a
 116  *             <code>sph_skein224_context</code>)
 117  */
 118 void sph_skein224_init(void *cc);
 119
 120 /**
 121  * Process some data bytes. It is acceptable that <code>len</code> is zero
 122  * (in which case this function does nothing).
 123  *
 124  * @param cc     the Skein-224 context
 125  * @param data   the input data
 126  * @param len    the input data length (in bytes)
 127  */
 128 void sph_skein224(void *cc, const void *data, size_t len);
 129
 130 /**
 131  * Terminate the current Skein-224 computation and output the result into
 132  * the provided buffer. The destination buffer must be wide enough to
 133  * accomodate the result (28 bytes). The context is automatically
 134  * reinitialized.
 135  *
 136  * @param cc    the Skein-224 context
 137  * @param dst   the destination buffer
 138  */
 139 void sph_skein224_close(void *cc, void *dst);
 140
 141 /**
 142  * Add a few additional bits (0 to 7) to the current computation, then
 143  * terminate it and output the result in the provided buffer, which must
 144  * be wide enough to accomodate the result (28 bytes). If bit number i
 145  * in <code>ub</code> has value 2^i, then the extra bits are those
 146  * numbered 7 downto 8-n (this is the big-endian convention at the byte
 147  * level). The context is automatically reinitialized.
 148  *
 149  * @param cc    the Skein-224 context
 150  * @param ub    the extra bits
 151  * @param n     the number of extra bits (0 to 7)
 152  * @param dst   the destination buffer
 153  */
 154 void sph_skein224_addbits_and_close(
 155         void *cc, unsigned ub, unsigned n, void *dst);
 156
 157 /**
 158  * Initialize a Skein-256 context. This process performs no memory allocation.
 159  *
 160  * @param cc   the Skein-256 context (pointer to a
 161  *             <code>sph_skein256_context</code>)
 162  */
 163 void sph_skein256_init(void *cc);
 164
 165 /**
 166  * Process some data bytes. It is acceptable that <code>len</code> is zero
 167  * (in which case this function does nothing).
 168  *
 169  * @param cc     the Skein-256 context
 170  * @param data   the input data
 171  * @param len    the input data length (in bytes)
 172  */
 173 void sph_skein256(void *cc, const void *data, size_t len);
 174
 175 /**
 176  * Terminate the current Skein-256 computation and output the result into
 177  * the provided buffer. The destination buffer must be wide enough to
 178  * accomodate the result (32 bytes). The context is automatically
 179  * reinitialized.
 180  *
 181  * @param cc    the Skein-256 context
 182  * @param dst   the destination buffer
 183  */
 184 void sph_skein256_close(void *cc, void *dst);
 185
 186 /**
 187  * Add a few additional bits (0 to 7) to the current computation, then
 188  * terminate it and output the result in the provided buffer, which must
 189  * be wide enough to accomodate the result (32 bytes). If bit number i
 190  * in <code>ub</code> has value 2^i, then the extra bits are those
 191  * numbered 7 downto 8-n (this is the big-endian convention at the byte
 192  * level). The context is automatically reinitialized.
 193  *
 194  * @param cc    the Skein-256 context
 195  * @param ub    the extra bits
 196  * @param n     the number of extra bits (0 to 7)
 197  * @param dst   the destination buffer
 198  */
 199 void sph_skein256_addbits_and_close(
 200         void *cc, unsigned ub, unsigned n, void *dst);
 201
 202 /**
 203  * Initialize a Skein-384 context. This process performs no memory allocation.
 204  *
 205  * @param cc   the Skein-384 context (pointer to a
 206  *             <code>sph_skein384_context</code>)
 207  */
 208 void sph_skein384_init(void *cc);
 209
 210 /**
 211  * Process some data bytes. It is acceptable that <code>len</code> is zero
 212  * (in which case this function does nothing).
 213  *
 214  * @param cc     the Skein-384 context
 215  * @param data   the input data
 216  * @param len    the input data length (in bytes)
 217  */
 218 void sph_skein384(void *cc, const void *data, size_t len);
 219
 220 /**
 221  * Terminate the current Skein-384 computation and output the result into
 222  * the provided buffer. The destination buffer must be wide enough to
 223  * accomodate the result (48 bytes). The context is automatically
 224  * reinitialized.
 225  *
 226  * @param cc    the Skein-384 context
 227  * @param dst   the destination buffer
 228  */
 229 void sph_skein384_close(void *cc, void *dst);
 230
 231 /**
 232  * Add a few additional bits (0 to 7) to the current computation, then
 233  * terminate it and output the result in the provided buffer, which must
 234  * be wide enough to accomodate the result (48 bytes). If bit number i
 235  * in <code>ub</code> has value 2^i, then the extra bits are those
 236  * numbered 7 downto 8-n (this is the big-endian convention at the byte
 237  * level). The context is automatically reinitialized.
 238  *
 239  * @param cc    the Skein-384 context
 240  * @param ub    the extra bits
 241  * @param n     the number of extra bits (0 to 7)
 242  * @param dst   the destination buffer
 243  */
 244 void sph_skein384_addbits_and_close(
 245         void *cc, unsigned ub, unsigned n, void *dst);
 246
 247 /**
 248  * Initialize a Skein-512 context. This process performs no memory allocation.
 249  *
 250  * @param cc   the Skein-512 context (pointer to a
 251  *             <code>sph_skein512_context</code>)
 252  */
 253 void sph_skein512_init(void *cc);
 254
 255 /**
 256  * Process some data bytes. It is acceptable that <code>len</code> is zero
 257  * (in which case this function does nothing).
 258  *
 259  * @param cc     the Skein-512 context
 260  * @param data   the input data
 261  * @param len    the input data length (in bytes)
 262  */
 263 void sph_skein512(void *cc, const void *data, size_t len);
 264
 265 /**
 266  * Terminate the current Skein-512 computation and output the result into
 267  * the provided buffer. The destination buffer must be wide enough to
 268  * accomodate the result (64 bytes). The context is automatically
 269  * reinitialized.
 270  *
 271  * @param cc    the Skein-512 context
 272  * @param dst   the destination buffer
 273  */
 274 void sph_skein512_close(void *cc, void *dst);
 275
 276 /**
 277  * Add a few additional bits (0 to 7) to the current computation, then
 278  * terminate it and output the result in the provided buffer, which must
 279  * be wide enough to accomodate the result (64 bytes). If bit number i
 280  * in <code>ub</code> has value 2^i, then the extra bits are those
 281  * numbered 7 downto 8-n (this is the big-endian convention at the byte
 282  * level). The context is automatically reinitialized.
 283  *
 284  * @param cc    the Skein-512 context
 285  * @param ub    the extra bits
 286  * @param n     the number of extra bits (0 to 7)
 287  * @param dst   the destination buffer
 288  */
 289 void sph_skein512_addbits_and_close(
 290         void *cc, unsigned ub, unsigned n, void *dst);
 291
 292 #endif
 293
 294 #ifdef __cplusplus
 295 }
 296 #endif
 297
 298 #endif