On 2014-08-12 11:17, Robbie King wrote: > Signed-off-by: Robbie King <[email protected]>
Reviewed-by: Anders Roxell <[email protected]> > --- > include/odp_crypto.h | 366 > ++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 files changed, 366 insertions(+), 0 deletions(-) > create mode 100644 include/odp_crypto.h > > diff --git a/include/odp_crypto.h b/include/odp_crypto.h > new file mode 100644 > index 0000000..c10f80e > --- /dev/null > +++ b/include/odp_crypto.h > @@ -0,0 +1,366 @@ > +/* Copyright (c) 2014, Linaro Limited > + * All rights reserved. > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > + > +/** > + * @file > + * > + * ODP crypto > + */ > + > +#ifndef ODP_CRYPTO_H_ > +#define ODP_CRYPTO_H_ > + > +#ifdef __cplusplus > +extern "C" { > +#endif > + > +#include <odp_std_types.h> > +#include <odp_buffer.h> > +#include <odp_buffer_pool.h> > +#include <odp_queue.h> > +#include <odp_packet.h> > + > +/** Invalid session handle */ > +#define ODP_CRYPTO_SESSION_INVALID (-1ULL) > + > +/** > + * Crypto API opaque session handle > + */ > +typedef uint64_t odp_crypto_session_t; > + > +/** > + * Crypto API operation mode > + */ > +enum odp_crypto_op_mode { > + ODP_CRYPTO_SYNC, /**< Synchronous, return results immediately */ > + ODP_CRYPTO_ASYNC, /**< Aynchronous, return results via posted event */ > +}; > + > +/** > + * Crypto API operation type > + */ > +enum odp_crypto_op { > + ODP_CRYPTO_OP_ENCODE, /**< Encrypt and/or compute authentication ICV */ > + ODP_CRYPTO_OP_DECODE /**< Decrypt and/or verify authentication ICV */ > +}; > + > +/** > + * Crypto API cipher algorithm > + */ > +enum odp_cipher_alg { > + ODP_CIPHER_ALG_NULL, /**< No cipher algorithm specified */ > + ODP_CIPHER_ALG_DES, /**< DES */ > + ODP_CIPHER_ALG_3DES_CBC, /**< Triple DES with cipher block chaining */ > +}; > + > +/** > + * Crypto API authentication algorithm > + */ > +enum odp_auth_alg { > + ODP_AUTH_ALG_NULL, /**< No authentication algorithm specified */ > + ODP_AUTH_ALG_MD5_96, /**< HMAC-MD5 with 96 bit key */ > +}; > + > +/** > + * Crypto API key structure > + */ > +typedef struct odp_crypto_key { > + uint8_t *data; /**< Key data */ > + uint32_t length; /**< Key length in bytes */ > +} odp_crypto_key_t; > + > +/** > + * Crypto API IV structure > + */ > +typedef struct odp_crypto_iv { > + uint8_t *data; /**< IV data */ > + uint32_t length; /**< IV length in bytes */ > +} odp_crypto_iv_t; > + > +/** > + * Crypto API data range specifier > + */ > +typedef struct odp_crypto_data_range { > + uint32_t offset; /**< Offset from beginning of buffer (chain) */ > + uint32_t length; /**< Length of data to operate on */ > +} odp_crypto_data_range_t; > + > +/** > + * Crypto API session creation paramters > + * > + * @todo Add "odp_session_proc_info_t" > + */ > +typedef struct odp_crypto_session_params { > + enum odp_crypto_op op; /**< Encode versus decode */ > + bool auth_cipher_text; /**< Authenticate/cipher ordering */ > + enum odp_crypto_op_mode pref_mode; /**< Preferred sync vs async */ > + enum odp_cipher_alg cipher_alg; /**< Cipher algorithm */ > + odp_crypto_key_t cipher_key; /**< Cipher key */ > + odp_crypto_iv_t iv; /**< Cipher Initialization Vector > (IV) */ > + enum odp_auth_alg auth_alg; /**< Authentication algorithm */ > + odp_crypto_key_t auth_key; /**< Authentication key */ > + odp_queue_t compl_queue; /**< Async mode completion event > queue */ > + odp_buffer_pool_t output_pool; /**< Output buffer pool */ > +} odp_crypto_session_params_t; > + > +/** > + * @var odp_crypto_session_params_t::auth_cipher_text > + * > + * Controls ordering of authentication and cipher operations, > + * and is relative to the operation (encode vs decode). > + * When encoding, @c TRUE indicates the authentication operation > + * should be peformed @b after the cipher operation else before. > + * When decoding, @c TRUE indicates the reverse order of operation. > + * > + * @var odp_crypto_session_params_t::compl_queue > + * > + * When the API operates asynchronously, the completion queue is > + * used to return the completion status of the operation to the > + * application. > + * > + * @var odp_crypto_session_params_t::output_pool > + * > + * When the output packet is not specified during the call to > + * odp_crypto_operation, the output packet buffer will be allocated > + * from this pool. > + */ > + > +/** > + * Crypto API per packet operation parameters > + * > + * @todo Clarify who zero's ICV and how this relates to "hash_result_offset" > + */ > +typedef struct odp_crypto_op_params { > + odp_crypto_session_t session; /**< Session handle from creation */ > + odp_packet_t pkt; /**< Input packet buffer */ > + odp_packet_t out_pkt; /**< Output packet buffer */ > + uint8_t *override_iv_ptr; /**< Override session IV pointer */ > + uint32_t hash_result_offset; /**< Offset from start of packet buffer > for hash result */ > + odp_crypto_data_range_t cipher_range; /**< Data range to apply cipher > */ > + odp_crypto_data_range_t auth_range; /**< Data range to authenticate > */ > +} odp_crypto_op_params_t; > + > +/** > + * @var odp_crypto_op_params_t::pkt > + * Specifies the input packet buffer for the crypto operation. When the > + * @c out_pkt variable is set to @c ODP_PACKET_INVALID (indicating a new > + * buffer should be allocated for the resulting packet), the \#define TBD > + * indicates whether the implementation will free the input packet buffer > + * or if it becomes the responsibility of the caller. > + * > + * @var odp_crypto_op_params_t::out_pkt > + * > + * The API supports both "in place" (the original packet "pkt" is > + * modified) and "copy" (the packet is replicated to a new buffer > + * which contains the modified data). > + * > + * The "in place" mode of operation is indicated by setting @c out_pkt > + * equal to @c pkt. For the copy mode of operation, setting @c out_pkt > + * to a valid packet buffer value indicates the caller wishes to specify > + * the destination buffer. Setting @c out_pkt to @c ODP_PACKET_INVALID > + * indicates the caller wishes the destination packet buffer be allocated > + * from the output pool specified during session creation. > + * > + * @sa odp_crypto_session_params_t::output_pool. > + */ > + > +/** > + * Crypto API session creation return code > + */ > +enum odp_crypto_ses_create_err { > + ODP_CRYPTO_SES_CREATE_ERR_NONE, /**< Session created */ > + ODP_CRYPTO_SES_CREATE_ERR_ENOMEM, /**< Creation failed, no > resources */ > + ODP_CRYPTO_SES_CREATE_ERR_INV_CIPHER, /**< Creation failed, bad cipher > params */ > + ODP_CRYPTO_SES_CREATE_ERR_INV_AUTH, /**< Creation failed, bad auth > params */ > +}; > + > +/** > + * Crypto API algorithm return code > + */ > +enum crypto_alg_err { > + ODP_CRYPTO_ALG_ERR_NONE, /**< Algorithm successful */ > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, /**< Invalid data block size */ > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, /**< Key size invalid for algorithm */ > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, /**< Computed ICV value mismatch */ > +}; > + > +/** > + * Crypto API hardware centric return code > + */ > +enum crypto_hw_err { > + ODP_CRYPTO_HW_ERR_NONE, /**< Operation completed successfully */ > + ODP_CRYPTO_HW_ERR_DMA, /**< Error detected during DMA of data > */ > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, /**< Operation failed due to buffer > pool depletion */ > +}; > + > +/** > + * Cryto API per packet operation completion status > + */ > +typedef struct odp_crypto_compl_status { > + enum crypto_alg_err alg_err; /**< Algorithm specific return code */ > + enum crypto_hw_err hw_err; /**< Hardware specific return code */ > +} odp_crypto_compl_status_t; > + > + > +/** > + * Crypto session creation (synchronous) > + * > + * @param params Session parameters > + * @param session Created session else ODP_CRYPTO_SESSION_INVALID > + * @param status Failure code if unsuccessful > + * > + * @return 0 if successful else -1 > + */ > +int > +odp_crypto_session_create(odp_crypto_session_params_t *params, > + odp_crypto_session_t *session, > + enum odp_crypto_ses_create_err *status); > + > +/** > + * Crypto session creation (asynchronous) > + * > + * Initiate crypto session creation. Results are delivered using > + * the completion event via the completion queue. > + * > + * @param params Session parameters > + * @param completion_event Event by which the session creation results are > + * delivered. > + * @param completion_queue Queue by which the completion event will be > + * delivered. > + * > + * @return 0 if successful else -1 > + * > + */ > +int > +odp_crypto_session_create_async(odp_crypto_session_params_t *params, > + odp_buffer_t completion_event, > + odp_queue_t completion_queue); > + > + > +/** > + * Crypto session creation completion status > + * > + * Accessor function for obtaining creation status from the completion event. > + * > + * @param completion_event Event containing operation results > + * @param status Pointer to store creation return code > + */ > +void > +odp_crypto_get_ses_create_compl_status(odp_buffer_t completion_event, > + enum odp_crypto_ses_create_err *status); > + > +/** > + * Crypto session creation completion return value > + * > + * Accessor function for obtaining handle for newly created session. > + * > + * @param completion_event Event containing operation results > + * @param session Pointer to store session handle > + */ > +void > +odp_crypto_get_ses_create_compl_session(odp_buffer_t completion_event, > + odp_crypto_session_t *session); > + > +/** > + * Crypto per packet operation > + * > + * 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 > + * in the completion event. If "posted" returns TRUE the result will be > + * delivered via the completion queue specified when the session was created. > + * > + * @todo Resolve if completion_event is necessary, can/should the output > + * packet buffer always be used instead. > + * > + * @param params Operation parameters > + * @param posted Pointer to return posted, TRUE for async > operation > + * @param completion_event Event by which the operation results are > delivered. > + * > + * @return 0 if successful else -1 > + */ > +int > +odp_crypto_operation(odp_crypto_op_params_t *params, > + bool *posted, > + odp_buffer_t completion_event); > + > +/** > + * Crypto per packet operation set user context in completion event > + * > + * @param completion_event Event containing operation results > + * @param ctx User data > + */ > +void > +odp_crypto_set_operation_compl_ctx(odp_buffer_t completion_event, > + void *ctx); > + > +/** > + * Crypto per packet operation completion status > + * > + * Accessor function for obtaining operation status from the completion > event. > + * > + * @param completion_event Event containing operation results > + * @param auth Pointer to store authentication results > + * @param cipher Pointer to store cipher results > + */ > +void > +odp_crypto_get_operation_compl_status(odp_buffer_t completion_event, > + odp_crypto_compl_status_t *auth, > + odp_crypto_compl_status_t *cipher); > + > +/** > + * Crypto per packet operation query completed operation packet > + * > + * Accessor function for obtaining current packet buffer, can be > + * different from input packet buffer on some systems > + * > + * @param completion_event Event containing operation results > + * > + * @return Packet structure where data now resides > + */ > +odp_packet_t > +odp_crypto_get_operation_compl_packet(odp_buffer_t completion_event); > + > +/** > + * Crypto per packet operation query user context in completion event > + * > + * @param completion_event Event containing operation results > + * > + * @return User data > + */ > +void * > +odp_crypto_get_operation_compl_ctx(odp_buffer_t completion_event); > + > +/** > + * Generate random byte string > + * > + * @param buf Pointer to store result > + * @param len Pointer to input length value as well as return value > + * @param use_entropy Use entropy > + * > + * @todo Define the implication of the use_entropy parameter > + * > + * @return 0 if succesful > + */ > +int > +odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy); > + > +/** > + * Initialize the crypto subsystem, called once from main thread > + * > + * @param max_sessions Maximum number of sessions to support > + * > + * @return 0 if succesful > + */ > +int > +odp_crypto_init(uint32_t max_sessions); > + > +#ifdef __cplusplus > +} > +#endif > + > +#endif > -- > 1.7.7.6 > > > _______________________________________________ > lng-odp mailing list > [email protected] > http://lists.linaro.org/mailman/listinfo/lng-odp -- Anders Roxell [email protected] M: +46 709 71 42 85 | IRC: roxell _______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
