Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [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 | /** |
Jake Edge | 85dfd52 | 2014-05-19 17:48:24 -0600 | [diff] [blame] | 31 | * @file skein_api.h |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 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. |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 39 | * |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 40 | * The functions enable applications to create a normal Skein hashes and |
| 41 | * message authentication codes (MAC). |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 42 | * |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 43 | * Using these functions is simple and straight forward: |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 44 | * |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 45 | * @code |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 46 | * |
Jake Edge | 85dfd52 | 2014-05-19 17:48:24 -0600 | [diff] [blame] | 47 | * #include "skein_api.h" |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 48 | * |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 49 | * ... |
Jason Cooper | 11d9ffb | 2014-03-24 01:49:04 +0000 | [diff] [blame] | 50 | * struct skein_ctx ctx; // a Skein hash or MAC context |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 51 | * |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 52 | * // prepare context, here for a Skein with a state size of 512 bits. |
Anton Saraev | 9435d3a | 2014-05-19 12:09:57 +0400 | [diff] [blame] | 53 | * skein_ctx_prepare(&ctx, SKEIN_512); |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 54 | * |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [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) |
Anton Saraev | 68ace62 | 2014-05-19 12:09:54 +0400 | [diff] [blame] | 58 | * skein_init(&ctx, 31); |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 59 | * |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 60 | * // Now update Skein with any number of message bits. A function that |
| 61 | * // takes a number of bytes is also available. |
Anton Saraev | 95f1840a | 2014-05-19 12:09:55 +0400 | [diff] [blame] | 62 | * skein_update_bits(&ctx, message, msg_length); |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 63 | * |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 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. |
Anton Saraev | 68ace62 | 2014-05-19 12:09:54 +0400 | [diff] [blame] | 67 | * skein_final(&ctx, result); |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 68 | * ... |
| 69 | * @endcode |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 70 | * |
Anton Saraev | 68ace62 | 2014-05-19 12:09:54 +0400 | [diff] [blame] | 71 | * An application may use @c skein_reset to reset a Skein context and use |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 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. |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 75 | * |
Anton Saraev | 68ace62 | 2014-05-19 12:09:54 +0400 | [diff] [blame] | 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. |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 78 | * |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 79 | */ |
| 80 | |
Jason Cooper | c2c7426 | 2014-03-24 02:32:49 +0000 | [diff] [blame] | 81 | #include <linux/types.h> |
Eric Rost | c17cdeb | 2014-10-24 17:32:53 -0500 | [diff] [blame] | 82 | #include "skein_base.h" |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 83 | |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 84 | /** |
| 85 | * Which Skein size to use |
| 86 | */ |
| 87 | enum skein_size { |
Anton Saraev | 9435d3a | 2014-05-19 12:09:57 +0400 | [diff] [blame] | 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 */ |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 91 | }; |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 92 | |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 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 { |
Anton Saraev | 95f1840a | 2014-05-19 12:09:55 +0400 | [diff] [blame] | 102 | u64 skein_size; |
Jake Edge | 007dfe5 | 2014-05-20 08:02:28 -0600 | [diff] [blame] | 103 | u64 x_save[SKEIN_MAX_STATE_WORDS]; /* save area for state variables */ |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 104 | union { |
| 105 | struct skein_ctx_hdr h; |
| 106 | struct skein_256_ctx s256; |
| 107 | struct skein_512_ctx s512; |
Anton Saraev | 3201b7f | 2014-05-19 12:09:56 +0400 | [diff] [blame] | 108 | struct skein_1024_ctx s1024; |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 109 | } m; |
| 110 | }; |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 111 | |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 112 | /** |
| 113 | * Prepare a Skein context. |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 114 | * |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 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 |
Colin Cronin | 20ba458 | 2015-05-13 18:05:42 -0700 | [diff] [blame^] | 124 | * SKEIN_SUCCESS of SKEIN_FAIL |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 125 | */ |
Anton Saraev | 68ace62 | 2014-05-19 12:09:54 +0400 | [diff] [blame] | 126 | int skein_ctx_prepare(struct skein_ctx *ctx, enum skein_size size); |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 127 | |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 128 | /** |
| 129 | * Initialize a Skein context. |
| 130 | * |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 131 | * Initializes the context with this data and saves the resulting Skein |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 132 | * state variables for further use. |
| 133 | * |
| 134 | * @param ctx |
| 135 | * Pointer to a Skein context. |
Anton Saraev | 95f1840a | 2014-05-19 12:09:55 +0400 | [diff] [blame] | 136 | * @param hash_bit_len |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 137 | * Number of MAC hash bits to compute |
| 138 | * @return |
Colin Cronin | 20ba458 | 2015-05-13 18:05:42 -0700 | [diff] [blame^] | 139 | * SKEIN_SUCCESS of SKEIN_FAIL |
Anton Saraev | 68ace62 | 2014-05-19 12:09:54 +0400 | [diff] [blame] | 140 | * @see skein_reset |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 141 | */ |
Anton Saraev | 95f1840a | 2014-05-19 12:09:55 +0400 | [diff] [blame] | 142 | int skein_init(struct skein_ctx *ctx, size_t hash_bit_len); |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 143 | |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 144 | /** |
| 145 | * Resets a Skein context for further use. |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 146 | * |
| 147 | * Restores the saved chaining variables to reset the Skein context. |
| 148 | * Thus applications can reuse the same setup to process several |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 149 | * messages. This saves a complete Skein initialization cycle. |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 150 | * |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 151 | * @param ctx |
| 152 | * Pointer to a pre-initialized Skein MAC context |
| 153 | */ |
Anton Saraev | 68ace62 | 2014-05-19 12:09:54 +0400 | [diff] [blame] | 154 | void skein_reset(struct skein_ctx *ctx); |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 155 | |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 156 | /** |
| 157 | * Initializes a Skein context for MAC usage. |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 158 | * |
| 159 | * Initializes the context with this data and saves the resulting Skein |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 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 |
Anton Saraev | 95f1840a | 2014-05-19 12:09:55 +0400 | [diff] [blame] | 169 | * @param key_len |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 170 | * Length of the key in bytes or zero |
Anton Saraev | 95f1840a | 2014-05-19 12:09:55 +0400 | [diff] [blame] | 171 | * @param hash_bit_len |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 172 | * Number of MAC hash bits to compute |
| 173 | * @return |
Colin Cronin | 20ba458 | 2015-05-13 18:05:42 -0700 | [diff] [blame^] | 174 | * SKEIN_SUCCESS of SKEIN_FAIL |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 175 | */ |
Anton Saraev | 95f1840a | 2014-05-19 12:09:55 +0400 | [diff] [blame] | 176 | int skein_mac_init(struct skein_ctx *ctx, const u8 *key, size_t key_len, |
| 177 | size_t hash_bit_len); |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 178 | |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 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. |
Anton Saraev | 95f1840a | 2014-05-19 12:09:55 +0400 | [diff] [blame] | 186 | * @param msg_byte_cnt |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 187 | * Length of the message in @b bytes |
| 188 | * @return |
| 189 | * Success or error code. |
| 190 | */ |
Anton Saraev | 68ace62 | 2014-05-19 12:09:54 +0400 | [diff] [blame] | 191 | int skein_update(struct skein_ctx *ctx, const u8 *msg, |
Anton Saraev | 95f1840a | 2014-05-19 12:09:55 +0400 | [diff] [blame] | 192 | size_t msg_byte_cnt); |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 193 | |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 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. |
Anton Saraev | 95f1840a | 2014-05-19 12:09:55 +0400 | [diff] [blame] | 204 | * @param msg_bit_cnt |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 205 | * Length of the message in @b bits. |
| 206 | */ |
Anton Saraev | 68ace62 | 2014-05-19 12:09:54 +0400 | [diff] [blame] | 207 | int skein_update_bits(struct skein_ctx *ctx, const u8 *msg, |
Anton Saraev | 95f1840a | 2014-05-19 12:09:55 +0400 | [diff] [blame] | 208 | size_t msg_bit_cnt); |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 209 | |
| 210 | /** |
| 211 | * Finalize Skein and return the hash. |
Jason Cooper | 06a620f | 2014-03-24 01:49:10 +0000 | [diff] [blame] | 212 | * |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 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 |
Anton Saraev | 95f1840a | 2014-05-19 12:09:55 +0400 | [diff] [blame] | 220 | * enough to store @c hash_bit_len bits. |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 221 | * @return |
| 222 | * Success or error code. |
Anton Saraev | 68ace62 | 2014-05-19 12:09:54 +0400 | [diff] [blame] | 223 | * @see skein_reset |
Jason Cooper | 39bd42b | 2014-03-24 01:49:09 +0000 | [diff] [blame] | 224 | */ |
Anton Saraev | 68ace62 | 2014-05-19 12:09:54 +0400 | [diff] [blame] | 225 | int skein_final(struct skein_ctx *ctx, u8 *hash); |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 226 | |
Jason Cooper | 449bb81 | 2014-03-24 01:48:58 +0000 | [diff] [blame] | 227 | /** |
| 228 | * @} |
| 229 | */ |
| 230 | #endif |