Alexandre Lision | 51140e1 | 2013-12-02 10:54:09 -0500 | [diff] [blame] | 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 | * |
Alexandre Lision | e24852d | 2014-02-04 13:13:02 -0500 | [diff] [blame] | 35 | * This API and the functions that implement this API simplify the usage |
Alexandre Lision | 51140e1 | 2013-12-02 10:54:09 -0500 | [diff] [blame] | 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 | * |
Alexandre Lision | e24852d | 2014-02-04 13:13:02 -0500 | [diff] [blame] | 40 | * The functions enable applications to create a normal Skein hashes and |
Alexandre Lision | 51140e1 | 2013-12-02 10:54:09 -0500 | [diff] [blame] | 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 | * |
Alexandre Lision | e24852d | 2014-02-04 13:13:02 -0500 | [diff] [blame] | 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) |
Alexandre Lision | 51140e1 | 2013-12-02 10:54:09 -0500 | [diff] [blame] | 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 |
Alexandre Lision | e24852d | 2014-02-04 13:13:02 -0500 | [diff] [blame] | 74 | * internal state data and saves a full Skein initialization round. |
Alexandre Lision | 51140e1 | 2013-12-02 10:54:09 -0500 | [diff] [blame] | 75 | * |
| 76 | * To create a MAC the application just uses @c skeinMacInit instead of |
Alexandre Lision | e24852d | 2014-02-04 13:13:02 -0500 | [diff] [blame] | 77 | * @c skeinInit. All other functions calls remain the same. |
Alexandre Lision | 51140e1 | 2013-12-02 10:54:09 -0500 | [diff] [blame] | 78 | * |
| 79 | */ |
| 80 | |
Alexandre Lision | e24852d | 2014-02-04 13:13:02 -0500 | [diff] [blame] | 81 | #include <crypto/skein.h> |
Alexandre Lision | 51140e1 | 2013-12-02 10:54:09 -0500 | [diff] [blame] | 82 | |
| 83 | #ifdef _MSC_VER |
| 84 | typedef signed __int8 int8_t; |
| 85 | typedef unsigned __int8 uint8_t; |
| 86 | typedef signed __int16 int16_t; |
| 87 | typedef unsigned __int16 uint16_t; |
| 88 | typedef signed __int32 int32_t; |
| 89 | typedef unsigned __int32 uint32_t; |
| 90 | typedef signed __int64 int64_t; |
| 91 | typedef unsigned __int64 uint64_t; |
| 92 | #else |
| 93 | #include <stdint.h> |
| 94 | #endif |
| 95 | |
| 96 | #ifdef __cplusplus |
| 97 | extern "C" |
| 98 | { |
| 99 | #endif |
| 100 | |
| 101 | /** |
| 102 | * Which Skein size to use |
| 103 | */ |
| 104 | typedef enum SkeinSize { |
| 105 | Skein256 = 256, /*!< Skein with 256 bit state */ |
| 106 | Skein512 = 512, /*!< Skein with 512 bit state */ |
| 107 | Skein1024 = 1024 /*!< Skein with 1024 bit state */ |
| 108 | } SkeinSize_t; |
| 109 | |
| 110 | /** |
| 111 | * Context for Skein. |
| 112 | * |
| 113 | * This structure was setup with some know-how of the internal |
| 114 | * Skein structures, in particular ordering of header and size dependent |
| 115 | * variables. If Skein implementation changes this, then adapt these |
| 116 | * structures as well. |
| 117 | */ |
| 118 | typedef struct SkeinCtx { |
| 119 | u64b_t skeinSize; |
| 120 | u64b_t XSave[SKEIN_MAX_STATE_WORDS]; /* save area for state variables */ |
| 121 | union { |
| 122 | Skein_Ctxt_Hdr_t h; |
| 123 | Skein_256_Ctxt_t s256; |
| 124 | Skein_512_Ctxt_t s512; |
| 125 | Skein1024_Ctxt_t s1024; |
| 126 | } m; |
| 127 | } SkeinCtx_t; |
| 128 | |
| 129 | /** |
| 130 | * Prepare a Skein context. |
| 131 | * |
| 132 | * An application must call this function before it can use the Skein |
| 133 | * context. The functions clears memory and initializes size dependent |
| 134 | * variables. |
| 135 | * |
| 136 | * @param ctx |
| 137 | * Pointer to a Skein context. |
| 138 | * @param size |
| 139 | * Which Skein size to use. |
| 140 | * @return |
| 141 | * SKEIN_SUCESS of SKEIN_FAIL |
| 142 | */ |
| 143 | int skeinCtxPrepare(SkeinCtx_t* ctx, SkeinSize_t size); |
| 144 | |
| 145 | /** |
| 146 | * Initialize a Skein context. |
| 147 | * |
| 148 | * Initializes the context with this data and saves the resulting Skein |
| 149 | * state variables for further use. |
| 150 | * |
| 151 | * @param ctx |
| 152 | * Pointer to a Skein context. |
| 153 | * @param hashBitLen |
| 154 | * Number of MAC hash bits to compute or zero |
| 155 | * @return |
| 156 | * SKEIN_SUCESS of SKEIN_FAIL |
| 157 | * @see skeinReset |
| 158 | */ |
| 159 | int skeinInit(SkeinCtx_t* ctx, size_t hashBitLen); |
| 160 | |
| 161 | /** |
| 162 | * Resets a Skein context for furter use. |
| 163 | * |
| 164 | * Restores the saved chaining variables to reset the Skein context. |
| 165 | * Thus applications can reuse the same setup to process several |
| 166 | * messages. This saves a complete Skein initialization cycle. |
| 167 | * |
| 168 | * @param ctx |
| 169 | * Pointer to a pre-initialized Skein MAC context |
| 170 | */ |
| 171 | void skeinReset(SkeinCtx_t* ctx); |
| 172 | |
| 173 | /** |
| 174 | * Initializes or reuses a Skein context for MAC usage. |
| 175 | * |
| 176 | * Initializes the context with this data and saves the resulting Skein |
| 177 | * state variables for further use. |
| 178 | * |
| 179 | * Applications call the normal Skein functions to update the MAC and |
| 180 | * get the final result. |
| 181 | * |
| 182 | * @param ctx |
| 183 | * Pointer to an empty or preinitialized Skein MAC context |
| 184 | * @param key |
| 185 | * Pointer to key bytes or NULL |
| 186 | * @param keyLen |
| 187 | * Length of the key in bytes or zero |
| 188 | * @param hashBitLen |
| 189 | * Number of MAC hash bits to compute or zero |
| 190 | * @return |
| 191 | * SKEIN_SUCESS of SKEIN_FAIL |
| 192 | */ |
| 193 | int skeinMacInit(SkeinCtx_t* ctx, const uint8_t *key, size_t keyLen, |
| 194 | size_t hashBitLen); |
| 195 | |
| 196 | /** |
| 197 | * Update Skein with the next part of the message. |
| 198 | * |
| 199 | * @param ctx |
| 200 | * Pointer to initialized Skein context |
| 201 | * @param msg |
| 202 | * Pointer to the message. |
| 203 | * @param msgByteCnt |
| 204 | * Length of the message in @b bytes |
| 205 | * @return |
| 206 | * Success or error code. |
| 207 | */ |
| 208 | int skeinUpdate(SkeinCtx_t *ctx, const uint8_t *msg, |
| 209 | size_t msgByteCnt); |
| 210 | |
| 211 | /** |
| 212 | * Update the hash with a message bit string. |
| 213 | * |
| 214 | * Skein can handle data not only as bytes but also as bit strings of |
| 215 | * arbitrary length (up to its maximum design size). |
| 216 | * |
| 217 | * @param ctx |
| 218 | * Pointer to initialized Skein context |
| 219 | * @param msg |
| 220 | * Pointer to the message. |
| 221 | * @param msgBitCnt |
| 222 | * Length of the message in @b bits. |
| 223 | */ |
| 224 | int skeinUpdateBits(SkeinCtx_t *ctx, const uint8_t *msg, |
| 225 | size_t msgBitCnt); |
| 226 | |
| 227 | /** |
| 228 | * Finalize Skein and return the hash. |
| 229 | * |
| 230 | * Before an application can reuse a Skein setup the application must |
| 231 | * reinitialize the Skein context.See the approriate initialization |
| 232 | * methods how to achieve this. |
| 233 | * |
| 234 | * @param ctx |
| 235 | * Pointer to initialized Skein context |
| 236 | * @param hash |
| 237 | * Pointer to buffer that receives the hash. The buffer must be large |
| 238 | * enough to store @c hashBitLen bits. |
| 239 | * @return |
| 240 | * Success or error code. |
| 241 | * @see skeinInit |
| 242 | * @see skeinMacInit |
| 243 | */ |
| 244 | int skeinFinal(SkeinCtx_t* ctx, uint8_t* hash); |
| 245 | |
| 246 | #ifdef __cplusplus |
| 247 | } |
| 248 | #endif |
| 249 | |
| 250 | /** |
| 251 | * @} |
| 252 | */ |
| 253 | #endif |