1 /* hmac.h - TinyCrypt interface to an HMAC implementation */ 2 3 /* 4 * Copyright (C) 2017 by Intel Corporation, All Rights Reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions are met: 8 * 9 * - Redistributions of source code must retain the above copyright notice, 10 * this list of conditions and the following disclaimer. 11 * 12 * - Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * - Neither the name of Intel Corporation nor the names of its contributors 17 * may be used to endorse or promote products derived from this software 18 * without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 24 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 25 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 26 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 27 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 28 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 29 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 30 * POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 /** 34 * @file 35 * @brief Interface to an HMAC implementation. 36 * 37 * Overview: HMAC is a message authentication code based on hash functions. 38 * TinyCrypt hard codes SHA-256 as the hash function. A message 39 * authentication code based on hash functions is also called a 40 * keyed cryptographic hash function since it performs a 41 * transformation specified by a key in an arbitrary length data 42 * set into a fixed length data set (also called tag). 43 * 44 * Security: The security of the HMAC depends on the length of the key and 45 * on the security of the hash function. Note that HMAC primitives 46 * are much less affected by collision attacks than their 47 * corresponding hash functions. 48 * 49 * Requires: SHA-256 50 * 51 * Usage: 1) call tc_hmac_set_key to set the HMAC key. 52 * 53 * 2) call tc_hmac_init to initialize a struct hash_state before 54 * processing the data. 55 * 56 * 3) call tc_hmac_update to process the next input segment; 57 * tc_hmac_update can be called as many times as needed to process 58 * all of the segments of the input; the order is important. 59 * 60 * 4) call tc_hmac_final to out put the tag. 61 */ 62 63 #ifndef __TC_HMAC_H__ 64 #define __TC_HMAC_H__ 65 66 #include <tinycrypt/sha256.h> 67 68 #ifdef __cplusplus 69 extern "C" { 70 #endif 71 72 struct tc_hmac_state_struct { 73 /* the internal state required by h */ 74 struct tc_sha256_state_struct hash_state; 75 /* HMAC key schedule */ 76 uint8_t key[2*TC_SHA256_BLOCK_SIZE]; 77 }; 78 typedef struct tc_hmac_state_struct *TCHmacState_t; 79 80 /** 81 * @brief HMAC set key procedure 82 * Configures ctx to use key 83 * @return returns TC_CRYPTO_SUCCESS (1) 84 * returns TC_CRYPTO_FAIL (0) if 85 * ctx == NULL or 86 * key == NULL or 87 * key_size == 0 88 * @param ctx IN/OUT -- the struct tc_hmac_state_struct to initial 89 * @param key IN -- the HMAC key to configure 90 * @param key_size IN -- the HMAC key size 91 */ 92 int tc_hmac_set_key(TCHmacState_t ctx, const uint8_t *key, 93 unsigned int key_size); 94 95 /** 96 * @brief HMAC init procedure 97 * Initializes ctx to begin the next HMAC operation 98 * @return returns TC_CRYPTO_SUCCESS (1) 99 * returns TC_CRYPTO_FAIL (0) if: ctx == NULL or key == NULL 100 * @param ctx IN/OUT -- struct tc_hmac_state_struct buffer to init 101 */ 102 int tc_hmac_init(TCHmacState_t ctx); 103 104 /** 105 * @brief HMAC update procedure 106 * Mixes data_length bytes addressed by data into state 107 * @return returns TC_CRYPTO_SUCCCESS (1) 108 * returns TC_CRYPTO_FAIL (0) if: ctx == NULL or key == NULL 109 * @note Assumes state has been initialized by tc_hmac_init 110 * @param ctx IN/OUT -- state of HMAC computation so far 111 * @param data IN -- data to incorporate into state 112 * @param data_length IN -- size of data in bytes 113 */ 114 int tc_hmac_update(TCHmacState_t ctx, const void *data, 115 unsigned int data_length); 116 117 /** 118 * @brief HMAC final procedure 119 * Writes the HMAC tag into the tag buffer 120 * @return returns TC_CRYPTO_SUCCESS (1) 121 * returns TC_CRYPTO_FAIL (0) if: 122 * tag == NULL or 123 * ctx == NULL or 124 * key == NULL or 125 * taglen != TC_SHA256_DIGEST_SIZE 126 * @note ctx is erased before exiting. This should never be changed/removed. 127 * @note Assumes the tag bufer is at least sizeof(hmac_tag_size(state)) bytes 128 * state has been initialized by tc_hmac_init 129 * @param tag IN/OUT -- buffer to receive computed HMAC tag 130 * @param taglen IN -- size of tag in bytes 131 * @param ctx IN/OUT -- the HMAC state for computing tag 132 */ 133 int tc_hmac_final(uint8_t *tag, unsigned int taglen, TCHmacState_t ctx); 134 135 #ifdef __cplusplus 136 } 137 #endif 138 139 #endif /*__TC_HMAC_H__*/ 140