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