]>
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 | /** | |
85dfd522 | 31 | * @file skein_api.h |
449bb812 JC |
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. | |
06a620f0 | 39 | * |
449bb812 JC |
40 | * The functions enable applications to create a normal Skein hashes and |
41 | * message authentication codes (MAC). | |
06a620f0 | 42 | * |
449bb812 | 43 | * Using these functions is simple and straight forward: |
06a620f0 | 44 | * |
449bb812 | 45 | * @code |
06a620f0 | 46 | * |
85dfd522 | 47 | * #include "skein_api.h" |
06a620f0 | 48 | * |
449bb812 | 49 | * ... |
11d9ffb2 | 50 | * struct skein_ctx ctx; // a Skein hash or MAC context |
06a620f0 | 51 | * |
449bb812 | 52 | * // prepare context, here for a Skein with a state size of 512 bits. |
9435d3ac | 53 | * skein_ctx_prepare(&ctx, SKEIN_512); |
06a620f0 | 54 | * |
449bb812 JC |
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) | |
68ace624 | 58 | * skein_init(&ctx, 31); |
06a620f0 | 59 | * |
449bb812 JC |
60 | * // Now update Skein with any number of message bits. A function that |
61 | * // takes a number of bytes is also available. | |
95f1840a | 62 | * skein_update_bits(&ctx, message, msg_length); |
06a620f0 | 63 | * |
449bb812 JC |
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. | |
68ace624 | 67 | * skein_final(&ctx, result); |
449bb812 JC |
68 | * ... |
69 | * @endcode | |
06a620f0 | 70 | * |
68ace624 | 71 | * An application may use @c skein_reset to reset a Skein context and use |
449bb812 JC |
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. | |
06a620f0 | 75 | * |
68ace624 AS |
76 | * To create a MAC the application just uses @c skein_mac_init instead of |
77 | * @c skein_init. All other functions calls remain the same. | |
06a620f0 | 78 | * |
449bb812 JC |
79 | */ |
80 | ||
c2c7426b | 81 | #include <linux/types.h> |
85dfd522 | 82 | #include "skein.h" |
449bb812 | 83 | |
39bd42b0 JC |
84 | /** |
85 | * Which Skein size to use | |
86 | */ | |
87 | enum skein_size { | |
9435d3ac AS |
88 | SKEIN_256 = 256, /*!< Skein with 256 bit state */ |
89 | SKEIN_512 = 512, /*!< Skein with 512 bit state */ | |
90 | SKEIN_1024 = 1024 /*!< Skein with 1024 bit state */ | |
39bd42b0 JC |
91 | }; |
92 | ||
93 | /** | |
94 | * Context for Skein. | |
95 | * | |
96 | * This structure was setup with some know-how of the internal | |
97 | * Skein structures, in particular ordering of header and size dependent | |
98 | * variables. If Skein implementation changes this, then adapt these | |
99 | * structures as well. | |
100 | */ | |
101 | struct skein_ctx { | |
95f1840a | 102 | u64 skein_size; |
007dfe5a | 103 | u64 x_save[SKEIN_MAX_STATE_WORDS]; /* save area for state variables */ |
39bd42b0 JC |
104 | union { |
105 | struct skein_ctx_hdr h; | |
106 | struct skein_256_ctx s256; | |
107 | struct skein_512_ctx s512; | |
3201b7f2 | 108 | struct skein_1024_ctx s1024; |
39bd42b0 JC |
109 | } m; |
110 | }; | |
111 | ||
112 | /** | |
113 | * Prepare a Skein context. | |
06a620f0 | 114 | * |
39bd42b0 JC |
115 | * An application must call this function before it can use the Skein |
116 | * context. The functions clears memory and initializes size dependent | |
117 | * variables. | |
118 | * | |
119 | * @param ctx | |
120 | * Pointer to a Skein context. | |
121 | * @param size | |
122 | * Which Skein size to use. | |
123 | * @return | |
124 | * SKEIN_SUCESS of SKEIN_FAIL | |
125 | */ | |
68ace624 | 126 | int skein_ctx_prepare(struct skein_ctx *ctx, enum skein_size size); |
39bd42b0 JC |
127 | |
128 | /** | |
129 | * Initialize a Skein context. | |
130 | * | |
06a620f0 | 131 | * Initializes the context with this data and saves the resulting Skein |
39bd42b0 JC |
132 | * state variables for further use. |
133 | * | |
134 | * @param ctx | |
135 | * Pointer to a Skein context. | |
95f1840a | 136 | * @param hash_bit_len |
39bd42b0 JC |
137 | * Number of MAC hash bits to compute |
138 | * @return | |
139 | * SKEIN_SUCESS of SKEIN_FAIL | |
68ace624 | 140 | * @see skein_reset |
39bd42b0 | 141 | */ |
95f1840a | 142 | int skein_init(struct skein_ctx *ctx, size_t hash_bit_len); |
39bd42b0 JC |
143 | |
144 | /** | |
145 | * Resets a Skein context for further use. | |
06a620f0 JC |
146 | * |
147 | * Restores the saved chaining variables to reset the Skein context. | |
148 | * Thus applications can reuse the same setup to process several | |
39bd42b0 | 149 | * messages. This saves a complete Skein initialization cycle. |
06a620f0 | 150 | * |
39bd42b0 JC |
151 | * @param ctx |
152 | * Pointer to a pre-initialized Skein MAC context | |
153 | */ | |
68ace624 | 154 | void skein_reset(struct skein_ctx *ctx); |
39bd42b0 JC |
155 | |
156 | /** | |
157 | * Initializes a Skein context for MAC usage. | |
06a620f0 JC |
158 | * |
159 | * Initializes the context with this data and saves the resulting Skein | |
39bd42b0 JC |
160 | * state variables for further use. |
161 | * | |
162 | * Applications call the normal Skein functions to update the MAC and | |
163 | * get the final result. | |
164 | * | |
165 | * @param ctx | |
166 | * Pointer to an empty or preinitialized Skein MAC context | |
167 | * @param key | |
168 | * Pointer to key bytes or NULL | |
95f1840a | 169 | * @param key_len |
39bd42b0 | 170 | * Length of the key in bytes or zero |
95f1840a | 171 | * @param hash_bit_len |
39bd42b0 JC |
172 | * Number of MAC hash bits to compute |
173 | * @return | |
174 | * SKEIN_SUCESS of SKEIN_FAIL | |
175 | */ | |
95f1840a AS |
176 | int skein_mac_init(struct skein_ctx *ctx, const u8 *key, size_t key_len, |
177 | size_t hash_bit_len); | |
39bd42b0 JC |
178 | |
179 | /** | |
180 | * Update Skein with the next part of the message. | |
181 | * | |
182 | * @param ctx | |
183 | * Pointer to initialized Skein context | |
184 | * @param msg | |
185 | * Pointer to the message. | |
95f1840a | 186 | * @param msg_byte_cnt |
39bd42b0 JC |
187 | * Length of the message in @b bytes |
188 | * @return | |
189 | * Success or error code. | |
190 | */ | |
68ace624 | 191 | int skein_update(struct skein_ctx *ctx, const u8 *msg, |
95f1840a | 192 | size_t msg_byte_cnt); |
39bd42b0 JC |
193 | |
194 | /** | |
195 | * Update the hash with a message bit string. | |
196 | * | |
197 | * Skein can handle data not only as bytes but also as bit strings of | |
198 | * arbitrary length (up to its maximum design size). | |
199 | * | |
200 | * @param ctx | |
201 | * Pointer to initialized Skein context | |
202 | * @param msg | |
203 | * Pointer to the message. | |
95f1840a | 204 | * @param msg_bit_cnt |
39bd42b0 JC |
205 | * Length of the message in @b bits. |
206 | */ | |
68ace624 | 207 | int skein_update_bits(struct skein_ctx *ctx, const u8 *msg, |
95f1840a | 208 | size_t msg_bit_cnt); |
39bd42b0 JC |
209 | |
210 | /** | |
211 | * Finalize Skein and return the hash. | |
06a620f0 | 212 | * |
39bd42b0 JC |
213 | * Before an application can reuse a Skein setup the application must |
214 | * reset the Skein context. | |
215 | * | |
216 | * @param ctx | |
217 | * Pointer to initialized Skein context | |
218 | * @param hash | |
219 | * Pointer to buffer that receives the hash. The buffer must be large | |
95f1840a | 220 | * enough to store @c hash_bit_len bits. |
39bd42b0 JC |
221 | * @return |
222 | * Success or error code. | |
68ace624 | 223 | * @see skein_reset |
39bd42b0 | 224 | */ |
68ace624 | 225 | int skein_final(struct skein_ctx *ctx, u8 *hash); |
449bb812 | 226 | |
449bb812 JC |
227 | /** |
228 | * @} | |
229 | */ | |
230 | #endif |