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.
diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 45655dd..5016ba8 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -444,6 +444,147 @@
/**@}*/
+
+/** \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