/* Copyright (c) 2014-2018, Linaro Limited * Copyright (c) 2021-2023, Nokia * All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause */ /** * @file * * ODP crypto */ #ifndef ODP_API_SPEC_CRYPTO_H_ #define ODP_API_SPEC_CRYPTO_H_ #include #include #include #include #include #ifdef __cplusplus extern "C" { #endif /** @defgroup odp_crypto ODP CRYPTO * Data ciphering and authentication. * @{ */ /** * Query crypto capabilities * * Outputs crypto capabilities on success. * * @param[out] capa Pointer to capability structure for output * * @retval 0 on success * @retval <0 on failure */ int odp_crypto_capability(odp_crypto_capability_t *capa); /** * Query supported cipher algorithm capabilities * * Outputs all supported configuration options for the algorithm. Output is * sorted (from the smallest to the largest) first by key length, then by IV * length. * * @param cipher Cipher algorithm * @param[out] capa Array of capability structures for output * @param num Maximum number of capability structures to output * * @return Number of capability structures for the algorithm. If this is larger * than 'num', only 'num' first structures were output and application * may call the function again with a larger value of 'num'. * @retval <0 on failure */ int odp_crypto_cipher_capability(odp_cipher_alg_t cipher, odp_crypto_cipher_capability_t capa[], int num); /** * Query supported authentication algorithm capabilities * * Outputs all supported configuration options for the algorithm. Output is * sorted (from the smallest to the largest) first by digest length, then by key * length. * * @param auth Authentication algorithm * @param[out] capa Array of capability structures for output * @param num Maximum number of capability structures to output * * @return Number of capability structures for the algorithm. If this is larger * than 'num', only 'num' first structures were output and application * may call the function again with a larger value of 'num'. * @retval <0 on failure */ int odp_crypto_auth_capability(odp_auth_alg_t auth, odp_crypto_auth_capability_t capa[], int num); /** * Crypto session creation * * Create a crypto session according to the session parameters. Use * odp_crypto_session_param_init() to initialize parameters into their * default values. If call ends up with an error no new session will be * created. * * The parameter structure as well as the key and IV data pointed to by it * can be freed after the call. * * @param param Session parameters * @param[out] session Created session else ODP_CRYPTO_SESSION_INVALID * @param[out] status Failure code if unsuccessful * * @retval 0 on success * @retval <0 on failure */ int odp_crypto_session_create(const odp_crypto_session_param_t *param, odp_crypto_session_t *session, odp_crypto_ses_create_err_t *status); /** * Crypto session destroy * * Destroy an unused session. Result is undefined if session is being used * (i.e. asynchronous operation is in progress). * * @param session Session handle * * @retval 0 on success * @retval <0 on failure */ int odp_crypto_session_destroy(odp_crypto_session_t session); #if ODP_DEPRECATED_API /** * Return crypto completion handle that is associated with event * * @deprecated Used only with the deprecated odp_crypto_operation() * * Note: any invalid parameters will cause undefined behavior and may cause * the application to abort or crash. * * @param ev An event of type ODP_EVENT_CRYPTO_COMPL * * @return crypto completion handle */ odp_crypto_compl_t odp_crypto_compl_from_event(odp_event_t ev); /** * Convert crypto completion handle to event handle * * @deprecated Used only with the deprecated odp_crypto_operation() * * @param completion_event Completion event to convert to generic event * * @return Event handle */ odp_event_t odp_crypto_compl_to_event(odp_crypto_compl_t completion_event); /** * Release crypto completion event * * @deprecated Used only with the deprecated odp_crypto_operation() * * @param completion_event Completion event we are done accessing */ void odp_crypto_compl_free(odp_crypto_compl_t completion_event); /** * Crypto per packet operation * * @deprecated Use odp_crypto_op() or odp_crypto_op_enq() instead. * * This function may be called only for sessions configured with * the ODP_CRYPTO_OP_TYPE_LEGACY operation type. * * Performs the cryptographic operations specified during session creation * on the packet. If the operation is performed synchronously, "posted" * will return FALSE and the result of the operation is immediately available. * If "posted" returns TRUE the result will be delivered via the completion * queue specified when the session was created. * * @param param Operation parameters * @param posted Pointer to return posted, TRUE for async operation * @param result Results of operation (when posted returns FALSE) * * @retval 0 on success * @retval <0 on failure */ int odp_crypto_operation(odp_crypto_op_param_t *param, odp_bool_t *posted, odp_crypto_op_result_t *result); /** * Crypto per packet operation query result from completion event * * @deprecated Used only with the deprecated odp_crypto_operation() * * @param completion_event Event containing operation results * @param result Pointer to result structure */ void odp_crypto_compl_result(odp_crypto_compl_t completion_event, odp_crypto_op_result_t *result); #endif /* ODP_DEPRECATED_API */ /** * Get printable value for an odp_crypto_session_t * * @param hdl odp_crypto_session_t handle to be printed * @return uint64_t value that can be used to print/display this * handle * * @note This routine is intended to be used for diagnostic purposes * to enable applications to generate a printable value that represents * an odp_crypto_session_t handle. */ uint64_t odp_crypto_session_to_u64(odp_crypto_session_t hdl); #if ODP_DEPRECATED_API /** * Get printable value for an odp_crypto_compl_t * * @deprecated Used only with the deprecated odp_crypto_operation() * * @param hdl odp_crypto_compl_t handle to be printed * @return uint64_t value that can be used to print/display this * handle * * @note This routine is intended to be used for diagnostic purposes * to enable applications to generate a printable value that represents * an odp_crypto_compl_t handle. */ uint64_t odp_crypto_compl_to_u64(odp_crypto_compl_t hdl); #endif /** * Initialize crypto session parameters * * Initialize an odp_crypto_session_param_t to its default values for * all fields. * * @param param Pointer to odp_crypto_session_param_t to be initialized */ void odp_crypto_session_param_init(odp_crypto_session_param_t *param); /** * Return crypto processed packet that is associated with event * * Get packet handle to an crypto processed packet event. Event subtype must be * ODP_EVENT_PACKET_CRYPTO. Crypto operation results can be examined with * odp_crypto_result(). * * Note: any invalid parameters will cause undefined behavior and may cause * the application to abort or crash. * * @param ev Event handle * * @return Packet handle */ odp_packet_t odp_crypto_packet_from_event(odp_event_t ev); /** * Convert crypto packet handle to event * * The packet handle must be an output of an crypto operation. * * @param pkt Packet handle from crypto operation * * @return Event handle */ odp_event_t odp_crypto_packet_to_event(odp_packet_t pkt); /** * Get crypto operation results from a crypto processed packet * * Successful crypto operations of all types (SYNC and ASYNC) produce packets * which contain crypto result metadata. This function copies the operation * results from a crypto processed packet. Event subtype of this kind of * packet is ODP_EVENT_PACKET_CRYPTO. Results are undefined if a non-crypto * processed packet is passed as input. * * @param packet A crypto processed packet (ODP_EVENT_PACKET_CRYPTO) * @param[out] result Pointer to operation result for output * * @retval 0 On success * @retval <0 On failure */ int odp_crypto_result(odp_crypto_packet_result_t *result, odp_packet_t packet); /** * Crypto packet operation * * Performs the SYNC cryptographic operations specified during session creation * on the packets. All arrays should be of num_pkt size. * * Use of the pkt_out parameter depends on the configured crypto operation * type as described below. * * ODP_CRYPTO_OP_TYPE_LEGACY: * * Caller should initialize each element of pkt_out either with the desired * output packet handle or with ODP_PACKET_INVALID to make ODP allocate a new * packet from provided pool. * * All packet data and metadata are copied from the input packet to the output * packet before the requested crypto operation is performed to the output * packet. If an output packet is given to the operation, it must be at least * as long as the input packet and, in encode operations, long enough for the * hash result to be fully inside the packet data. Memory layout of the output * packet may change during the crypto operation. If the output packet is * longer than needed, it is not truncated and the extra data bytes retain * their content. * * It is ok to pass the same packet handle as both the input packet and the * output packet for the same crypto operation. In that case the input packet * is consumed but returned as the output packet (with possibly different * memory layout). * * ODP_CRYPTO_OP_TYPE_BASIC: * * ODP allocates the output packet from the pool from which the input * packet was allocated. The processed input packet is consumed. All * packet data and metadata are copied from the input packet to the output * packet before the requested crypto operation is applied to the output * packet. Memory layout (including packet data pointers, head and tail room, * segmentation) of the output packet may differ from that of the input * packet. * * 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 processed (0 ... num_pkt) * @retval <0 on failure */ int odp_crypto_op(const odp_packet_t pkt_in[], odp_packet_t pkt_out[], const odp_crypto_packet_op_param_t param[], int num_pkt); /** * Crypto packet operation * * Performs the ASYNC cryptographic operations specified during session * creation on the packets. Behaves otherwise like odp_crypto_op() but * returns output packets through events. * * With operation types other than ODP_CRYPTO_OP_TYPE_LEGACY, packet * data of processed packets may not be valid before odp_crypto_result() * has been called. * * 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. * * @param pkt_in Packets to be processed * @param 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) * @retval <0 on failure */ int odp_crypto_op_enq(const odp_packet_t pkt_in[], const odp_packet_t pkt_out[], const odp_crypto_packet_op_param_t param[], int num_pkt); /** * @} */ #ifdef __cplusplus } #endif #include #endif