From 3d1711bc27a819876552e1104a3f2fdfb0760a4e Mon Sep 17 00:00:00 2001 From: Petri Savolainen Date: Thu, 1 Nov 2018 10:06:25 +0200 Subject: api: ipsec: add auth_key_extra IPSEC crypto param IPSEC needs salt (extra keying material) when GMAC authentication algorithm is used. Added auth_key_extra for that use case. Also improved algorithm, key and key_extra usage documentation. All algorithms that need salt/nonce are now listed. Cipher side key information need to be set always when algorithm is not NULL. Authentication side key information is ignored when a single algorithm (AEAD) does both cipher and authentication. Signed-off-by: Petri Savolainen Reviewed-by: Dmitry Eremin-Solenikov Reviewed-by: Bill Fischofer Signed-off-by: Maxim Uvarov --- include/odp/api/spec/ipsec.h | 50 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 44 insertions(+), 6 deletions(-) (limited to 'include') diff --git a/include/odp/api/spec/ipsec.h b/include/odp/api/spec/ipsec.h index 2d1c4d9ba..1b65e8d06 100644 --- a/include/odp/api/spec/ipsec.h +++ b/include/odp/api/spec/ipsec.h @@ -364,27 +364,65 @@ typedef enum odp_ipsec_tunnel_type_t { * IPSEC crypto parameters */ typedef struct odp_ipsec_crypto_param_t { - /** Cipher algorithm */ + /** Cipher algorithm + * + * Select cipher algorithm to be used. ODP_CIPHER_ALG_NULL indicates + * that ciphering is disabled. See 'ciphers' field of + * odp_ipsec_capability_t for supported cipher algorithms. Algorithm + * descriptions can be found from odp_cipher_alg_t documentation. Note + * that some algorithms restrict choice of the pairing authentication + * algorithm. When ciphering is enabled, cipher key and potential extra + * key material (cipher_key_extra) need to be set. The default value + * is ODP_CIPHER_ALG_NULL. + */ odp_cipher_alg_t cipher_alg; /** Cipher key */ odp_crypto_key_t cipher_key; - /** Extra keying material for cipher key + /** Extra keying material for cipher algorithm * * Additional data used as salt or nonce if the algorithm requires it, * other algorithms ignore this field. These algorithms require this - * field set: - * - AES_GCM: 4 bytes of salt - **/ + * field to be set: + * - ODP_CIPHER_ALG_AES_CTR: 4 bytes of nonce + * - ODP_CIPHER_ALG_AES_GCM: 4 bytes of salt + * - ODP_CIPHER_ALG_AES_CCM: 3 bytes of salt + * - ODP_CIPHER_ALG_CHACHA20_POLY1305: 4 bytes of salt + */ odp_crypto_key_t cipher_key_extra; - /** Authentication algorithm */ + /** Authentication algorithm + * + * Select authentication algorithm to be used. ODP_AUTH_ALG_NULL + * indicates that authentication is disabled. See 'auths' field of + * odp_ipsec_capability_t for supported authentication algorithms. + * Algorithm descriptions can be found from odp_auth_alg_t + * documentation. Note that some algorithms restrict choice of the + * pairing cipher algorithm. When single algorithm provides both + * ciphering and authentication (i.e. Authenticated Encryption), + * authentication side key information ('auth_key' and + * 'auth_key_extra') is ignored, and cipher side values are + * used instead. These algorithms ignore authentication side key + * information: ODP_AUTH_ALG_AES_GCM, ODP_AUTH_ALG_AES_CCM and + * ODP_AUTH_ALG_CHACHA20_POLY1305. Otherwise, authentication side + * parameters must be set when authentication is enabled. The default + * value is ODP_AUTH_ALG_NULL. + */ odp_auth_alg_t auth_alg; /** Authentication key */ odp_crypto_key_t auth_key; + /** Extra keying material for authentication algorithm + * + * Additional data used as salt or nonce if the algorithm requires it, + * other algorithms ignore this field. These algorithms require this + * field to be set: + * - ODP_AUTH_ALG_AES_GMAC: 4 bytes of salt + */ + odp_crypto_key_t auth_key_extra; + } odp_ipsec_crypto_param_t; /** IPv4 header parameters */ -- cgit v1.2.3