xref: /illumos-gate/usr/src/uts/common/sys/skein.h (revision 45818ee1)
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_ */
179