More documentation
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 5edc04f..69c93dd 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -201,11 +201,24 @@
((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(type) & \
~PSA_KEY_TYPE_ECC_CURVE_MASK) == PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE)
+/** The block size of a block cipher.
+ *
+ * \param type A cipher key type (value of type #psa_key_type_t).
+ *
+ * \return The block size for a block cipher, or 1 for a stream cipher.
+ * The return value is undefined if \c type does not identify
+ * a cipher algorithm.
+ *
+ * \note This macro returns a compile-time constant if its argument is one.
+ *
+ * \warning This macro may evaluate its argument multiple times.
+ */
#define PSA_BLOCK_CIPHER_BLOCK_SIZE(type) \
( \
(type) == PSA_KEY_TYPE_AES ? 16 : \
(type) == PSA_KEY_TYPE_DES ? 8 : \
(type) == PSA_KEY_TYPE_CAMELLIA ? 16 : \
+ (type) == PSA_KEY_TYPE_ARC4 ? 1 : \
0)
/** \brief Encoding of a cryptographic algorithm.
@@ -233,11 +246,12 @@
(((alg) & PSA_ALG_VENDOR_FLAG) != 0)
/** Whether the specified algorithm is a hash algorithm.
*
- * \param alg An algorithm identifier (\c PSA_ALG_XXX value)
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
*
* \return 1 if \c alg is a hash algorithm, 0 otherwise.
* This macro may return either 0 or 1 if \c alg is not a valid
- * algorithm identifier. */
+ * algorithm identifier.
+ */
#define PSA_ALG_IS_HASH(alg) \
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_HASH)
#define PSA_ALG_IS_MAC(alg) \
@@ -474,11 +488,41 @@
/** \brief Encoding of permitted usage on a key. */
typedef uint32_t psa_key_usage_t;
+/** Whether the key may be exported.
+ *
+ * A public key or the public part of a key pair may always be exported
+ * regardless of the value of this permission flag.
+ *
+ * If a key does not have export permission, implementations shall not
+ * allow the key to be exported in plain form from the cryptoprocessor,
+ * whether through psa_export_key() or through a proprietary interface.
+ * The key may however be exportable in a wrapped form, i.e. in a form
+ * where it is encrypted by another key.
+ */
#define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t)0x00000001)
+/** Whether the key may be used to encrypt a message.
+ *
+ * For a key pair, this concerns the public key.
+ */
#define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t)0x00000100)
+
+/** Whether the key may be used to decrypt a message.
+ *
+ * For a key pair, this concerns the private key.
+ */
#define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200)
+
+/** Whether the key may be used to sign a message.
+ *
+ * For a key pair, this concerns the private key.
+ */
#define PSA_KEY_USAGE_SIGN ((psa_key_usage_t)0x00000400)
+
+/** Whether the key may be used to verify a message signature.
+ *
+ * For a key pair, this concerns the public key.
+ */
#define PSA_KEY_USAGE_VERIFY ((psa_key_usage_t)0x00000800)
/** The type of the key policy data structure.
@@ -492,6 +536,12 @@
* usage of the key. */
void psa_key_policy_init(psa_key_policy_t *policy);
+/** \brief Set the standard fields of a policy structure.
+ *
+ * Note that this function does not make any consistency check of the
+ * parameters. The values are only checked when applying the policy to
+ * a key slot with psa_set_key_policy().
+ */
void psa_key_policy_set_usage(psa_key_policy_t *policy,
psa_key_usage_t usage,
psa_algorithm_t alg);
@@ -505,10 +555,15 @@
* This function must be called on an empty key slot, before importing,
* generating or creating a key in the slot. Changing the policy of an
* existing key is not permitted.
+ *
+ * Implementations may set restrictions on supported key policies
+ * depending on the key type and the key slot.
*/
psa_status_t psa_set_key_policy(psa_key_slot_t key,
const psa_key_policy_t *policy);
+/** \brief Get the usage policy for a key slot.
+ */
psa_status_t psa_get_key_policy(psa_key_slot_t key,
psa_key_policy_t *policy);