1 /* 2 * Copyright 1995-2016 The OpenSSL Project Authors. All Rights Reserved. 3 * 4 * Licensed under the OpenSSL license (the "License"). You may not use 5 * this file except in compliance with the License. You can obtain a copy 6 * in the file LICENSE in the source distribution or at 7 * https://www.openssl.org/source/license.html 8 */ 9 10 #ifndef OPENSSL_HEADER_HMAC_H 11 #define OPENSSL_HEADER_HMAC_H 12 13 #include <openssl/base.h> 14 15 #include <openssl/digest.h> 16 17 #if defined(__cplusplus) 18 extern "C" { 19 #endif 20 21 22 // HMAC contains functions for constructing PRFs from Merkle–Damgård hash 23 // functions using HMAC. 24 25 26 // One-shot operation. 27 28 // HMAC calculates the HMAC of |data_len| bytes of |data|, using the given key 29 // and hash function, and writes the result to |out|. On entry, |out| must 30 // contain at least |EVP_MD_size| bytes of space. The actual length of the 31 // result is written to |*out_len|. An output size of |EVP_MAX_MD_SIZE| will 32 // always be large enough. It returns |out| or NULL on error. 33 OPENSSL_EXPORT uint8_t *HMAC(const EVP_MD *evp_md, const void *key, 34 size_t key_len, const uint8_t *data, 35 size_t data_len, uint8_t *out, 36 unsigned int *out_len); 37 38 39 // Incremental operation. 40 41 // HMAC_CTX_init initialises |ctx| for use in an HMAC operation. It's assumed 42 // that HMAC_CTX objects will be allocated on the stack thus no allocation 43 // function is provided. 44 OPENSSL_EXPORT void HMAC_CTX_init(HMAC_CTX *ctx); 45 46 // HMAC_CTX_new allocates and initialises a new |HMAC_CTX| and returns it, or 47 // NULL on allocation failure. The caller must use |HMAC_CTX_free| to release 48 // the resulting object. 49 OPENSSL_EXPORT HMAC_CTX *HMAC_CTX_new(void); 50 51 // HMAC_CTX_cleanup frees data owned by |ctx|. It does not free |ctx| itself. 52 OPENSSL_EXPORT void HMAC_CTX_cleanup(HMAC_CTX *ctx); 53 54 // HMAC_CTX_cleanse zeros the digest state from |ctx| and then performs the 55 // actions of |HMAC_CTX_cleanup|. 56 OPENSSL_EXPORT void HMAC_CTX_cleanse(HMAC_CTX *ctx); 57 58 // HMAC_CTX_free calls |HMAC_CTX_cleanup| and then frees |ctx| itself. 59 OPENSSL_EXPORT void HMAC_CTX_free(HMAC_CTX *ctx); 60 61 // HMAC_Init_ex sets up an initialised |HMAC_CTX| to use |md| as the hash 62 // function and |key| as the key. For a non-initial call, |md| may be NULL, in 63 // which case the previous hash function will be used. If the hash function has 64 // not changed and |key| is NULL, |ctx| reuses the previous key. It returns one 65 // on success or zero on allocation failure. 66 // 67 // WARNING: NULL and empty keys are ambiguous on non-initial calls. Passing NULL 68 // |key| but repeating the previous |md| reuses the previous key rather than the 69 // empty key. 70 OPENSSL_EXPORT int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, size_t key_len, 71 const EVP_MD *md, ENGINE *impl); 72 73 // HMAC_Update hashes |data_len| bytes from |data| into the current HMAC 74 // operation in |ctx|. It returns one. 75 OPENSSL_EXPORT int HMAC_Update(HMAC_CTX *ctx, const uint8_t *data, 76 size_t data_len); 77 78 // HMAC_Final completes the HMAC operation in |ctx| and writes the result to 79 // |out| and the sets |*out_len| to the length of the result. On entry, |out| 80 // must contain at least |HMAC_size| bytes of space. An output size of 81 // |EVP_MAX_MD_SIZE| will always be large enough. It returns one on success or 82 // zero on allocation failure. 83 OPENSSL_EXPORT int HMAC_Final(HMAC_CTX *ctx, uint8_t *out, 84 unsigned int *out_len); 85 86 87 // Utility functions. 88 89 // HMAC_size returns the size, in bytes, of the HMAC that will be produced by 90 // |ctx|. On entry, |ctx| must have been setup with |HMAC_Init_ex|. 91 OPENSSL_EXPORT size_t HMAC_size(const HMAC_CTX *ctx); 92 93 // HMAC_CTX_get_md returns |ctx|'s hash function. 94 OPENSSL_EXPORT const EVP_MD *HMAC_CTX_get_md(const HMAC_CTX *ctx); 95 96 // HMAC_CTX_copy_ex sets |dest| equal to |src|. On entry, |dest| must have been 97 // initialised by calling |HMAC_CTX_init|. It returns one on success and zero 98 // on error. 99 OPENSSL_EXPORT int HMAC_CTX_copy_ex(HMAC_CTX *dest, const HMAC_CTX *src); 100 101 // HMAC_CTX_reset calls |HMAC_CTX_cleanup| followed by |HMAC_CTX_init|. 102 OPENSSL_EXPORT void HMAC_CTX_reset(HMAC_CTX *ctx); 103 104 105 // Deprecated functions. 106 107 OPENSSL_EXPORT int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, 108 const EVP_MD *md); 109 110 // HMAC_CTX_copy calls |HMAC_CTX_init| on |dest| and then sets it equal to 111 // |src|. On entry, |dest| must /not/ be initialised for an operation with 112 // |HMAC_Init_ex|. It returns one on success and zero on error. 113 OPENSSL_EXPORT int HMAC_CTX_copy(HMAC_CTX *dest, const HMAC_CTX *src); 114 115 116 // Private functions 117 118 struct hmac_ctx_st { 119 const EVP_MD *md; 120 EVP_MD_CTX md_ctx; 121 EVP_MD_CTX i_ctx; 122 EVP_MD_CTX o_ctx; 123 } /* HMAC_CTX */; 124 125 126 #if defined(__cplusplus) 127 } // extern C 128 129 #if !defined(BORINGSSL_NO_CXX) 130 extern "C++" { 131 132 BSSL_NAMESPACE_BEGIN 133 134 BORINGSSL_MAKE_DELETER(HMAC_CTX, HMAC_CTX_free) 135 136 using ScopedHMAC_CTX = 137 internal::StackAllocated<HMAC_CTX, void, HMAC_CTX_init, HMAC_CTX_cleanup>; 138 139 BSSL_NAMESPACE_END 140 141 } // extern C++ 142 #endif 143 144 #endif 145 146 #endif // OPENSSL_HEADER_HMAC_H 147