Skip to content

Minor API specification fixes after 1.0beta1 #47

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Mar 5, 2019
Merged

Minor API specification fixes after 1.0beta1 #47

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
4c6fdbb
Fix typos in doxygen formatting commands
gilles-peskine-arm Feb 8, 2019
6bce7f7
Fix copypasta in multipart AEAD macro
gilles-peskine-arm Feb 8, 2019
12b58ab
Remove duplicate definition of PSA_ALG_IS_WILDCARD
gilles-peskine-arm Feb 8, 2019
47e79fb
Fix minor errors in key derivation and key agreement documentation
gilles-peskine-arm Feb 8, 2019
63f7930
Doxygen: fix missing markup indicator that was causing broken links
gilles-peskine-arm Feb 15, 2019
d338b91
Fix some copypasta in one-shot hash and MAC function descriptions
gilles-peskine-arm Feb 15, 2019
9153ec0
Add documentation for some macros
gilles-peskine-arm Feb 15, 2019
bf7a98b
Fix typos found in PSA Crypto API 1.0 beta2 before publication
gilles-peskine-arm Feb 22, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 15 additions & 14 deletions include/psa/crypto.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -754,7 +754,7 @@ psa_status_t psa_export_public_key(psa_key_handle_t handle,
* to another. The target key retains its lifetime and location.
*
* In an implementation where slots have different ownerships,
* this functin may be used to share a key with a different party,
* this function may be used to share a key with a different party,
* subject to implementation-defined restrictions on key sharing.
* In this case \p constraint would typically prevent the recipient
* from exporting the key.
Expand Down Expand Up @@ -830,8 +830,7 @@ psa_status_t psa_copy_key(psa_key_handle_t source_handle,
* \param hash_size Size of the \p hash buffer in bytes.
* \param[out] hash_length On success, the number of bytes
* that make up the hash value. This is always
* #PSA_HASH_SIZE(\c alg) where \c alg is the
* hash algorithm that is calculated.
* #PSA_HASH_SIZE(\p alg).
*
* \retval #PSA_SUCCESS
* Success.
Expand Down Expand Up @@ -1139,15 +1138,13 @@ psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
*
* \param handle Handle to the key to use for the operation.
* \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
* such that #PSA_ALG_IS_MAC(alg) is true).
* such that #PSA_ALG_IS_MAC(\p alg) is true).
* \param[in] input Buffer containing the input message.
* \param input_length Size of the \p input buffer in bytes.
* \param[out] mac Buffer where the MAC value is to be written.
* \param mac_size Size of the \p mac buffer in bytes.
* \param[out] mac_length On success, the number of bytes
* that make up the mac value. This is always
* #PSA_HASH_SIZE(\c alg) where \c alg is the
* hash algorithm that is calculated.
* that make up the MAC value.
*
* \retval #PSA_SUCCESS
* Success.
Expand Down Expand Up @@ -1179,7 +1176,7 @@ psa_status_t psa_mac_compute(psa_key_handle_t handle,
*
* \param handle Handle to the key to use for the operation.
* \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
* such that #PSA_ALG_IS_MAC(alg) is true).
* such that #PSA_ALG_IS_MAC(\p alg) is true).
* \param[in] input Buffer containing the input message.
* \param input_length Size of the \p input buffer in bytes.
* \param[out] mac Buffer containing the expected MAC value.
Expand Down Expand Up @@ -1289,7 +1286,7 @@ static psa_mac_operation_t psa_mac_operation_init(void);
* It must remain valid until the operation
* terminates.
* \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
* such that #PSA_ALG_IS_MAC(alg) is true).
* such that #PSA_ALG_IS_MAC(\p alg) is true).
*
* \retval #PSA_SUCCESS
* Success.
Expand Down Expand Up @@ -1962,7 +1959,7 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
* #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg,
* \p plaintext_length).
* \param[out] ciphertext_length On success, the size of the output
* in the \b ciphertext buffer.
* in the \p ciphertext buffer.
*
* \retval #PSA_SUCCESS
* Success.
Expand Down Expand Up @@ -2018,7 +2015,7 @@ psa_status_t psa_aead_encrypt(psa_key_handle_t handle,
* #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg,
* \p ciphertext_length).
* \param[out] plaintext_length On success, the size of the output
* in the \b plaintext buffer.
* in the \p plaintext buffer.
*
* \retval #PSA_SUCCESS
* Success.
Expand Down Expand Up @@ -3129,9 +3126,9 @@ psa_status_t psa_key_derivation_input_key(psa_crypto_generator_t *generator,
* public key type corresponding to the type of
* private_key. That is, this function performs the
* equivalent of
* `psa_import_key(internal_public_key_handle,
* PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(private_key_type),
* peer_key, peer_key_length)` where
* #psa_import_key(`internal_public_key_handle`,
* #PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(`private_key_type`),
* `peer_key`, `peer_key_length`) where
* `private_key_type` is the type of `private_key`.
* For example, for EC keys, this means that peer_key
* is interpreted as a point on the curve that the
Expand Down Expand Up @@ -3175,6 +3172,10 @@ psa_status_t psa_key_agreement(psa_crypto_generator_t *generator,
* a key derivation, use psa_key_agreement() and other functions from
* the key derivation and generator interface.
*
* \param alg The key agreement algorithm to compute
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_RAW_KEY_AGREEMENT(\p alg)
* is true).
* \param private_key Handle to the private key to use.
* \param[in] peer_key Public key of the peer. It must be
* in the same format that psa_import_key()
Expand Down
10 changes: 5 additions & 5 deletions include/psa/crypto_sizes.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -228,7 +228,7 @@
* \param key_type The type of the MAC key.
* \param key_bits The size of the MAC key in bits.
* \param alg A MAC algorithm (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_MAC(alg) is true).
* #PSA_ALG_IS_MAC(\p alg) is true).
*
* \return The MAC size for the specified algorithm with
* the specified key parameters.
Expand All @@ -253,7 +253,7 @@
*
* \param alg An AEAD algorithm
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(alg) is true).
* #PSA_ALG_IS_AEAD(\p alg) is true).
* \param plaintext_length Size of the plaintext in bytes.
*
* \return The AEAD ciphertext size for the specified
Expand All @@ -277,7 +277,7 @@
*
* \param alg An AEAD algorithm
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(alg) is true).
* #PSA_ALG_IS_AEAD(\p alg) is true).
*
* \return The maximum trailing ciphertext size for the
* specified algorithm.
Expand All @@ -286,7 +286,7 @@
* correct size for an AEAD algorithm that it
* recognizes, but does not support.
*/
#define PSA_AEAD_FINISH_OUTPUT_SIZE(alg, plaintext_length) \
#define PSA_AEAD_FINISH_OUTPUT_SIZE(alg) \
((size_t)0)

/** The maximum size of the output of psa_aead_decrypt(), in bytes.
Expand All @@ -298,7 +298,7 @@
*
* \param alg An AEAD algorithm
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_AEAD(alg) is true).
* #PSA_ALG_IS_AEAD(\p alg) is true).
* \param ciphertext_length Size of the plaintext in bytes.
*
* \return The AEAD ciphertext size for the specified
Expand Down
71 changes: 37 additions & 34 deletions include/psa/crypto_values.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,7 @@
* the global integrity of the keystore. Depending on the global
* integrity guarantees offered by the implementation, access to other
* data may or may not fail even if the data is still readable but
* its integrity canont be guaranteed.
* its integrity cannot be guaranteed.
*
* Implementations should only use this error code to report a
* permanent storage corruption. However application writers should
Expand Down Expand Up @@ -613,7 +613,6 @@
#define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg) \
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION)

#define PSA_ALG_KEY_SELECTION_FLAG ((psa_algorithm_t)0x01000000)
/** Whether the specified algorithm is a key agreement algorithm.
*
* \param alg An algorithm identifier (value of type #psa_algorithm_t).
Expand All @@ -623,8 +622,7 @@
* algorithm identifier.
*/
#define PSA_ALG_IS_KEY_AGREEMENT(alg) \
(((alg) & PSA_ALG_CATEGORY_MASK & ~PSA_ALG_KEY_SELECTION_FLAG) == \
PSA_ALG_CATEGORY_KEY_AGREEMENT)
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_AGREEMENT)

/** Whether the specified algorithm is a key derivation algorithm.
*
Expand All @@ -637,17 +635,6 @@
#define PSA_ALG_IS_KEY_DERIVATION(alg) \
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_DERIVATION)

/** Whether the specified algorithm is a key selection algorithm.
*
* \param alg An algorithm identifier (value of type #psa_algorithm_t).
*
* \return 1 if \p alg is a key selection algorithm, 0 otherwise.
* This macro may return either 0 or 1 if \p alg is not a supported
* algorithm identifier.
*/
#define PSA_ALG_IS_KEY_SELECTION(alg) \
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_SELECTION)

#define PSA_ALG_HASH_MASK ((psa_algorithm_t)0x000000ff)

#define PSA_ALG_MD2 ((psa_algorithm_t)0x01000001)
Expand Down Expand Up @@ -898,7 +885,12 @@
*/
#define PSA_ALG_CBC_PKCS7 ((psa_algorithm_t)0x04600101)

/** The CCM authenticated encryption algorithm.
*/
#define PSA_ALG_CCM ((psa_algorithm_t)0x06001001)

/** The GCM authenticated encryption algorithm.
*/
#define PSA_ALG_GCM ((psa_algorithm_t)0x06001002)

/* In the encoding of a AEAD algorithm, the bits corresponding to
Expand Down Expand Up @@ -1020,6 +1012,20 @@
(PSA_ALG_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
#define PSA_ALG_DETERMINISTIC_DSA_BASE ((psa_algorithm_t)0x10050000)
#define PSA_ALG_DSA_DETERMINISTIC_FLAG ((psa_algorithm_t)0x00010000)
/** Deterministic DSA signature with hashing.
*
* This is the deterministic variant defined by RFC 6979 of
* the signature scheme defined by FIPS 186-4.
*
* \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_HASH(\p hash_alg) is true).
* This includes #PSA_ALG_ANY_HASH
* when specifying the algorithm in a usage policy.
*
* \return The corresponding DSA signature algorithm.
* \return Unspecified if \p alg is not a supported
* hash algorithm.
*/
#define PSA_ALG_DETERMINISTIC_DSA(hash_alg) \
(PSA_ALG_DETERMINISTIC_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
#define PSA_ALG_IS_DSA(alg) \
Expand Down Expand Up @@ -1313,8 +1319,23 @@
#define PSA_ALG_KEY_AGREEMENT_GET_BASE(alg) \
(((alg) & PSA_ALG_KEY_AGREEMENT_MASK) | PSA_ALG_CATEGORY_KEY_AGREEMENT)

/** Whether the specified algorithm is a raw key agreement algorithm.
*
* A raw key agreement algorithm is one that does not specify
* a key derivation function.
* Usually, raw key agreement algorithms are constructed directly with
* a \c PSA_ALG_xxx macro while non-raw key agreement algorithms are
* constructed with PSA_ALG_KEY_AGREEMENT().
*
* \param alg An algorithm identifier (value of type #psa_algorithm_t).
*
* \return 1 if \p alg is a raw key agreement algorithm, 0 otherwise.
* This macro may return either 0 or 1 if \p alg is not a supported
* algorithm identifier.
*/
#define PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) \
(PSA_ALG_KEY_AGREEMENT_GET_KDF(alg) == PSA_ALG_CATEGORY_KEY_DERIVATION)
(PSA_ALG_IS_KEY_AGREEMENT(alg) && \
PSA_ALG_KEY_AGREEMENT_GET_KDF(alg) == PSA_ALG_CATEGORY_KEY_DERIVATION)

#define PSA_ALG_IS_KEY_DERIVATION_OR_AGREEMENT(alg) \
((PSA_ALG_IS_KEY_DERIVATION(alg) || PSA_ALG_IS_KEY_AGREEMENT(alg)))
Expand Down Expand Up @@ -1404,24 +1425,6 @@
PSA_ALG_SIGN_GET_HASH(alg) == PSA_ALG_ANY_HASH : \
(alg) == PSA_ALG_ANY_HASH)

/** Whether the specified algorithm encoding is a wildcard.
*
* Wildcard values may only be used to set the usage algorithm field in
* a policy, not to perform an operation.
*
* \param alg An algorithm identifier (value of type #psa_algorithm_t).
*
* \return 1 if \c alg is a wildcard algorithm encoding.
* \return 0 if \c alg is a non-wildcard algorithm encoding (suitable for
* an operation).
* \return This macro may return either 0 or 1 if \c alg is not a supported
* algorithm identifier.
*/
#define PSA_ALG_IS_WILDCARD(alg) \
(PSA_ALG_IS_HASH_AND_SIGN(alg) ? \
PSA_ALG_SIGN_GET_HASH(alg) == PSA_ALG_ANY_HASH : \
(alg) == PSA_ALG_ANY_HASH)

/**@}*/

/** \defgroup key_lifetimes Key lifetimes
Expand Down