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 skein_api.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 "skein_api.h" 48 * 49 * ... 50 * struct skein_ctx ctx; // a Skein hash or MAC context 51 * 52 * // prepare context, here for a Skein with a state size of 512 bits. 53 * skein_ctx_prepare(&ctx, SKEIN_512); 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 * skein_init(&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 * skein_update_bits(&ctx, message, msg_length); 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 * skein_final(&ctx, result); 68 * ... 69 * @endcode 70 * 71 * An application may use @c skein_reset 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 skein_mac_init instead of 77 * @c skein_init. All other functions calls remain the same. 78 * 79 */ 80 81 #include <linux/types.h> 82 #include "skein_base.h" 83 84 /** 85 * Which Skein size to use 86 */ 87 enum skein_size { 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 */ 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 { 102 u64 skein_size; 103 u64 x_save[SKEIN_MAX_STATE_WORDS]; /* save area for state variables */ 104 union { 105 struct skein_ctx_hdr h; 106 struct skein_256_ctx s256; 107 struct skein_512_ctx s512; 108 struct skein_1024_ctx s1024; 109 } m; 110 }; 111 112 /** 113 * Prepare a Skein context. 114 * 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_SUCCESS of SKEIN_FAIL 125 */ 126 int skein_ctx_prepare(struct skein_ctx *ctx, enum skein_size size); 127 128 /** 129 * Initialize a Skein context. 130 * 131 * Initializes the context with this data and saves the resulting Skein 132 * state variables for further use. 133 * 134 * @param ctx 135 * Pointer to a Skein context. 136 * @param hash_bit_len 137 * Number of MAC hash bits to compute 138 * @return 139 * SKEIN_SUCCESS of SKEIN_FAIL 140 * @see skein_reset 141 */ 142 int skein_init(struct skein_ctx *ctx, size_t hash_bit_len); 143 144 /** 145 * Resets a Skein context for further use. 146 * 147 * Restores the saved chaining variables to reset the Skein context. 148 * Thus applications can reuse the same setup to process several 149 * messages. This saves a complete Skein initialization cycle. 150 * 151 * @param ctx 152 * Pointer to a pre-initialized Skein MAC context 153 */ 154 void skein_reset(struct skein_ctx *ctx); 155 156 /** 157 * Initializes a Skein context for MAC usage. 158 * 159 * Initializes the context with this data and saves the resulting Skein 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 169 * @param key_len 170 * Length of the key in bytes or zero 171 * @param hash_bit_len 172 * Number of MAC hash bits to compute 173 * @return 174 * SKEIN_SUCCESS of SKEIN_FAIL 175 */ 176 int skein_mac_init(struct skein_ctx *ctx, const u8 *key, size_t key_len, 177 size_t hash_bit_len); 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. 186 * @param msg_byte_cnt 187 * Length of the message in @b bytes 188 * @return 189 * Success or error code. 190 */ 191 int skein_update(struct skein_ctx *ctx, const u8 *msg, 192 size_t msg_byte_cnt); 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. 204 * @param msg_bit_cnt 205 * Length of the message in @b bits. 206 */ 207 int skein_update_bits(struct skein_ctx *ctx, const u8 *msg, 208 size_t msg_bit_cnt); 209 210 /** 211 * Finalize Skein and return the hash. 212 * 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 220 * enough to store @c hash_bit_len bits. 221 * @return 222 * Success or error code. 223 * @see skein_reset 224 */ 225 int skein_final(struct skein_ctx *ctx, u8 *hash); 226 227 /** 228 * @} 229 */ 230 #endif 231