psa: Add initializers for cipher operation objects
Add new initializers for cipher operation objects and use them in our
tests and library code. Prefer using the macro initializers due to their
straightforwardness.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index f94830d..c266f9f 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1229,17 +1229,59 @@
/** The type of the state data structure for multipart cipher operations.
*
+ * Before calling any function on a cipher operation object, the application
+ * must initialize it by any of the following means:
+ * - Set the structure to all-bits-zero, for example:
+ * \code
+ * psa_cipher_operation_t operation;
+ * memset(&operation, 0, sizeof(operation));
+ * \endcode
+ * - Initialize the structure to logical zero values, for example:
+ * \code
+ * psa_cipher_operation_t operation = {0};
+ * \endcode
+ * - Initialize the structure to the initializer #PSA_CIPHER_OPERATION_INIT,
+ * for example:
+ * \code
+ * psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
+ * \endcode
+ * - Assign the result of the function psa_cipher_operation_init()
+ * to the structure, for example:
+ * \code
+ * psa_cipher_operation_t operation;
+ * operation = psa_cipher_operation_init();
+ * \endcode
+ *
* This is an implementation-defined \c struct. Applications should not
* make any assumptions about the content of this structure except
* as directed by the documentation of a specific implementation. */
typedef struct psa_cipher_operation_s psa_cipher_operation_t;
+/** \def PSA_CIPHER_OPERATION_INIT
+ *
+ * This macro returns a suitable initializer for a cipher operation object of
+ * type #psa_cipher_operation_t.
+ */
+#ifdef __DOXYGEN_ONLY__
+/* This is an example definition for documentation purposes.
+ * Implementations should define a suitable value in `crypto_struct.h`.
+ */
+#define PSA_CIPHER_OPERATION_INIT {0}
+#endif
+
+/** Return an initial value for a cipher operation object.
+ */
+static psa_cipher_operation_t psa_cipher_operation_init(void);
+
/** Set the key for a multipart symmetric encryption operation.
*
* The sequence of operations to encrypt a message with a symmetric cipher
* is as follows:
* -# Allocate an operation object which will be passed to all the functions
* listed here.
+ * -# Initialize the operation object with one of the methods described in the
+ * documentation for #psa_cipher_operation_t, e.g.
+ * PSA_CIPHER_OPERATION_INIT.
* -# Call psa_cipher_encrypt_setup() to specify the algorithm and key.
* The key remains associated with the operation even if the content
* of the key slot changes.
@@ -1252,7 +1294,7 @@
* -# Call psa_cipher_finish().
*
* The application may call psa_cipher_abort() at any time after the operation
- * has been initialized with psa_cipher_encrypt_setup().
+ * has been initialized.
*
* After a successful call to psa_cipher_encrypt_setup(), the application must
* eventually terminate the operation. The following events terminate an
@@ -1261,7 +1303,9 @@
* or psa_cipher_update().
* - A call to psa_cipher_finish() or psa_cipher_abort().
*
- * \param[out] operation The operation object to use.
+ * \param[in,out] operation The operation object to set up. It must have
+ * been initialized as per the documentation for
+ * #psa_cipher_operation_t and not yet in use.
* \param handle Handle to the key to use for the operation.
* \param alg The cipher algorithm to compute
* (\c PSA_ALG_XXX value such that
@@ -1295,6 +1339,9 @@
* is as follows:
* -# Allocate an operation object which will be passed to all the functions
* listed here.
+ * -# Initialize the operation object with one of the methods described in the
+ * documentation for #psa_cipher_operation_t, e.g.
+ * PSA_CIPHER_OPERATION_INIT.
* -# Call psa_cipher_decrypt_setup() to specify the algorithm and key.
* The key remains associated with the operation even if the content
* of the key slot changes.
@@ -1307,7 +1354,7 @@
* -# Call psa_cipher_finish().
*
* The application may call psa_cipher_abort() at any time after the operation
- * has been initialized with psa_cipher_decrypt_setup().
+ * has been initialized.
*
* After a successful call to psa_cipher_decrypt_setup(), the application must
* eventually terminate the operation. The following events terminate an
@@ -1315,7 +1362,9 @@
* - A failed call to psa_cipher_update().
* - A call to psa_cipher_finish() or psa_cipher_abort().
*
- * \param[out] operation The operation object to use.
+ * \param[in,out] operation The operation object to set up. It must have
+ * been initialized as per the documentation for
+ * #psa_cipher_operation_t and not yet in use.
* \param handle Handle to the key to use for the operation.
* \param alg The cipher algorithm to compute
* (\c PSA_ALG_XXX value such that
diff --git a/include/psa/crypto_struct.h b/include/psa/crypto_struct.h
index 5eb2624..ee3ecd7 100644
--- a/include/psa/crypto_struct.h
+++ b/include/psa/crypto_struct.h
@@ -145,6 +145,13 @@
} ctx;
};
+#define PSA_CIPHER_OPERATION_INIT {0, 0, 0, 0, 0, 0, {0}}
+static inline struct psa_cipher_operation_s psa_cipher_operation_init( void )
+{
+ const struct psa_cipher_operation_s v = PSA_CIPHER_OPERATION_INIT;
+ return( v );
+}
+
#if defined(MBEDTLS_MD_C)
typedef struct
{