mirror of
https://github.com/Mbed-TLS/mbedtls.git
synced 2025-08-08 17:42:09 +03:00
Remove domain parameters from the official API
Move psa_get_key_domain_parameters() and psa_set_key_domain_parameters() out of the official API and declare them to be implementation-specific extensions. Expand the documentation of psa_set_key_domain_parameters() a bit to explain how domain parameters are used. Remove all mentions of domain parameters from the documentation of API functions. This leaves DH and DSA effectively unusable.
This commit is contained in:
Gilles Peskine
@@ -444,6 +444,147 @@ psa_status_t psa_generate_random_key_to_handle(psa_key_handle_t handle,
|
||||
|
||||
/**@}*/
|
||||
|
||||
|
||||
/** \addtogroup attributes
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* \brief Set domain parameters for a key.
|
||||
*
|
||||
* Some key types require additional domain parameters in addition to
|
||||
* the key type identifier and the key size. Use this function instead
|
||||
* of psa_set_key_type() when you need to specify domain parameters.
|
||||
*
|
||||
* The format for the required domain parameters varies based on the key type.
|
||||
*
|
||||
* - For RSA keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY or #PSA_KEY_TYPE_RSA_KEYPAIR),
|
||||
* the domain parameter data consists of the public exponent,
|
||||
* represented as a big-endian integer with no leading zeros.
|
||||
* This information is used when generating an RSA key pair.
|
||||
* When importing a key, the public exponent is read from the imported
|
||||
* key data and the exponent recorded in the attribute structure is ignored.
|
||||
* As an exception, the public exponent 65537 is represented by an empty
|
||||
* byte string.
|
||||
* - For DSA keys (#PSA_KEY_TYPE_DSA_PUBLIC_KEY or #PSA_KEY_TYPE_DSA_KEYPAIR),
|
||||
* the `Dss-Parms` format as defined by RFC 3279 §2.3.2.
|
||||
* ```
|
||||
* Dss-Parms ::= SEQUENCE {
|
||||
* p INTEGER,
|
||||
* q INTEGER,
|
||||
* g INTEGER
|
||||
* }
|
||||
* ```
|
||||
* - For Diffie-Hellman key exchange keys (#PSA_KEY_TYPE_DH_PUBLIC_KEY or
|
||||
* #PSA_KEY_TYPE_DH_KEYPAIR), the
|
||||
* `DomainParameters` format as defined by RFC 3279 §2.3.3.
|
||||
* ```
|
||||
* DomainParameters ::= SEQUENCE {
|
||||
* p INTEGER, -- odd prime, p=jq +1
|
||||
* g INTEGER, -- generator, g
|
||||
* q INTEGER, -- factor of p-1
|
||||
* j INTEGER OPTIONAL, -- subgroup factor
|
||||
* validationParms ValidationParms OPTIONAL
|
||||
* }
|
||||
* ValidationParms ::= SEQUENCE {
|
||||
* seed BIT STRING,
|
||||
* pgenCounter INTEGER
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* \note This function may allocate memory or other resources.
|
||||
* Once you have called this function on an attribute structure,
|
||||
* you must call psa_reset_key_attributes() to free these resources.
|
||||
*
|
||||
* \note This is an experimental extension to the interface. It may change
|
||||
* in future versions of the library.
|
||||
*
|
||||
* \param[in,out] attributes Attribute structure where the specified domain
|
||||
* parameters will be stored.
|
||||
* If this function fails, the content of
|
||||
* \p attributes is not modified.
|
||||
* \param type Key type (a \c PSA_KEY_TYPE_XXX value).
|
||||
* \param[in] data Buffer containing the key domain parameters.
|
||||
* The content of this buffer is interpreted
|
||||
* according to \p type as described above.
|
||||
* \param data_length Size of the \p data buffer in bytes.
|
||||
*
|
||||
* \retval #PSA_SUCCESS
|
||||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||||
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||||
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
||||
*/
|
||||
psa_status_t psa_set_key_domain_parameters(psa_key_attributes_t *attributes,
|
||||
psa_key_type_t type,
|
||||
const uint8_t *data,
|
||||
size_t data_length);
|
||||
|
||||
/**
|
||||
* \brief Get domain parameters for a key.
|
||||
*
|
||||
* Get the domain parameters for a key with this function, if any. The format
|
||||
* of the domain parameters written to \p data is specified in the
|
||||
* documentation for psa_set_key_domain_parameters().
|
||||
*
|
||||
* \note This is an experimental extension to the interface. It may change
|
||||
* in future versions of the library.
|
||||
*
|
||||
* \param[in] attributes The key attribute structure to query.
|
||||
* \param[out] data On success, the key domain parameters.
|
||||
* \param data_size Size of the \p data buffer in bytes.
|
||||
* The buffer is guaranteed to be large
|
||||
* enough if its size in bytes is at least
|
||||
* the value given by
|
||||
* PSA_KEY_DOMAIN_PARAMETERS_SIZE().
|
||||
* \param[out] data_length On success, the number of bytes
|
||||
* that make up the key domain parameters data.
|
||||
*
|
||||
* \retval #PSA_SUCCESS
|
||||
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
||||
*/
|
||||
psa_status_t psa_get_key_domain_parameters(
|
||||
const psa_key_attributes_t *attributes,
|
||||
uint8_t *data,
|
||||
size_t data_size,
|
||||
size_t *data_length);
|
||||
|
||||
/** Safe output buffer size for psa_get_key_domain_parameters().
|
||||
*
|
||||
* This macro returns a compile-time constant if its arguments are
|
||||
* compile-time constants.
|
||||
*
|
||||
* \warning This function may call its arguments multiple times or
|
||||
* zero times, so you should not pass arguments that contain
|
||||
* side effects.
|
||||
*
|
||||
* \note This is an experimental extension to the interface. It may change
|
||||
* in future versions of the library.
|
||||
*
|
||||
* \param key_type A supported key type.
|
||||
* \param key_bits The size of the key in bits.
|
||||
*
|
||||
* \return If the parameters are valid and supported, return
|
||||
* a buffer size in bytes that guarantees that
|
||||
* psa_get_key_domain_parameters() will not fail with
|
||||
* #PSA_ERROR_BUFFER_TOO_SMALL.
|
||||
* If the parameters are a valid combination that is not supported
|
||||
* by the implementation, this macro either shall return either a
|
||||
* sensible size or 0.
|
||||
* If the parameters are not valid, the
|
||||
* return value is unspecified.
|
||||
*/
|
||||
#define PSA_KEY_DOMAIN_PARAMETERS_SIZE(key_type, key_bits) \
|
||||
(PSA_KEY_TYPE_IS_RSA(key_type) ? sizeof(int) : \
|
||||
PSA_KEY_TYPE_IS_DH(key_type) ? PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) : \
|
||||
PSA_KEY_TYPE_IS_DSA(key_type) ? PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) : \
|
||||
0)
|
||||
#define PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) \
|
||||
(4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 3 /*without optional parts*/)
|
||||
#define PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) \
|
||||
(4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 2 /*p, g*/ + 34 /*q*/)
|
||||
|
||||
/**@}*/
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
Reference in New Issue
Block a user