diff --git a/include/crypto/cipher.h b/include/crypto/cipher.h index 6deb322ceec..fe79c3c27e2 100644 --- a/include/crypto/cipher.h +++ b/include/crypto/cipher.h @@ -27,33 +27,32 @@ struct crypto_driver_api { int (*query_hw_caps)(struct device *dev); - /* Setup a crypto session */ + /* Setup a crypto session */ int (*begin_session)(struct device *dev, struct cipher_ctx *ctx, enum cipher_algo algo, enum cipher_mode mode, enum cipher_op op_type); - /* Tear down an established session */ + /* Tear down an established session */ int (*free_session)(struct device *dev, struct cipher_ctx *ctx); - /* Register async crypto op completion callback with the driver*/ + /* Register async crypto op completion callback with the driver */ int (*crypto_async_callback_set)(struct device *dev, crypto_completion_cb cb); }; -/* Following are the calls an app could make to get cipher stuff done. - * The first two relates to crypto "session" setup / tear down. - * Further we have four mode specific (CTR, CCM, CBC ...) calls to perform the - * actual crypto operation in the context of a session. Also we have an +/* Following are the public API a user app may call. + * The first two relate to crypto "session" setup / teardown. Further we + * have four cipher mode specific (CTR, CCM, CBC ...) calls to perform the + * actual crypto operation in the context of a session. Also we have an * API to provide the callback for async operations. */ - /* * @brief Query the crypto hardware capabilities * * This API is used by the app to query the capabilities supported by the * crypto device. Based on this the app can specify a subset of the supported - * options to be honored for a session during cipher_begin_session() + * options to be honored for a session during cipher_begin_session(). * * @param[in] dev Pointer to the device structure for the driver instance. * @@ -69,13 +68,13 @@ static inline int cipher_query_hwcaps(struct device *dev) tmp = api->query_hw_caps(dev); __ASSERT((tmp & (CAP_OPAQUE_KEY_HNDL | CAP_RAW_KEY)) != 0, - "Driver should support atleast one key type: RAW/Opaque"); + "Driver should support at least one key type: RAW/Opaque"); __ASSERT((tmp & (CAP_INPLACE_OPS | CAP_SEPARATE_IO_BUFS)) != 0, - "Driver should support atleast one IO buf type: Inplace/separate"); + "Driver should support at least one IO buf type: Inplace/separate"); __ASSERT((tmp & (CAP_SYNC_OPS | CAP_ASYNC_OPS)) != 0, - "Driver should support atleast one op-type: sync/async"); + "Driver should support at least one op-type: sync/async"); return tmp; } @@ -89,13 +88,14 @@ static inline int cipher_query_hwcaps(struct device *dev) * * @param[in] dev Pointer to the device structure for the driver instance. * @param[in] ctx Pointer to the context structure. Various one time - * parameters like key, keylength etc are supplied via - * this field. Take a look at the ctx structure definition - * to know which fields are to be populated by the app - * before making this call. + * parameters like key, keylength, etc. are supplied via + * this structure. The structure documentation specifies + * which fields are to be populated by the app before + * making this call. * @param[in] algo The crypto algorithm to be used in this session. e.g AES * @param[in] mode The cipher mode to be used in this session. e.g CBC, CTR * @param[in] optype Whether we should encrypt or decrypt in this session + * * @return 0 on success, negative errno code on fail. */ static inline int cipher_begin_session(struct device *dev, @@ -130,13 +130,13 @@ static inline int cipher_begin_session(struct device *dev, } /* - * @brief Cleanup a crypto session + * @brief Cleanup a crypto session * * Clears the hardware and/or driver state of a previous session. * * @param[in] dev Pointer to the device structure for the driver instance. - * @param[in] ctx Pointer to the crypto context structure, of the session - * to be freed. + * @param[in] ctx Pointer to the crypto context structure of the session + * to be freed. * * @return 0 on success, negative errno code on fail. */ @@ -162,7 +162,7 @@ static inline int cipher_free_session(struct device *dev, * @param[in] cb Pointer to application callback to be called by the driver. * * @return 0 on success, -ENOTSUP if the driver does not support async op, - * negative errno code on fail. + * negative errno code on other error. */ static inline int cipher_callback_set(struct device *dev, crypto_completion_cb cb) @@ -180,11 +180,11 @@ static inline int cipher_callback_set(struct device *dev, } /* - * @brief Perform Single block crypto op. This should not be overloaded to - * operate on multiple blocks for security reasons. + * @brief Perform single-block crypto operation (ECB cipher mode). This + * should not be overloaded to operate on multiple blocks for security reasons. * * @param[in] ctx Pointer to the crypto context of this op. - * @param[in/out] pkt Structure holding the Input/Output buffer pointers. + * @param[in/out] pkt Structure holding the input/output buffer pointers. * * @return 0 on success, negative errno code on fail. */ @@ -202,10 +202,10 @@ static inline int cipher_block_op(struct cipher_ctx *ctx, * @brief Perform Cipher Block Chaining (CBC) crypto operation. * * @param[in] ctx Pointer to the crypto context of this op. - * @param[in/out] pkt Structure holding the Input/Output buffer pointers. - * @param[in] iv Initialization Vector for the operation. Same - * iv value should not be reused across multiple - * operations (within a session context) for security. + * @param[in/out] pkt Structure holding the input/output buffer pointers. + * @param[in] iv Initialization Vector (IV) for the operation. Same + * IV value should not be reused across multiple + * operations (within a session context) for security. * * @return 0 on success, negative errno code on fail. */ @@ -223,16 +223,16 @@ static inline int cipher_cbc_op(struct cipher_ctx *ctx, * @brief Perform Counter (CTR) mode crypto operation. * * @param[in] ctx Pointer to the crypto context of this op. - * @param[in/out] pkt Structure holding the Input/Output buffer pointers. - * @param[in] iv Initialization Vector for the operation. We use a - * split counter formed by appending iv and ctr. - * Consequently ivlen = keylen - ctrlen. 'ctrlen' is - * specified during session setup through the - * 'ctx.mode_params.ctr_params.ctr_len' parameter. IV - * should not be reused across multiple operations - * (within a session context) for security. The non-iv - * part of the split counter is transparent to the caller - * and is fully managed by the crypto provider. + * @param[in/out] pkt Structure holding the input/output buffer pointers. + * @param[in] iv Initialization Vector (IV) for the operation. We use a + * split counter formed by appending IV and ctr. + * Consequently ivlen = keylen - ctrlen. 'ctrlen' is + * specified during session setup through the + * 'ctx.mode_params.ctr_params.ctr_len' parameter. IV + * should not be reused across multiple operations + * (within a session context) for security. The non-IV + * part of the split counter is transparent to the caller + * and is fully managed by the crypto provider. * * @return 0 on success, negative errno code on fail. */ @@ -250,11 +250,11 @@ static inline int cipher_ctr_op(struct cipher_ctx *ctx, * @brief Perform Counter with CBC-MAC (CCM) mode crypto operation * * @param[in] ctx Pointer to the crypto context of this op. - * @param[in/out] pkt Structure holding the Input/Output, Assosciated Data - * and tag buffer pointers. - * @param[in] nonce Nonce for the operation. Same Nonce value should not - * be reused across multiple operations (within a - * session context) for security. + * @param[in/out] pkt Structure holding the input/output, Assosciated + * Data (AD) and auth tag buffer pointers. + * @param[in] nonce Nonce for the operation. Same nonce value should not + * be reused across multiple operations (within a + * session context) for security. * * @return 0 on success, negative errno code on fail. */ diff --git a/include/crypto/cipher_structs.h b/include/crypto/cipher_structs.h index e923832126a..ecd8f520225 100644 --- a/include/crypto/cipher_structs.h +++ b/include/crypto/cipher_structs.h @@ -112,47 +112,44 @@ struct cipher_ctx { /* If the driver supports multiple simultaneously crypto sessions, this * will identify the specific driver state this crypto session relates - * to. Since dynamic memory allocation is is not possible, it is + * to. Since dynamic memory allocation is not possible, it is * suggested that at build time drivers allocate space for the * max simultaneous sessions they intend to support. To be populated - * by the driver on return from begin_session() + * by the driver on return from begin_session(). */ void *drv_sessn_state; - /* Place for the app to put info relevant stuff for resuming when - * completion call back happens for async ops. Totally managed by the + /* Place for the user app to put info relevant stuff for resuming when + * completion callback happens for async ops. Totally managed by the * app. */ void *app_sessn_state; - - /* Standard mode parameters, which remain constant for all ops + /* Cypher mode parameters, which remain constant for all ops * in a session. To be populated by the app before calling - * begin_session() + * begin_session(). */ union { struct ccm_params ccm_info; struct ctr_params ctr_info; - } mode_params; - /* Cryptographic keylength in bytes. To be populated by the app * before calling begin_session() */ u16_t keylen; - - /* How certain fields are to be interpreted for this sesssion. + /* How certain fields are to be interpreted for this session. + * (A bitmask of CAP_* below.) * To be populated by the app before calling begin_session(). * An app can obtain the capability flags supported by a hw/driver - * by calling cipher_query_hwcaps(). (A bitmask of CAP_* below) + * by calling cipher_query_hwcaps(). */ u16_t flags; }; -/* Various cipher_ctx.flags options. Not all drivers support all flags. - * An app can query the supported hw / driver +/* cipher_ctx.flags values. Not all drivers support all flags. + * A user app can query the supported hw / driver * capabilities via provided API (cipher_query_hwcaps()), and choose a * supported config during the session setup. */ @@ -175,41 +172,41 @@ struct cipher_ctx { /* Whether the hardware/driver supports autononce feature */ #define CAP_AUTONONCE BIT(7) - /* More flags to be added as necessary */ + /* Structure encoding IO parameters of one cryptographic * operation like encrypt/decrypt. The fields which has not been explicitly * called out has to be filled up by the app before making the cipher_xxx_op() - * call + * call. */ struct cipher_pkt { - /* Start address of Input buffer */ + /* Start address of input buffer */ u8_t *in_buf; /* Bytes to be operated upon */ int in_len; - /* Start of the Output buffer, to be allocated by - * the application. Can be NULL for in place ops. To be populated - * with contents by the driver on return from op / async_callback + /* Start of the output buffer, to be allocated by + * the application. Can be NULL for in-place ops. To be populated + * with contents by the driver on return from op / async callback. */ u8_t *out_buf; /* Size of the out_buf area allocated by the application. Drivers should - * not write past the size of output buffer + * not write past the size of output buffer. */ int out_buf_max; /* To be populated by driver on return from cipher_xxx_op() and - * holds the size of the actual result + * holds the size of the actual result. */ int out_len; /* Context this packet relates to. This can be useful to get the - * session details esp for async ops. Will be populated by the - * cipher_xxx_op() API based on the ctx parameter + * session details, especially for async ops. Will be populated by the + * cipher_xxx_op() API based on the ctx parameter. */ struct cipher_ctx *ctx; }; @@ -219,27 +216,27 @@ struct cipher_pkt { * contents prior to making cipher_ccm_op() call. */ struct cipher_aead_pkt { - /* IO buffers for Encryption. This has to be supplied by the app */ + /* IO buffers for encryption. This has to be supplied by the app. */ struct cipher_pkt *pkt; - /* Start address for Associated data. This has to be supplied by app */ + /* Start address for Associated Data. This has to be supplied by app. */ u8_t *ad; - /* Size of Associated data. This has to be supplied by the app */ + /* Size of Associated Data. This has to be supplied by the app. */ u32_t ad_len; - /* Start address for the Auth hash. For an Encryption op this will + /* Start address for the auth hash. For an encryption op this will * be populated by the driver when it returns from cipher_ccm_op call. - * For a decryption op this has to be supplied by the app. + * For a decryption op this has to be supplied by the app. */ u8_t *tag; }; /* Prototype for the application function to be invoked by the crypto driver * on completion of an async request. The app may get the session context - * via the pkt->ctx field. For ccm ops the encopassing AEAD packet maybe + * via the pkt->ctx field. For CCM ops the encompassing AEAD packet may be * accessed via container_of(). The type of a packet can be determined via - * pkt->ctx.ops.mode + * pkt->ctx.ops.mode . */ typedef void (*crypto_completion_cb)(struct cipher_pkt *completed, int status);