1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 /* Copyright(c) 2007-2025 Intel Corporation */ 3 4 /** 5 ***************************************************************************** 6 * @file lac_sym_key.h 7 * 8 * @defgroup LacSymKey Key Generation 9 * 10 * @ingroup LacSym 11 * 12 * @lld_start 13 * 14 * @lld_overview 15 * 16 * Key generation component is responsible for SSL, TLS & MGF operations. All 17 * memory required for the keygen operations is got from the keygen cookie 18 * structure which is carved up as required. 19 * 20 * For SSL the QAT accelerates the nested hash function with MD5 as the 21 * outer hash and SHA1 as the inner hash. 22 * 23 * Refer to sections in draft-freier-ssl-version3-02.txt: 24 * 6.1 Asymmetric cryptographic computations - This refers to converting 25 * the pre-master secret to the master secret. 26 * 6.2.2 Converting the master secret into keys and MAC secrets - Using 27 * the master secret to generate the key material. 28 * 29 * For TLS the QAT accelerates the PRF function as described in 30 * rfc4346 - TLS version 1.1 (this obsoletes rfc2246 - TLS version 1.0) 31 * 5. HMAC and the pseudorandom function - For the TLS PRF and getting 32 * S1 and S2 from the secret. 33 * 6.3. Key calculation - For how the key material is generated 34 * 7.4.9. Finished - How the finished message uses the TLS PRF 35 * 8.1. Computing the master secret 36 * 37 * 38 * @lld_dependencies 39 * \ref LacSymQatHash: for building up hash content descriptor 40 * \ref LacMem: for virt to phys conversions 41 * 42 * @lld_initialisation 43 * The response handler is registered with Symmetric. The Maximum SSL is 44 * allocated. A structure is allocated containing all the TLS labels that 45 * are supported. On shutdown the memory for these structures are freed. 46 * 47 * @lld_module_algorithms 48 * @lld_process_context 49 * 50 * @lld_end 51 * 52 * 53 *****************************************************************************/ 54 #ifndef LAC_SYM_KEY_H_ 55 #define LAC_SYM_KEY_H_ 56 57 #include "icp_qat_fw_la.h" 58 #include "cpa_cy_key.h" 59 60 /**< @ingroup LacSymKey 61 * Label for SSL. Size is 136 bytes for 16 iterations, which can theroretically 62 * generate up to 256 bytes of output data. QAT will generate a maximum of 63 * 255 bytes */ 64 65 #define LAC_SYM_KEY_TLS_MASTER_SECRET_LABEL ("master secret") 66 /**< @ingroup LacSymKey 67 * Label for TLS Master Secret Key Derivation, as defined in RFC4346 */ 68 69 #define LAC_SYM_KEY_TLS_KEY_MATERIAL_LABEL ("key expansion") 70 /**< @ingroup LacSymKey 71 * Label for TLS Key Material Generation, as defined in RFC4346. */ 72 73 #define LAC_SYM_KEY_TLS_CLIENT_FIN_LABEL ("client finished") 74 /**< @ingroup LacSymKey 75 * Label for TLS Client finished Message, as defined in RFC4346. */ 76 77 #define LAC_SYM_KEY_TLS_SERVER_FIN_LABEL ("server finished") 78 /**< @ingroup LacSymKey 79 * Label for TLS Server finished Message, as defined in RFC4346. */ 80 81 /* 82 ******************************************************************************* 83 * Define Constants and Macros for SSL, TLS and MGF 84 ******************************************************************************* 85 */ 86 87 #define LAC_SYM_KEY_NO_HASH_BLK_OFFSET_QW 0 88 /**< Used to indicate there is no hash block offset in the content descriptor 89 */ 90 91 /* 92 ******************************************************************************* 93 * Define Constant lengths for HKDF TLS v1.3 sublabels. 94 ******************************************************************************* 95 */ 96 #define HKDF_SUB_LABEL_KEY_LENGTH ((Cpa8U)13) 97 #define HKDF_SUB_LABEL_IV_LENGTH ((Cpa8U)12) 98 #define HKDF_SUB_LABEL_RESUMPTION_LENGTH ((Cpa8U)20) 99 #define HKDF_SUB_LABEL_FINISHED_LENGTH ((Cpa8U)18) 100 #define HKDF_SUB_LABELS_ALL \ 101 (CPA_CY_HKDF_SUBLABEL_KEY | CPA_CY_HKDF_SUBLABEL_IV | \ 102 CPA_CY_HKDF_SUBLABEL_RESUMPTION | CPA_CY_HKDF_SUBLABEL_FINISHED) 103 #define LAC_KEY_HKDF_SUBLABELS_NUM 4 104 #define LAC_KEY_HKDF_DIGESTS 0 105 #define LAC_KEY_HKDF_CIPHERS_MAX (CPA_CY_HKDF_TLS_AES_128_CCM_8_SHA256 + 1) 106 #define LAC_KEY_HKDF_SUBLABELS_MAX (LAC_KEY_HKDF_SUBLABELS_NUM + 1) 107 108 /** 109 ****************************************************************************** 110 * @ingroup LacSymKey 111 * TLS label struct 112 * 113 * @description 114 * This structure is used to hold the various TLS labels. Each field is 115 * on an 8 byte boundary provided the structure itself is 8 bytes aligned. 116 *****************************************************************************/ 117 typedef struct lac_sym_key_tls_labels_s { 118 Cpa8U masterSecret[ICP_QAT_FW_LA_TLS_LABEL_LEN_MAX]; 119 /**< Master secret label */ 120 Cpa8U keyMaterial[ICP_QAT_FW_LA_TLS_LABEL_LEN_MAX]; 121 /**< Key material label */ 122 Cpa8U clientFinished[ICP_QAT_FW_LA_TLS_LABEL_LEN_MAX]; 123 /**< client finished label */ 124 Cpa8U serverFinished[ICP_QAT_FW_LA_TLS_LABEL_LEN_MAX]; 125 /**< server finished label */ 126 } lac_sym_key_tls_labels_t; 127 128 /** 129 ****************************************************************************** 130 * @ingroup LacSymKey 131 * TLS HKDF sub label struct 132 * 133 * @description 134 * This structure is used to hold the various TLS HKDF sub labels. 135 * Each field is on an 8 byte boundary. 136 *****************************************************************************/ 137 typedef struct lac_sym_key_tls_hkdf_sub_labels_s { 138 CpaCyKeyGenHKDFExpandLabel keySublabel256; 139 /**< CPA_CY_HKDF_SUBLABEL_KEY */ 140 CpaCyKeyGenHKDFExpandLabel ivSublabel256; 141 /**< CPA_CY_HKDF_SUBLABEL_IV */ 142 CpaCyKeyGenHKDFExpandLabel resumptionSublabel256; 143 /**< CPA_CY_HKDF_SUBLABEL_RESUMPTION */ 144 CpaCyKeyGenHKDFExpandLabel finishedSublabel256; 145 /**< CPA_CY_HKDF_SUBLABEL_FINISHED */ 146 CpaCyKeyGenHKDFExpandLabel keySublabel384; 147 /**< CPA_CY_HKDF_SUBLABEL_KEY */ 148 CpaCyKeyGenHKDFExpandLabel ivSublabel384; 149 /**< CPA_CY_HKDF_SUBLABEL_IV */ 150 CpaCyKeyGenHKDFExpandLabel resumptionSublabel384; 151 /**< CPA_CY_HKDF_SUBLABEL_RESUMPTION */ 152 CpaCyKeyGenHKDFExpandLabel finishedSublabel384; 153 /**< CPA_CY_HKDF_SUBLABEL_FINISHED */ 154 CpaCyKeyGenHKDFExpandLabel keySublabelChaChaPoly; 155 /**< CPA_CY_HKDF_SUBLABEL_KEY */ 156 CpaCyKeyGenHKDFExpandLabel ivSublabelChaChaPoly; 157 /**< CPA_CY_HKDF_SUBLABEL_IV */ 158 CpaCyKeyGenHKDFExpandLabel resumptionSublabelChaChaPoly; 159 /**< CPA_CY_HKDF_SUBLABEL_RESUMPTION */ 160 CpaCyKeyGenHKDFExpandLabel finishedSublabelChaChaPoly; 161 /**< CPA_CY_HKDF_SUBLABEL_FINISHED */ 162 Cpa64U sublabelPhysAddr256; 163 /**< Physical address of the SHA-256 subLabels */ 164 Cpa64U sublabelPhysAddr384; 165 /**< Physical address of the SHA-384 subLabels */ 166 Cpa64U sublabelPhysAddrChaChaPoly; 167 /**< Physical address of the ChaChaPoly subLabels */ 168 } lac_sym_key_tls_hkdf_sub_labels_t; 169 170 /** 171 ****************************************************************************** 172 * @ingroup LacSymKey 173 * This function prints the stats to standard out. 174 * 175 * @retval CPA_STATUS_SUCCESS Status Success 176 * @retval CPA_STATUS_FAIL General failure 177 * 178 *****************************************************************************/ 179 void LacKeygen_StatsShow(CpaInstanceHandle instanceHandle); 180 181 #endif 182