1 /* $Id: sph_skein.h 253 2011-06-07 18:33:10Z tp $ */ 2 /** 3 * Skein interface. The Skein specification defines three main 4 * functions, called Skein-256, Skein-512 and Skein-1024, which can be 5 * further parameterized with an output length. For the SHA-3 6 * competition, Skein-512 is used for output sizes of 224, 256, 384 and 7 * 512 bits; this is what this code implements. Thus, we hereafter call 8 * Skein-224, Skein-256, Skein-384 and Skein-512 what the Skein 9 * specification defines as Skein-512-224, Skein-512-256, Skein-512-384 10 * and Skein-512-512, respectively. 11 * 12 * ==========================(LICENSE BEGIN)============================ 13 * 14 * Copyright (c) 2007-2010 Projet RNRT SAPHIR 15 * 16 * Permission is hereby granted, free of charge, to any person obtaining 17 * a copy of this software and associated documentation files (the 18 * "Software"), to deal in the Software without restriction, including 19 * without limitation the rights to use, copy, modify, merge, publish, 20 * distribute, sublicense, and/or sell copies of the Software, and to 21 * permit persons to whom the Software is furnished to do so, subject to 22 * the following conditions: 23 * 24 * The above copyright notice and this permission notice shall be 25 * included in all copies or substantial portions of the Software. 26 * 27 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 28 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 29 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 30 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 31 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 32 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 33 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 34 * 35 * ===========================(LICENSE END)============================= 36 * 37 * @file sph_skein.h 38 * @author Thomas Pornin <thomas.pornin@cryptolog.com> 39 */ 40 41 #ifndef SPH_SKEIN_H__ 42 #define SPH_SKEIN_H__ 43 44 #include <stddef.h> 45 #include "sph_types.h" 46 47 #if SPH_64 48 49 /** 50 * Output size (in bits) for Skein-224. 51 */ 52 #define SPH_SIZE_skein224 224 53 54 /** 55 * Output size (in bits) for Skein-256. 56 */ 57 #define SPH_SIZE_skein256 256 58 59 /** 60 * Output size (in bits) for Skein-384. 61 */ 62 #define SPH_SIZE_skein384 384 63 64 /** 65 * Output size (in bits) for Skein-512. 66 */ 67 #define SPH_SIZE_skein512 512 68 69 /** 70 * This structure is a context for Skein computations (with a 384- or 71 * 512-bit output): it contains the intermediate values and some data 72 * from the last entered block. Once a Skein computation has been 73 * performed, the context can be reused for another computation. 74 * 75 * The contents of this structure are private. A running Skein computation 76 * can be cloned by copying the context (e.g. with a simple 77 * <code>memcpy()</code>). 78 */ 79 typedef struct { 80 #ifndef DOXYGEN_IGNORE 81 unsigned char buf[64]; /* first field, for alignment */ 82 size_t ptr; 83 sph_u64 h0, h1, h2, h3, h4, h5, h6, h7; 84 sph_u64 bcount; 85 #endif 86 } sph_skein_big_context; 87 88 /** 89 * Type for a Skein-224 context (identical to the common "big" context). 90 */ 91 typedef sph_skein_big_context sph_skein224_context; 92 93 /** 94 * Type for a Skein-256 context (identical to the common "big" context). 95 */ 96 typedef sph_skein_big_context sph_skein256_context; 97 98 /** 99 * Type for a Skein-384 context (identical to the common "big" context). 100 */ 101 typedef sph_skein_big_context sph_skein384_context; 102 103 /** 104 * Type for a Skein-512 context (identical to the common "big" context). 105 */ 106 typedef sph_skein_big_context sph_skein512_context; 107 108 /** 109 * Initialize a Skein-224 context. This process performs no memory allocation. 110 * 111 * @param cc the Skein-224 context (pointer to a 112 * <code>sph_skein224_context</code>) 113 */ 114 void sph_skein224_init(void *cc); 115 116 /** 117 * Process some data bytes. It is acceptable that <code>len</code> is zero 118 * (in which case this function does nothing). 119 * 120 * @param cc the Skein-224 context 121 * @param data the input data 122 * @param len the input data length (in bytes) 123 */ 124 void sph_skein224(void *cc, const void *data, size_t len); 125 126 /** 127 * Terminate the current Skein-224 computation and output the result into 128 * the provided buffer. The destination buffer must be wide enough to 129 * accommodate the result (28 bytes). The context is automatically 130 * reinitialized. 131 * 132 * @param cc the Skein-224 context 133 * @param dst the destination buffer 134 */ 135 void sph_skein224_close(void *cc, void *dst); 136 137 /** 138 * Add a few additional bits (0 to 7) to the current computation, then 139 * terminate it and output the result in the provided buffer, which must 140 * be wide enough to accommodate the result (28 bytes). If bit number i 141 * in <code>ub</code> has value 2^i, then the extra bits are those 142 * numbered 7 downto 8-n (this is the big-endian convention at the byte 143 * level). The context is automatically reinitialized. 144 * 145 * @param cc the Skein-224 context 146 * @param ub the extra bits 147 * @param n the number of extra bits (0 to 7) 148 * @param dst the destination buffer 149 */ 150 void sph_skein224_addbits_and_close( 151 void *cc, unsigned ub, unsigned n, void *dst); 152 153 /** 154 * Initialize a Skein-256 context. This process performs no memory allocation. 155 * 156 * @param cc the Skein-256 context (pointer to a 157 * <code>sph_skein256_context</code>) 158 */ 159 void sph_skein256_init(void *cc); 160 161 /** 162 * Process some data bytes. It is acceptable that <code>len</code> is zero 163 * (in which case this function does nothing). 164 * 165 * @param cc the Skein-256 context 166 * @param data the input data 167 * @param len the input data length (in bytes) 168 */ 169 void sph_skein256(void *cc, const void *data, size_t len); 170 171 /** 172 * Terminate the current Skein-256 computation and output the result into 173 * the provided buffer. The destination buffer must be wide enough to 174 * accommodate the result (32 bytes). The context is automatically 175 * reinitialized. 176 * 177 * @param cc the Skein-256 context 178 * @param dst the destination buffer 179 */ 180 void sph_skein256_close(void *cc, void *dst); 181 182 /** 183 * Add a few additional bits (0 to 7) to the current computation, then 184 * terminate it and output the result in the provided buffer, which must 185 * be wide enough to accommodate the result (32 bytes). If bit number i 186 * in <code>ub</code> has value 2^i, then the extra bits are those 187 * numbered 7 downto 8-n (this is the big-endian convention at the byte 188 * level). The context is automatically reinitialized. 189 * 190 * @param cc the Skein-256 context 191 * @param ub the extra bits 192 * @param n the number of extra bits (0 to 7) 193 * @param dst the destination buffer 194 */ 195 void sph_skein256_addbits_and_close( 196 void *cc, unsigned ub, unsigned n, void *dst); 197 198 /** 199 * Initialize a Skein-384 context. This process performs no memory allocation. 200 * 201 * @param cc the Skein-384 context (pointer to a 202 * <code>sph_skein384_context</code>) 203 */ 204 void sph_skein384_init(void *cc); 205 206 /** 207 * Process some data bytes. It is acceptable that <code>len</code> is zero 208 * (in which case this function does nothing). 209 * 210 * @param cc the Skein-384 context 211 * @param data the input data 212 * @param len the input data length (in bytes) 213 */ 214 void sph_skein384(void *cc, const void *data, size_t len); 215 216 /** 217 * Terminate the current Skein-384 computation and output the result into 218 * the provided buffer. The destination buffer must be wide enough to 219 * accommodate the result (48 bytes). The context is automatically 220 * reinitialized. 221 * 222 * @param cc the Skein-384 context 223 * @param dst the destination buffer 224 */ 225 void sph_skein384_close(void *cc, void *dst); 226 227 /** 228 * Add a few additional bits (0 to 7) to the current computation, then 229 * terminate it and output the result in the provided buffer, which must 230 * be wide enough to accommodate the result (48 bytes). If bit number i 231 * in <code>ub</code> has value 2^i, then the extra bits are those 232 * numbered 7 downto 8-n (this is the big-endian convention at the byte 233 * level). The context is automatically reinitialized. 234 * 235 * @param cc the Skein-384 context 236 * @param ub the extra bits 237 * @param n the number of extra bits (0 to 7) 238 * @param dst the destination buffer 239 */ 240 void sph_skein384_addbits_and_close( 241 void *cc, unsigned ub, unsigned n, void *dst); 242 243 /** 244 * Initialize a Skein-512 context. This process performs no memory allocation. 245 * 246 * @param cc the Skein-512 context (pointer to a 247 * <code>sph_skein512_context</code>) 248 */ 249 void sph_skein512_init(void *cc); 250 251 /** 252 * Process some data bytes. It is acceptable that <code>len</code> is zero 253 * (in which case this function does nothing). 254 * 255 * @param cc the Skein-512 context 256 * @param data the input data 257 * @param len the input data length (in bytes) 258 */ 259 void sph_skein512(void *cc, const void *data, size_t len); 260 261 /** 262 * Terminate the current Skein-512 computation and output the result into 263 * the provided buffer. The destination buffer must be wide enough to 264 * accommodate the result (64 bytes). The context is automatically 265 * reinitialized. 266 * 267 * @param cc the Skein-512 context 268 * @param dst the destination buffer 269 */ 270 void sph_skein512_close(void *cc, void *dst); 271 272 /** 273 * Add a few additional bits (0 to 7) to the current computation, then 274 * terminate it and output the result in the provided buffer, which must 275 * be wide enough to accommodate the result (64 bytes). If bit number i 276 * in <code>ub</code> has value 2^i, then the extra bits are those 277 * numbered 7 downto 8-n (this is the big-endian convention at the byte 278 * level). The context is automatically reinitialized. 279 * 280 * @param cc the Skein-512 context 281 * @param ub the extra bits 282 * @param n the number of extra bits (0 to 7) 283 * @param dst the destination buffer 284 */ 285 void sph_skein512_addbits_and_close( 286 void *cc, unsigned ub, unsigned n, void *dst); 287 288 #endif 289 290 #endif 291