api: crypto: add an out-of-place type operation type

Add ODP_CRYPTO_OP_TYPE_OP that writes the output of the crypto operation
into a caller provided output packet and does not consume the input packet.

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

2 files changed, 82 insertions, 8 deletions

diff --git a/include/odp/api/spec/crypto.h b/include/odp/api/spec/crypto.h
index 674f476b0..05ab514a0 100644
--- a/include/odp/api/spec/crypto.h
+++ b/include/odp/api/spec/crypto.h
@@ -316,12 +316,39 @@ int odp_crypto_result(odp_crypto_packet_result_t *result,
  * The value of pktout[n] is ignored as pktout[n] is used purely as an
  * output parameter that returns the handle of the newly allocated packet.
  *
+ * ODP_CRYPTO_OP_TYPE_OOP:
+ *
+ * Writes the output bytes of the crypto operation in a caller provided
+ * output packet passed through pkt_out[n]. Input packets are not consumed
+ * nor modified. Memory layout (including packet data pointers, head and
+ * tail room, segmentation) of the output packet may change during the
+ * operation.
+ *
+ * Crypto output is the processed crypto_range, auth_range and
+ * MAC/digest (in encode sessions) of the input packet. The operation
+ * behaves as if crypto range and auth range were first copied from the
+ * input packet to the output packet and then the crypto operation
+ * was applied to the output packet.
+ *
+ * Crypto range and auth range of null cipher and auth algorithms are
+ * ignored, i.e. not copied in the output packet. Auth range of (AEAD)
+ * algorithms that ignore auth range is not copied.
+ *
+ * The offset of the crypto range and auth range in the output packet is
+ * the same as in the input packet, adjusted by dst_offset_shift operation
+ * parameter.
+ *
+ * pkt_out[n] must be a valid handle to a packet that is long enough to
+ * contain the shifted crypto range, auth range and, in encode sessions,
+ * the MAC/digest result. pkt_out[n] must not be the same as any input
+ * packet or any other output packet.
+ *
  * @param         pkt_in   Packets to be processed
  * @param[in,out] pkt_out  Packet handle array for resulting packets
  * @param         param    Operation parameters array
  * @param         num_pkt  Number of packets to be processed
  *
- * @return Number of input packets consumed (0 ... num_pkt)
+ * @return Number of input packets processed (0 ... num_pkt)
  * @retval <0 on failure
  */
 int odp_crypto_op(const odp_packet_t pkt_in[],
@@ -336,6 +363,11 @@ int odp_crypto_op(const odp_packet_t pkt_in[],
  * creation on the packets. Behaves otherwise like odp_crypto_op() but
  * returns output packets through events.
  *
+ * With ODP_CRYPTO_OP_TYPE_OOP, an enqueued input packet is consumed but
+ * returned back unmodified after the crypto operation is complete. The
+ * caller may not access the input packet until getting the handle back
+ * through odp_crypto_result().
+ *
  * All arrays should be of num_pkt size, except that pkt_out parameter
  * is ignored when the crypto operation type is ODP_CRYPTO_OP_TYPE_BASIC.
  *
diff --git a/include/odp/api/spec/crypto_types.h b/include/odp/api/spec/crypto_types.h
index 205bdb700..574f56445 100644
--- a/include/odp/api/spec/crypto_types.h
+++ b/include/odp/api/spec/crypto_types.h
@@ -529,6 +529,22 @@ typedef enum odp_crypto_op_type_t {
 	 * odp_crypto_op() and odp_crypto_op_enq() can be used.
 	 */
 	ODP_CRYPTO_OP_TYPE_BASIC,
+
+	/**
+	 * Out-of-place crypto operation. Output packet is provided by
+	 * the caller and the input packet is not consumed nor modified.
+	 *
+	 * Output of the crypto operation is written in the caller provided
+	 * output packet without affecting other data and metadata of the
+	 * output packet. Memory layout of the output packet may change
+	 * during the operation.
+	 *
+	 * Crypto output is the processed crypto_range, auth_range and
+	 * MAC/digest (in encode sessions) of the input packet.
+	 *
+	 * odp_crypto_op() and odp_crypto_op_enq() can be used.
+	 */
+	ODP_CRYPTO_OP_TYPE_OOP,
 } odp_crypto_op_type_t;
 
 /**
@@ -669,8 +685,8 @@ typedef struct odp_crypto_session_param_t {
 	 *  crypto operation in the legacy operation type, the output
 	 *  packet will be allocated from this pool.
 	 *
-	 *  In ODP_CRYPTO_OP_TYPE_BASIC operation type this must be set to
-	 *  ODP_POOL_INVALID.
+	 *  In ODP_CRYPTO_OP_TYPE_BASIC and ODP_CRYPTO_OP_TYPE_OOP
+	 *  operation types this must be set to ODP_POOL_INVALID.
 	 */
 	odp_pool_t output_pool;
 
@@ -769,16 +785,23 @@ typedef struct odp_crypto_packet_op_param_t {
 	/** Offset from start of packet for hash result
 	 *
 	 *  In case of decode sessions, the expected hash will be read from
-	 *  this offset and compared with the calculated hash. After the
-	 *  operation the hash bytes will have undefined values.
+	 *  this offset from the input packet and compared with the calculated
+	 *  hash. After the operation the hash bytes will have undefined
+	 *  values except with out-of-place sessions (ODP_CRYPTO_OP_TYPE_OOP
+	 *  operation type).
+	 *
+	 *  With out-of-place decode sessions the input packet is not modified
+	 *  but if the hash location overlaps the cipher range or the auth
+	 *  range, then the corresponding location in the output packet will
+	 *  have undefined content.
 	 *
 	 *  In case of encode sessions the calculated hash will be stored in
-	 *  this offset.
+	 *  this offset in the output packet.
 	 *
 	 *  If the hash_result_in_auth_range session parameter is true,
 	 *  the hash result location may overlap auth_range. In that case the
-	 *  result location will be zeroed in decode sessions before hash
-	 *  calculation. Zeroing is not done in encode sessions.
+	 *  result location will be treated as containing zero bytes for the
+	 *  purpose of hash calculation in decode sessions.
 	 */
 	uint32_t hash_result_offset;
 
@@ -793,6 +816,19 @@ typedef struct odp_crypto_packet_op_param_t {
 	/** Data range to authenticate */
 	odp_packet_data_range_t auth_range;
 
+	/** Shift of the output offsets with ODP_CRYPTO_OP_TYPE_OOP
+	 *
+	 *  The processed crypto range and auth range of the input packet
+	 *  will be written in the output packet at the offset specified
+	 *  in the ranges (i.e. the same as in the input packet), shifted
+	 *  by this many bytes. This allows directing the output to
+	 *  a different packet offset than the offset of the input data.
+	 *
+	 *  This is ignored if the crypto operation type is not
+	 *  ODP_CRYPTO_OP_TYPE_OOP.
+	 */
+	int32_t dst_offset_shift;
+
 } odp_crypto_packet_op_param_t;
 
 /**
@@ -914,6 +950,12 @@ typedef struct odp_crypto_packet_result_t {
 	/** Request completed successfully */
 	odp_bool_t  ok;
 
+	/** Input packet passed to odp_crypo_op_enq() when the operation
+	 *  type of the session is ODP_CRYPTO_OP_TYPE_OOP. In other cases
+	 *  this field does not have a valid value.
+	 */
+	odp_packet_t pkt_in;
+
 	/** Cipher status */
 	odp_crypto_op_status_t cipher_status;