Remove redundant declarations and update docs

Signed-off-by: Ben Taylor <ben.taylor@linaro.org>

Author: Ben Taylor

include/psa/crypto.h

@@ -117,251 +117,6 @@ psa_status_t psa_crypto_init(void);
  * of type #psa_key_attributes_t.
  */
 
-/** Return an initial value for a key attributes structure.
- */
-static psa_key_attributes_t psa_key_attributes_init(void);
-
-/** Declare a key as persistent and set its key identifier.
- *
- * If the attribute structure currently declares the key as volatile (which
- * is the default content of an attribute structure), this function sets
- * the lifetime attribute to #PSA_KEY_LIFETIME_PERSISTENT.
- *
- * This function does not access storage, it merely stores the given
- * value in the structure.
- * The persistent key will be written to storage when the attribute
- * structure is passed to a key creation function such as
- * psa_import_key(), psa_generate_key(), psa_generate_key_custom(),
- * psa_key_derivation_output_key(), psa_key_derivation_output_key_custom()
- * or psa_copy_key().
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate each of its arguments exactly once.
- *
- * \param[out] attributes  The attribute structure to write to.
- * \param key              The persistent identifier for the key.
- *                         This can be any value in the range from
- *                         #PSA_KEY_ID_USER_MIN to #PSA_KEY_ID_USER_MAX
- *                         inclusive.
- */
-static void psa_set_key_id(psa_key_attributes_t *attributes,
-                           mbedtls_svc_key_id_t key);
-
-#ifdef MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
-/** Set the owner identifier of a key.
- *
- * When key identifiers encode key owner identifiers, psa_set_key_id() does
- * not allow to define in key attributes the owner of volatile keys as
- * psa_set_key_id() enforces the key to be persistent.
- *
- * This function allows to set in key attributes the owner identifier of a
- * key. It is intended to be used for volatile keys. For persistent keys,
- * it is recommended to use the PSA Cryptography API psa_set_key_id() to define
- * the owner of a key.
- *
- * \param[out] attributes  The attribute structure to write to.
- * \param owner            The key owner identifier.
- */
-static void mbedtls_set_key_owner_id(psa_key_attributes_t *attributes,
-                                     mbedtls_key_owner_id_t owner);
-#endif
-
-/** Set the location of a persistent key.
- *
- * To make a key persistent, you must give it a persistent key identifier
- * with psa_set_key_id(). By default, a key that has a persistent identifier
- * is stored in the default storage area identifier by
- * #PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage
- * area, or to explicitly declare the key as volatile.
- *
- * This function does not access storage, it merely stores the given
- * value in the structure.
- * The persistent key will be written to storage when the attribute
- * structure is passed to a key creation function such as
- * psa_import_key(), psa_generate_key(), psa_generate_key_custom(),
- * psa_key_derivation_output_key(), psa_key_derivation_output_key_custom()
- * or psa_copy_key().
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate each of its arguments exactly once.
- *
- * \param[out] attributes       The attribute structure to write to.
- * \param lifetime              The lifetime for the key.
- *                              If this is #PSA_KEY_LIFETIME_VOLATILE, the
- *                              key will be volatile, and the key identifier
- *                              attribute is reset to 0.
- */
-static void psa_set_key_lifetime(psa_key_attributes_t *attributes,
-                                 psa_key_lifetime_t lifetime);
-
-/** Retrieve the key identifier from key attributes.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate its argument exactly once.
- *
- * \param[in] attributes        The key attribute structure to query.
- *
- * \return The persistent identifier stored in the attribute structure.
- *         This value is unspecified if the attribute structure declares
- *         the key as volatile.
- */
-static mbedtls_svc_key_id_t psa_get_key_id(
-    const psa_key_attributes_t *attributes);
-
-/** Retrieve the lifetime from key attributes.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate its argument exactly once.
- *
- * \param[in] attributes        The key attribute structure to query.
- *
- * \return The lifetime value stored in the attribute structure.
- */
-static psa_key_lifetime_t psa_get_key_lifetime(
-    const psa_key_attributes_t *attributes);
-
-/** Declare usage flags for a key.
- *
- * Usage flags are part of a key's usage policy. They encode what
- * kind of operations are permitted on the key. For more details,
- * refer to the documentation of the type #psa_key_usage_t.
- *
- * This function overwrites any usage flags
- * previously set in \p attributes.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate each of its arguments exactly once.
- *
- * \param[out] attributes       The attribute structure to write to.
- * \param usage_flags           The usage flags to write.
- */
-static void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
-                                    psa_key_usage_t usage_flags);
-
-/** Retrieve the usage flags from key attributes.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate its argument exactly once.
- *
- * \param[in] attributes        The key attribute structure to query.
- *
- * \return The usage flags stored in the attribute structure.
- */
-static psa_key_usage_t psa_get_key_usage_flags(
-    const psa_key_attributes_t *attributes);
-
-/** Declare the permitted algorithm policy for a key.
- *
- * The permitted algorithm policy of a key encodes which algorithm or
- * algorithms are permitted to be used with this key. The following
- * algorithm policies are supported:
- * - 0 does not allow any cryptographic operation with the key. The key
- *   may be used for non-cryptographic actions such as exporting (if
- *   permitted by the usage flags).
- * - An algorithm value permits this particular algorithm.
- * - An algorithm wildcard built from #PSA_ALG_ANY_HASH allows the specified
- *   signature scheme with any hash algorithm.
- * - An algorithm built from #PSA_ALG_AT_LEAST_THIS_LENGTH_MAC allows
- *   any MAC algorithm from the same base class (e.g. CMAC) which
- *   generates/verifies a MAC length greater than or equal to the length
- *   encoded in the wildcard algorithm.
- * - An algorithm built from #PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG
- *   allows any AEAD algorithm from the same base class (e.g. CCM) which
- *   generates/verifies a tag length greater than or equal to the length
- *   encoded in the wildcard algorithm.
- *
- * This function overwrites any algorithm policy
- * previously set in \p attributes.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate each of its arguments exactly once.
- *
- * \param[out] attributes       The attribute structure to write to.
- * \param alg                   The permitted algorithm policy to write.
- */
-static void psa_set_key_algorithm(psa_key_attributes_t *attributes,
-                                  psa_algorithm_t alg);
-
-
-/** Retrieve the algorithm policy from key attributes.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate its argument exactly once.
- *
- * \param[in] attributes        The key attribute structure to query.
- *
- * \return The algorithm stored in the attribute structure.
- */
-static psa_algorithm_t psa_get_key_algorithm(
-    const psa_key_attributes_t *attributes);
-
-/** Declare the type of a key.
- *
- * This function overwrites any key type
- * previously set in \p attributes.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate each of its arguments exactly once.
- *
- * \param[out] attributes       The attribute structure to write to.
- * \param type                  The key type to write.
- *                              If this is 0, the key type in \p attributes
- *                              becomes unspecified.
- */
-static void psa_set_key_type(psa_key_attributes_t *attributes,
-                             psa_key_type_t type);
-
-
-/** Declare the size of a key.
- *
- * This function overwrites any key size previously set in \p attributes.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate each of its arguments exactly once.
- *
- * \param[out] attributes       The attribute structure to write to.
- * \param bits                  The key size in bits.
- *                              If this is 0, the key size in \p attributes
- *                              becomes unspecified. Keys of size 0 are
- *                              not supported.
- */
-static void psa_set_key_bits(psa_key_attributes_t *attributes,
-                             size_t bits);
-
-/** Retrieve the key type from key attributes.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate its argument exactly once.
- *
- * \param[in] attributes        The key attribute structure to query.
- *
- * \return The key type stored in the attribute structure.
- */
-static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes);
-
-/** Retrieve the key size from key attributes.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate its argument exactly once.
- *
- * \param[in] attributes        The key attribute structure to query.
- *
- * \return The key size stored in the attribute structure, in bits.
- */
-static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);
-
 /** Retrieve the attributes of a key.
  *
  * This function first resets the attribute structure as with
@@ -945,10 +700,6 @@ typedef struct psa_hash_operation_s psa_hash_operation_t;
  * of type #psa_hash_operation_t.
  */
 
-/** Return an initial value for a hash operation object.
- */
-static psa_hash_operation_t psa_hash_operation_init(void);
-
 /** Set up a multipart hash operation.
  *
  * The sequence of operations to calculate a hash (message digest)
@@ -1213,10 +964,6 @@ typedef struct psa_xof_operation_s psa_xof_operation_t;
  * of type #psa_xof_operation_t.
  */
 
-/** Return an initial value for a XOF operation object.
- */
-static psa_xof_operation_t psa_xof_operation_init(void);
-
 /** Set up a multipart XOF (extendable-operation function) operation.
  *
  * The sequence of operations to calculate a XOF is as follows:
@@ -1493,10 +1240,6 @@ typedef struct psa_mac_operation_s psa_mac_operation_t;
  * #psa_mac_operation_t.
  */
 
-/** Return an initial value for a MAC operation object.
- */
-static psa_mac_operation_t psa_mac_operation_init(void);
-
 /** Set up a multipart MAC calculation operation.
  *
  * This function sets up the calculation of the MAC
@@ -1906,10 +1649,6 @@ typedef struct psa_cipher_operation_s psa_cipher_operation_t;
  * type #psa_cipher_operation_t.
  */
 
-/** 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
@@ -2424,10 +2163,6 @@ typedef struct psa_aead_operation_s psa_aead_operation_t;
  * type #psa_aead_operation_t.
  */
 
-/** Return an initial value for an AEAD operation object.
- */
-static psa_aead_operation_t psa_aead_operation_init(void);
-
 /** Set the key for a multipart authenticated encryption operation.
  *
  * The sequence of operations to encrypt a message with authentication
@@ -3411,10 +3146,6 @@ typedef struct psa_key_derivation_s psa_key_derivation_operation_t;
  * object of type #psa_key_derivation_operation_t.
  */
 
-/** Return an initial value for a key derivation operation object.
- */
-static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
-
 /** Set up a key derivation operation.
  *
  * A key derivation algorithm takes some inputs and uses them to generate