api: crypto: add bit mode session parameters for cipher and auth

Add cipher_range_in_bits and auth_range_in_bits session parameters that
control whether cipher/auth range is given in bits or bytes. By default
the range is in bytes.

Change bit_mode cipher/auth capability flag to indicate whether bit mode
is supported in addition to byte mode that is always supported. Previously
bit_mode capability told whether the cipher/auth had to be used in bit
or byte mode.

This simplifies crypto API usage as ODP applications that do not require
bit mode can simply request byte mode sessions and do not have to check
in which mode a particular algorithm in a particular ODP implementation
has to be used and then convert range units accordingly.

After this change it is possible for an ODP implementation to start
supporting bit mode for an algorithm without affecting applications that
use byte mode and do not fully do the capability checking and unit
conversion dance.

This also removes the ambiguity regarding the range units of the null
algorithms. Currently some ODP implementations advertise null algorithm
capabilities both with and without bit_mode, which is inconsistent and
will break as soon as the ranges of the null algorithms are not ignored
(as then the ODP implementation could not tell if the range given to
it was in bits or bytes).

Signed-off-by: Janne Peltonen <janne.peltonen@nokia.com>
Reviewed-by: Petri Savolainen <petri.savolainen@nokia.com>
Reviewed-by: Jere Leppänen <jere.leppanen@nokia.com>
Reviewed-by: Anoob Joseph <anoobj@marvell.com>

1 files changed, 58 insertions, 26 deletions

diff --git a/include/odp/api/spec/crypto_types.h b/include/odp/api/spec/crypto_types.h
index 46d9ae3f7..5bcb1e2e0 100644
--- a/include/odp/api/spec/crypto_types.h
+++ b/include/odp/api/spec/crypto_types.h
@@ -560,6 +560,30 @@ typedef struct odp_crypto_session_param_t {
 	 */
 	odp_crypto_op_type_t op_type;
 
+	/** Cipher range unit
+	 *
+	 *  When this flag is true, cipher range offset and length are in bits.
+	 *  Otherwise the offset and length are in bytes.
+	 *
+	 *  If cipher capabilities do not include bit_mode, setting this to
+	 *  true causes a session creation failure.
+	 *
+	 *  The default value is false.
+	 */
+	odp_bool_t cipher_range_in_bits;
+
+	/** Auth range unit
+	 *
+	 *  When this flag is true, auth range offset and length are in bits.
+	 *  Otherwise the offset and length are in bytes.
+	 *
+	 *  If auth capabilities do not include bit_mode, setting this to
+	 *  true causes a session creation failure.
+	 *
+	 *  The default value is false.
+	 */
+	odp_bool_t auth_range_in_bits;
+
 	/** Authenticate cipher vs. plain text
 	 *
 	 *  Controls ordering of authentication and cipher operations,
@@ -725,6 +749,9 @@ typedef struct odp_crypto_packet_op_param_t {
 
 	/** Data range to be ciphered.
 	 *
+	 *  The range is given in bits or bytes as configured at session
+	 *  creation.
+	 *
 	 *  Ignored by the null cipher with operation types other than
 	 *  ODP_CRYPTO_OP_TYPE_OOP. Must be set to zero range (zero offset
 	 *  and zero length) with the null cipher used with the out-of-place
@@ -734,6 +761,9 @@ typedef struct odp_crypto_packet_op_param_t {
 
 	/** Data range to be authenticated
 	 *
+	 *  The range is given in bits or bytes as configured at session
+	 *  creation.
+	 *
 	 *  The value is ignored with authenticated encryption algorithms,
 	 *  such as AES-GCM, which authenticate data in the cipher range
 	 *  and the AAD.
@@ -937,22 +967,23 @@ typedef struct odp_crypto_cipher_capability_t {
 	/** IV length in bytes */
 	uint32_t iv_len;
 
-	/** Cipher is operating in bitwise mode
+	/** Cipher supports bit mode
 	 *
-	 * This cipher works on series of bits, rather than sequences of bytes:
-	 * cipher_range in odp_crypto_op_param_t and
-	 * odp_crypto_packet_op_param_t will use bits, rather than bytes.
+	 * This cipher can work on a range of bits in addition to a range of
+	 * bytes. When this capability is not present, only byte ranges are
+	 * supported. The unit of cipher range is selected at session creation
+	 * through the cipher_range_in_bits session parameter.
 	 *
-	 * Note: data buffer MUST start on the byte boundary, using offset
-	 * which is not divisible by 8 is unsupported and will result in
-	 * unspecified behaviour.
+	 * Note: In bit mode the cipher range must start on a byte boundary.
+	 * Using an offset which is not divisible by 8 will result in
+	 * undefined behaviour.
 	 *
-	 * Note2: If the data length is not a multiple of 8, the remaining
-	 * bits of the data in the last byte of the input/output will be the
-	 * most significant bits, i.e. the most significant bit is considered
-	 * to be the first bit of a byte for the purpose of input and output
-	 * data range. The output bits that fall out of the output range are
-	 * undefined.
+	 * Note2: If the range length in bit mode is not a multiple of 8,
+	 * the remaining bits of the data in the last byte of the input/output
+	 * will be the most significant bits, i.e. the most significant bit is
+	 * considered to be the first bit of a byte for the purpose of input
+	 * and output data range. The output bits that fall out of the output
+	 * range are undefined.
 	 */
 	odp_bool_t bit_mode;
 
@@ -984,22 +1015,23 @@ typedef struct odp_crypto_auth_capability_t {
 		uint32_t inc;
 	} aad_len;
 
-	/** Auth is operating in bitstring mode
+	/** Auth algorithm supports bit mode
 	 *
-	 * This auth works on series of bits, rather than sequences of bytes:
-	 * auth_range in odp_crypto_op_param_t and
-	 * odp_crypto_packet_op_param_t will use bits, rather than bytes.
+	 * This auth algorithm can work on a range of bits in addition to
+	 * a range of bytes. When this capability is not present, only byte
+	 * ranges are supported. The unit of auth range is selected at session
+	 * creation through the auth_range_in_bits session parameter.
 	 *
-	 * Note: data buffer MUST start on the byte boundary, using offset
-	 * which is not divisible by 8 is unsupported and will result in
-	 * unpredictable behaviour.
+	 * Note: In bit mode the auth range must start on a byte boundary.
+	 * Using an offset which is not divisible by 8 will result in
+	 * undefined behaviour.
 	 *
-	 * Note2: If the data length is not a multiple of 8, the remaining
-	 * bits of the data in the last byte of the input/output will be the
-	 * most significant bits, i.e. the most significant bit is considered
-	 * to be the first bit of a byte for the purpose of input and output
-	 * data range. The output bits that fall out of the output range are
-	 * undefined.
+	 * Note2: If the range length in bit mode is not a multiple of 8,
+	 * the remaining bits of the data in the last byte of the input/output
+	 * will be the most significant bits, i.e. the most significant bit is
+	 * considered to be the first bit of a byte for the purpose of input
+	 * and output data range. The output bits that fall out of the output
+	 * range are undefined.
 	 */
 	odp_bool_t bit_mode;