include/sys/skein.h

   1 /*
   2  * Interface declarations for Skein hashing.
   3  * Source code author: Doug Whiting, 2008.
   4  * This algorithm and source code is released to the public domain.
   5  *
   6  * The following compile-time switches may be defined to control some
   7  * tradeoffs between speed, code size, error checking, and security.
   8  *
   9  * The "default" note explains what happens when the switch is not defined.
  10  *
  11  *  SKEIN_DEBUG            -- make callouts from inside Skein code
  12  *                            to examine/display intermediate values.
  13  *                            [default: no callouts (no overhead)]
  14  *
  15  *  SKEIN_ERR_CHECK        -- how error checking is handled inside Skein
  16  *                            code. If not defined, most error checking
  17  *                            is disabled (for performance). Otherwise,
  18  *                            the switch value is interpreted as:
  19  *                                0: use assert()      to flag errors
  20  *                                1: return SKEIN_FAIL to flag errors
  21  */
  22 /* Copyright 2013 Doug Whiting. This code is released to the public domain. */
  23 #ifndef _SYS_SKEIN_H_
  24 #define _SYS_SKEIN_H_
  25
  26 #ifdef  _KERNEL
  27 #include <sys/types.h>          /* get size_t definition */
  28 #else
  29 #include <stdint.h>
  30 #include <stdlib.h>
  31 #endif
  32
  33 #ifdef  __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 enum {
  38         SKEIN_SUCCESS = 0,      /* return codes from Skein calls */
  39         SKEIN_FAIL = 1,
  40         SKEIN_BAD_HASHLEN = 2
  41 };
  42
  43 #define SKEIN_MODIFIER_WORDS    (2)     /* number of modifier (tweak) words */
  44
  45 #define SKEIN_256_STATE_WORDS   (4)
  46 #define SKEIN_512_STATE_WORDS   (8)
  47 #define SKEIN1024_STATE_WORDS   (16)
  48 #define SKEIN_MAX_STATE_WORDS   (16)
  49
  50 #define SKEIN_256_STATE_BYTES   (8 * SKEIN_256_STATE_WORDS)
  51 #define SKEIN_512_STATE_BYTES   (8 * SKEIN_512_STATE_WORDS)
  52 #define SKEIN1024_STATE_BYTES   (8 * SKEIN1024_STATE_WORDS)
  53
  54 #define SKEIN_256_STATE_BITS    (64 * SKEIN_256_STATE_WORDS)
  55 #define SKEIN_512_STATE_BITS    (64 * SKEIN_512_STATE_WORDS)
  56 #define SKEIN1024_STATE_BITS    (64 * SKEIN1024_STATE_WORDS)
  57
  58 #define SKEIN_256_BLOCK_BYTES   (8 * SKEIN_256_STATE_WORDS)
  59 #define SKEIN_512_BLOCK_BYTES   (8 * SKEIN_512_STATE_WORDS)
  60 #define SKEIN1024_BLOCK_BYTES   (8 * SKEIN1024_STATE_WORDS)
  61
  62 typedef struct {
  63         size_t hashBitLen;      /* size of hash result, in bits */
  64         size_t bCnt;            /* current byte count in buffer b[] */
  65         /* tweak words: T[0]=byte cnt, T[1]=flags */
  66         uint64_t T[SKEIN_MODIFIER_WORDS];
  67 } Skein_Ctxt_Hdr_t;
  68
  69 typedef struct {                /*  256-bit Skein hash context structure */
  70         Skein_Ctxt_Hdr_t h;     /* common header context variables */
  71         uint64_t X[SKEIN_256_STATE_WORDS];      /* chaining variables */
  72         /* partial block buffer (8-byte aligned) */
  73         uint8_t b[SKEIN_256_BLOCK_BYTES];
  74 } Skein_256_Ctxt_t;
  75
  76 typedef struct {                /*  512-bit Skein hash context structure */
  77         Skein_Ctxt_Hdr_t h;     /* common header context variables */
  78         uint64_t X[SKEIN_512_STATE_WORDS];      /* chaining variables */
  79         /* partial block buffer (8-byte aligned) */
  80         uint8_t b[SKEIN_512_BLOCK_BYTES];
  81 } Skein_512_Ctxt_t;
  82
  83 typedef struct {                /* 1024-bit Skein hash context structure */
  84         Skein_Ctxt_Hdr_t h;     /* common header context variables */
  85         uint64_t X[SKEIN1024_STATE_WORDS];      /* chaining variables */
  86         /* partial block buffer (8-byte aligned) */
  87         uint8_t b[SKEIN1024_BLOCK_BYTES];
  88 } Skein1024_Ctxt_t;
  89
  90 /*   Skein APIs for (incremental) "straight hashing" */
  91 int Skein_256_Init(Skein_256_Ctxt_t *ctx, size_t hashBitLen);
  92 int Skein_512_Init(Skein_512_Ctxt_t *ctx, size_t hashBitLen);
  93 int Skein1024_Init(Skein1024_Ctxt_t *ctx, size_t hashBitLen);
  94
  95 int Skein_256_Update(Skein_256_Ctxt_t *ctx, const uint8_t *msg,
  96     size_t msgByteCnt);
  97 int Skein_512_Update(Skein_512_Ctxt_t *ctx, const uint8_t *msg,
  98     size_t msgByteCnt);
  99 int Skein1024_Update(Skein1024_Ctxt_t *ctx, const uint8_t *msg,
 100     size_t msgByteCnt);
 101
 102 int Skein_256_Final(Skein_256_Ctxt_t *ctx, uint8_t *hashVal);
 103 int Skein_512_Final(Skein_512_Ctxt_t *ctx, uint8_t *hashVal);
 104 int Skein1024_Final(Skein1024_Ctxt_t *ctx, uint8_t *hashVal);
 105
 106 /*
 107  * Skein APIs for "extended" initialization: MAC keys, tree hashing.
 108  * After an InitExt() call, just use Update/Final calls as with Init().
 109  *
 110  * Notes: Same parameters as _Init() calls, plus treeInfo/key/keyBytes.
 111  *          When keyBytes == 0 and treeInfo == SKEIN_SEQUENTIAL,
 112  *              the results of InitExt() are identical to calling Init().
 113  *          The function Init() may be called once to "precompute" the IV for
 114  *              a given hashBitLen value, then by saving a copy of the context
 115  *              the IV computation may be avoided in later calls.
 116  *          Similarly, the function InitExt() may be called once per MAC key
 117  *              to precompute the MAC IV, then a copy of the context saved and
 118  *              reused for each new MAC computation.
 119  */
 120 int Skein_256_InitExt(Skein_256_Ctxt_t *ctx, size_t hashBitLen,
 121     uint64_t treeInfo, const uint8_t *key, size_t keyBytes);
 122 int Skein_512_InitExt(Skein_512_Ctxt_t *ctx, size_t hashBitLen,
 123     uint64_t treeInfo, const uint8_t *key, size_t keyBytes);
 124 int Skein1024_InitExt(Skein1024_Ctxt_t *ctx, size_t hashBitLen,
 125     uint64_t treeInfo, const uint8_t *key, size_t keyBytes);
 126
 127 /*
 128  * Skein APIs for MAC and tree hash:
 129  *      Final_Pad: pad, do final block, but no OUTPUT type
 130  *      Output:    do just the output stage
 131  */
 132 int Skein_256_Final_Pad(Skein_256_Ctxt_t *ctx, uint8_t *hashVal);
 133 int Skein_512_Final_Pad(Skein_512_Ctxt_t *ctx, uint8_t *hashVal);
 134 int Skein1024_Final_Pad(Skein1024_Ctxt_t *ctx, uint8_t *hashVal);
 135
 136 #ifndef SKEIN_TREE_HASH
 137 #define SKEIN_TREE_HASH (1)
 138 #endif
 139 #if     SKEIN_TREE_HASH
 140 int Skein_256_Output(Skein_256_Ctxt_t *ctx, uint8_t *hashVal);
 141 int Skein_512_Output(Skein_512_Ctxt_t *ctx, uint8_t *hashVal);
 142 int Skein1024_Output(Skein1024_Ctxt_t *ctx, uint8_t *hashVal);
 143 #endif
 144
 145 /*
 146  * When you initialize a Skein KCF hashing method you can pass this param
 147  * structure in cm_param to fine-tune the algorithm's defaults.
 148  */
 149 typedef struct skein_param {
 150         size_t  sp_digest_bitlen;               /* length of digest in bits */
 151 } skein_param_t;
 152
 153 /* Module definitions */
 154 #ifdef  SKEIN_MODULE_IMPL
 155 #define CKM_SKEIN_256                           "CKM_SKEIN_256"
 156 #define CKM_SKEIN_512                           "CKM_SKEIN_512"
 157 #define CKM_SKEIN1024                           "CKM_SKEIN1024"
 158 #define CKM_SKEIN_256_MAC                       "CKM_SKEIN_256_MAC"
 159 #define CKM_SKEIN_512_MAC                       "CKM_SKEIN_512_MAC"
 160 #define CKM_SKEIN1024_MAC                       "CKM_SKEIN1024_MAC"
 161
 162 typedef enum skein_mech_type {
 163         SKEIN_256_MECH_INFO_TYPE,
 164         SKEIN_512_MECH_INFO_TYPE,
 165         SKEIN1024_MECH_INFO_TYPE,
 166         SKEIN_256_MAC_MECH_INFO_TYPE,
 167         SKEIN_512_MAC_MECH_INFO_TYPE,
 168         SKEIN1024_MAC_MECH_INFO_TYPE
 169 } skein_mech_type_t;
 170
 171 #define VALID_SKEIN_DIGEST_MECH(__mech)                         \
 172         ((int)(__mech) >= SKEIN_256_MECH_INFO_TYPE &&           \
 173         (__mech) <= SKEIN1024_MECH_INFO_TYPE)
 174 #define VALID_SKEIN_MAC_MECH(__mech)                            \
 175         ((int)(__mech) >= SKEIN_256_MAC_MECH_INFO_TYPE &&       \
 176         (__mech) <= SKEIN1024_MAC_MECH_INFO_TYPE)
 177 #endif  /* SKEIN_MODULE_IMPL */
 178
 179 #ifdef  __cplusplus
 180 }
 181 #endif
 182
 183 #endif  /* _SYS_SKEIN_H_ */