Skip to content

Commit

Permalink
include: crypto: Cleanup docstrings
Browse files Browse the repository at this point in the history 
Fix typos, use punctuation and capitalization more consistently. In
a few cases, rewrite sentences for clarity.

Signed-off-by: Paul Sokolovsky <[email protected]>
  • Loading branch information
@pfalcon @galak
pfalcon authored and galak committed Jan 13, 2020
1 parent 5196617 commit 57d538c
Show file tree
Hide file tree
Showing 2 changed files with 70 additions and 73 deletions.
84 changes: 42 additions & 42 deletions include/crypto/cipher.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand All @@ -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;

}
Expand All @@ -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,
Expand Down Expand Up @@ -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.
*/
Expand All @@ -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)
Expand All @@ -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.
*/
Expand All @@ -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.
*/
Expand All @@ -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.
*/
Expand All @@ -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.
*/
Expand Down
59 changes: 28 additions & 31 deletions include/crypto/cipher_structs.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand All @@ -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;
};
Expand All @@ -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);

Expand Down

0 comments on commit 57d538c

Please sign in to comment.