]>
Commit | Line | Data |
---|---|---|
449bb812 JC |
1 | /* |
2 | Copyright (c) 2010 Werner Dittmann | |
3 | ||
4 | Permission is hereby granted, free of charge, to any person | |
5 | obtaining a copy of this software and associated documentation | |
6 | files (the "Software"), to deal in the Software without | |
7 | restriction, including without limitation the rights to use, | |
8 | copy, modify, merge, publish, distribute, sublicense, and/or sell | |
9 | copies of the Software, and to permit persons to whom the | |
10 | Software is furnished to do so, subject to the following | |
11 | conditions: | |
12 | ||
13 | The above copyright notice and this permission notice shall be | |
14 | included in all copies or substantial portions of the Software. | |
15 | ||
16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, | |
17 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES | |
18 | OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND | |
19 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT | |
20 | HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, | |
21 | WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING | |
22 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR | |
23 | OTHER DEALINGS IN THE SOFTWARE. | |
24 | ||
25 | */ | |
26 | ||
27 | #ifndef SKEINAPI_H | |
28 | #define SKEINAPI_H | |
29 | ||
30 | /** | |
31 | * @file skeinApi.h | |
32 | * @brief A Skein API and its functions. | |
33 | * @{ | |
34 | * | |
35 | * This API and the functions that implement this API simplify the usage | |
36 | * of Skein. The design and the way to use the functions follow the openSSL | |
37 | * design but at the same time take care of some Skein specific behaviour | |
38 | * and possibilities. | |
39 | * | |
40 | * The functions enable applications to create a normal Skein hashes and | |
41 | * message authentication codes (MAC). | |
42 | * | |
43 | * Using these functions is simple and straight forward: | |
44 | * | |
45 | * @code | |
46 | * | |
47 | * #include <skeinApi.h> | |
48 | * | |
49 | * ... | |
50 | * SkeinCtx_t ctx; // a Skein hash or MAC context | |
51 | * | |
52 | * // prepare context, here for a Skein with a state size of 512 bits. | |
53 | * skeinCtxPrepare(&ctx, Skein512); | |
54 | * | |
55 | * // Initialize the context to set the requested hash length in bits | |
56 | * // here request a output hash size of 31 bits (Skein supports variable | |
57 | * // output sizes even very strange sizes) | |
58 | * skeinInit(&ctx, 31); | |
59 | * | |
60 | * // Now update Skein with any number of message bits. A function that | |
61 | * // takes a number of bytes is also available. | |
62 | * skeinUpdateBits(&ctx, message, msgLength); | |
63 | * | |
64 | * // Now get the result of the Skein hash. The output buffer must be | |
65 | * // large enough to hold the request number of output bits. The application | |
66 | * // may now extract the bits. | |
67 | * skeinFinal(&ctx, result); | |
68 | * ... | |
69 | * @endcode | |
70 | * | |
71 | * An application may use @c skeinReset to reset a Skein context and use | |
72 | * it for creation of another hash with the same Skein state size and output | |
73 | * bit length. In this case the API implementation restores some internal | |
74 | * internal state data and saves a full Skein initialization round. | |
75 | * | |
76 | * To create a MAC the application just uses @c skeinMacInit instead of | |
77 | * @c skeinInit. All other functions calls remain the same. | |
78 | * | |
79 | */ | |
80 | ||
81 | #include <skein.h> | |
82 | #include <stdint.h> | |
83 | ||
84 | #ifdef __cplusplus | |
85 | extern "C" | |
86 | { | |
87 | #endif | |
88 | ||
89 | /** | |
90 | * Which Skein size to use | |
91 | */ | |
92 | typedef enum SkeinSize { | |
93 | Skein256 = 256, /*!< Skein with 256 bit state */ | |
94 | Skein512 = 512, /*!< Skein with 512 bit state */ | |
95 | Skein1024 = 1024 /*!< Skein with 1024 bit state */ | |
96 | } SkeinSize_t; | |
97 | ||
98 | /** | |
99 | * Context for Skein. | |
100 | * | |
101 | * This structure was setup with some know-how of the internal | |
102 | * Skein structures, in particular ordering of header and size dependent | |
103 | * variables. If Skein implementation changes this, then adapt these | |
104 | * structures as well. | |
105 | */ | |
106 | typedef struct SkeinCtx { | |
107 | u64b_t skeinSize; | |
108 | u64b_t XSave[SKEIN_MAX_STATE_WORDS]; /* save area for state variables */ | |
109 | union { | |
110 | Skein_Ctxt_Hdr_t h; | |
111 | Skein_256_Ctxt_t s256; | |
112 | Skein_512_Ctxt_t s512; | |
113 | Skein1024_Ctxt_t s1024; | |
114 | } m; | |
115 | } SkeinCtx_t; | |
116 | ||
117 | /** | |
118 | * Prepare a Skein context. | |
119 | * | |
120 | * An application must call this function before it can use the Skein | |
121 | * context. The functions clears memory and initializes size dependent | |
122 | * variables. | |
123 | * | |
124 | * @param ctx | |
125 | * Pointer to a Skein context. | |
126 | * @param size | |
127 | * Which Skein size to use. | |
128 | * @return | |
129 | * SKEIN_SUCESS of SKEIN_FAIL | |
130 | */ | |
131 | int skeinCtxPrepare(SkeinCtx_t* ctx, SkeinSize_t size); | |
132 | ||
133 | /** | |
134 | * Initialize a Skein context. | |
135 | * | |
136 | * Initializes the context with this data and saves the resulting Skein | |
137 | * state variables for further use. | |
138 | * | |
139 | * @param ctx | |
140 | * Pointer to a Skein context. | |
141 | * @param hashBitLen | |
142 | * Number of MAC hash bits to compute | |
143 | * @return | |
144 | * SKEIN_SUCESS of SKEIN_FAIL | |
145 | * @see skeinReset | |
146 | */ | |
147 | int skeinInit(SkeinCtx_t* ctx, size_t hashBitLen); | |
148 | ||
149 | /** | |
150 | * Resets a Skein context for further use. | |
151 | * | |
152 | * Restores the saved chaining variables to reset the Skein context. | |
153 | * Thus applications can reuse the same setup to process several | |
154 | * messages. This saves a complete Skein initialization cycle. | |
155 | * | |
156 | * @param ctx | |
157 | * Pointer to a pre-initialized Skein MAC context | |
158 | */ | |
159 | void skeinReset(SkeinCtx_t* ctx); | |
160 | ||
161 | /** | |
162 | * Initializes a Skein context for MAC usage. | |
163 | * | |
164 | * Initializes the context with this data and saves the resulting Skein | |
165 | * state variables for further use. | |
166 | * | |
167 | * Applications call the normal Skein functions to update the MAC and | |
168 | * get the final result. | |
169 | * | |
170 | * @param ctx | |
171 | * Pointer to an empty or preinitialized Skein MAC context | |
172 | * @param key | |
173 | * Pointer to key bytes or NULL | |
174 | * @param keyLen | |
175 | * Length of the key in bytes or zero | |
176 | * @param hashBitLen | |
177 | * Number of MAC hash bits to compute | |
178 | * @return | |
179 | * SKEIN_SUCESS of SKEIN_FAIL | |
180 | */ | |
181 | int skeinMacInit(SkeinCtx_t* ctx, const uint8_t *key, size_t keyLen, | |
182 | size_t hashBitLen); | |
183 | ||
184 | /** | |
185 | * Update Skein with the next part of the message. | |
186 | * | |
187 | * @param ctx | |
188 | * Pointer to initialized Skein context | |
189 | * @param msg | |
190 | * Pointer to the message. | |
191 | * @param msgByteCnt | |
192 | * Length of the message in @b bytes | |
193 | * @return | |
194 | * Success or error code. | |
195 | */ | |
196 | int skeinUpdate(SkeinCtx_t *ctx, const uint8_t *msg, | |
197 | size_t msgByteCnt); | |
198 | ||
199 | /** | |
200 | * Update the hash with a message bit string. | |
201 | * | |
202 | * Skein can handle data not only as bytes but also as bit strings of | |
203 | * arbitrary length (up to its maximum design size). | |
204 | * | |
205 | * @param ctx | |
206 | * Pointer to initialized Skein context | |
207 | * @param msg | |
208 | * Pointer to the message. | |
209 | * @param msgBitCnt | |
210 | * Length of the message in @b bits. | |
211 | */ | |
212 | int skeinUpdateBits(SkeinCtx_t *ctx, const uint8_t *msg, | |
213 | size_t msgBitCnt); | |
214 | ||
215 | /** | |
216 | * Finalize Skein and return the hash. | |
217 | * | |
218 | * Before an application can reuse a Skein setup the application must | |
219 | * reset the Skein context. | |
220 | * | |
221 | * @param ctx | |
222 | * Pointer to initialized Skein context | |
223 | * @param hash | |
224 | * Pointer to buffer that receives the hash. The buffer must be large | |
225 | * enough to store @c hashBitLen bits. | |
226 | * @return | |
227 | * Success or error code. | |
228 | * @see skeinReset | |
229 | */ | |
230 | int skeinFinal(SkeinCtx_t* ctx, uint8_t* hash); | |
231 | ||
232 | #ifdef __cplusplus | |
233 | } | |
234 | #endif | |
235 | ||
236 | /** | |
237 | * @} | |
238 | */ | |
239 | #endif |