michaelh/zephyr
1
0
Fork 0
Code Releases Activity

docs: crypto: crypto API documentation

Browse source 
Fix crypto API doxygen syntax and integrate into documentation as RST.

Fixes #21820

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif 2020-03-12 14:14:53 -04:00
commit b12869a3f9
5 changed files with 149 additions and 67 deletions
Download patch file Download diff file Expand all files Collapse all files

25
.known-issues/doc/crypto.conf Normal file
View file

@ -0,0 +1,25 @@
#
# crypto unnamed struct definition
#doc/reference/crypto/index.rst
^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]crypto[/\\]index.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
^[ \t]*
^[ \t]*\^
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
^[ \t]*
^[ \t]*\^
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
^[ \t]*
^[ \t]*\^
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
^.*cipher_ctx.mode_params.*
^[- \t]*\^
#
^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]crypto[/\\]index.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
^[ \t]*
^[ \t]*\^
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
^[ \t]*
^[ \t]*\^
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
^.*cipher_ctx.key.*
^[- \t]*\^

16
doc/reference/crypto/index.rst Normal file
View file

@ -0,0 +1,16 @@
.. _crypto_cipher:
Crypto
#######
Overview
********
.. _crypto_cipher_api:
API Reference
*************
.. doxygengroup:: crypto_cipher
:project: Zephyr

1
doc/reference/index.rst
View file

@ -8,6 +8,7 @@ API Reference
bluetooth/index.rst bluetooth/index.rst
kconfig/index.rst kconfig/index.rst
crypto/index.rst
drivers/index.rst drivers/index.rst
display/index.rst display/index.rst
file_system/index.rst file_system/index.rst

85
include/crypto/cipher.h
View file

@ -14,6 +14,21 @@
* as a part of ongoing development. * as a part of ongoing development.
*/ */
/**
* @brief Crypto APIs
* @defgroup crypto Crypto
* @{
* @}
*/
/**
* @brief Crypto Cipher APIs
* @defgroup crypto_cipher Cipher
* @ingroup crypto
* @{
*/
#ifndef ZEPHYR_INCLUDE_CRYPTO_CIPHER_H_ #ifndef ZEPHYR_INCLUDE_CRYPTO_CIPHER_H_
#define ZEPHYR_INCLUDE_CRYPTO_CIPHER_H_ #define ZEPHYR_INCLUDE_CRYPTO_CIPHER_H_
@ -47,14 +62,14 @@ __subsystem struct crypto_driver_api {
* API to provide the callback for async operations. * API to provide the callback for async operations.
*/ */
/* /**
* @brief Query the crypto hardware capabilities * @brief Query the crypto hardware capabilities
* *
* This API is used by the app to query the capabilities supported by the * 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 * 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. * @param dev Pointer to the device structure for the driver instance.
* *
* @return bitmask of supported options. * @return bitmask of supported options.
*/ */
@ -79,22 +94,22 @@ static inline int cipher_query_hwcaps(struct device *dev)
} }
/* /**
* @brief Setup a crypto session * @brief Setup a crypto session
* *
* Initializes one time parameters, like the session key, algorithm and cipher * Initializes one time parameters, like the session key, algorithm and cipher
* mode which may remain constant for all operations in the session. The state * mode which may remain constant for all operations in the session. The state
* may be cached in hardware and/or driver data state variables. * may be cached in hardware and/or driver data state variables.
* *
* @param[in] dev Pointer to the device structure for the driver instance. * @param dev Pointer to the device structure for the driver instance.
* @param[in] ctx Pointer to the context structure. Various one time * @param ctx Pointer to the context structure. Various one time
* parameters like key, keylength, etc. are supplied via * parameters like key, keylength, etc. are supplied via
* this structure. The structure documentation specifies * this structure. The structure documentation specifies
* which fields are to be populated by the app before * which fields are to be populated by the app before
* making this call. * making this call.
* @param[in] algo The crypto algorithm to be used in this session. e.g AES * @param 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 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 * @param optype Whether we should encrypt or decrypt in this session
* *
* @return 0 on success, negative errno code on fail. * @return 0 on success, negative errno code on fail.
*/ */
@ -129,13 +144,13 @@ static inline int cipher_begin_session(struct device *dev,
return api->begin_session(dev, ctx, algo, mode, optype); return api->begin_session(dev, ctx, algo, mode, optype);
} }
/* /**
* @brief Cleanup a crypto session * @brief Cleanup a crypto session
* *
* Clears the hardware and/or driver state of a previous 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 dev Pointer to the device structure for the driver instance.
* @param[in] ctx Pointer to the crypto context structure of the session * @param ctx Pointer to the crypto context structure of the session
* to be freed. * to be freed.
* *
* @return 0 on success, negative errno code on fail. * @return 0 on success, negative errno code on fail.
@ -150,7 +165,7 @@ static inline int cipher_free_session(struct device *dev,
return api->free_session(dev, ctx); return api->free_session(dev, ctx);
} }
/* /**
* @brief Registers an async crypto op completion callback with the driver * @brief Registers an async crypto op completion callback with the driver
* *
* The application can register an async crypto op completion callback handler * The application can register an async crypto op completion callback handler
@ -158,8 +173,8 @@ static inline int cipher_free_session(struct device *dev,
* crypto_do_op(). Based on crypto device hardware semantics, this is likely to * crypto_do_op(). Based on crypto device hardware semantics, this is likely to
* be invoked from an ISR context. * be invoked from an ISR context.
* *
* @param[in] dev Pointer to the device structure for the driver instance. * @param dev Pointer to the device structure for the driver instance.
* @param[in] cb Pointer to application callback to be called by the driver. * @param cb Pointer to application callback to be called by the driver.
* *
* @return 0 on success, -ENOTSUP if the driver does not support async op, * @return 0 on success, -ENOTSUP if the driver does not support async op,
* negative errno code on other error. * negative errno code on other error.
@ -179,12 +194,12 @@ static inline int cipher_callback_set(struct device *dev,
} }
/* /**
* @brief Perform single-block crypto operation (ECB cipher mode). This * @brief Perform single-block crypto operation (ECB cipher mode). This
* should not be overloaded to operate on multiple blocks for security reasons. * should not be overloaded to operate on multiple blocks for security reasons.
* *
* @param[in] ctx Pointer to the crypto context of this op. * @param ctx Pointer to the crypto context of this op.
* @param[in/out] pkt Structure holding the input/output buffer pointers. * @param pkt Structure holding the input/output buffer pointers.
* *
* @return 0 on success, negative errno code on fail. * @return 0 on success, negative errno code on fail.
*/ */
@ -198,12 +213,12 @@ static inline int cipher_block_op(struct cipher_ctx *ctx,
return ctx->ops.block_crypt_hndlr(ctx, pkt); return ctx->ops.block_crypt_hndlr(ctx, pkt);
} }
/* /**
* @brief Perform Cipher Block Chaining (CBC) crypto operation. * @brief Perform Cipher Block Chaining (CBC) crypto operation.
* *
* @param[in] ctx Pointer to the crypto context of this op. * @param ctx Pointer to the crypto context of this op.
* @param[in/out] pkt Structure holding the input/output buffer pointers. * @param pkt Structure holding the input/output buffer pointers.
* @param[in] iv Initialization Vector (IV) for the operation. Same * @param iv Initialization Vector (IV) for the operation. Same
* IV value should not be reused across multiple * IV value should not be reused across multiple
* operations (within a session context) for security. * operations (within a session context) for security.
* *
@ -219,12 +234,12 @@ static inline int cipher_cbc_op(struct cipher_ctx *ctx,
return ctx->ops.cbc_crypt_hndlr(ctx, pkt, iv); return ctx->ops.cbc_crypt_hndlr(ctx, pkt, iv);
} }
/* /**
* @brief Perform Counter (CTR) mode crypto operation. * @brief Perform Counter (CTR) mode crypto operation.
* *
* @param[in] ctx Pointer to the crypto context of this op. * @param ctx Pointer to the crypto context of this op.
* @param[in/out] pkt Structure holding the input/output buffer pointers. * @param pkt Structure holding the input/output buffer pointers.
* @param[in] iv Initialization Vector (IV) for the operation. We use a * @param iv Initialization Vector (IV) for the operation. We use a
* split counter formed by appending IV and ctr. * split counter formed by appending IV and ctr.
* Consequently ivlen = keylen - ctrlen. 'ctrlen' is * Consequently ivlen = keylen - ctrlen. 'ctrlen' is
* specified during session setup through the * specified during session setup through the
@ -246,13 +261,13 @@ static inline int cipher_ctr_op(struct cipher_ctx *ctx,
return ctx->ops.ctr_crypt_hndlr(ctx, pkt, iv); return ctx->ops.ctr_crypt_hndlr(ctx, pkt, iv);
} }
/* /**
* @brief Perform Counter with CBC-MAC (CCM) mode crypto operation * @brief Perform Counter with CBC-MAC (CCM) mode crypto operation
* *
* @param[in] ctx Pointer to the crypto context of this op. * @param ctx Pointer to the crypto context of this op.
* @param[in/out] pkt Structure holding the input/output, Assosciated * @param pkt Structure holding the input/output, Assosciated
* Data (AD) and auth tag buffer pointers. * Data (AD) and auth tag buffer pointers.
* @param[in] nonce Nonce for the operation. Same nonce value should not * @param nonce Nonce for the operation. Same nonce value should not
* be reused across multiple operations (within a * be reused across multiple operations (within a
* session context) for security. * session context) for security.
* *
@ -268,13 +283,13 @@ static inline int cipher_ccm_op(struct cipher_ctx *ctx,
return ctx->ops.ccm_crypt_hndlr(ctx, pkt, nonce); return ctx->ops.ccm_crypt_hndlr(ctx, pkt, nonce);
} }
/* /**
* @brief Perform Galois/Counter Mode (GCM) crypto operation * @brief Perform Galois/Counter Mode (GCM) crypto operation
* *
* @param[in] ctx Pointer to the crypto context of this op. * @param ctx Pointer to the crypto context of this op.
* @param[in/out] pkt Structure holding the input/output, Associated * @param pkt Structure holding the input/output, Associated
* Data (AD) and auth tag buffer pointers. * Data (AD) and auth tag buffer pointers.
* @param[in] nonce Nonce for the operation. Same nonce value should not * @param nonce Nonce for the operation. Same nonce value should not
* be reused across multiple operations (within a * be reused across multiple operations (within a
* session context) for security. * session context) for security.
* *
@ -290,4 +305,8 @@ static inline int cipher_gcm_op(struct cipher_ctx *ctx,
return ctx->ops.gcm_crypt_hndlr(ctx, pkt, nonce); return ctx->ops.gcm_crypt_hndlr(ctx, pkt, nonce);
} }
/**
* @}
*/
#endif /* ZEPHYR_INCLUDE_CRYPTO_CIPHER_H_ */ #endif /* ZEPHYR_INCLUDE_CRYPTO_CIPHER_H_ */

89
include/crypto/cipher_structs.h
View file

@ -19,20 +19,28 @@
#include <device.h> #include <device.h>
#include <sys/util.h> #include <sys/util.h>
/**
* @addtogroup crypto_cipher
* @{
*/
/** Cipher Algorithm */
enum cipher_algo { enum cipher_algo {
CRYPTO_CIPHER_ALGO_AES = 1, CRYPTO_CIPHER_ALGO_AES = 1,
}; };
/** Cipher Operation */
enum cipher_op { enum cipher_op {
CRYPTO_CIPHER_OP_DECRYPT = 0, CRYPTO_CIPHER_OP_DECRYPT = 0,
CRYPTO_CIPHER_OP_ENCRYPT = 1, CRYPTO_CIPHER_OP_ENCRYPT = 1,
}; };
/* Possible cipher mode options. More to be /**
* added as required. * Possible cipher mode options.
*
* More to be added as required.
*/ */
enum cipher_mode { enum cipher_mode {
CRYPTO_CIPHER_MODE_ECB = 1, CRYPTO_CIPHER_MODE_ECB = 1,
CRYPTO_CIPHER_MODE_CBC = 2, CRYPTO_CIPHER_MODE_CBC = 2,
@ -93,19 +101,21 @@ struct gcm_params {
u16_t nonce_len; u16_t nonce_len;
}; };
/* Structure encoding session parameters. Refer to comments for individual /**
* fields to know the contract in terms of who fills what and when w.r.t * Structure encoding session parameters.
* begin_session() call. *
* Refer to comments for individual fields to know the contract
* in terms of who fills what and when w.r.t begin_session() call.
*/ */
struct cipher_ctx { struct cipher_ctx {
/* Place for driver to return function pointers to be invoked per /** Place for driver to return function pointers to be invoked per
* cipher operation. To be populated by crypto driver on return from * cipher operation. To be populated by crypto driver on return from
* begin_session() based on the algo/mode chosen by the app. * begin_session() based on the algo/mode chosen by the app.
*/ */
struct cipher_ops ops; struct cipher_ops ops;
/* To be populated by the app before calling begin_session() */ /** To be populated by the app before calling begin_session() */
union { union {
/* Cryptographic key to be used in this session */ /* Cryptographic key to be used in this session */
u8_t *bit_stream; u8_t *bit_stream;
@ -115,12 +125,12 @@ struct cipher_ctx {
void *handle; void *handle;
} key; } key;
/* The device driver instance this crypto context relates to. Will be /** The device driver instance this crypto context relates to. Will be
* populated by the begin_session() API. * populated by the begin_session() API.
*/ */
struct device *device; struct device *device;
/* If the driver supports multiple simultaneously crypto sessions, this /** If the driver supports multiple simultaneously crypto sessions, this
* will identify the specific driver state this crypto session relates * will identify the specific driver state this crypto session relates
* to. Since dynamic memory allocation 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 * suggested that at build time drivers allocate space for the
@ -129,13 +139,13 @@ struct cipher_ctx {
*/ */
void *drv_sessn_state; void *drv_sessn_state;
/* Place for the user 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 * completion callback happens for async ops. Totally managed by the
* app. * app.
*/ */
void *app_sessn_state; void *app_sessn_state;
/* Cypher 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 * in a session. To be populated by the app before calling
* begin_session(). * begin_session().
*/ */
@ -145,12 +155,12 @@ struct cipher_ctx {
struct gcm_params gcm_info; struct gcm_params gcm_info;
} mode_params; } mode_params;
/* Cryptographic keylength in bytes. To be populated by the app /** Cryptographic keylength in bytes. To be populated by the app
* before calling begin_session() * before calling begin_session()
*/ */
u16_t keylen; u16_t keylen;
/* How certain fields are to be interpreted for this session. /** How certain fields are to be interpreted for this session.
* (A bitmask of CAP_* below.) * (A bitmask of CAP_* below.)
* To be populated by the app before calling begin_session(). * To be populated by the app before calling begin_session().
* An app can obtain the capability flags supported by a hw/driver * An app can obtain the capability flags supported by a hw/driver
@ -170,76 +180,84 @@ struct cipher_ctx {
/* TBD to define */ /* TBD to define */
#define CAP_KEY_LOADING_API BIT(2) #define CAP_KEY_LOADING_API BIT(2)
/* Whether the output is placed in separate buffer or not */ /** Whether the output is placed in separate buffer or not */
#define CAP_INPLACE_OPS BIT(3) #define CAP_INPLACE_OPS BIT(3)
#define CAP_SEPARATE_IO_BUFS BIT(4) #define CAP_SEPARATE_IO_BUFS BIT(4)
/* These denotes if the output (completion of a cipher_xxx_op) is conveyed /**
* These denotes if the output (completion of a cipher_xxx_op) is conveyed
* by the op function returning, or it is conveyed by an async notification * by the op function returning, or it is conveyed by an async notification
*/ */
#define CAP_SYNC_OPS BIT(5) #define CAP_SYNC_OPS BIT(5)
#define CAP_ASYNC_OPS BIT(6) #define CAP_ASYNC_OPS BIT(6)
/* Whether the hardware/driver supports autononce feature */ /** Whether the hardware/driver supports autononce feature */
#define CAP_AUTONONCE BIT(7) #define CAP_AUTONONCE BIT(7)
/* Don't prefix IV to cipher blocks */ /** Don't prefix IV to cipher blocks */
#define CAP_NO_IV_PREFIX BIT(8) #define CAP_NO_IV_PREFIX BIT(8)
/* More flags to be added as necessary */ /* 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 * Structure encoding IO parameters of one cryptographic
* called out has to be filled up by the app before making the cipher_xxx_op() * 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 { struct cipher_pkt {
/* Start address of input buffer */ /** Start address of input buffer */
u8_t *in_buf; u8_t *in_buf;
/* Bytes to be operated upon */ /** Bytes to be operated upon */
int in_len; int in_len;
/* Start of the output buffer, to be allocated by /** Start of the output buffer, to be allocated by
* the application. Can be NULL for in-place ops. To be populated * the application. Can be NULL for in-place ops. To be populated
* with contents by the driver on return from op / async callback. * with contents by the driver on return from op / async callback.
*/ */
u8_t *out_buf; u8_t *out_buf;
/* Size of the out_buf area allocated by the application. Drivers should /** Size of the out_buf area allocated by the application. Drivers
* not write past the size of output buffer. * should not write past the size of output buffer.
*/ */
int out_buf_max; int out_buf_max;
/* To be populated by driver on return from cipher_xxx_op() and /** 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; int out_len;
/* Context this packet relates to. This can be useful to get the /** Context this packet relates to. This can be useful to get the
* session details, especially for async ops. Will be populated by the * session details, especially for async ops. Will be populated by the
* cipher_xxx_op() API based on the ctx parameter. * cipher_xxx_op() API based on the ctx parameter.
*/ */
struct cipher_ctx *ctx; struct cipher_ctx *ctx;
}; };
/* Structure encoding IO parameters in AEAD (Authenticated Encryption /**
* with Associated Data) scenario like in CCM. App has to furnish valid * Structure encoding IO parameters in AEAD (Authenticated Encryption
* contents prior to making cipher_ccm_op() call. * with Associated Data) scenario like in CCM.
*
* App has to furnish valid contents prior to making cipher_ccm_op() call.
*/ */
struct cipher_aead_pkt { 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; 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; 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; 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. * 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.
*/ */
@ -254,4 +272,7 @@ struct cipher_aead_pkt {
*/ */
typedef void (*crypto_completion_cb)(struct cipher_pkt *completed, int status); typedef void (*crypto_completion_cb)(struct cipher_pkt *completed, int status);
/**
* @}
*/
#endif /* ZEPHYR_INCLUDE_CRYPTO_CIPHER_STRUCTS_H_ */ #endif /* ZEPHYR_INCLUDE_CRYPTO_CIPHER_STRUCTS_H_ */