Skip to content

API: minor corrections after beta 2 #83

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 7 commits into from
Mar 12, 2019
Merged

API: minor corrections after beta 2 #83

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
2e37c0d
Fix leftover occurrences of "key selection algorithm"
gilles-peskine-arm Mar 5, 2019
ae2e5e0
Remove copypasta'ed error reason in psa_aead_finish
gilles-peskine-arm Mar 5, 2019
3be6b7f
Fix some copypasta in references to parameter names
gilles-peskine-arm Mar 5, 2019
fa4486d
Specify psa_generator_import_key for each key type
gilles-peskine-arm Mar 11, 2019
2de2c0d
Clarify deterministic generation by re-drawing
gilles-peskine-arm Mar 11, 2019
5579971
psa_generator_import_key (ECC): minor corrections
gilles-peskine-arm Mar 12, 2019
ee67dd6
Fix Doxygen warnings
gilles-peskine-arm Mar 12, 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
154 changes: 109 additions & 45 deletions include/psa/crypto.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -792,12 +792,12 @@ psa_status_t psa_export_public_key(psa_key_handle_t handle,
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_OCCUPIED_SLOT
* \p target already contains key material.
* \p target_handle already contains key material.
* \retval #PSA_ERROR_EMPTY_SLOT
* \p source does not contain key material.
* \p source_handle does not contain key material.
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The policy constraints on the source, on the target and
* \p constraints are incompatible.
* \p constraint are incompatible.
* \retval #PSA_ERROR_NOT_PERMITTED
* The source key is not exportable and its lifetime does not
* allow copying it to the target's lifetime.
Expand Down Expand Up @@ -1152,7 +1152,7 @@ psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
* \retval #PSA_ERROR_EMPTY_SLOT
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p key is not compatible with \p alg.
* \p handle is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a MAC algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Expand Down Expand Up @@ -1191,7 +1191,7 @@ psa_status_t psa_mac_compute(psa_key_handle_t handle,
* \retval #PSA_ERROR_EMPTY_SLOT
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p key is not compatible with \p alg.
* \p handle is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a MAC algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Expand Down Expand Up @@ -1294,7 +1294,7 @@ static psa_mac_operation_t psa_mac_operation_init(void);
* \retval #PSA_ERROR_EMPTY_SLOT
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p key is not compatible with \p alg.
* \p handle is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a MAC algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Expand Down Expand Up @@ -1532,7 +1532,7 @@ psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
* \retval #PSA_ERROR_EMPTY_SLOT
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p key is not compatible with \p alg.
* \p handle is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a cipher algorithm.
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
Expand Down Expand Up @@ -1574,7 +1574,7 @@ psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
* \retval #PSA_ERROR_EMPTY_SLOT
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p key is not compatible with \p alg.
* \p handle is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a cipher algorithm.
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
Expand Down Expand Up @@ -1680,7 +1680,7 @@ static psa_cipher_operation_t psa_cipher_operation_init(void);
* \retval #PSA_ERROR_EMPTY_SLOT
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p key is not compatible with \p alg.
* \p handle is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a cipher algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Expand Down Expand Up @@ -1739,7 +1739,7 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
* \retval #PSA_ERROR_EMPTY_SLOT
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p key is not compatible with \p alg.
* \p handle is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a cipher algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Expand Down Expand Up @@ -1967,7 +1967,7 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
* \retval #PSA_ERROR_EMPTY_SLOT
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p key is not compatible with \p alg.
* \p handle is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not an AEAD algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Expand Down Expand Up @@ -2025,7 +2025,7 @@ psa_status_t psa_aead_encrypt(psa_key_handle_t handle,
* The ciphertext is not authentic.
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p key is not compatible with \p alg.
* \p handle is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not an AEAD algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Expand Down Expand Up @@ -2144,7 +2144,7 @@ static psa_aead_operation_t psa_aead_operation_init(void);
* \retval #PSA_ERROR_EMPTY_SLOT
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p key is not compatible with \p alg.
* \p handle is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not an AEAD algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Expand Down Expand Up @@ -2206,7 +2206,7 @@ psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
* \retval #PSA_ERROR_EMPTY_SLOT
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p key is not compatible with \p alg.
* \p handle is not compatible with \p alg.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not an AEAD algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Expand Down Expand Up @@ -2444,7 +2444,7 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation,
* psa_aead_update() does not buffer any output and therefore \p ciphertext
* will not contain any output and can be a 0-sized buffer.
* - \p tag contains the authentication tag. Its length is always
* #PSA_AEAD_TAG_LENGTH(\p alg) where \p alg is the AEAD algorithm
* #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is the AEAD algorithm
* that the operation performs.
*
* When this function returns, the operation becomes inactive.
Expand All @@ -2467,7 +2467,7 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation,
* The operation state is not valid (not set up, nonce not set,
* decryption, or already completed).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p output buffer is too small.
* The size of the \p ciphertext or \p tag buffer is too small.
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The total length of input to psa_aead_update_ad() so far is
* less than the additional data length that was previously
Expand Down Expand Up @@ -2509,8 +2509,6 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not set up, nonce not set,
* encryption, or already completed).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p output buffer is too small.
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The total length of input to psa_aead_update_ad() so far is
* less than the additional data length that was previously
Expand Down Expand Up @@ -2576,7 +2574,7 @@ psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
* \param handle Handle to the key to use for the operation.
* It must be an asymmetric key pair.
* \param alg A signature algorithm that is compatible with
* the type of \p key.
* the type of \p handle.
* \param[in] hash The hash or message to sign.
* \param hash_length Size of the \p hash buffer in bytes.
* \param[out] signature Buffer where the signature is to be written.
Expand All @@ -2590,7 +2588,7 @@ psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
* determine a sufficient buffer size by calling
* #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
* where \c key_type and \c key_bits are the type and bit-size
* respectively of \p key.
* respectively of \p handle.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Expand Down Expand Up @@ -2623,7 +2621,7 @@ psa_status_t psa_asymmetric_sign(psa_key_handle_t handle,
* \param handle Handle to the key to use for the operation.
* It must be a public key or an asymmetric key pair.
* \param alg A signature algorithm that is compatible with
* the type of \p key.
* the type of \p handle.
* \param[in] hash The hash or message whose signature is to be
* verified.
* \param hash_length Size of the \p hash buffer in bytes.
Expand Down Expand Up @@ -2660,7 +2658,7 @@ psa_status_t psa_asymmetric_verify(psa_key_handle_t handle,
* It must be a public key or an asymmetric
* key pair.
* \param alg An asymmetric encryption algorithm that is
* compatible with the type of \p key.
* compatible with the type of \p handle.
* \param[in] input The message to encrypt.
* \param input_length Size of the \p input buffer in bytes.
* \param[in] salt A salt or label, if supported by the
Expand All @@ -2687,7 +2685,7 @@ psa_status_t psa_asymmetric_verify(psa_key_handle_t handle,
* determine a sufficient buffer size by calling
* #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
* where \c key_type and \c key_bits are the type and bit-size
* respectively of \p key.
* respectively of \p handle.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Expand Down Expand Up @@ -2716,7 +2714,7 @@ psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle,
* \param handle Handle to the key to use for the operation.
* It must be an asymmetric key pair.
* \param alg An asymmetric encryption algorithm that is
* compatible with the type of \p key.
* compatible with the type of \p handle.
* \param[in] input The message to decrypt.
* \param input_length Size of the \p input buffer in bytes.
* \param[in] salt A salt or label, if supported by the
Expand All @@ -2743,7 +2741,7 @@ psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle,
* determine a sufficient buffer size by calling
* #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
* where \c key_type and \c key_bits are the type and bit-size
* respectively of \p key.
* respectively of \p handle.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Expand Down Expand Up @@ -2880,24 +2878,92 @@ psa_status_t psa_generator_read(psa_crypto_generator_t *generator,
uint8_t *output,
size_t output_length);

/** Create a symmetric key from data read from a generator.
*
* This function reads a sequence of bytes from a generator and imports
* these bytes as a key.
* The data that is read is discarded from the generator. The generator's
* capacity is decreased by the number of bytes read.
*
* This function is equivalent to calling #psa_generator_read and
* passing the resulting output to #psa_import_key, but
* if the implementation provides an isolation boundary then
* the key material is not exposed outside the isolation boundary.
/** Generate a key deterministically from data read from a generator.
*
* This function uses the output of a generator to derive a key.
* How much output it consumes and how the key is derived depends on the
* key type.
*
* - For key types for which the key is an arbitrary sequence of bytes
* of a given size,
* this function is functionally equivalent to calling #psa_generator_read
* and passing the resulting output to #psa_import_key.
* However, this function has a security benefit:
* if the implementation provides an isolation boundary then
* the key material is not exposed outside the isolation boundary.
* As a consequence, for these key types, this function always consumes
* exactly (\p bits / 8) bytes from the generator.
* The following key types defined in this specification follow this scheme:
*
* - #PSA_KEY_TYPE_AES;
* - #PSA_KEY_TYPE_ARIA;
* - #PSA_KEY_TYPE_ARC4;
* - #PSA_KEY_TYPE_CAMELLIA;
* - #PSA_KEY_TYPE_CHACHAPOLY;
* - #PSA_KEY_TYPE_DERIVE;
* - #PSA_KEY_TYPE_HMAC.
*
* - For ECC keys on a Montgomery elliptic curve
* (#PSA_KEY_TYPE_ECC_KEYPAIR(\c curve) where \c curve designates a
* Montgomery curve), this function always draws a byte string whose
* length is determined by the curve, and sets the mandatory bits
* accordingly. That is:
*
* - #PSA_ECC_CURVE_CURVE25519: draw a 32-byte string
* and process it as specified in RFC 7748 §5.
* - #PSA_ECC_CURVE_CURVE448: draw a 56-byte string
* and process it as specified in RFC 7748 §5.
*
* - For key types for which the key is represented by a single sequence of
* \p bits bits with constraints as to which bit sequences are acceptable,
* this function draws a byte string of length (\p bits / 8) bytes rounded
* up to the nearest whole number of bytes. If the resulting byte string
* is acceptable, it becomes the key, otherwise the drawn bytes are discarded.
* This process is repeated until an acceptable byte string is drawn.
* The byte string drawn from the generator is interpreted as specified
* for the output produced by psa_export_key().
* The following key types defined in this specification follow this scheme:
*
* - #PSA_KEY_TYPE_DES.
* Force-set the parity bits, but discard forbidden weak keys.
* For 2-key and 3-key triple-DES, the three keys are generated
* successively (for example, for 3-key triple-DES,
* if the first 8 bytes specify a weak key and the next 8 bytes do not,
* discard the first 8 bytes, use the next 8 bytes as the first key,
* and continue reading output from the generator to derive the other
* two keys).
* - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEYPAIR),
* DSA keys (#PSA_KEY_TYPE_DSA_KEYPAIR), and
* ECC keys on a Weierstrass elliptic curve
* (#PSA_KEY_TYPE_ECC_KEYPAIR(\c curve) where \c curve designates a
* Weierstrass curve).
* For these key types, interpret the byte string as integer
* in big-endian order. Discard it if it is not in the range
* [0, *N* - 2] where *N* is the boundary of the private key domain
* (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
* or the order of the curve's coordinate field for ECC).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In case of ECC the boundary is the order of the curve's base point (here I use the term curve in the sense of the set of cryptographic domain parameters and not as a mathematical object, but I assume that is what we do throughout this documentation).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed. Fixed, thanks.

* Add 1 to the resulting integer and use this as the private key *x*.
* This is the method described as
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The method described in the standard is more relaxed in some cases (for example when generating DH keys the standard allows going for shorter private keys than the size of the prime). I think writing something like "This method allows for compliance with NIST and FIPS standards, see:" would be more accurate.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tweaked the wording.

* "key-pair generation by testing candidates"
* in NIST SP 800-56A §5.6.1.1.4 for Diffie-Hellman,
* in FIPS 186-4 §B.1.2 for DSA, and
* in NIST SP 800-56A §5.6.1.2.2 or
* FIPS 186-4 §B.4.2 for elliptic curve keys.
*
* - For other key types, including #PSA_KEY_TYPE_RSA_KEYPAIR,
* the way in which the generator output is consumed is
* implementation-defined.
*
* In all cases, the data that is read is discarded from the generator.
* The generator's capacity is decreased by the number of bytes read.
*
* \param handle Handle to the slot where the key will be stored.
* It must have been obtained by calling
* psa_allocate_key() or psa_create_key() and must
* not contain key material yet.
* \param type Key type (a \c PSA_KEY_TYPE_XXX value).
* This must be a symmetric key type.
* This must be a secret key type or a key pair type
* .
* \param bits Key size in bits.
* \param[in,out] generator The generator object to read from.
*
Expand All @@ -2906,12 +2972,10 @@ psa_status_t psa_generator_read(psa_crypto_generator_t *generator,
* If the key is persistent, the key material and the key's metadata
* have been saved to persistent storage.
* \retval #PSA_ERROR_INSUFFICIENT_CAPACITY
* There were fewer than \p output_length bytes
* in the generator. Note that in this case, no
* output is written to the output buffer.
* The generator's capacity is set to 0, thus
* subsequent calls to this function will not
* succeed, even with a smaller output buffer.
* There was not enough data to create the desired key.
* Note that in this case, no output is written to the output buffer.
* The generator's capacity is set to 0, thus subsequent calls to
* this function will not succeed, even with a smaller output buffer.
* \retval #PSA_ERROR_NOT_SUPPORTED
* The key type or key size is not supported, either by the
* implementation in general or in this particular slot.
Expand Down Expand Up @@ -3114,8 +3178,8 @@ psa_status_t psa_key_derivation_input_key(psa_crypto_generator_t *generator,
* psa_key_derivation_setup() with a
* key agreement and derivation algorithm
* \c alg (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_KEY_AGREEMENT(\p alg) is true
* and #PSA_ALG_IS_RAW_KEY_AGREEMENT(\p alg)
* #PSA_ALG_IS_KEY_AGREEMENT(\c alg) is true
* and #PSA_ALG_IS_RAW_KEY_AGREEMENT(\c alg)
* is false).
* The generator must be ready for an
* input of the type given by \p step.
Expand Down
2 changes: 1 addition & 1 deletion include/psa/crypto_extra.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ psa_status_t mbedtls_psa_inject_entropy(const unsigned char *seed,
* FIMXE This function is no longer part of the official API. Its prototype
* is only kept around for the sake of tests that haven't been updated yet.
*
* A key derivation algorithm takes three inputs: a secret input \p key and
* A key derivation algorithm takes three inputs: a secret input \p handle and
* two non-secret inputs \p label and p salt.
* The result of this function is a byte generator which can
* be used to produce keys and other cryptographic material.
Expand Down
Loading