docs: crypto: crypto API documentation
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
parent
9b9436dfbe
commit
b12869a3f9
|
|
@ -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]*\^
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
.. _crypto_cipher:
|
||||
|
||||
|
||||
Crypto
|
||||
#######
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
.. _crypto_cipher_api:
|
||||
|
||||
API Reference
|
||||
*************
|
||||
|
||||
.. doxygengroup:: crypto_cipher
|
||||
:project: Zephyr
|
||||
|
|
@ -8,6 +8,7 @@ API Reference
|
|||
|
||||
bluetooth/index.rst
|
||||
kconfig/index.rst
|
||||
crypto/index.rst
|
||||
drivers/index.rst
|
||||
display/index.rst
|
||||
file_system/index.rst
|
||||
|
|
|
|||
|
|
@ -14,6 +14,21 @@
|
|||
* 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_
|
||||
#define ZEPHYR_INCLUDE_CRYPTO_CIPHER_H_
|
||||
|
||||
|
|
@ -47,14 +62,14 @@ __subsystem struct crypto_driver_api {
|
|||
* 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().
|
||||
*
|
||||
* @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.
|
||||
*/
|
||||
|
|
@ -79,22 +94,22 @@ static inline int cipher_query_hwcaps(struct device *dev)
|
|||
|
||||
}
|
||||
|
||||
/*
|
||||
/**
|
||||
* @brief Setup a crypto session
|
||||
*
|
||||
* Initializes one time parameters, like the session key, algorithm and cipher
|
||||
* mode which may remain constant for all operations in the session. The state
|
||||
* may be cached in hardware and/or driver data state variables.
|
||||
*
|
||||
* @param[in] dev Pointer to the device structure for the driver instance.
|
||||
* @param[in] ctx Pointer to the context structure. Various one time
|
||||
* @param dev Pointer to the device structure for the driver instance.
|
||||
* @param ctx Pointer to the context structure. Various one time
|
||||
* 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
|
||||
* @param algo The crypto algorithm to be used in this session. e.g AES
|
||||
* @param mode The cipher mode to be used in this session. e.g CBC, CTR
|
||||
* @param optype Whether we should encrypt or decrypt in this session
|
||||
*
|
||||
* @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);
|
||||
}
|
||||
|
||||
/*
|
||||
/**
|
||||
* @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
|
||||
* @param dev Pointer to the device structure for the driver instance.
|
||||
* @param ctx Pointer to the crypto context structure of the session
|
||||
* to be freed.
|
||||
*
|
||||
* @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);
|
||||
}
|
||||
|
||||
/*
|
||||
/**
|
||||
* @brief Registers an async crypto op completion callback with the driver
|
||||
*
|
||||
* 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
|
||||
* be invoked from an ISR context.
|
||||
*
|
||||
* @param[in] dev Pointer to the device structure for the driver instance.
|
||||
* @param[in] cb Pointer to application callback to be called by the driver.
|
||||
* @param dev Pointer to the device structure for the driver instance.
|
||||
* @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,
|
||||
* 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
|
||||
* 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 ctx Pointer to the crypto context of this op.
|
||||
* @param pkt Structure holding the input/output buffer pointers.
|
||||
*
|
||||
* @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);
|
||||
}
|
||||
|
||||
/*
|
||||
/**
|
||||
* @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 (IV) for the operation. Same
|
||||
* @param ctx Pointer to the crypto context of this op.
|
||||
* @param pkt Structure holding the input/output buffer pointers.
|
||||
* @param iv Initialization Vector (IV) for the operation. Same
|
||||
* IV value should not be reused across multiple
|
||||
* 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);
|
||||
}
|
||||
|
||||
/*
|
||||
/**
|
||||
* @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 (IV) for the operation. We use a
|
||||
* @param ctx Pointer to the crypto context of this op.
|
||||
* @param pkt Structure holding the input/output buffer pointers.
|
||||
* @param 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
|
||||
|
|
@ -246,13 +261,13 @@ static inline int cipher_ctr_op(struct cipher_ctx *ctx,
|
|||
return ctx->ops.ctr_crypt_hndlr(ctx, pkt, iv);
|
||||
}
|
||||
|
||||
/*
|
||||
/**
|
||||
* @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
|
||||
* @param ctx Pointer to the crypto context of this op.
|
||||
* @param 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
|
||||
* @param nonce Nonce for the operation. Same nonce value should not
|
||||
* be reused across multiple operations (within a
|
||||
* 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);
|
||||
}
|
||||
|
||||
/*
|
||||
/**
|
||||
* @brief Perform Galois/Counter Mode (GCM) crypto operation
|
||||
*
|
||||
* @param[in] ctx Pointer to the crypto context of this op.
|
||||
* @param[in/out] pkt Structure holding the input/output, Associated
|
||||
* @param ctx Pointer to the crypto context of this op.
|
||||
* @param pkt Structure holding the input/output, Associated
|
||||
* 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
|
||||
* 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);
|
||||
}
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
#endif /* ZEPHYR_INCLUDE_CRYPTO_CIPHER_H_ */
|
||||
|
|
|
|||
|
|
@ -19,20 +19,28 @@
|
|||
|
||||
#include <device.h>
|
||||
#include <sys/util.h>
|
||||
/**
|
||||
* @addtogroup crypto_cipher
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
||||
/** Cipher Algorithm */
|
||||
enum cipher_algo {
|
||||
CRYPTO_CIPHER_ALGO_AES = 1,
|
||||
};
|
||||
|
||||
/** Cipher Operation */
|
||||
enum cipher_op {
|
||||
CRYPTO_CIPHER_OP_DECRYPT = 0,
|
||||
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 {
|
||||
CRYPTO_CIPHER_MODE_ECB = 1,
|
||||
CRYPTO_CIPHER_MODE_CBC = 2,
|
||||
|
|
@ -93,19 +101,21 @@ struct gcm_params {
|
|||
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
|
||||
* begin_session() call.
|
||||
/**
|
||||
* 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 begin_session() call.
|
||||
*/
|
||||
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
|
||||
* begin_session() based on the algo/mode chosen by the app.
|
||||
*/
|
||||
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 {
|
||||
/* Cryptographic key to be used in this session */
|
||||
u8_t *bit_stream;
|
||||
|
|
@ -115,12 +125,12 @@ struct cipher_ctx {
|
|||
void *handle;
|
||||
} 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.
|
||||
*/
|
||||
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
|
||||
* to. Since dynamic memory allocation is not possible, it is
|
||||
* suggested that at build time drivers allocate space for the
|
||||
|
|
@ -129,13 +139,13 @@ struct cipher_ctx {
|
|||
*/
|
||||
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
|
||||
* app.
|
||||
*/
|
||||
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
|
||||
* begin_session().
|
||||
*/
|
||||
|
|
@ -145,12 +155,12 @@ struct cipher_ctx {
|
|||
struct gcm_params gcm_info;
|
||||
} 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()
|
||||
*/
|
||||
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.)
|
||||
* To be populated by the app before calling begin_session().
|
||||
* An app can obtain the capability flags supported by a hw/driver
|
||||
|
|
@ -170,76 +180,84 @@ struct cipher_ctx {
|
|||
/* TBD to define */
|
||||
#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_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
|
||||
*/
|
||||
#define CAP_SYNC_OPS BIT(5)
|
||||
#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)
|
||||
|
||||
/* Don't prefix IV to cipher blocks */
|
||||
/** Don't prefix IV to cipher blocks */
|
||||
#define CAP_NO_IV_PREFIX BIT(8)
|
||||
|
||||
/* 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()
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
struct cipher_pkt {
|
||||
|
||||
/* Start address of input buffer */
|
||||
/** Start address of input buffer */
|
||||
u8_t *in_buf;
|
||||
|
||||
/* Bytes to be operated upon */
|
||||
/** Bytes to be operated upon */
|
||||
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
|
||||
* 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.
|
||||
/** Size of the out_buf area allocated by the application. Drivers
|
||||
* should not write past the size of output buffer.
|
||||
*/
|
||||
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.
|
||||
*/
|
||||
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
|
||||
* cipher_xxx_op() API based on the ctx parameter.
|
||||
*/
|
||||
struct cipher_ctx *ctx;
|
||||
};
|
||||
|
||||
/* Structure encoding IO parameters in AEAD (Authenticated Encryption
|
||||
* with Associated Data) scenario like in CCM. App has to furnish valid
|
||||
* contents prior to making cipher_ccm_op() call.
|
||||
/**
|
||||
* Structure encoding IO parameters in AEAD (Authenticated Encryption
|
||||
* with Associated Data) scenario like in CCM.
|
||||
*
|
||||
* App has to furnish valid contents prior to making cipher_ccm_op() call.
|
||||
*/
|
||||
struct cipher_aead_pkt {
|
||||
/* 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.
|
||||
*/
|
||||
|
|
@ -254,4 +272,7 @@ struct cipher_aead_pkt {
|
|||
*/
|
||||
typedef void (*crypto_completion_cb)(struct cipher_pkt *completed, int status);
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
#endif /* ZEPHYR_INCLUDE_CRYPTO_CIPHER_STRUCTS_H_ */
|
||||
|
|
|
|||
Loading…
Reference in New Issue