crypto_extra.h

00001 /**
00002  * \file psa/crypto_extra.h
00003  *
00004  * \brief PSA cryptography module: Mbed TLS vendor extensions
00005  *
00006  * \note This file may not be included directly. Applications must
00007  * include psa/crypto.h.
00008  *
00009  * This file is reserved for vendor-specific definitions.
00010  */
00011 /*
00012  *  Copyright (C) 2018, ARM Limited, All Rights Reserved
00013  *  SPDX-License-Identifier: Apache-2.0
00014  *
00015  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00016  *  not use this file except in compliance with the License.
00017  *  You may obtain a copy of the License at
00018  *
00019  *  http://www.apache.org/licenses/LICENSE-2.0
00020  *
00021  *  Unless required by applicable law or agreed to in writing, software
00022  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00023  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00024  *  See the License for the specific language governing permissions and
00025  *  limitations under the License.
00026  *
00027  *  This file is part of mbed TLS (https://tls.mbed.org)
00028  */
00029 
00030 #ifndef PSA_CRYPTO_EXTRA_H
00031 #define PSA_CRYPTO_EXTRA_H
00032 
00033 #include "mbedtls/platform_util.h"
00034 
00035 #ifdef __cplusplus
00036 extern "C" {
00037 #endif
00038 
00039 /* UID for secure storage seed */
00040 #define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52
00041 
00042 /*
00043  * Deprecated PSA Crypto error code definitions
00044  */
00045 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
00046 #define PSA_ERROR_UNKNOWN_ERROR \
00047     MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_GENERIC_ERROR )
00048 #define PSA_ERROR_OCCUPIED_SLOT \
00049     MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_ALREADY_EXISTS )
00050 #define PSA_ERROR_EMPTY_SLOT \
00051     MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_DOES_NOT_EXIST )
00052 #define PSA_ERROR_INSUFFICIENT_CAPACITY \
00053     MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_INSUFFICIENT_DATA )
00054 #define PSA_ERROR_TAMPERING_DETECTED \
00055     MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_CORRUPTION_DETECTED )
00056 #endif
00057 
00058 /** \addtogroup attributes
00059  * @{
00060  */
00061 
00062 /** \brief Declare the enrollment algorithm for a key.
00063  *
00064  * An operation on a key may indifferently use the algorithm set with
00065  * psa_set_key_algorithm() or with this function.
00066  *
00067  * \param[out] attributes       The attribute structure to write to.
00068  * \param alg2                  A second algorithm that the key may be used
00069  *                              for, in addition to the algorithm set with
00070  *                              psa_set_key_algorithm().
00071  *
00072  * \warning Setting an enrollment algorithm is not recommended, because
00073  *          using the same key with different algorithms can allow some
00074  *          attacks based on arithmetic relations between different
00075  *          computations made with the same key, or can escalate harmless
00076  *          side channels into exploitable ones. Use this function only
00077  *          if it is necessary to support a protocol for which it has been
00078  *          verified that the usage of the key with multiple algorithms
00079  *          is safe.
00080  */
00081 static inline void psa_set_key_enrollment_algorithm(
00082     psa_key_attributes_t *attributes,
00083     psa_algorithm_t alg2)
00084 {
00085     attributes->core.policy.alg2 = alg2;
00086 }
00087 
00088 /** Retrieve the enrollment algorithm policy from key attributes.
00089  *
00090  * \param[in] attributes        The key attribute structure to query.
00091  *
00092  * \return The enrollment algorithm stored in the attribute structure.
00093  */
00094 static inline psa_algorithm_t psa_get_key_enrollment_algorithm(
00095     const psa_key_attributes_t *attributes)
00096 {
00097     return( attributes->core.policy.alg2 );
00098 }
00099 
00100 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
00101 
00102 /** Retrieve the slot number where a key is stored.
00103  *
00104  * A slot number is only defined for keys that are stored in a secure
00105  * element.
00106  *
00107  * This information is only useful if the secure element is not entirely
00108  * managed through the PSA Cryptography API. It is up to the secure
00109  * element driver to decide how PSA slot numbers map to any other interface
00110  * that the secure element may have.
00111  *
00112  * \param[in] attributes        The key attribute structure to query.
00113  * \param[out] slot_number      On success, the slot number containing the key.
00114  *
00115  * \retval #PSA_SUCCESS
00116  *         The key is located in a secure element, and \p *slot_number
00117  *         indicates the slot number that contains it.
00118  * \retval #PSA_ERROR_NOT_PERMITTED
00119  *         The caller is not permitted to query the slot number.
00120  *         Mbed Crypto currently does not return this error.
00121  * \retval #PSA_ERROR_INVALID_ARGUMENT
00122  *         The key is not located in a secure element.
00123  */
00124 psa_status_t psa_get_key_slot_number(
00125     const psa_key_attributes_t *attributes,
00126     psa_key_slot_number_t *slot_number );
00127 
00128 /** Choose the slot number where a key is stored.
00129  *
00130  * This function declares a slot number in the specified attribute
00131  * structure.
00132  *
00133  * A slot number is only meaningful for keys that are stored in a secure
00134  * element. It is up to the secure element driver to decide how PSA slot
00135  * numbers map to any other interface that the secure element may have.
00136  *
00137  * \note Setting a slot number in key attributes for a key creation can
00138  *       cause the following errors when creating the key:
00139  *       - #PSA_ERROR_NOT_SUPPORTED if the selected secure element does
00140  *         not support choosing a specific slot number.
00141  *       - #PSA_ERROR_NOT_PERMITTED if the caller is not permitted to
00142  *         choose slot numbers in general or to choose this specific slot.
00143  *       - #PSA_ERROR_INVALID_ARGUMENT if the chosen slot number is not
00144  *         valid in general or not valid for this specific key.
00145  *       - #PSA_ERROR_ALREADY_EXISTS if there is already a key in the
00146  *         selected slot.
00147  *
00148  * \param[out] attributes       The attribute structure to write to.
00149  * \param slot_number           The slot number to set.
00150  */
00151 static inline void psa_set_key_slot_number(
00152     psa_key_attributes_t *attributes,
00153     psa_key_slot_number_t slot_number )
00154 {
00155     attributes->core.flags |= MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER;
00156     attributes->slot_number = slot_number;
00157 }
00158 
00159 /** Remove the slot number attribute from a key attribute structure.
00160  *
00161  * This function undoes the action of psa_set_key_slot_number().
00162  *
00163  * \param[out] attributes       The attribute structure to write to.
00164  */
00165 static inline void psa_clear_key_slot_number(
00166     psa_key_attributes_t *attributes )
00167 {
00168     attributes->core.flags &= ~MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER;
00169 }
00170 
00171 /** Register a key that is already present in a secure element.
00172  *
00173  * The key must be located in a secure element designated by the
00174  * lifetime field in \p attributes, in the slot set with
00175  * psa_set_key_slot_number() in the attribute structure.
00176  * This function makes the key available through the key identifier
00177  * specified in \p attributes.
00178  *
00179  * \param[in] attributes        The attributes of the existing key.
00180  *
00181  * \retval #PSA_SUCCESS
00182  *         The key was successfully registered.
00183  *         Note that depending on the design of the driver, this may or may
00184  *         not guarantee that a key actually exists in the designated slot
00185  *         and is compatible with the specified attributes.
00186  * \retval #PSA_ERROR_ALREADY_EXISTS
00187  *         There is already a key with the identifier specified in
00188  *         \p attributes.
00189  * \retval #PSA_ERROR_NOT_SUPPORTED
00190  *         The secure element driver for the specified lifetime does not
00191  *         support registering a key.
00192  * \retval #PSA_ERROR_INVALID_ARGUMENT
00193  *         \p attributes specifies a lifetime which is not located
00194  *         in a secure element.
00195  * \retval #PSA_ERROR_INVALID_ARGUMENT
00196  *         No slot number is specified in \p attributes,
00197  *         or the specified slot number is not valid.
00198  * \retval #PSA_ERROR_NOT_PERMITTED
00199  *         The caller is not authorized to register the specified key slot.
00200  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
00201  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
00202  * \retval #PSA_ERROR_HARDWARE_FAILURE
00203  * \retval #PSA_ERROR_CORRUPTION_DETECTED
00204  * \retval #PSA_ERROR_BAD_STATE
00205  *         The library has not been previously initialized by psa_crypto_init().
00206  *         It is implementation-dependent whether a failure to initialize
00207  *         results in this error code.
00208  */
00209 psa_status_t mbedtls_psa_register_se_key(
00210     const psa_key_attributes_t *attributes);
00211 
00212 #endif /* MBEDTLS_PSA_CRYPTO_SE_C */
00213 
00214 /**@}*/
00215 
00216 /**
00217  * \brief Library deinitialization.
00218  *
00219  * This function clears all data associated with the PSA layer,
00220  * including the whole key store.
00221  *
00222  * This is an Mbed TLS extension.
00223  */
00224 void mbedtls_psa_crypto_free( void );
00225 
00226 /** \brief Statistics about
00227  * resource consumption related to the PSA keystore.
00228  *
00229  * \note The content of this structure is not part of the stable API and ABI
00230  *       of Mbed Crypto and may change arbitrarily from version to version.
00231  */
00232 typedef struct mbedtls_psa_stats_s
00233 {
00234     /** Number of slots containing key material for a volatile key. */
00235     size_t volatile_slots;
00236     /** Number of slots containing key material for a key which is in
00237      * internal persistent storage. */
00238     size_t persistent_slots;
00239     /** Number of slots containing a reference to a key in a
00240      * secure element. */
00241     size_t external_slots;
00242     /** Number of slots which are occupied, but do not contain
00243      * key material yet. */
00244     size_t half_filled_slots;
00245     /** Number of slots that contain cache data. */
00246     size_t cache_slots;
00247     /** Number of slots that are not used for anything. */
00248     size_t empty_slots;
00249     /** Largest key id value among open keys in internal persistent storage. */
00250     psa_app_key_id_t max_open_internal_key_id;
00251     /** Largest key id value among open keys in secure elements. */
00252     psa_app_key_id_t max_open_external_key_id;
00253 } mbedtls_psa_stats_t;
00254 
00255 /** \brief Get statistics about
00256  * resource consumption related to the PSA keystore.
00257  *
00258  * \note When Mbed Crypto is built as part of a service, with isolation
00259  *       between the application and the keystore, the service may or
00260  *       may not expose this function.
00261  */
00262 void mbedtls_psa_get_stats( mbedtls_psa_stats_t *stats );
00263 
00264 /**
00265  * \brief Inject an initial entropy seed for the random generator into
00266  *        secure storage.
00267  *
00268  * This function injects data to be used as a seed for the random generator
00269  * used by the PSA Crypto implementation. On devices that lack a trusted
00270  * entropy source (preferably a hardware random number generator),
00271  * the Mbed PSA Crypto implementation uses this value to seed its
00272  * random generator.
00273  *
00274  * On devices without a trusted entropy source, this function must be
00275  * called exactly once in the lifetime of the device. On devices with
00276  * a trusted entropy source, calling this function is optional.
00277  * In all cases, this function may only be called before calling any
00278  * other function in the PSA Crypto API, including psa_crypto_init().
00279  *
00280  * When this function returns successfully, it populates a file in
00281  * persistent storage. Once the file has been created, this function
00282  * can no longer succeed.
00283  *
00284  * If any error occurs, this function does not change the system state.
00285  * You can call this function again after correcting the reason for the
00286  * error if possible.
00287  *
00288  * \warning This function **can** fail! Callers MUST check the return status.
00289  *
00290  * \warning If you use this function, you should use it as part of a
00291  *          factory provisioning process. The value of the injected seed
00292  *          is critical to the security of the device. It must be
00293  *          *secret*, *unpredictable* and (statistically) *unique per device*.
00294  *          You should be generate it randomly using a cryptographically
00295  *          secure random generator seeded from trusted entropy sources.
00296  *          You should transmit it securely to the device and ensure
00297  *          that its value is not leaked or stored anywhere beyond the
00298  *          needs of transmitting it from the point of generation to
00299  *          the call of this function, and erase all copies of the value
00300  *          once this function returns.
00301  *
00302  * This is an Mbed TLS extension.
00303  *
00304  * \note This function is only available on the following platforms:
00305  * * If the compile-time option MBEDTLS_PSA_INJECT_ENTROPY is enabled.
00306  *   Note that you must provide compatible implementations of
00307  *   mbedtls_nv_seed_read and mbedtls_nv_seed_write.
00308  * * In a client-server integration of PSA Cryptography, on the client side,
00309  *   if the server supports this feature.
00310  * \param[in] seed          Buffer containing the seed value to inject.
00311  * \param[in] seed_size     Size of the \p seed buffer.
00312  *                          The size of the seed in bytes must be greater
00313  *                          or equal to both #MBEDTLS_ENTROPY_MIN_PLATFORM
00314  *                          and #MBEDTLS_ENTROPY_BLOCK_SIZE.
00315  *                          It must be less or equal to
00316  *                          #MBEDTLS_ENTROPY_MAX_SEED_SIZE.
00317  *
00318  * \retval #PSA_SUCCESS
00319  *         The seed value was injected successfully. The random generator
00320  *         of the PSA Crypto implementation is now ready for use.
00321  *         You may now call psa_crypto_init() and use the PSA Crypto
00322  *         implementation.
00323  * \retval #PSA_ERROR_INVALID_ARGUMENT
00324  *         \p seed_size is out of range.
00325  * \retval #PSA_ERROR_STORAGE_FAILURE
00326  *         There was a failure reading or writing from storage.
00327  * \retval #PSA_ERROR_NOT_PERMITTED
00328  *         The library has already been initialized. It is no longer
00329  *         possible to call this function.
00330  */
00331 psa_status_t mbedtls_psa_inject_entropy(const uint8_t *seed,
00332                                         size_t seed_size);
00333 
00334 /** \addtogroup crypto_types
00335  * @{
00336  */
00337 
00338 /** DSA public key.
00339  *
00340  * The import and export format is the
00341  * representation of the public key `y = g^x mod p` as a big-endian byte
00342  * string. The length of the byte string is the length of the base prime `p`
00343  * in bytes.
00344  */
00345 #define PSA_KEY_TYPE_DSA_PUBLIC_KEY             ((psa_key_type_t)0x60020000)
00346 
00347 /** DSA key pair (private and public key).
00348  *
00349  * The import and export format is the
00350  * representation of the private key `x` as a big-endian byte string. The
00351  * length of the byte string is the private key size in bytes (leading zeroes
00352  * are not stripped).
00353  *
00354  * Determinstic DSA key derivation with psa_generate_derived_key follows
00355  * FIPS 186-4 §B.1.2: interpret the byte string as integer
00356  * in big-endian order. Discard it if it is not in the range
00357  * [0, *N* - 2] where *N* is the boundary of the private key domain
00358  * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
00359  * or the order of the curve's base point for ECC).
00360  * Add 1 to the resulting integer and use this as the private key *x*.
00361  *
00362  */
00363 #define PSA_KEY_TYPE_DSA_KEY_PAIR                ((psa_key_type_t)0x70020000)
00364 
00365 /** Whether a key type is an DSA key (pair or public-only). */
00366 #define PSA_KEY_TYPE_IS_DSA(type)                                       \
00367     (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY)
00368 
00369 #define PSA_ALG_DSA_BASE                        ((psa_algorithm_t)0x10040000)
00370 /** DSA signature with hashing.
00371  *
00372  * This is the signature scheme defined by FIPS 186-4,
00373  * with a random per-message secret number (*k*).
00374  *
00375  * \param hash_alg      A hash algorithm (\c PSA_ALG_XXX value such that
00376  *                      #PSA_ALG_IS_HASH(\p hash_alg) is true).
00377  *                      This includes #PSA_ALG_ANY_HASH
00378  *                      when specifying the algorithm in a usage policy.
00379  *
00380  * \return              The corresponding DSA signature algorithm.
00381  * \return              Unspecified if \p hash_alg is not a supported
00382  *                      hash algorithm.
00383  */
00384 #define PSA_ALG_DSA(hash_alg)                             \
00385     (PSA_ALG_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
00386 #define PSA_ALG_DETERMINISTIC_DSA_BASE          ((psa_algorithm_t)0x10050000)
00387 #define PSA_ALG_DSA_DETERMINISTIC_FLAG          ((psa_algorithm_t)0x00010000)
00388 /** Deterministic DSA signature with hashing.
00389  *
00390  * This is the deterministic variant defined by RFC 6979 of
00391  * the signature scheme defined by FIPS 186-4.
00392  *
00393  * \param hash_alg      A hash algorithm (\c PSA_ALG_XXX value such that
00394  *                      #PSA_ALG_IS_HASH(\p hash_alg) is true).
00395  *                      This includes #PSA_ALG_ANY_HASH
00396  *                      when specifying the algorithm in a usage policy.
00397  *
00398  * \return              The corresponding DSA signature algorithm.
00399  * \return              Unspecified if \p hash_alg is not a supported
00400  *                      hash algorithm.
00401  */
00402 #define PSA_ALG_DETERMINISTIC_DSA(hash_alg)                             \
00403     (PSA_ALG_DETERMINISTIC_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
00404 #define PSA_ALG_IS_DSA(alg)                                             \
00405     (((alg) & ~PSA_ALG_HASH_MASK & ~PSA_ALG_DSA_DETERMINISTIC_FLAG) ==  \
00406      PSA_ALG_DSA_BASE)
00407 #define PSA_ALG_DSA_IS_DETERMINISTIC(alg)               \
00408     (((alg) & PSA_ALG_DSA_DETERMINISTIC_FLAG) != 0)
00409 #define PSA_ALG_IS_DETERMINISTIC_DSA(alg)                       \
00410     (PSA_ALG_IS_DSA(alg) && PSA_ALG_DSA_IS_DETERMINISTIC(alg))
00411 #define PSA_ALG_IS_RANDOMIZED_DSA(alg)                          \
00412     (PSA_ALG_IS_DSA(alg) && !PSA_ALG_DSA_IS_DETERMINISTIC(alg))
00413 
00414 
00415 /* We need to expand the sample definition of this macro from
00416  * the API definition. */
00417 #undef PSA_ALG_IS_HASH_AND_SIGN
00418 #define PSA_ALG_IS_HASH_AND_SIGN(alg)                                   \
00419     (PSA_ALG_IS_RSA_PSS(alg) || PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) ||    \
00420      PSA_ALG_IS_DSA(alg) || PSA_ALG_IS_ECDSA(alg))
00421 
00422 /**@}*/
00423 
00424 /** \addtogroup attributes
00425  * @{
00426  */
00427 
00428 /** Custom Diffie-Hellman group.
00429  *
00430  * For keys of type #PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_GROUP_CUSTOM) or
00431  * #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_GROUP_CUSTOM), the group data comes
00432  * from domain parameters set by psa_set_key_domain_parameters().
00433  */
00434 /* This value is a deprecated value meaning an explicit curve in the IANA
00435  * registry. */
00436 #define PSA_DH_GROUP_CUSTOM             ((psa_dh_group_t) 0xff01)
00437 
00438 
00439 /**
00440  * \brief Set domain parameters for a key.
00441  *
00442  * Some key types require additional domain parameters in addition to
00443  * the key type identifier and the key size. Use this function instead
00444  * of psa_set_key_type() when you need to specify domain parameters.
00445  *
00446  * The format for the required domain parameters varies based on the key type.
00447  *
00448  * - For RSA keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY or #PSA_KEY_TYPE_RSA_KEY_PAIR),
00449  *   the domain parameter data consists of the public exponent,
00450  *   represented as a big-endian integer with no leading zeros.
00451  *   This information is used when generating an RSA key pair.
00452  *   When importing a key, the public exponent is read from the imported
00453  *   key data and the exponent recorded in the attribute structure is ignored.
00454  *   As an exception, the public exponent 65537 is represented by an empty
00455  *   byte string.
00456  * - For DSA keys (#PSA_KEY_TYPE_DSA_PUBLIC_KEY or #PSA_KEY_TYPE_DSA_KEY_PAIR),
00457  *   the `Dss-Parms` format as defined by RFC 3279 §2.3.2.
00458  *   ```
00459  *   Dss-Parms ::= SEQUENCE  {
00460  *      p       INTEGER,
00461  *      q       INTEGER,
00462  *      g       INTEGER
00463  *   }
00464  *   ```
00465  * - For Diffie-Hellman key exchange keys
00466  *   (#PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_GROUP_CUSTOM) or
00467  *   #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_GROUP_CUSTOM)), the
00468  *   `DomainParameters` format as defined by RFC 3279 §2.3.3.
00469  *   ```
00470  *   DomainParameters ::= SEQUENCE {
00471  *      p               INTEGER,                    -- odd prime, p=jq +1
00472  *      g               INTEGER,                    -- generator, g
00473  *      q               INTEGER,                    -- factor of p-1
00474  *      j               INTEGER OPTIONAL,           -- subgroup factor
00475  *      validationParms ValidationParms OPTIONAL
00476  *   }
00477  *   ValidationParms ::= SEQUENCE {
00478  *      seed            BIT STRING,
00479  *      pgenCounter     INTEGER
00480  *   }
00481  *   ```
00482  *
00483  * \note This function may allocate memory or other resources.
00484  *       Once you have called this function on an attribute structure,
00485  *       you must call psa_reset_key_attributes() to free these resources.
00486  *
00487  * \note This is an experimental extension to the interface. It may change
00488  *       in future versions of the library.
00489  *
00490  * \param[in,out] attributes    Attribute structure where the specified domain
00491  *                              parameters will be stored.
00492  *                              If this function fails, the content of
00493  *                              \p attributes is not modified.
00494  * \param type                  Key type (a \c PSA_KEY_TYPE_XXX value).
00495  * \param[in] data              Buffer containing the key domain parameters.
00496  *                              The content of this buffer is interpreted
00497  *                              according to \p type as described above.
00498  * \param data_length           Size of the \p data buffer in bytes.
00499  *
00500  * \retval #PSA_SUCCESS
00501  * \retval #PSA_ERROR_INVALID_ARGUMENT
00502  * \retval #PSA_ERROR_NOT_SUPPORTED
00503  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
00504  */
00505 psa_status_t psa_set_key_domain_parameters(psa_key_attributes_t *attributes,
00506                                            psa_key_type_t type,
00507                                            const uint8_t *data,
00508                                            size_t data_length);
00509 
00510 /**
00511  * \brief Get domain parameters for a key.
00512  *
00513  * Get the domain parameters for a key with this function, if any. The format
00514  * of the domain parameters written to \p data is specified in the
00515  * documentation for psa_set_key_domain_parameters().
00516  *
00517  * \note This is an experimental extension to the interface. It may change
00518  *       in future versions of the library.
00519  *
00520  * \param[in] attributes        The key attribute structure to query.
00521  * \param[out] data             On success, the key domain parameters.
00522  * \param data_size             Size of the \p data buffer in bytes.
00523  *                              The buffer is guaranteed to be large
00524  *                              enough if its size in bytes is at least
00525  *                              the value given by
00526  *                              PSA_KEY_DOMAIN_PARAMETERS_SIZE().
00527  * \param[out] data_length      On success, the number of bytes
00528  *                              that make up the key domain parameters data.
00529  *
00530  * \retval #PSA_SUCCESS
00531  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
00532  */
00533 psa_status_t psa_get_key_domain_parameters(
00534     const psa_key_attributes_t *attributes,
00535     uint8_t *data,
00536     size_t data_size,
00537     size_t *data_length);
00538 
00539 /** Safe output buffer size for psa_get_key_domain_parameters().
00540  *
00541  * This macro returns a compile-time constant if its arguments are
00542  * compile-time constants.
00543  *
00544  * \warning This function may call its arguments multiple times or
00545  *          zero times, so you should not pass arguments that contain
00546  *          side effects.
00547  *
00548  * \note This is an experimental extension to the interface. It may change
00549  *       in future versions of the library.
00550  *
00551  * \param key_type  A supported key type.
00552  * \param key_bits  The size of the key in bits.
00553  *
00554  * \return If the parameters are valid and supported, return
00555  *         a buffer size in bytes that guarantees that
00556  *         psa_get_key_domain_parameters() will not fail with
00557  *         #PSA_ERROR_BUFFER_TOO_SMALL.
00558  *         If the parameters are a valid combination that is not supported
00559  *         by the implementation, this macro shall return either a
00560  *         sensible size or 0.
00561  *         If the parameters are not valid, the
00562  *         return value is unspecified.
00563  */
00564 #define PSA_KEY_DOMAIN_PARAMETERS_SIZE(key_type, key_bits)              \
00565     (PSA_KEY_TYPE_IS_RSA(key_type) ? sizeof(int) :                      \
00566      PSA_KEY_TYPE_IS_DH(key_type) ? PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) : \
00567      PSA_KEY_TYPE_IS_DSA(key_type) ? PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) : \
00568      0)
00569 #define PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits)     \
00570     (4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 3 /*without optional parts*/)
00571 #define PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits)    \
00572     (4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 2 /*p, g*/ + 34 /*q*/)
00573 
00574 /**@}*/
00575 
00576 #ifdef __cplusplus
00577 }
00578 #endif
00579 
00580 #endif /* PSA_CRYPTO_EXTRA_H */