1 /*************************************************************************** 2 * Copyright (c) 2024 Microsoft Corporation 3 * 4 * This program and the accompanying materials are made available under the 5 * terms of the MIT License which is available at 6 * https://opensource.org/licenses/MIT. 7 * 8 * SPDX-License-Identifier: MIT 9 **************************************************************************/ 10 11 12 /**************************************************************************/ 13 /**************************************************************************/ 14 /** */ 15 /** NetX Crypto Component */ 16 /** */ 17 /** HMAC-based Extract-and-Expand Key Derivation Function (HKDF) */ 18 /** */ 19 /**************************************************************************/ 20 /**************************************************************************/ 21 22 23 /**************************************************************************/ 24 /* */ 25 /* COMPONENT DEFINITION RELEASE */ 26 /* */ 27 /* nx_crypto_hkdf.h PORTABLE C */ 28 /* 6.1 */ 29 /* */ 30 /* AUTHOR */ 31 /* */ 32 /* Timothy Stapko, Microsoft Corporation */ 33 /* */ 34 /* DESCRIPTION */ 35 /* */ 36 /* This file defines the NetX HKDF algorithm, derived from RFC 5869. */ 37 /* From user-specified input, the HKDF generates a block of data */ 38 /* suitable for use as key material for various cryptographic */ 39 /* protocols such as TLS 1.3. */ 40 /* */ 41 /* It is assumed that nx_api.h and nx_port.h have already been */ 42 /* included. */ 43 /* */ 44 /* RELEASE HISTORY */ 45 /* */ 46 /* DATE NAME DESCRIPTION */ 47 /* */ 48 /* 05-19-2020 Timothy Stapko Initial Version 6.0 */ 49 /* 09-30-2020 Timothy Stapko Modified comment(s), */ 50 /* resulting in version 6.1 */ 51 /* */ 52 /**************************************************************************/ 53 54 #ifndef NX_CRYPTO_HKDF_H 55 #define NX_CRYPTO_HKDF_H 56 57 /* Determine if a C++ compiler is being used. If so, ensure that standard 58 C is used to process the API information. */ 59 #ifdef __cplusplus 60 61 /* Yes, C++ compiler is present. Use standard C. */ 62 extern "C" { 63 64 #endif 65 66 67 #include "nx_crypto.h" 68 #include "nx_crypto_sha2.h" 69 #include "nx_crypto_hmac_sha5.h" 70 71 typedef struct NX_CRYPTO_HKDF_STRUCT 72 { 73 /* Pointer to salt value for HKDF-extract operation. */ 74 UCHAR *nx_crypto_hkdf_salt; 75 NX_CRYPTO_KEY_SIZE nx_crypto_hkdf_salt_length; 76 77 /* Pointer to Input Keying Material (IKM) for HKDF-extract. */ 78 UCHAR *nx_crypto_hkdf_ikm; 79 UINT nx_crypto_hkdf_ikm_length; 80 81 /* Application-specific "info" used in the HKDF-expand operation. */ 82 UCHAR *nx_crypto_hkdf_info; 83 UINT nx_crypto_hkdf_info_size; 84 85 /* Buffer to store Pseudo-Random Key (PRK) output from HKDF-extract. 86 The buffer must be as large as the largest HMAC hash output 87 (e.g. SHA-512 output length). */ 88 UCHAR nx_crypto_hkdf_prk[64]; 89 UINT nx_crypto_hkdf_prk_size; /* Actual output size (hash length). */ 90 91 /* The HMAC method to use (generic HMAC wrapper). */ 92 NX_CRYPTO_METHOD *nx_crypto_hmac_method; 93 94 /* The hash method to be used (e.g. SHA-256, SHA-384). */ 95 NX_CRYPTO_METHOD *nx_crypto_hash_method; 96 97 /* Temporary space for HKDF-expand intermediary (T). It must be large enough 98 * to hold the previous T concatenated with "info" and a single octet counter. 99 * Length > 64 + 50 + 1. Must be 4-byte aligned for hmac metadata below. */ 100 UCHAR nx_crypto_hkdf_temp_T[120]; 101 102 /* Workspace for the HMAC operations. */ 103 UCHAR nx_crypto_hmac_metadata[sizeof(NX_CRYPTO_SHA512_HMAC)]; 104 105 /* Output from HMAC operations. */ 106 UCHAR *nx_crypto_hmac_output; 107 UINT nx_crypto_hmac_output_size; 108 } NX_CRYPTO_HKDF; 109 110 extern NX_CRYPTO_METHOD crypto_method_hmac_md5; 111 extern NX_CRYPTO_METHOD crypto_method_hmac_sha1; 112 extern NX_CRYPTO_METHOD crypto_method_hmac_sha256; 113 extern NX_CRYPTO_METHOD crypto_method_hmac_sha384; 114 extern NX_CRYPTO_METHOD crypto_method_hmac_sha512; 115 116 UINT _nx_crypto_hkdf_extract(NX_CRYPTO_HKDF *hkdf); 117 UINT _nx_crypto_hkdf_expand(NX_CRYPTO_HKDF *hkdf, UCHAR *output, UINT desired_length); 118 119 /* Define the function prototypes for HKDF. */ 120 121 UINT _nx_crypto_method_hkdf_init(struct NX_CRYPTO_METHOD_STRUCT *method, 122 UCHAR *key, NX_CRYPTO_KEY_SIZE key_size_in_bits, 123 VOID **handle, 124 VOID *crypto_metadata, 125 ULONG crypto_metadata_size); 126 127 UINT _nx_crypto_method_hkdf_cleanup(VOID *crypto_metadata); 128 129 UINT _nx_crypto_method_hkdf_operation(UINT op, /* Encrypt, Decrypt, Authenticate */ 130 VOID *handle, /* Crypto handler */ 131 struct NX_CRYPTO_METHOD_STRUCT *method, 132 UCHAR *key, 133 NX_CRYPTO_KEY_SIZE key_size_in_bits, 134 UCHAR *input, 135 ULONG input_length_in_byte, 136 UCHAR *iv_ptr, 137 UCHAR *output, 138 ULONG output_length_in_byte, 139 VOID *crypto_metadata, 140 ULONG crypto_metadata_size, 141 VOID *packet_ptr, 142 VOID (*nx_crypto_hw_process_callback)(VOID *packet_ptr, UINT status)); 143 144 #ifdef __cplusplus 145 } 146 #endif 147 148 #endif 149
