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

84
include/crypto/cipher.h
View file

@ -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.
*/