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