michaelh/zephyr
1
0
Fork 0
Code Releases Activity

include: crypto: Cleanup docstrings

Browse source 
Fix typos, use punctuation and capitalization more consistently. In
a few cases, rewrite sentences for clarity.

Signed-off-by: Paul Sokolovsky <paul.sokolovsky@linaro.org>
This commit is contained in:
Paul Sokolovsky 2020-01-10 15:22:29 +03:00 • committed by Kumar Gala
commit 57d538cef8
2 changed files with 70 additions and 73 deletions
Download patch file Download diff file Expand all files Collapse all files

48
include/crypto/cipher.h
View file

@ -40,20 +40,19 @@ struct crypto_driver_api {
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
/* 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.
*
@ -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,
@ -135,7 +135,7 @@ static inline int cipher_begin_session(struct device *dev,
* 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
* @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,9 +202,9 @@ 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
* @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,14 +223,14 @@ 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.
* @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
* (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.
*
@ -250,9 +250,9 @@ 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
* @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.
*

55
include/crypto/cipher_structs.h
View file

@ -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
/* 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,16 +216,16 @@ 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.
*/
@ -237,9 +234,9 @@ struct cipher_aead_pkt {
/* 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);