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.
6 * The following compile-time switches may be defined to control some
7 * tradeoffs between speed, code size, error checking, and security.
9 * The "default" note explains what happens when the switch is not defined.
11 * SKEIN_DEBUG -- make callouts from inside Skein code
12 * to examine/display intermediate values.
13 * [default: no callouts (no overhead)]
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
22 /* Copyright 2013 Doug Whiting. This code is released to the public domain. */
27 #include <sys/types.h> /* get size_t definition */
38 SKEIN_SUCCESS = 0, /* return codes from Skein calls */
43 #define SKEIN_MODIFIER_WORDS (2) /* number of modifier (tweak) words */
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)
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)
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)
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)
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];
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];
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];
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];
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);
95 int Skein_256_Update(Skein_256_Ctxt_t *ctx, const uint8_t *msg,
97 int Skein_512_Update(Skein_512_Ctxt_t *ctx, const uint8_t *msg,
99 int Skein1024_Update(Skein1024_Ctxt_t *ctx, const uint8_t *msg,
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);
107 * Skein APIs for "extended" initialization: MAC keys, tree hashing.
108 * After an InitExt() call, just use Update/Final calls as with Init().
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.
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);
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
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);
136 #ifndef SKEIN_TREE_HASH
137 #define SKEIN_TREE_HASH (1)
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);
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.
149 typedef struct skein_param {
150 size_t sp_digest_bitlen; /* length of digest in bits */
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"
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
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 */
183 #endif /* _SYS_SKEIN_H_ */