xref: /freebsd/sys/dev/qat/qat_api/common/crypto/sym/include/lac_sym.h (revision 71625ec9)

/* SPDX-License-Identifier: BSD-3-Clause */
/* Copyright(c) 2007-2022 Intel Corporation */

/**
 ***************************************************************************
 * @file lac_sym.h
 *
 * @defgroup LacSym    Symmetric
 *
 * @ingroup Lac
 *
 * Symmetric component includes cipher, Hash, chained cipher & hash,
 * authenticated encryption and key generation.
 *
 * @lld_start
 * @lld_overview
 *
 * The symmetric component demuliplexes the following crypto operations to
 * the appropriate sub-components: cipher, hash, algorithm chaining and
 * authentication encryption. It is a common layer between the above
 * mentioned components where common resources are allocated and paramater
 * checks are done. The operation specific resource allocation and parameter
 * checks are done in the sub-component itself.
 *
 * The symmetric component demultiplexes the session register/deregister
 * and perform functions to the appropriate subcomponents.
 *
 * @lld_dependencies
 * - \ref LacSymPartial "Partial Packet Code":  This code manages the partial
 *    packet state for a session.
 * - \ref LacBufferDesc  "Common Buffer Code" : This code traverses a buffer
 *   chain to ensure it is valid.
 * - \ref LacSymStats "Statistics": Manages statistics for symmetric
 * - \ref LacSymQat "Symmetric QAT": The symmetric qat component is
 *   initialiased by the symmetric component.
 * - \ref LacCipher "Cipher" : demultiplex cipher opertions to this component.
 * - \ref LacHash "Hash" : demultiplex hash opertions to this component.
 *   to this component.
 * - \ref LacAlgChain "Algorithm Chaining": The algorithm chaining component
 * - OSAL : Memory allocation, Mutex's, atomics
 *
 * @lld_initialisation
 * This component is initialied during the LAC initialisation sequence. It
 * initialises the session table, statistics, symmetric QAT, initialises the
 * hash definitions lookup table, the hash alg supported lookup table and
 * registers a callback function with the symmetric response handler to process
 * response messages for Cipher, Hash and Algorithm-Chaining requests.
 *
 * @lld_module_algorithms
 *
 * @lld_process_context
 * Refer to \ref LacHash "Hash" and \ref LacCipher "Cipher" for sequence
 * diagrams from the symmetric component through the sub components.
 *
 * @lld_end
 *
 ***************************************************************************/

/***************************************************************************/

#ifndef LAC_SYM_H
#define LAC_SYM_H

#include "cpa.h"
#include "cpa_cy_sym.h"
#include "cpa_cy_sym_dp.h"
#include "lac_common.h"
#include "lac_mem_pools.h"
#include "lac_sym_cipher_defs.h"
#include "icp_qat_fw_la.h"

#define LAC_SYM_KEY_TLS_PREFIX_SIZE 128
/**< Hash Prefix size in bytes for TLS (128 = MAX = SHA2 (384, 512)*/

#define LAC_SYM_OPTIMISED_CD_SIZE 64
/**< The size of the optimised content desc in DRAM*/

#define LAC_SYM_KEY_MAX_HASH_STATE_BUFFER (LAC_SYM_KEY_TLS_PREFIX_SIZE * 2)
/**< hash state prefix buffer structure that holds the maximum sized secret */

#define LAC_SYM_HASH_BUFFER_LEN 64
/**< Buffer length to hold 16 byte MD5 key and 20 byte SHA1 key */

/* The ARC4 key will not be stored in the content descriptor so we only need to
 * reserve enough space for the next biggest cipher setup block.
 * Kasumi needs to store 2 keys and to have the size of 2 blocks for fw*/
#define LAC_SYM_QAT_MAX_CIPHER_SETUP_BLK_SZ                                    \
	(sizeof(icp_qat_hw_cipher_config_t) + 2 * ICP_QAT_HW_KASUMI_KEY_SZ +   \
	 2 * ICP_QAT_HW_KASUMI_BLK_SZ)
/**< @ingroup LacSymQat
 * Maximum size for the cipher setup block of the content descriptor */

#define LAC_SYM_QAT_MAX_HASH_SETUP_BLK_SZ sizeof(icp_qat_hw_auth_algo_blk_t)
/**< @ingroup LacSymQat
 * Maximum size for the hash setup block of the content descriptor */

#define LAC_SYM_QAT_CONTENT_DESC_MAX_SIZE                                      \
	LAC_ALIGN_POW2_ROUNDUP(LAC_SYM_QAT_MAX_CIPHER_SETUP_BLK_SZ +           \
				   LAC_SYM_QAT_MAX_HASH_SETUP_BLK_SZ,          \
			       (1 << LAC_64BYTE_ALIGNMENT_SHIFT))
/**< @ingroup LacSymQat
 *  Maximum size of content descriptor. This is incremented to the next multiple
 * of 64 so that it can be 64 byte aligned */

#define LAC_SYM_QAT_API_ALIGN_COOKIE_OFFSET                                    \
	(offsetof(CpaCySymDpOpData, instanceHandle))
/**< @ingroup LacSymQat
 * Size which needs to be reserved before the instanceHandle field of
 * lac_sym_bulk_cookie_s to align it to the correspondent instanceHandle
 * in CpaCySymDpOpData */

#define LAC_SIZE_OF_CACHE_HDR_IN_LW 6
/**< Size of Header part of reqCache/shramReqCache */

#define LAC_SIZE_OF_CACHE_MID_IN_LW 2
/**< Size of Mid part (LW14/15) of reqCache/shramReqCache */

#define LAC_SIZE_OF_CACHE_FTR_IN_LW 6
/**< Size of Footer part of reqCache/shramReqCache */

#define LAC_SIZE_OF_CACHE_TO_CLEAR_IN_LW 20
/**< Size of dummy reqCache/shramReqCache to clear */

#define LAC_START_OF_CACHE_MID_IN_LW 14
/**< Starting LW of reqCache/shramReqCache Mid */

#define LAC_START_OF_CACHE_FTR_IN_LW 26
/**< Starting LW of reqCache/shramReqCache Footer */

/**
 *******************************************************************************
 * @ingroup LacSym
 *      Symmetric cookie
 *
 * @description
 *      This cookie stores information for a particular symmetric perform op.
 *      This includes the request params, re-aligned Cipher IV, the request
 *      message sent to the QAT engine, and various user-supplied parameters
 *      for the operation which will be needed in our callback function.
 *      A pointer to this cookie is stored in the opaque data field of the QAT
 *      message so that it can be accessed in the asynchronous callback.
 *      Cookies for multiple operations on a given session can be linked
 *      together to allow queuing of requests using the pNext field.
 *
 *      The parameters are placed in order to match the CpaCySymDpOpData
 *structure
 *****************************************************************************/
typedef struct lac_sym_bulk_cookie_s {

	/* CpaCySymDpOpData struct so need to keep this here for correct
	 * alignment*/
	Cpa8U reserved[LAC_SYM_QAT_API_ALIGN_COOKIE_OFFSET];
	/** NOTE: Field must be correctly aligned in memory for access by QAT
	 * engine
	 */
	CpaInstanceHandle instanceHandle;
	/**< Instance handle for the operation */
	CpaCySymSessionCtx sessionCtx;
	/**< Session context */
	void *pCallbackTag;
	/**< correlator supplied by the client */
	icp_qat_fw_la_bulk_req_t qatMsg;
	/**< QAT request message */
	const CpaCySymOpData *pOpData;
	/**< pointer to the op data structure that the user supplied in the
	 * perform
	 * operation. The op data is modified in the process callback function
	 * and the pointer is returned to the user in their callback function */
	CpaBoolean updateSessionIvOnSend;
	/**< Boolean flag to indicate if the session cipher IV buffer should be
	 * updated prior to sending the request */
	CpaBoolean updateUserIvOnRecieve;
	/**< Boolean flag to indicate if the user's cipher IV buffer should be
	 * updated after receiving the response from the QAT */
	CpaBoolean updateKeySizeOnRecieve;
/**< Boolean flag to indicate if the cipher key size should be
 * updated after receiving the response from the QAT */
	CpaBufferList *pDstBuffer;
	/**< Pointer to destination buffer to hold the data output */
	struct lac_sym_bulk_cookie_s *pNext;
	/**< Pointer to next node in linked list (if request is queued) */
} lac_sym_bulk_cookie_t;

/**
*******************************************************************************
* @ingroup LacSymKey
*      symmetric Key cookie
* @description
*      This cookie stores information for a particular keygen perform op.
*      This includes a hash content descriptor, request params, hash state
*      buffer, and various user-supplied parameters for the operation which
*      will be needed in our callback function.
*      A pointer to this cookie is stored in the opaque data field of the QAT
*      message so that it can be accessed in the asynchronous callback.
*****************************************************************************/
typedef struct lac_sym_key_cookie_s {
	CpaInstanceHandle instanceHandle;
	/**< QAT device id supplied by the client */
	void *pCallbackTag;
	/**< Mechanism used. TLS, SSL or MGF */
	Cpa8U contentDesc[LAC_SYM_QAT_MAX_HASH_SETUP_BLK_SZ];
	/**< Content descriptor.
	 **< NOTE: Field must be correctly aligned in memory for access by QAT
	 * engine */
	union {
		icp_qat_fw_la_ssl_key_material_input_t sslKeyInput;
		/**< SSL key material input structure */
		icp_qat_fw_la_tls_key_material_input_t tlsKeyInput;
		/**< TLS key material input structure */
		icp_qat_fw_la_hkdf_key_material_input_t tlsHKDFKeyInput;
		/**< TLS HHKDF key material input structure */
	} u;
	/**< NOTE: Field must be correctly aligned in memory for access by QAT
	 * engine */
	Cpa8U hashStateBuffer[LAC_SYM_KEY_MAX_HASH_STATE_BUFFER];
	/**< hash state prefix buffer
	 * NOTE: Field must be correctly aligned in memory for access by QAT
	 * engine
	 */
	CpaCyGenFlatBufCbFunc pKeyGenCb;
	/**< callback function supplied by the client */
	void *pKeyGenOpData;
	/**< pointer to the (SSL/TLS) or MGF op data structure that the user
	 * supplied in the perform operation */
	CpaFlatBuffer *pKeyGenOutputData;
	/**< Output data pointer supplied by the client */
	Cpa8U hashKeyBuffer[LAC_SYM_HASH_BUFFER_LEN];
	/**< 36 byte buffer to store MD5 key and SHA1 key */
} lac_sym_key_cookie_t;

/**
*******************************************************************************
* @ingroup LacSymNrbg
*      symmetric NRBG cookie
* @description
*      This cookie stores information for a particular NRBG operation.
*      This includes various user-supplied parameters for the operation which
*      will be needed in our callback function.
*      A pointer to this cookie is stored in the opaque data field of the QAT
*      message so that it can be accessed in the asynchronous callback.
*****************************************************************************/
typedef struct lac_sym_nrbg_cookie_s {
	CpaInstanceHandle instanceHandle;
	/**< QAT device id supplied by the client */
	void *pCallbackTag;
	/**< Opaque data supplied by the client */
	icp_qat_fw_la_trng_test_result_t trngHTResult;
	/**< TRNG health test result
	 **< NOTE: Field must be correctly aligned in memory for access by QAT
	 * engine */
	icp_qat_fw_la_trng_req_t trngReq;
	/**< TRNG request message */
	CpaCyGenFlatBufCbFunc pCb;
	/**< Callback function supplied by the client */
	void *pOpData;
	/**< Op data pointer supplied by the client */
	CpaFlatBuffer *pOutputData;
	/**< Output data pointer supplied by the client */
} lac_sym_nrbg_cookie_t;

/**
*******************************************************************************
* @ingroup LacSym
*      symmetric cookie
* @description
*      used to determine the amount of memory to allocate for the symmetric
*      cookie pool. As symmetric, random and key generation shared the same
*      pool
*****************************************************************************/
typedef struct lac_sym_cookie_s {
	union {
		lac_sym_bulk_cookie_t bulkCookie;
		/**< symmetric bulk cookie */
		lac_sym_key_cookie_t keyCookie;
		/**< symmetric key cookie */
		lac_sym_nrbg_cookie_t nrbgCookie;
		/**< symmetric NRBG cookie */
	} u;
	Cpa64U keyContentDescPhyAddr;
	Cpa64U keyHashStateBufferPhyAddr;
	Cpa64U keySslKeyInputPhyAddr;
	Cpa64U keyTlsKeyInputPhyAddr;
} lac_sym_cookie_t;

typedef struct icp_qat_la_auth_req_params_s {
	/** equivalent of LW26 of icp_qat_fw_la_auth_req_params_s */
	union {
		uint8_t inner_prefix_sz;
		/**< Size in bytes of the inner prefix data */

		uint8_t aad_sz;
		/**< Size in bytes of padded AAD data to prefix to the packet
		 * for CCM
		 *  or GCM processing */
	} u2;

	uint8_t resrvd1;
	/**< reserved */

	uint8_t hash_state_sz;
	/**< Number of quad words of inner and outer hash prefix data to process
	 * Maximum size is 240 */

	uint8_t auth_res_sz;
	/**< Size in bytes of the authentication result */
} icp_qat_la_auth_req_params_t;

/* Header (LW's 0 - 5) of struct icp_qat_fw_la_bulk_req_s */
typedef struct icp_qat_la_bulk_req_hdr_s {
	/**< LWs 0-1 */
	icp_qat_fw_comn_req_hdr_t comn_hdr;
	/**< Common request header - for Service Command Id,
	 * use service-specific Crypto Command Id.
	 * Service Specific Flags - use Symmetric Crypto Command Flags
	 * (all of cipher, auth, SSL3, TLS and MGF,
	 * excluding TRNG - field unused) */

	/**< LWs 2-5 */
	icp_qat_fw_comn_req_hdr_cd_pars_t cd_pars;
	/**< Common Request content descriptor field which points either to a
	 * content descriptor
	 * parameter block or contains the service-specific data itself. */
} icp_qat_la_bulk_req_hdr_t;

/** Footer (LW's 26 - 31) of struct icp_qat_fw_la_bulk_req_s */
typedef struct icp_qat_la_bulk_req_ftr_s {
	/**< LW 0 - equivalent to LW26 of icp_qat_fw_la_bulk_req_t */
	icp_qat_la_auth_req_params_t serv_specif_rqpars;
	/**< Common request service-specific parameter field */

	/**< LW's 1-5, equivalent to LWs 27-31 of icp_qat_fw_la_bulk_req_s */
	icp_qat_fw_comn_req_cd_ctrl_t cd_ctrl;
	/**< Common request content descriptor control block -
	 * this field is service-specific */
} icp_qat_la_bulk_req_ftr_t;

/**
 ***
 *******************************************************************************
 * @ingroup LacSym
 *      Compile time check of lac_sym_bulk_cookie_t
 *
 * @description
 *      Performs a compile time check of lac_sym_bulk_cookie_t to ensure IA
 *      assumptions are valid.
 *
 *****************************************************************************/
void LacSym_CompileTimeAssertions(void);

void LacDp_WriteRingMsgFull(CpaCySymDpOpData *pRequest,
			    icp_qat_fw_la_bulk_req_t *pCurrentQatMsg);
void LacDp_WriteRingMsgOpt(CpaCySymDpOpData *pRequest,
			   icp_qat_fw_la_bulk_req_t *pCurrentQatMsg);

#endif /* LAC_SYM_H */