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