hmac.h

All headers

HMAC contains functions for constructing PRFs from Merkle–Damgård hash functions using HMAC.

  1. One-shot operation
  2. HMAC
  3. Incremental operation
  4. HMAC_CTX_init
  5. HMAC_CTX_new
  6. HMAC_CTX_cleanup
  7. HMAC_CTX_cleanse
  8. HMAC_CTX_free
  9. HMAC_Init_ex
  10. HMAC_Update
  11. HMAC_Final
  12. Utility functions
  13. HMAC_size
  14. HMAC_CTX_get_md
  15. HMAC_CTX_copy_ex
  16. HMAC_CTX_reset
  17. Deprecated functions
  18. HMAC_Init
  19. HMAC_CTX_copy

One-shot operation.

HMAC calculates the HMAC of data_len bytes of data, using the given key and hash function, and writes the result to out. On entry, out must contain at least EVP_MD_size bytes of space. The actual length of the result is written to *out_len. An output size of EVP_MAX_MD_SIZE will always be large enough. It returns out or NULL on error.

OPENSSL_EXPORT uint8_t *HMAC(const EVP_MD *evp_md, const void *key,
                             size_t key_len, const uint8_t *data,
                             size_t data_len, uint8_t *out,
                             unsigned int *out_len);

Incremental operation.

HMAC_CTX_init initialises ctx for use in an HMAC operation. It's assumed that HMAC_CTX objects will be allocated on the stack thus no allocation function is provided.

OPENSSL_EXPORT void HMAC_CTX_init(HMAC_CTX *ctx);

HMAC_CTX_new allocates and initialises a new HMAC_CTX and returns it, or NULL on allocation failure. The caller must use HMAC_CTX_free to release the resulting object.

OPENSSL_EXPORT HMAC_CTX *HMAC_CTX_new(void);

HMAC_CTX_cleanup frees data owned by ctx. It does not free ctx itself.

OPENSSL_EXPORT void HMAC_CTX_cleanup(HMAC_CTX *ctx);

HMAC_CTX_cleanse zeros the digest state from ctx and then performs the actions of HMAC_CTX_cleanup.

OPENSSL_EXPORT void HMAC_CTX_cleanse(HMAC_CTX *ctx);

HMAC_CTX_free calls HMAC_CTX_cleanup and then frees ctx itself.

OPENSSL_EXPORT void HMAC_CTX_free(HMAC_CTX *ctx);

HMAC_Init_ex sets up an initialised HMAC_CTX to use md as the hash function and key as the key. For a non-initial call, md may be NULL, in which case the previous hash function will be used. If the hash function has not changed and key is NULL, ctx reuses the previous key. It returns one on success or zero on allocation failure.

WARNING: NULL and empty keys are ambiguous on non-initial calls. Passing NULL key but repeating the previous md reuses the previous key rather than the empty key.

OPENSSL_EXPORT int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, size_t key_len,
                                const EVP_MD *md, ENGINE *impl);

HMAC_Update hashes data_len bytes from data into the current HMAC operation in ctx. It returns one.

OPENSSL_EXPORT int HMAC_Update(HMAC_CTX *ctx, const uint8_t *data,
                               size_t data_len);

HMAC_Final completes the HMAC operation in ctx and writes the result to out and the sets *out_len to the length of the result. On entry, out must contain at least HMAC_size bytes of space. An output size of EVP_MAX_MD_SIZE will always be large enough. It returns one on success or zero on allocation failure.

OPENSSL_EXPORT int HMAC_Final(HMAC_CTX *ctx, uint8_t *out,
                              unsigned int *out_len);

Utility functions.

HMAC_size returns the size, in bytes, of the HMAC that will be produced by ctx. On entry, ctx must have been setup with HMAC_Init_ex.

OPENSSL_EXPORT size_t HMAC_size(const HMAC_CTX *ctx);

HMAC_CTX_get_md returns ctx's hash function.

OPENSSL_EXPORT const EVP_MD *HMAC_CTX_get_md(const HMAC_CTX *ctx);

HMAC_CTX_copy_ex sets dest equal to src. On entry, dest must have been initialised by calling HMAC_CTX_init. It returns one on success and zero on error.

OPENSSL_EXPORT int HMAC_CTX_copy_ex(HMAC_CTX *dest, const HMAC_CTX *src);

HMAC_CTX_reset calls HMAC_CTX_cleanup followed by HMAC_CTX_init.

OPENSSL_EXPORT void HMAC_CTX_reset(HMAC_CTX *ctx);

Deprecated functions.

OPENSSL_EXPORT int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len,
                             const EVP_MD *md);

HMAC_CTX_copy calls HMAC_CTX_init on dest and then sets it equal to src. On entry, dest must /not/ be initialised for an operation with HMAC_Init_ex. It returns one on success and zero on error.

OPENSSL_EXPORT int HMAC_CTX_copy(HMAC_CTX *dest, const HMAC_CTX *src);