diff --git a/.known-issues/doc/crypto.conf b/.known-issues/doc/crypto.conf new file mode 100644 index 00000000000..06247055257 --- /dev/null +++ b/.known-issues/doc/crypto.conf @@ -0,0 +1,25 @@ +# +# crypto unnamed struct definition +#doc/reference/crypto/index.rst +^(?P([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]crypto[/\\]index.rst):(?P[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([\-:\\/\w\.])+[/\\]doc[/\\]reference[/\\]crypto[/\\]index.rst):(?P[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]*\^ diff --git a/doc/reference/crypto/index.rst b/doc/reference/crypto/index.rst new file mode 100644 index 00000000000..edead1420c4 --- /dev/null +++ b/doc/reference/crypto/index.rst @@ -0,0 +1,16 @@ +.. _crypto_cipher: + + +Crypto +####### + +Overview +******** + +.. _crypto_cipher_api: + +API Reference +************* + +.. doxygengroup:: crypto_cipher + :project: Zephyr diff --git a/doc/reference/index.rst b/doc/reference/index.rst index f48adf85d51..455529f4242 100644 --- a/doc/reference/index.rst +++ b/doc/reference/index.rst @@ -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 diff --git a/include/crypto/cipher.h b/include/crypto/cipher.h index 7d5790a7134..019daa4e2c2 100644 --- a/include/crypto/cipher.h +++ b/include/crypto/cipher.h @@ -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_ */ diff --git a/include/crypto/cipher_structs.h b/include/crypto/cipher_structs.h index 022da0c49ad..e9405059bc3 100644 --- a/include/crypto/cipher_structs.h +++ b/include/crypto/cipher_structs.h @@ -19,20 +19,28 @@ #include #include +/** + * @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_ */