// Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com) All rights reserved.
// SPDX-License-Identifier: Apache-2.0

#ifndef OPENSSL_HEADER_HMAC_H
#define OPENSSL_HEADER_HMAC_H

#include <openssl/base.h>

#include <openssl/digest.h>
#include <openssl/sha.h>
#include <openssl/md5.h>

#if defined(__cplusplus)
extern "C" {
#endif


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


// 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 zeroises |ctx| since it's allocated on the stack.
// This brings the context to its initial state.
OPENSSL_EXPORT void HMAC_CTX_cleanup(HMAC_CTX *ctx);

// HMAC_CTX_cleanse calls |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. This function resets |HMAC_CTX| to a
// fresh state, even if |HMAC_Update| or |HMAC_Final| have been called
// previously. 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 and resets to a clean state
// ready for new data. 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 then 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);


// Precomputed key functions

// HMAC_MD5_PRECOMPUTED_KEY_SIZE is the precomputed key size for MD5, in bytes
#define HMAC_MD5_PRECOMPUTED_KEY_SIZE 32
// HMAC_SHA1_PRECOMPUTED_KEY_SIZE is the precomputed key size for SHA1, in bytes
#define HMAC_SHA1_PRECOMPUTED_KEY_SIZE 40
// HMAC_SHA224_PRECOMPUTED_KEY_SIZE is the precomputed key size for SHA224, in bytes
#define HMAC_SHA224_PRECOMPUTED_KEY_SIZE 64
// HMAC_SHA256_PRECOMPUTED_KEY_SIZE is the precomputed key size for SHA256, in bytes
#define HMAC_SHA256_PRECOMPUTED_KEY_SIZE 64
// HMAC_SHA384_PRECOMPUTED_KEY_SIZE is the precomputed key size for SHA384, in bytes
#define HMAC_SHA384_PRECOMPUTED_KEY_SIZE 128
// HMAC_SHA512_PRECOMPUTED_KEY_SIZE is the precomputed key size for SHA512, in bytes
#define HMAC_SHA512_PRECOMPUTED_KEY_SIZE 128
// HMAC_SHA512_224_PRECOMPUTED_KEY_SIZE is the precomputed key size for SHA512_224, in bytes
#define HMAC_SHA512_224_PRECOMPUTED_KEY_SIZE 128
// HMAC_SHA512_256_PRECOMPUTED_KEY_SIZE is the precomputed key size for SHA512_256, in bytes
#define HMAC_SHA512_256_PRECOMPUTED_KEY_SIZE 128

// HMAC_MAX_PRECOMPUTED_KEY_SIZE is the largest precomputed key size, in bytes.
#define HMAC_MAX_PRECOMPUTED_KEY_SIZE (2 * (EVP_MAX_MD_CHAINING_LENGTH))

// HMAC_set_precomputed_key_export sets the context |ctx| to allow export of the
// precomputed key using HMAC_get_precomputed_key. On entry, HMAC_CTX must have
// been initialized via HMAC_Init_*, and neither HMAC_Update nor HMAC_Final
// must have been called after the last HMAC_Init_ex. It returns one on success
// and zero on error.
// After a successful call to HMAC_set_precomputed_key_export, HMAC_Update and
// HMAC_Final will fail.
//
// Note: The main reason for this function is to satisfy FIPS assertion AS09.16,
// since HMAC_get_precomputed_key returns key material (i.e., a CSP in NIST
// terminology).
OPENSSL_EXPORT int HMAC_set_precomputed_key_export(HMAC_CTX *ctx);

// HMAC_get_precomputed_key exports the precomputed key. If |out| is NULL,
// |out_len| is set to the size of the precomputed key. After such a call,
// |HMAC_get_precomputed_key| can directly be called again with a non-null
// |out|. But |HMAC_Update| and |HMAC_Final| will still fail.
//
// If |out| is not NULL, |*out_len| must contain the number of bytes of space
// available at |out|. If sufficient, the precomputed key will be written in
// |out| and |out_len| will be updated with the true length (which is
// |HMAC_xxx_PRECOMPUTED_KEY_SIZE| for hash function xxx). An output size of
// |HMAC_MAX_PRECOMPUTED_KEY_SIZE| will always be large enough. After a
// successful call to |HMAC_get_precomputed_key| with a non-NULL |out|, the
// context can be directly used for computing an HMAC using |HMAC_Update| and
// |HMAC_Final|.
//
// The function returns one on success and zero on error.
//
// The precomputed key is the concatenation:
//   precomputed_key = key_ipad || key_opad
// where:
//   key_ipad = Hash_Compression_Function(key' xor ipad)
//   key_opad = Hash_Compression_Function(key' xor opad)
//   key' = padding of key with 0 on the right to be of the block length
//                if length of key is at most the block length
//          or Hash(key)
//                otherwise
//
// Knowledge of precomputed_key is sufficient to compute HMAC. Use of the
// precomputed key instead of the key reduces by 2 the number of hash
// compression function calls (or more if key is larger than the block length)
OPENSSL_EXPORT int HMAC_get_precomputed_key(HMAC_CTX *ctx, uint8_t *out,
                                           size_t *out_len);

// HMAC_Init_from_precomputed_key sets up an initialised |HMAC_CTX| to use
// |md| as the hash function and |precomputed_key| as the precomputed key
// (see |HMAC_get_precomputed_key|).
// For a non-initial call, |md| may be NULL, in which case the previous hash
// function is used. If the hash function has not changed and |precomputed_key|
// is NULL, the previous key is used. This non-initial call is interchangeable
// with calling |HMAC_Init_ex| with the same parameters. It returns one on
// success or zero on failure.
//
// Note: Contrary to input keys to |HMAC_Init_ex|, which can be the empty key,
//   an input precomputed key cannot be empty in an initial call to
//   |HMAC_Init_from_precomputed_key|. Otherwise, the call fails and returns zero.
OPENSSL_EXPORT int HMAC_Init_from_precomputed_key(HMAC_CTX *ctx,
                                                 const uint8_t *precomputed_key,
                                                 size_t precompute_key_len,
                                                 const EVP_MD *md);


// 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);


// Private functions
typedef struct hmac_methods_st HmacMethods;

// We use a union to ensure that enough space is allocated and never actually
// bother with the named members. We do not externalize SHA3 ctx definition,
// so hard-code ctx size below and use a compile-time assertion where that ctx
// is defined to ensure it does not exceed size bounded by |md_ctx_union|. This
// is OK because union members are never referenced, they're only used for sizing.
union md_ctx_union {
  MD5_CTX md5;
  SHA_CTX sha1;
  SHA256_CTX sha256;
  SHA512_CTX sha512;
  uint8_t sha3[400];
};

struct hmac_ctx_st {
  const EVP_MD *md;
  const HmacMethods *methods;
  union md_ctx_union md_ctx;
  union md_ctx_union i_ctx;
  union md_ctx_union o_ctx;
  int8_t state;
} /* HMAC_CTX */;


#if defined(__cplusplus)
}  // extern C

#if !defined(BORINGSSL_NO_CXX)
extern "C++" {

BSSL_NAMESPACE_BEGIN

BORINGSSL_MAKE_DELETER(HMAC_CTX, HMAC_CTX_free)

using ScopedHMAC_CTX =
    internal::StackAllocated<HMAC_CTX, void, HMAC_CTX_init, HMAC_CTX_cleanup>;

BSSL_NAMESPACE_END

}  // extern C++
#endif

#endif


// Errors

#define HMAC_R_MISSING_PARAMETERS 100
#define HMAC_R_BUFFER_TOO_SMALL 102
#define HMAC_R_SET_PRECOMPUTED_KEY_EXPORT_NOT_CALLED 103
#define HMAC_R_NOT_CALLED_JUST_AFTER_INIT 104
#define HMAC_R_PRECOMPUTED_KEY_NOT_SUPPORTED_FOR_DIGEST 105
#define HMAC_R_UNSUPPORTED_DIGEST 106

#endif  // OPENSSL_HEADER_HMAC_H