diff --git a/include/psa/crypto.h b/include/psa/crypto.h index b54585a7e..732bc2fad 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -1195,13 +1195,27 @@ typedef uint32_t psa_algorithm_t; * \brief Import a key in binary format. * * This function supports any output from psa_export_key(). Refer to the - * documentation of psa_export_key() for the format for each key type. + * documentation of psa_export_public_key() for the format of public keys + * and to the documentation of psa_export_key() for the format for + * other key types. + * + * This specification supports a single format for each key type. + * Implementations may support other formats as long as the standard + * format is supported. Implementations that support other formats + * should ensure that the formats are clearly unambiguous so as to + * minimize the risk that an invalid input is accidentally interpreted + * according to a different format. * * \param key Slot where the key will be stored. This must be a * valid slot for a key of the chosen type. It must * be unoccupied. - * \param type Key type (a \c PSA_KEY_TYPE_XXX value). - * \param[in] data Buffer containing the key data. + * \param type Key type (a \c PSA_KEY_TYPE_XXX value). On a successful + * import, the key slot will contain a key of this type. + * \param[in] data Buffer containing the key data. The content of this + * buffer is interpreted according to \p type. It must + * contain the format described in the documentation + * of psa_export_key() or psa_export_public_key() for + * the chosen type. * \param data_length Size of the \p data buffer in bytes. * * \retval #PSA_SUCCESS @@ -1300,10 +1314,10 @@ psa_status_t psa_get_key_information(psa_key_slot_t key, * The output of this function can be passed to psa_import_key() to * create an equivalent object. * - * If a key is created with psa_import_key() and then exported with - * this function, it is not guaranteed that the resulting data is - * identical: the implementation may choose a different representation - * of the same key if the format permits it. + * If the implementation of psa_import_key() supports other formats + * beyond the format specified here, the output from psa_export_key() + * must use the representation specified here, not the original + * representation. * * For standard key types, the output format is as follows: *