drivers/staging/skein/skein_api.h

   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