5ed8a0ec73
Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
1940 lines
82 KiB
C
1940 lines
82 KiB
C
/**
|
||
* \file psa/crypto_extra.h
|
||
*
|
||
* \brief PSA cryptography module: Mbed TLS vendor extensions
|
||
*
|
||
* \note This file may not be included directly. Applications must
|
||
* include psa/crypto.h.
|
||
*
|
||
* This file is reserved for vendor-specific definitions.
|
||
*/
|
||
/*
|
||
* Copyright The Mbed TLS Contributors
|
||
* SPDX-License-Identifier: Apache-2.0
|
||
*
|
||
* Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||
* not use this file except in compliance with the License.
|
||
* You may obtain a copy of the License at
|
||
*
|
||
* http://www.apache.org/licenses/LICENSE-2.0
|
||
*
|
||
* Unless required by applicable law or agreed to in writing, software
|
||
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
* See the License for the specific language governing permissions and
|
||
* limitations under the License.
|
||
*/
|
||
|
||
#ifndef PSA_CRYPTO_EXTRA_H
|
||
#define PSA_CRYPTO_EXTRA_H
|
||
#include "mbedtls/private_access.h"
|
||
|
||
#include "mbedtls/platform_util.h"
|
||
|
||
#include "crypto_types.h"
|
||
#include "crypto_compat.h"
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/* UID for secure storage seed */
|
||
#define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52
|
||
|
||
/* See mbedtls_config.h for definition */
|
||
#if !defined(MBEDTLS_PSA_KEY_SLOT_COUNT)
|
||
#define MBEDTLS_PSA_KEY_SLOT_COUNT 32
|
||
#endif
|
||
|
||
/** \addtogroup attributes
|
||
* @{
|
||
*/
|
||
|
||
/** \brief Declare the enrollment algorithm for a key.
|
||
*
|
||
* An operation on a key may indifferently use the algorithm set with
|
||
* psa_set_key_algorithm() or with this function.
|
||
*
|
||
* \param[out] attributes The attribute structure to write to.
|
||
* \param alg2 A second algorithm that the key may be used
|
||
* for, in addition to the algorithm set with
|
||
* psa_set_key_algorithm().
|
||
*
|
||
* \warning Setting an enrollment algorithm is not recommended, because
|
||
* using the same key with different algorithms can allow some
|
||
* attacks based on arithmetic relations between different
|
||
* computations made with the same key, or can escalate harmless
|
||
* side channels into exploitable ones. Use this function only
|
||
* if it is necessary to support a protocol for which it has been
|
||
* verified that the usage of the key with multiple algorithms
|
||
* is safe.
|
||
*/
|
||
static inline void psa_set_key_enrollment_algorithm(
|
||
psa_key_attributes_t *attributes,
|
||
psa_algorithm_t alg2)
|
||
{
|
||
attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg2) = alg2;
|
||
}
|
||
|
||
/** Retrieve the enrollment algorithm policy from key attributes.
|
||
*
|
||
* \param[in] attributes The key attribute structure to query.
|
||
*
|
||
* \return The enrollment algorithm stored in the attribute structure.
|
||
*/
|
||
static inline psa_algorithm_t psa_get_key_enrollment_algorithm(
|
||
const psa_key_attributes_t *attributes)
|
||
{
|
||
return( attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg2) );
|
||
}
|
||
|
||
#if defined(MBEDTLS_PSA_CRYPTO_SE_C)
|
||
|
||
/** Retrieve the slot number where a key is stored.
|
||
*
|
||
* A slot number is only defined for keys that are stored in a secure
|
||
* element.
|
||
*
|
||
* This information is only useful if the secure element is not entirely
|
||
* managed through the PSA Cryptography API. It is up to the secure
|
||
* element driver to decide how PSA slot numbers map to any other interface
|
||
* that the secure element may have.
|
||
*
|
||
* \param[in] attributes The key attribute structure to query.
|
||
* \param[out] slot_number On success, the slot number containing the key.
|
||
*
|
||
* \retval #PSA_SUCCESS
|
||
* The key is located in a secure element, and \p *slot_number
|
||
* indicates the slot number that contains it.
|
||
* \retval #PSA_ERROR_NOT_PERMITTED
|
||
* The caller is not permitted to query the slot number.
|
||
* Mbed Crypto currently does not return this error.
|
||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||
* The key is not located in a secure element.
|
||
*/
|
||
psa_status_t psa_get_key_slot_number(
|
||
const psa_key_attributes_t *attributes,
|
||
psa_key_slot_number_t *slot_number );
|
||
|
||
/** Choose the slot number where a key is stored.
|
||
*
|
||
* This function declares a slot number in the specified attribute
|
||
* structure.
|
||
*
|
||
* A slot number is only meaningful for keys that are stored in a secure
|
||
* element. It is up to the secure element driver to decide how PSA slot
|
||
* numbers map to any other interface that the secure element may have.
|
||
*
|
||
* \note Setting a slot number in key attributes for a key creation can
|
||
* cause the following errors when creating the key:
|
||
* - #PSA_ERROR_NOT_SUPPORTED if the selected secure element does
|
||
* not support choosing a specific slot number.
|
||
* - #PSA_ERROR_NOT_PERMITTED if the caller is not permitted to
|
||
* choose slot numbers in general or to choose this specific slot.
|
||
* - #PSA_ERROR_INVALID_ARGUMENT if the chosen slot number is not
|
||
* valid in general or not valid for this specific key.
|
||
* - #PSA_ERROR_ALREADY_EXISTS if there is already a key in the
|
||
* selected slot.
|
||
*
|
||
* \param[out] attributes The attribute structure to write to.
|
||
* \param slot_number The slot number to set.
|
||
*/
|
||
static inline void psa_set_key_slot_number(
|
||
psa_key_attributes_t *attributes,
|
||
psa_key_slot_number_t slot_number )
|
||
{
|
||
attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(flags) |= MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER;
|
||
attributes->MBEDTLS_PRIVATE(slot_number) = slot_number;
|
||
}
|
||
|
||
/** Remove the slot number attribute from a key attribute structure.
|
||
*
|
||
* This function undoes the action of psa_set_key_slot_number().
|
||
*
|
||
* \param[out] attributes The attribute structure to write to.
|
||
*/
|
||
static inline void psa_clear_key_slot_number(
|
||
psa_key_attributes_t *attributes )
|
||
{
|
||
attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(flags) &= ~MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER;
|
||
}
|
||
|
||
/** Register a key that is already present in a secure element.
|
||
*
|
||
* The key must be located in a secure element designated by the
|
||
* lifetime field in \p attributes, in the slot set with
|
||
* psa_set_key_slot_number() in the attribute structure.
|
||
* This function makes the key available through the key identifier
|
||
* specified in \p attributes.
|
||
*
|
||
* \param[in] attributes The attributes of the existing key.
|
||
*
|
||
* \retval #PSA_SUCCESS
|
||
* The key was successfully registered.
|
||
* Note that depending on the design of the driver, this may or may
|
||
* not guarantee that a key actually exists in the designated slot
|
||
* and is compatible with the specified attributes.
|
||
* \retval #PSA_ERROR_ALREADY_EXISTS
|
||
* There is already a key with the identifier specified in
|
||
* \p attributes.
|
||
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||
* The secure element driver for the specified lifetime does not
|
||
* support registering a key.
|
||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||
* The identifier in \p attributes is invalid, namely the identifier is
|
||
* not in the user range, or
|
||
* \p attributes specifies a lifetime which is not located
|
||
* in a secure element, or no slot number is specified in \p attributes,
|
||
* or the specified slot number is not valid.
|
||
* \retval #PSA_ERROR_NOT_PERMITTED
|
||
* The caller is not authorized to register the specified key slot.
|
||
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
||
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
|
||
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
||
* \retval #PSA_ERROR_DATA_INVALID
|
||
* \retval #PSA_ERROR_DATA_CORRUPT
|
||
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
||
* \retval #PSA_ERROR_BAD_STATE
|
||
* The library has not been previously initialized by psa_crypto_init().
|
||
* It is implementation-dependent whether a failure to initialize
|
||
* results in this error code.
|
||
*/
|
||
psa_status_t mbedtls_psa_register_se_key(
|
||
const psa_key_attributes_t *attributes);
|
||
|
||
#endif /* MBEDTLS_PSA_CRYPTO_SE_C */
|
||
|
||
/**@}*/
|
||
|
||
/**
|
||
* \brief Library deinitialization.
|
||
*
|
||
* This function clears all data associated with the PSA layer,
|
||
* including the whole key store.
|
||
*
|
||
* This is an Mbed TLS extension.
|
||
*/
|
||
void mbedtls_psa_crypto_free( void );
|
||
|
||
/** \brief Statistics about
|
||
* resource consumption related to the PSA keystore.
|
||
*
|
||
* \note The content of this structure is not part of the stable API and ABI
|
||
* of Mbed Crypto and may change arbitrarily from version to version.
|
||
*/
|
||
typedef struct mbedtls_psa_stats_s
|
||
{
|
||
/** Number of slots containing key material for a volatile key. */
|
||
size_t MBEDTLS_PRIVATE(volatile_slots);
|
||
/** Number of slots containing key material for a key which is in
|
||
* internal persistent storage. */
|
||
size_t MBEDTLS_PRIVATE(persistent_slots);
|
||
/** Number of slots containing a reference to a key in a
|
||
* secure element. */
|
||
size_t MBEDTLS_PRIVATE(external_slots);
|
||
/** Number of slots which are occupied, but do not contain
|
||
* key material yet. */
|
||
size_t MBEDTLS_PRIVATE(half_filled_slots);
|
||
/** Number of slots that contain cache data. */
|
||
size_t MBEDTLS_PRIVATE(cache_slots);
|
||
/** Number of slots that are not used for anything. */
|
||
size_t MBEDTLS_PRIVATE(empty_slots);
|
||
/** Number of slots that are locked. */
|
||
size_t MBEDTLS_PRIVATE(locked_slots);
|
||
/** Largest key id value among open keys in internal persistent storage. */
|
||
psa_key_id_t MBEDTLS_PRIVATE(max_open_internal_key_id);
|
||
/** Largest key id value among open keys in secure elements. */
|
||
psa_key_id_t MBEDTLS_PRIVATE(max_open_external_key_id);
|
||
} mbedtls_psa_stats_t;
|
||
|
||
/** \brief Get statistics about
|
||
* resource consumption related to the PSA keystore.
|
||
*
|
||
* \note When Mbed Crypto is built as part of a service, with isolation
|
||
* between the application and the keystore, the service may or
|
||
* may not expose this function.
|
||
*/
|
||
void mbedtls_psa_get_stats( mbedtls_psa_stats_t *stats );
|
||
|
||
/**
|
||
* \brief Inject an initial entropy seed for the random generator into
|
||
* secure storage.
|
||
*
|
||
* This function injects data to be used as a seed for the random generator
|
||
* used by the PSA Crypto implementation. On devices that lack a trusted
|
||
* entropy source (preferably a hardware random number generator),
|
||
* the Mbed PSA Crypto implementation uses this value to seed its
|
||
* random generator.
|
||
*
|
||
* On devices without a trusted entropy source, this function must be
|
||
* called exactly once in the lifetime of the device. On devices with
|
||
* a trusted entropy source, calling this function is optional.
|
||
* In all cases, this function may only be called before calling any
|
||
* other function in the PSA Crypto API, including psa_crypto_init().
|
||
*
|
||
* When this function returns successfully, it populates a file in
|
||
* persistent storage. Once the file has been created, this function
|
||
* can no longer succeed.
|
||
*
|
||
* If any error occurs, this function does not change the system state.
|
||
* You can call this function again after correcting the reason for the
|
||
* error if possible.
|
||
*
|
||
* \warning This function **can** fail! Callers MUST check the return status.
|
||
*
|
||
* \warning If you use this function, you should use it as part of a
|
||
* factory provisioning process. The value of the injected seed
|
||
* is critical to the security of the device. It must be
|
||
* *secret*, *unpredictable* and (statistically) *unique per device*.
|
||
* You should be generate it randomly using a cryptographically
|
||
* secure random generator seeded from trusted entropy sources.
|
||
* You should transmit it securely to the device and ensure
|
||
* that its value is not leaked or stored anywhere beyond the
|
||
* needs of transmitting it from the point of generation to
|
||
* the call of this function, and erase all copies of the value
|
||
* once this function returns.
|
||
*
|
||
* This is an Mbed TLS extension.
|
||
*
|
||
* \note This function is only available on the following platforms:
|
||
* * If the compile-time option MBEDTLS_PSA_INJECT_ENTROPY is enabled.
|
||
* Note that you must provide compatible implementations of
|
||
* mbedtls_nv_seed_read and mbedtls_nv_seed_write.
|
||
* * In a client-server integration of PSA Cryptography, on the client side,
|
||
* if the server supports this feature.
|
||
* \param[in] seed Buffer containing the seed value to inject.
|
||
* \param[in] seed_size Size of the \p seed buffer.
|
||
* The size of the seed in bytes must be greater
|
||
* or equal to both #MBEDTLS_ENTROPY_BLOCK_SIZE
|
||
* and the value of \c MBEDTLS_ENTROPY_MIN_PLATFORM
|
||
* in `library/entropy_poll.h` in the Mbed TLS source
|
||
* code.
|
||
* It must be less or equal to
|
||
* #MBEDTLS_ENTROPY_MAX_SEED_SIZE.
|
||
*
|
||
* \retval #PSA_SUCCESS
|
||
* The seed value was injected successfully. The random generator
|
||
* of the PSA Crypto implementation is now ready for use.
|
||
* You may now call psa_crypto_init() and use the PSA Crypto
|
||
* implementation.
|
||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||
* \p seed_size is out of range.
|
||
* \retval #PSA_ERROR_STORAGE_FAILURE
|
||
* There was a failure reading or writing from storage.
|
||
* \retval #PSA_ERROR_NOT_PERMITTED
|
||
* The library has already been initialized. It is no longer
|
||
* possible to call this function.
|
||
*/
|
||
psa_status_t mbedtls_psa_inject_entropy(const uint8_t *seed,
|
||
size_t seed_size);
|
||
|
||
/** \addtogroup crypto_types
|
||
* @{
|
||
*/
|
||
|
||
/** DSA public key.
|
||
*
|
||
* The import and export format is the
|
||
* representation of the public key `y = g^x mod p` as a big-endian byte
|
||
* string. The length of the byte string is the length of the base prime `p`
|
||
* in bytes.
|
||
*/
|
||
#define PSA_KEY_TYPE_DSA_PUBLIC_KEY ((psa_key_type_t)0x4002)
|
||
|
||
/** DSA key pair (private and public key).
|
||
*
|
||
* The import and export format is the
|
||
* representation of the private key `x` as a big-endian byte string. The
|
||
* length of the byte string is the private key size in bytes (leading zeroes
|
||
* are not stripped).
|
||
*
|
||
* Deterministic DSA key derivation with psa_generate_derived_key follows
|
||
* FIPS 186-4 §B.1.2: 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 base point for ECC).
|
||
* Add 1 to the resulting integer and use this as the private key *x*.
|
||
*
|
||
*/
|
||
#define PSA_KEY_TYPE_DSA_KEY_PAIR ((psa_key_type_t)0x7002)
|
||
|
||
/** Whether a key type is an DSA key (pair or public-only). */
|
||
#define PSA_KEY_TYPE_IS_DSA(type) \
|
||
(PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY)
|
||
|
||
#define PSA_ALG_DSA_BASE ((psa_algorithm_t)0x06000400)
|
||
/** DSA signature with hashing.
|
||
*
|
||
* This is the signature scheme defined by FIPS 186-4,
|
||
* with a random per-message secret number (*k*).
|
||
*
|
||
* \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
|
||
* #PSA_ALG_IS_HASH(\p hash_alg) is true).
|
||
* This includes #PSA_ALG_ANY_HASH
|
||
* when specifying the algorithm in a usage policy.
|
||
*
|
||
* \return The corresponding DSA signature algorithm.
|
||
* \return Unspecified if \p hash_alg is not a supported
|
||
* hash algorithm.
|
||
*/
|
||
#define PSA_ALG_DSA(hash_alg) \
|
||
(PSA_ALG_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
|
||
#define PSA_ALG_DETERMINISTIC_DSA_BASE ((psa_algorithm_t)0x06000500)
|
||
#define PSA_ALG_DSA_DETERMINISTIC_FLAG PSA_ALG_ECDSA_DETERMINISTIC_FLAG
|
||
/** Deterministic DSA signature with hashing.
|
||
*
|
||
* This is the deterministic variant defined by RFC 6979 of
|
||
* the signature scheme defined by FIPS 186-4.
|
||
*
|
||
* \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
|
||
* #PSA_ALG_IS_HASH(\p hash_alg) is true).
|
||
* This includes #PSA_ALG_ANY_HASH
|
||
* when specifying the algorithm in a usage policy.
|
||
*
|
||
* \return The corresponding DSA signature algorithm.
|
||
* \return Unspecified if \p hash_alg is not a supported
|
||
* hash algorithm.
|
||
*/
|
||
#define PSA_ALG_DETERMINISTIC_DSA(hash_alg) \
|
||
(PSA_ALG_DETERMINISTIC_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
|
||
#define PSA_ALG_IS_DSA(alg) \
|
||
(((alg) & ~PSA_ALG_HASH_MASK & ~PSA_ALG_DSA_DETERMINISTIC_FLAG) == \
|
||
PSA_ALG_DSA_BASE)
|
||
#define PSA_ALG_DSA_IS_DETERMINISTIC(alg) \
|
||
(((alg) & PSA_ALG_DSA_DETERMINISTIC_FLAG) != 0)
|
||
#define PSA_ALG_IS_DETERMINISTIC_DSA(alg) \
|
||
(PSA_ALG_IS_DSA(alg) && PSA_ALG_DSA_IS_DETERMINISTIC(alg))
|
||
#define PSA_ALG_IS_RANDOMIZED_DSA(alg) \
|
||
(PSA_ALG_IS_DSA(alg) && !PSA_ALG_DSA_IS_DETERMINISTIC(alg))
|
||
|
||
|
||
/* We need to expand the sample definition of this macro from
|
||
* the API definition. */
|
||
#undef PSA_ALG_IS_VENDOR_HASH_AND_SIGN
|
||
#define PSA_ALG_IS_VENDOR_HASH_AND_SIGN(alg) \
|
||
PSA_ALG_IS_DSA(alg)
|
||
|
||
/**@}*/
|
||
|
||
/** \addtogroup attributes
|
||
* @{
|
||
*/
|
||
|
||
/** Custom Diffie-Hellman group.
|
||
*
|
||
* For keys of type #PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_FAMILY_CUSTOM) or
|
||
* #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_FAMILY_CUSTOM), the group data comes
|
||
* from domain parameters set by psa_set_key_domain_parameters().
|
||
*/
|
||
#define PSA_DH_FAMILY_CUSTOM ((psa_dh_family_t) 0x7e)
|
||
|
||
|
||
/**
|
||
* \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_KEY_PAIR),
|
||
* 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_KEY_PAIR),
|
||
* the `Dss-Params` format as defined by RFC 3279 §2.3.2.
|
||
* ```
|
||
* Dss-Params ::= SEQUENCE {
|
||
* p INTEGER,
|
||
* q INTEGER,
|
||
* g INTEGER
|
||
* }
|
||
* ```
|
||
* - For Diffie-Hellman key exchange keys
|
||
* (#PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_FAMILY_CUSTOM) or
|
||
* #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_FAMILY_CUSTOM)), 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
|
||
* validationParams ValidationParams OPTIONAL
|
||
* }
|
||
* ValidationParams ::= 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 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*/)
|
||
|
||
/**@}*/
|
||
|
||
/** \defgroup psa_tls_helpers TLS helper functions
|
||
* @{
|
||
*/
|
||
|
||
#if defined(MBEDTLS_ECP_C)
|
||
#include <mbedtls/ecp.h>
|
||
|
||
/** Convert an ECC curve identifier from the Mbed TLS encoding to PSA.
|
||
*
|
||
* \note This function is provided solely for the convenience of
|
||
* Mbed TLS and may be removed at any time without notice.
|
||
*
|
||
* \param grpid An Mbed TLS elliptic curve identifier
|
||
* (`MBEDTLS_ECP_DP_xxx`).
|
||
* \param[out] bits On success, the bit size of the curve.
|
||
*
|
||
* \return The corresponding PSA elliptic curve identifier
|
||
* (`PSA_ECC_FAMILY_xxx`).
|
||
* \return \c 0 on failure (\p grpid is not recognized).
|
||
*/
|
||
static inline psa_ecc_family_t mbedtls_ecc_group_to_psa( mbedtls_ecp_group_id grpid,
|
||
size_t *bits )
|
||
{
|
||
switch( grpid )
|
||
{
|
||
case MBEDTLS_ECP_DP_SECP192R1:
|
||
*bits = 192;
|
||
return( PSA_ECC_FAMILY_SECP_R1 );
|
||
case MBEDTLS_ECP_DP_SECP224R1:
|
||
*bits = 224;
|
||
return( PSA_ECC_FAMILY_SECP_R1 );
|
||
case MBEDTLS_ECP_DP_SECP256R1:
|
||
*bits = 256;
|
||
return( PSA_ECC_FAMILY_SECP_R1 );
|
||
case MBEDTLS_ECP_DP_SECP384R1:
|
||
*bits = 384;
|
||
return( PSA_ECC_FAMILY_SECP_R1 );
|
||
case MBEDTLS_ECP_DP_SECP521R1:
|
||
*bits = 521;
|
||
return( PSA_ECC_FAMILY_SECP_R1 );
|
||
case MBEDTLS_ECP_DP_BP256R1:
|
||
*bits = 256;
|
||
return( PSA_ECC_FAMILY_BRAINPOOL_P_R1 );
|
||
case MBEDTLS_ECP_DP_BP384R1:
|
||
*bits = 384;
|
||
return( PSA_ECC_FAMILY_BRAINPOOL_P_R1 );
|
||
case MBEDTLS_ECP_DP_BP512R1:
|
||
*bits = 512;
|
||
return( PSA_ECC_FAMILY_BRAINPOOL_P_R1 );
|
||
case MBEDTLS_ECP_DP_CURVE25519:
|
||
*bits = 255;
|
||
return( PSA_ECC_FAMILY_MONTGOMERY );
|
||
case MBEDTLS_ECP_DP_SECP192K1:
|
||
*bits = 192;
|
||
return( PSA_ECC_FAMILY_SECP_K1 );
|
||
case MBEDTLS_ECP_DP_SECP224K1:
|
||
*bits = 224;
|
||
return( PSA_ECC_FAMILY_SECP_K1 );
|
||
case MBEDTLS_ECP_DP_SECP256K1:
|
||
*bits = 256;
|
||
return( PSA_ECC_FAMILY_SECP_K1 );
|
||
case MBEDTLS_ECP_DP_CURVE448:
|
||
*bits = 448;
|
||
return( PSA_ECC_FAMILY_MONTGOMERY );
|
||
default:
|
||
*bits = 0;
|
||
return( 0 );
|
||
}
|
||
}
|
||
|
||
/** Convert an ECC curve identifier from the PSA encoding to Mbed TLS.
|
||
*
|
||
* \note This function is provided solely for the convenience of
|
||
* Mbed TLS and may be removed at any time without notice.
|
||
*
|
||
* \param curve A PSA elliptic curve identifier
|
||
* (`PSA_ECC_FAMILY_xxx`).
|
||
* \param bits The bit-length of a private key on \p curve.
|
||
* \param bits_is_sloppy If true, \p bits may be the bit-length rounded up
|
||
* to the nearest multiple of 8. This allows the caller
|
||
* to infer the exact curve from the length of a key
|
||
* which is supplied as a byte string.
|
||
*
|
||
* \return The corresponding Mbed TLS elliptic curve identifier
|
||
* (`MBEDTLS_ECP_DP_xxx`).
|
||
* \return #MBEDTLS_ECP_DP_NONE if \c curve is not recognized.
|
||
* \return #MBEDTLS_ECP_DP_NONE if \p bits is not
|
||
* correct for \p curve.
|
||
*/
|
||
mbedtls_ecp_group_id mbedtls_ecc_group_of_psa( psa_ecc_family_t curve,
|
||
size_t bits,
|
||
int bits_is_sloppy );
|
||
#endif /* MBEDTLS_ECP_C */
|
||
|
||
/**@}*/
|
||
|
||
/** \defgroup psa_external_rng External random generator
|
||
* @{
|
||
*/
|
||
|
||
#if defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)
|
||
/** External random generator function, implemented by the platform.
|
||
*
|
||
* When the compile-time option #MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled,
|
||
* this function replaces Mbed TLS's entropy and DRBG modules for all
|
||
* random generation triggered via PSA crypto interfaces.
|
||
*
|
||
* \note This random generator must deliver random numbers with cryptographic
|
||
* quality and high performance. It must supply unpredictable numbers
|
||
* with a uniform distribution. The implementation of this function
|
||
* is responsible for ensuring that the random generator is seeded
|
||
* with sufficient entropy. If you have a hardware TRNG which is slow
|
||
* or delivers non-uniform output, declare it as an entropy source
|
||
* with mbedtls_entropy_add_source() instead of enabling this option.
|
||
*
|
||
* \param[in,out] context Pointer to the random generator context.
|
||
* This is all-bits-zero on the first call
|
||
* and preserved between successive calls.
|
||
* \param[out] output Output buffer. On success, this buffer
|
||
* contains random data with a uniform
|
||
* distribution.
|
||
* \param output_size The size of the \p output buffer in bytes.
|
||
* \param[out] output_length On success, set this value to \p output_size.
|
||
*
|
||
* \retval #PSA_SUCCESS
|
||
* Success. The output buffer contains \p output_size bytes of
|
||
* cryptographic-quality random data, and \c *output_length is
|
||
* set to \p output_size.
|
||
* \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
|
||
* The random generator requires extra entropy and there is no
|
||
* way to obtain entropy under current environment conditions.
|
||
* This error should not happen under normal circumstances since
|
||
* this function is responsible for obtaining as much entropy as
|
||
* it needs. However implementations of this function may return
|
||
* #PSA_ERROR_INSUFFICIENT_ENTROPY if there is no way to obtain
|
||
* entropy without blocking indefinitely.
|
||
* \retval #PSA_ERROR_HARDWARE_FAILURE
|
||
* A failure of the random generator hardware that isn't covered
|
||
* by #PSA_ERROR_INSUFFICIENT_ENTROPY.
|
||
*/
|
||
psa_status_t mbedtls_psa_external_get_random(
|
||
mbedtls_psa_external_random_context_t *context,
|
||
uint8_t *output, size_t output_size, size_t *output_length );
|
||
#endif /* MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG */
|
||
|
||
/**@}*/
|
||
|
||
/** \defgroup psa_builtin_keys Built-in keys
|
||
* @{
|
||
*/
|
||
|
||
/** The minimum value for a key identifier that is built into the
|
||
* implementation.
|
||
*
|
||
* The range of key identifiers from #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN
|
||
* to #MBEDTLS_PSA_KEY_ID_BUILTIN_MAX within the range from
|
||
* #PSA_KEY_ID_VENDOR_MIN and #PSA_KEY_ID_VENDOR_MAX and must not intersect
|
||
* with any other set of implementation-chosen key identifiers.
|
||
*
|
||
* This value is part of the library's ABI since changing it would invalidate
|
||
* the values of built-in key identifiers in applications.
|
||
*/
|
||
#define MBEDTLS_PSA_KEY_ID_BUILTIN_MIN ((psa_key_id_t)0x7fff0000)
|
||
|
||
/** The maximum value for a key identifier that is built into the
|
||
* implementation.
|
||
*
|
||
* See #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN for more information.
|
||
*/
|
||
#define MBEDTLS_PSA_KEY_ID_BUILTIN_MAX ((psa_key_id_t)0x7fffefff)
|
||
|
||
/** A slot number identifying a key in a driver.
|
||
*
|
||
* Values of this type are used to identify built-in keys.
|
||
*/
|
||
typedef uint64_t psa_drv_slot_number_t;
|
||
|
||
#if defined(MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS)
|
||
/** Test whether a key identifier belongs to the builtin key range.
|
||
*
|
||
* \param key_id Key identifier to test.
|
||
*
|
||
* \retval 1
|
||
* The key identifier is a builtin key identifier.
|
||
* \retval 0
|
||
* The key identifier is not a builtin key identifier.
|
||
*/
|
||
static inline int psa_key_id_is_builtin( psa_key_id_t key_id )
|
||
{
|
||
return( ( key_id >= MBEDTLS_PSA_KEY_ID_BUILTIN_MIN ) &&
|
||
( key_id <= MBEDTLS_PSA_KEY_ID_BUILTIN_MAX ) );
|
||
}
|
||
|
||
/** Platform function to obtain the location and slot number of a built-in key.
|
||
*
|
||
* An application-specific implementation of this function must be provided if
|
||
* #MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS is enabled. This would typically be provided
|
||
* as part of a platform's system image.
|
||
*
|
||
* #MBEDTLS_SVC_KEY_ID_GET_KEY_ID(\p key_id) needs to be in the range from
|
||
* #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN to #MBEDTLS_PSA_KEY_ID_BUILTIN_MAX.
|
||
*
|
||
* In a multi-application configuration
|
||
* (\c MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER is defined),
|
||
* this function should check that #MBEDTLS_SVC_KEY_ID_GET_OWNER_ID(\p key_id)
|
||
* is allowed to use the given key.
|
||
*
|
||
* \param key_id The key ID for which to retrieve the
|
||
* location and slot attributes.
|
||
* \param[out] lifetime On success, the lifetime associated with the key
|
||
* corresponding to \p key_id. Lifetime is a
|
||
* combination of which driver contains the key,
|
||
* and with what persistence level the key is
|
||
* intended to be used. If the platform
|
||
* implementation does not contain specific
|
||
* information about the intended key persistence
|
||
* level, the persistence level may be reported as
|
||
* #PSA_KEY_PERSISTENCE_DEFAULT.
|
||
* \param[out] slot_number On success, the slot number known to the driver
|
||
* registered at the lifetime location reported
|
||
* through \p lifetime which corresponds to the
|
||
* requested built-in key.
|
||
*
|
||
* \retval #PSA_SUCCESS
|
||
* The requested key identifier designates a built-in key.
|
||
* In a multi-application configuration, the requested owner
|
||
* is allowed to access it.
|
||
* \retval #PSA_ERROR_DOES_NOT_EXIST
|
||
* The requested key identifier is not a built-in key which is known
|
||
* to this function. If a key exists in the key storage with this
|
||
* identifier, the data from the storage will be used.
|
||
* \return (any other error)
|
||
* Any other error is propagated to the function that requested the key.
|
||
* Common errors include:
|
||
* - #PSA_ERROR_NOT_PERMITTED: the key exists but the requested owner
|
||
* is not allowed to access it.
|
||
*/
|
||
psa_status_t mbedtls_psa_platform_get_builtin_key(
|
||
mbedtls_svc_key_id_t key_id,
|
||
psa_key_lifetime_t *lifetime,
|
||
psa_drv_slot_number_t *slot_number );
|
||
#endif /* MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS */
|
||
|
||
/** @} */
|
||
|
||
/** \addtogroup crypto_types
|
||
* @{
|
||
*/
|
||
|
||
#define PSA_ALG_CATEGORY_PAKE ((psa_algorithm_t)0x0a000000)
|
||
|
||
/** Whether the specified algorithm is a password-authenticated key exchange.
|
||
*
|
||
* \param alg An algorithm identifier (value of type #psa_algorithm_t).
|
||
*
|
||
* \return 1 if \p alg is a password-authenticated key exchange (PAKE)
|
||
* algorithm, 0 otherwise.
|
||
* This macro may return either 0 or 1 if \p alg is not a supported
|
||
* algorithm identifier.
|
||
*/
|
||
#define PSA_ALG_IS_PAKE(alg) \
|
||
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_PAKE)
|
||
|
||
/** The Password-authenticated key exchange by juggling (J-PAKE) algorithm.
|
||
*
|
||
* This is J-PAKE as defined by RFC 8236, instantiated with the following
|
||
* parameters:
|
||
*
|
||
* - The group can be either an elliptic curve or defined over a finite field.
|
||
* - Schnorr NIZK proof as defined by RFC 8235 and using the same group as the
|
||
* J-PAKE algorithm.
|
||
* - A cryptographic hash function.
|
||
*
|
||
* To select these parameters and set up the cipher suite, call these functions
|
||
* in any order:
|
||
*
|
||
* \code
|
||
* psa_pake_cs_set_algorithm(cipher_suite, PSA_ALG_JPAKE);
|
||
* psa_pake_cs_set_primitive(cipher_suite,
|
||
* PSA_PAKE_PRIMITIVE(type, family, bits));
|
||
* psa_pake_cs_set_hash(cipher_suite, hash);
|
||
* \endcode
|
||
*
|
||
* For more information on how to set a specific curve or field, refer to the
|
||
* documentation of the individual \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
|
||
*
|
||
* After initializing a J-PAKE operation, call
|
||
*
|
||
* \code
|
||
* psa_pake_setup(operation, cipher_suite);
|
||
* psa_pake_set_user(operation, ...);
|
||
* psa_pake_set_peer(operation, ...);
|
||
* psa_pake_set_password_key(operation, ...);
|
||
* \endcode
|
||
*
|
||
* The password is provided as a key. This can be the password text itself,
|
||
* in an agreed character encoding, or some value derived from the password
|
||
* as required by a higher level protocol.
|
||
*
|
||
* (The implementation converts the key material to a number as described in
|
||
* Section 2.3.8 of _SEC 1: Elliptic Curve Cryptography_
|
||
* (https://www.secg.org/sec1-v2.pdf), before reducing it modulo \c q. Here
|
||
* \c q is order of the group defined by the primitive set in the cipher suite.
|
||
* The \c psa_pake_set_password_key() function returns an error if the result
|
||
* of the reduction is 0.)
|
||
*
|
||
* The key exchange flow for J-PAKE is as follows:
|
||
* -# To get the first round data that needs to be sent to the peer, call
|
||
* \code
|
||
* // Get g1
|
||
* psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
|
||
* // Get the ZKP public key for x1
|
||
* psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
|
||
* // Get the ZKP proof for x1
|
||
* psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
|
||
* // Get g2
|
||
* psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
|
||
* // Get the ZKP public key for x2
|
||
* psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
|
||
* // Get the ZKP proof for x2
|
||
* psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
|
||
* \endcode
|
||
* -# To provide the first round data received from the peer to the operation,
|
||
* call
|
||
* \code
|
||
* // Set g3
|
||
* psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
|
||
* // Set the ZKP public key for x3
|
||
* psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
|
||
* // Set the ZKP proof for x3
|
||
* psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
|
||
* // Set g4
|
||
* psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
|
||
* // Set the ZKP public key for x4
|
||
* psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
|
||
* // Set the ZKP proof for x4
|
||
* psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
|
||
* \endcode
|
||
* -# To get the second round data that needs to be sent to the peer, call
|
||
* \code
|
||
* // Get A
|
||
* psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
|
||
* // Get ZKP public key for x2*s
|
||
* psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
|
||
* // Get ZKP proof for x2*s
|
||
* psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
|
||
* \endcode
|
||
* -# To provide the second round data received from the peer to the operation,
|
||
* call
|
||
* \code
|
||
* // Set B
|
||
* psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
|
||
* // Set ZKP public key for x4*s
|
||
* psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
|
||
* // Set ZKP proof for x4*s
|
||
* psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
|
||
* \endcode
|
||
* -# To access the shared secret call
|
||
* \code
|
||
* // Get Ka=Kb=K
|
||
* psa_pake_get_implicit_key()
|
||
* \endcode
|
||
*
|
||
* For more information consult the documentation of the individual
|
||
* \c PSA_PAKE_STEP_XXX constants.
|
||
*
|
||
* At this point there is a cryptographic guarantee that only the authenticated
|
||
* party who used the same password is able to compute the key. But there is no
|
||
* guarantee that the peer is the party it claims to be and was able to do so.
|
||
*
|
||
* That is, the authentication is only implicit (the peer is not authenticated
|
||
* at this point, and no action should be taken that assume that they are - like
|
||
* for example accessing restricted files).
|
||
*
|
||
* To make the authentication explicit there are various methods, see Section 5
|
||
* of RFC 8236 for two examples.
|
||
*
|
||
*/
|
||
#define PSA_ALG_JPAKE ((psa_algorithm_t)0x0a000100)
|
||
|
||
/** @} */
|
||
|
||
/** \defgroup pake Password-authenticated key exchange (PAKE)
|
||
*
|
||
* This is a proposed PAKE interface for the PSA Crypto API. It is not part of
|
||
* the official PSA Crypto API yet.
|
||
*
|
||
* \note The content of this section is not part of the stable API and ABI
|
||
* of Mbed Crypto and may change arbitrarily from version to version.
|
||
* Same holds for the corresponding macros #PSA_ALG_CATEGORY_PAKE and
|
||
* #PSA_ALG_JPAKE.
|
||
* @{
|
||
*/
|
||
|
||
/** \brief Encoding of the application role of PAKE
|
||
*
|
||
* Encodes the application's role in the algorithm is being executed. For more
|
||
* information see the documentation of individual \c PSA_PAKE_ROLE_XXX
|
||
* constants.
|
||
*/
|
||
typedef uint8_t psa_pake_role_t;
|
||
|
||
/** Encoding of input and output indicators for PAKE.
|
||
*
|
||
* Some PAKE algorithms need to exchange more data than just a single key share.
|
||
* This type is for encoding additional input and output data for such
|
||
* algorithms.
|
||
*/
|
||
typedef uint8_t psa_pake_step_t;
|
||
|
||
/** Encoding of the type of the PAKE's primitive.
|
||
*
|
||
* Values defined by this standard will never be in the range 0x80-0xff.
|
||
* Vendors who define additional types must use an encoding in this range.
|
||
*
|
||
* For more information see the documentation of individual
|
||
* \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
|
||
*/
|
||
typedef uint8_t psa_pake_primitive_type_t;
|
||
|
||
/** \brief Encoding of the family of the primitive associated with the PAKE.
|
||
*
|
||
* For more information see the documentation of individual
|
||
* \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
|
||
*/
|
||
typedef uint8_t psa_pake_family_t;
|
||
|
||
/** \brief Encoding of the primitive associated with the PAKE.
|
||
*
|
||
* For more information see the documentation of the #PSA_PAKE_PRIMITIVE macro.
|
||
*/
|
||
typedef uint32_t psa_pake_primitive_t;
|
||
|
||
/** A value to indicate no role in a PAKE algorithm.
|
||
* This value can be used in a call to psa_pake_set_role() for symmetric PAKE
|
||
* algorithms which do not assign roles.
|
||
*/
|
||
#define PSA_PAKE_ROLE_NONE ((psa_pake_role_t)0x00)
|
||
|
||
/** The first peer in a balanced PAKE.
|
||
*
|
||
* Although balanced PAKE algorithms are symmetric, some of them needs an
|
||
* ordering of peers for the transcript calculations. If the algorithm does not
|
||
* need this, both #PSA_PAKE_ROLE_FIRST and #PSA_PAKE_ROLE_SECOND are
|
||
* accepted.
|
||
*/
|
||
#define PSA_PAKE_ROLE_FIRST ((psa_pake_role_t)0x01)
|
||
|
||
/** The second peer in a balanced PAKE.
|
||
*
|
||
* Although balanced PAKE algorithms are symmetric, some of them needs an
|
||
* ordering of peers for the transcript calculations. If the algorithm does not
|
||
* need this, either #PSA_PAKE_ROLE_FIRST or #PSA_PAKE_ROLE_SECOND are
|
||
* accepted.
|
||
*/
|
||
#define PSA_PAKE_ROLE_SECOND ((psa_pake_role_t)0x02)
|
||
|
||
/** The client in an augmented PAKE.
|
||
*
|
||
* Augmented PAKE algorithms need to differentiate between client and server.
|
||
*/
|
||
#define PSA_PAKE_ROLE_CLIENT ((psa_pake_role_t)0x11)
|
||
|
||
/** The server in an augmented PAKE.
|
||
*
|
||
* Augmented PAKE algorithms need to differentiate between client and server.
|
||
*/
|
||
#define PSA_PAKE_ROLE_SERVER ((psa_pake_role_t)0x12)
|
||
|
||
/** The PAKE primitive type indicating the use of elliptic curves.
|
||
*
|
||
* The values of the \c family and \c bits fields of the cipher suite identify a
|
||
* specific elliptic curve, using the same mapping that is used for ECC
|
||
* (::psa_ecc_family_t) keys.
|
||
*
|
||
* (Here \c family means the value returned by psa_pake_cs_get_family() and
|
||
* \c bits means the value returned by psa_pake_cs_get_bits().)
|
||
*
|
||
* Input and output during the operation can involve group elements and scalar
|
||
* values:
|
||
* -# The format for group elements is the same as for public keys on the
|
||
* specific curve would be. For more information, consult the documentation of
|
||
* psa_export_public_key().
|
||
* -# The format for scalars is the same as for private keys on the specific
|
||
* curve would be. For more information, consult the documentation of
|
||
* psa_export_key().
|
||
*/
|
||
#define PSA_PAKE_PRIMITIVE_TYPE_ECC ((psa_pake_primitive_type_t)0x01)
|
||
|
||
/** The PAKE primitive type indicating the use of Diffie-Hellman groups.
|
||
*
|
||
* The values of the \c family and \c bits fields of the cipher suite identify
|
||
* a specific Diffie-Hellman group, using the same mapping that is used for
|
||
* Diffie-Hellman (::psa_dh_family_t) keys.
|
||
*
|
||
* (Here \c family means the value returned by psa_pake_cs_get_family() and
|
||
* \c bits means the value returned by psa_pake_cs_get_bits().)
|
||
*
|
||
* Input and output during the operation can involve group elements and scalar
|
||
* values:
|
||
* -# The format for group elements is the same as for public keys on the
|
||
* specific group would be. For more information, consult the documentation of
|
||
* psa_export_public_key().
|
||
* -# The format for scalars is the same as for private keys on the specific
|
||
* group would be. For more information, consult the documentation of
|
||
* psa_export_key().
|
||
*/
|
||
#define PSA_PAKE_PRIMITIVE_TYPE_DH ((psa_pake_primitive_type_t)0x02)
|
||
|
||
/** Construct a PAKE primitive from type, family and bit-size.
|
||
*
|
||
* \param pake_type The type of the primitive
|
||
* (value of type ::psa_pake_primitive_type_t).
|
||
* \param pake_family The family of the primitive
|
||
* (the type and interpretation of this parameter depends
|
||
* on \p type, for more information consult the
|
||
* documentation of individual ::psa_pake_primitive_type_t
|
||
* constants).
|
||
* \param pake_bits The bit-size of the primitive
|
||
* (Value of type \c size_t. The interpretation
|
||
* of this parameter depends on \p family, for more
|
||
* information consult the documentation of individual
|
||
* ::psa_pake_primitive_type_t constants).
|
||
*
|
||
* \return The constructed primitive value of type ::psa_pake_primitive_t.
|
||
* Return 0 if the requested primitive can't be encoded as
|
||
* ::psa_pake_primitive_t.
|
||
*/
|
||
#define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits) \
|
||
((pake_bits & 0xFFFF) != pake_bits) ? 0 : \
|
||
((psa_pake_primitive_t) (((pake_type) << 24 | \
|
||
(pake_family) << 16) | (pake_bits)))
|
||
|
||
/** The key share being sent to or received from the peer.
|
||
*
|
||
* The format for both input and output at this step is the same as for public
|
||
* keys on the group determined by the primitive (::psa_pake_primitive_t) would
|
||
* be.
|
||
*
|
||
* For more information on the format, consult the documentation of
|
||
* psa_export_public_key().
|
||
*
|
||
* For information regarding how the group is determined, consult the
|
||
* documentation #PSA_PAKE_PRIMITIVE.
|
||
*/
|
||
#define PSA_PAKE_STEP_KEY_SHARE ((psa_pake_step_t)0x01)
|
||
|
||
/** A Schnorr NIZKP public key.
|
||
*
|
||
* This is the ephemeral public key in the Schnorr Non-Interactive
|
||
* Zero-Knowledge Proof (the value denoted by the letter 'V' in RFC 8235).
|
||
*
|
||
* The format for both input and output at this step is the same as for public
|
||
* keys on the group determined by the primitive (::psa_pake_primitive_t) would
|
||
* be.
|
||
*
|
||
* For more information on the format, consult the documentation of
|
||
* psa_export_public_key().
|
||
*
|
||
* For information regarding how the group is determined, consult the
|
||
* documentation #PSA_PAKE_PRIMITIVE.
|
||
*/
|
||
#define PSA_PAKE_STEP_ZK_PUBLIC ((psa_pake_step_t)0x02)
|
||
|
||
/** A Schnorr NIZKP proof.
|
||
*
|
||
* This is the proof in the Schnorr Non-Interactive Zero-Knowledge Proof (the
|
||
* value denoted by the letter 'r' in RFC 8235).
|
||
*
|
||
* Both for input and output, the value at this step is an integer less than
|
||
* the order of the group selected in the cipher suite. The format depends on
|
||
* the group as well:
|
||
*
|
||
* - For Montgomery curves, the encoding is little endian.
|
||
* - For everything else the encoding is big endian (see Section 2.3.8 of
|
||
* _SEC 1: Elliptic Curve Cryptography_ at https://www.secg.org/sec1-v2.pdf).
|
||
*
|
||
* In both cases leading zeroes are allowed as long as the length in bytes does
|
||
* not exceed the byte length of the group order.
|
||
*
|
||
* For information regarding how the group is determined, consult the
|
||
* documentation #PSA_PAKE_PRIMITIVE.
|
||
*/
|
||
#define PSA_PAKE_STEP_ZK_PROOF ((psa_pake_step_t)0x03)
|
||
|
||
/** The type of the data structure for PAKE cipher suites.
|
||
*
|
||
* This is an implementation-defined \c struct. Applications should not
|
||
* make any assumptions about the content of this structure.
|
||
* Implementation details can change in future versions without notice.
|
||
*/
|
||
typedef struct psa_pake_cipher_suite_s psa_pake_cipher_suite_t;
|
||
|
||
/** Return an initial value for a PAKE cipher suite object.
|
||
*/
|
||
static psa_pake_cipher_suite_t psa_pake_cipher_suite_init( void );
|
||
|
||
/** Retrieve the PAKE algorithm from a PAKE cipher suite.
|
||
*
|
||
* This function may be declared as `static` (i.e. without external
|
||
* linkage). This function may be provided as a function-like macro,
|
||
* but in this case it must evaluate its argument exactly once.
|
||
*
|
||
* \param[in] cipher_suite The cipher suite structure to query.
|
||
*
|
||
* \return The PAKE algorithm stored in the cipher suite structure.
|
||
*/
|
||
static psa_algorithm_t psa_pake_cs_get_algorithm(
|
||
const psa_pake_cipher_suite_t *cipher_suite );
|
||
|
||
/** Declare the PAKE algorithm for the cipher suite.
|
||
*
|
||
* This function overwrites any PAKE algorithm
|
||
* previously set in \p cipher_suite.
|
||
*
|
||
* This function may be declared as `static` (i.e. without external
|
||
* linkage). This function may be provided as a function-like macro,
|
||
* but in this case it must evaluate each of its arguments exactly once.
|
||
*
|
||
* \param[out] cipher_suite The cipher suite structure to write to.
|
||
* \param algorithm The PAKE algorithm to write.
|
||
* (`PSA_ALG_XXX` values of type ::psa_algorithm_t
|
||
* such that #PSA_ALG_IS_PAKE(\c alg) is true.)
|
||
* If this is 0, the PAKE algorithm in
|
||
* \p cipher_suite becomes unspecified.
|
||
*/
|
||
static void psa_pake_cs_set_algorithm( psa_pake_cipher_suite_t *cipher_suite,
|
||
psa_algorithm_t algorithm );
|
||
|
||
/** Retrieve the primitive from a PAKE cipher suite.
|
||
*
|
||
* This function may be declared as `static` (i.e. without external linkage).
|
||
* This function may be provided as a function-like macro, but in this case it
|
||
* must evaluate its argument exactly once.
|
||
*
|
||
* \param[in] cipher_suite The cipher suite structure to query.
|
||
*
|
||
* \return The primitive stored in the cipher suite structure.
|
||
*/
|
||
static psa_pake_primitive_t psa_pake_cs_get_primitive(
|
||
const psa_pake_cipher_suite_t *cipher_suite );
|
||
|
||
/** Declare the primitive for a PAKE cipher suite.
|
||
*
|
||
* This function overwrites any primitive previously set in \p cipher_suite.
|
||
*
|
||
* This function may be declared as `static` (i.e. without external
|
||
* linkage). This function may be provided as a function-like macro,
|
||
* but in this case it must evaluate each of its arguments exactly once.
|
||
*
|
||
* \param[out] cipher_suite The cipher suite structure to write to.
|
||
* \param primitive The primitive to write. If this is 0, the
|
||
* primitive type in \p cipher_suite becomes
|
||
* unspecified.
|
||
*/
|
||
static void psa_pake_cs_set_primitive( psa_pake_cipher_suite_t *cipher_suite,
|
||
psa_pake_primitive_t primitive );
|
||
|
||
/** Retrieve the PAKE family from a PAKE cipher suite.
|
||
*
|
||
* This function may be declared as `static` (i.e. without external
|
||
* linkage). This function may be provided as a function-like macro,
|
||
* but in this case it must evaluate its argument exactly once.
|
||
*
|
||
* \param[in] cipher_suite The cipher suite structure to query.
|
||
*
|
||
* \return The PAKE family stored in the cipher suite structure.
|
||
*/
|
||
static psa_pake_family_t psa_pake_cs_get_family(
|
||
const psa_pake_cipher_suite_t *cipher_suite );
|
||
|
||
/** Retrieve the PAKE primitive bit-size from a PAKE cipher suite.
|
||
*
|
||
* This function may be declared as `static` (i.e. without external
|
||
* linkage). This function may be provided as a function-like macro,
|
||
* but in this case it must evaluate its argument exactly once.
|
||
*
|
||
* \param[in] cipher_suite The cipher suite structure to query.
|
||
*
|
||
* \return The PAKE primitive bit-size stored in the cipher suite structure.
|
||
*/
|
||
static uint16_t psa_pake_cs_get_bits(
|
||
const psa_pake_cipher_suite_t *cipher_suite );
|
||
|
||
/** Retrieve the hash algorithm from a PAKE cipher suite.
|
||
*
|
||
* This function may be declared as `static` (i.e. without external
|
||
* linkage). This function may be provided as a function-like macro,
|
||
* but in this case it must evaluate its argument exactly once.
|
||
*
|
||
* \param[in] cipher_suite The cipher suite structure to query.
|
||
*
|
||
* \return The hash algorithm stored in the cipher suite structure. The return
|
||
* value is 0 if the PAKE is not parametrised by a hash algorithm or if
|
||
* the hash algorithm is not set.
|
||
*/
|
||
static psa_algorithm_t psa_pake_cs_get_hash(
|
||
const psa_pake_cipher_suite_t *cipher_suite );
|
||
|
||
/** Declare the hash algorithm for a PAKE cipher suite.
|
||
*
|
||
* This function overwrites any hash algorithm
|
||
* previously set in \p cipher_suite.
|
||
*
|
||
* This function may be declared as `static` (i.e. without external
|
||
* linkage). This function may be provided as a function-like macro,
|
||
* but in this case it must evaluate each of its arguments exactly once.
|
||
*
|
||
* Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
|
||
* values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
|
||
* for more information.
|
||
*
|
||
* \param[out] cipher_suite The cipher suite structure to write to.
|
||
* \param hash The hash involved in the cipher suite.
|
||
* (`PSA_ALG_XXX` values of type ::psa_algorithm_t
|
||
* such that #PSA_ALG_IS_HASH(\c alg) is true.)
|
||
* If this is 0, the hash algorithm in
|
||
* \p cipher_suite becomes unspecified.
|
||
*/
|
||
static void psa_pake_cs_set_hash( psa_pake_cipher_suite_t *cipher_suite,
|
||
psa_algorithm_t hash );
|
||
|
||
/** The type of the state data structure for PAKE operations.
|
||
*
|
||
* Before calling any function on a PAKE operation object, the application
|
||
* must initialize it by any of the following means:
|
||
* - Set the structure to all-bits-zero, for example:
|
||
* \code
|
||
* psa_pake_operation_t operation;
|
||
* memset(&operation, 0, sizeof(operation));
|
||
* \endcode
|
||
* - Initialize the structure to logical zero values, for example:
|
||
* \code
|
||
* psa_pake_operation_t operation = {0};
|
||
* \endcode
|
||
* - Initialize the structure to the initializer #PSA_PAKE_OPERATION_INIT,
|
||
* for example:
|
||
* \code
|
||
* psa_pake_operation_t operation = PSA_PAKE_OPERATION_INIT;
|
||
* \endcode
|
||
* - Assign the result of the function psa_pake_operation_init()
|
||
* to the structure, for example:
|
||
* \code
|
||
* psa_pake_operation_t operation;
|
||
* operation = psa_pake_operation_init();
|
||
* \endcode
|
||
*
|
||
* This is an implementation-defined \c struct. Applications should not
|
||
* make any assumptions about the content of this structure.
|
||
* Implementation details can change in future versions without notice. */
|
||
typedef struct psa_pake_operation_s psa_pake_operation_t;
|
||
|
||
/** Return an initial value for an PAKE operation object.
|
||
*/
|
||
static psa_pake_operation_t psa_pake_operation_init( void );
|
||
|
||
/** Set the session information for a password-authenticated key exchange.
|
||
*
|
||
* The sequence of operations to set up a password-authenticated key exchange
|
||
* is as follows:
|
||
* -# Allocate an operation object which will be passed to all the functions
|
||
* listed here.
|
||
* -# Initialize the operation object with one of the methods described in the
|
||
* documentation for #psa_pake_operation_t, e.g.
|
||
* #PSA_PAKE_OPERATION_INIT.
|
||
* -# Call psa_pake_setup() to specify the cipher suite.
|
||
* -# Call \c psa_pake_set_xxx() functions on the operation to complete the
|
||
* setup. The exact sequence of \c psa_pake_set_xxx() functions that needs
|
||
* to be called depends on the algorithm in use.
|
||
*
|
||
* Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
|
||
* values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
|
||
* for more information.
|
||
*
|
||
* A typical sequence of calls to perform a password-authenticated key
|
||
* exchange:
|
||
* -# Call psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...) to get the
|
||
* key share that needs to be sent to the peer.
|
||
* -# Call psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...) to provide
|
||
* the key share that was received from the peer.
|
||
* -# Depending on the algorithm additional calls to psa_pake_output() and
|
||
* psa_pake_input() might be necessary.
|
||
* -# Call psa_pake_get_implicit_key() for accessing the shared secret.
|
||
*
|
||
* Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
|
||
* values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
|
||
* for more information.
|
||
*
|
||
* If an error occurs at any step after a call to psa_pake_setup(),
|
||
* the operation will need to be reset by a call to psa_pake_abort(). The
|
||
* application may call psa_pake_abort() at any time after the operation
|
||
* has been initialized.
|
||
*
|
||
* After a successful call to psa_pake_setup(), the application must
|
||
* eventually terminate the operation. The following events terminate an
|
||
* operation:
|
||
* - A call to psa_pake_abort().
|
||
* - A successful call to psa_pake_get_implicit_key().
|
||
*
|
||
* \param[in,out] operation The operation object to set up. It must have
|
||
* been initialized but not set up yet.
|
||
* \param[in] cipher_suite The cipher suite to use. (A cipher suite fully
|
||
* characterizes a PAKE algorithm and determines
|
||
* the algorithm as well.)
|
||
*
|
||
* \retval #PSA_SUCCESS
|
||
* Success.
|
||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||
* The algorithm in \p cipher_suite is not a PAKE algorithm, or the
|
||
* PAKE primitive in \p cipher_suite is not compatible with the
|
||
* PAKE algorithm, or the hash algorithm in \p cipher_suite is invalid
|
||
* or not compatible with the PAKE algorithm and primitive.
|
||
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||
* The algorithm in \p cipher_suite is not a supported PAKE algorithm,
|
||
* or the PAKE primitive in \p cipher_suite is not supported or not
|
||
* compatible with the PAKE algorithm, or the hash algorithm in
|
||
* \p cipher_suite is not supported or not compatible with the PAKE
|
||
* algorithm and primitive.
|
||
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
||
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
||
* \retval #PSA_ERROR_BAD_STATE
|
||
* The operation state is not valid, or
|
||
* the library has not been previously initialized by psa_crypto_init().
|
||
* It is implementation-dependent whether a failure to initialize
|
||
* results in this error code.
|
||
*/
|
||
psa_status_t psa_pake_setup( psa_pake_operation_t *operation,
|
||
const psa_pake_cipher_suite_t *cipher_suite );
|
||
|
||
/** Set the password for a password-authenticated key exchange from key ID.
|
||
*
|
||
* Call this function when the password, or a value derived from the password,
|
||
* is already present in the key store.
|
||
*
|
||
* \param[in,out] operation The operation object to set the password for. It
|
||
* must have been set up by psa_pake_setup() and
|
||
* not yet in use (neither psa_pake_output() nor
|
||
* psa_pake_input() has been called yet). It must
|
||
* be on operation for which the password hasn't
|
||
* been set yet (psa_pake_set_password_key()
|
||
* hasn't been called yet).
|
||
* \param password Identifier of the key holding the password or a
|
||
* value derived from the password (eg. by a
|
||
* memory-hard function). It must remain valid
|
||
* until the operation terminates. It must be of
|
||
* type #PSA_KEY_TYPE_PASSWORD or
|
||
* #PSA_KEY_TYPE_PASSWORD_HASH. It has to allow
|
||
* the usage #PSA_KEY_USAGE_DERIVE.
|
||
*
|
||
* \retval #PSA_SUCCESS
|
||
* Success.
|
||
* \retval #PSA_ERROR_INVALID_HANDLE
|
||
* \p password is not a valid key identifier.
|
||
* \retval #PSA_ERROR_NOT_PERMITTED
|
||
* The key does not have the #PSA_KEY_USAGE_DERIVE flag, or it does not
|
||
* permit the \p operation's algorithm.
|
||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||
* The key type for \p password is not #PSA_KEY_TYPE_PASSWORD or
|
||
* #PSA_KEY_TYPE_PASSWORD_HASH, or \p password is not compatible with
|
||
* the \p operation's cipher suite.
|
||
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||
* The key type or key size of \p password is not supported with the
|
||
* \p operation's cipher suite.
|
||
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
||
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
||
* \retval #PSA_ERROR_STORAGE_FAILURE
|
||
* \retval #PSA_ERROR_DATA_CORRUPT
|
||
* \retval #PSA_ERROR_DATA_INVALID
|
||
* \retval #PSA_ERROR_BAD_STATE
|
||
* The operation state is not valid (it must have been set up.), or
|
||
* the library has not been previously initialized by psa_crypto_init().
|
||
* It is implementation-dependent whether a failure to initialize
|
||
* results in this error code.
|
||
*/
|
||
psa_status_t psa_pake_set_password_key( psa_pake_operation_t *operation,
|
||
mbedtls_svc_key_id_t password );
|
||
|
||
/** Set the user ID for a password-authenticated key exchange.
|
||
*
|
||
* Call this function to set the user ID. For PAKE algorithms that associate a
|
||
* user identifier with each side of the session you need to call
|
||
* psa_pake_set_peer() as well. For PAKE algorithms that associate a single
|
||
* user identifier with the session, call psa_pake_set_user() only.
|
||
*
|
||
* Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
|
||
* values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
|
||
* for more information.
|
||
*
|
||
* \param[in,out] operation The operation object to set the user ID for. It
|
||
* must have been set up by psa_pake_setup() and
|
||
* not yet in use (neither psa_pake_output() nor
|
||
* psa_pake_input() has been called yet). It must
|
||
* be on operation for which the user ID hasn't
|
||
* been set (psa_pake_set_user() hasn't been
|
||
* called yet).
|
||
* \param[in] user_id The user ID to authenticate with.
|
||
* \param user_id_len Size of the \p user_id buffer in bytes.
|
||
*
|
||
* \retval #PSA_SUCCESS
|
||
* Success.
|
||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||
* \p user_id is not valid for the \p operation's algorithm and cipher
|
||
* suite.
|
||
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||
* The value of \p user_id is not supported by the implementation.
|
||
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
||
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
||
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
||
* \retval #PSA_ERROR_BAD_STATE
|
||
* The operation state is not valid, or
|
||
* the library has not been previously initialized by psa_crypto_init().
|
||
* It is implementation-dependent whether a failure to initialize
|
||
* results in this error code.
|
||
*/
|
||
psa_status_t psa_pake_set_user( psa_pake_operation_t *operation,
|
||
const uint8_t *user_id,
|
||
size_t user_id_len );
|
||
|
||
/** Set the peer ID for a password-authenticated key exchange.
|
||
*
|
||
* Call this function in addition to psa_pake_set_user() for PAKE algorithms
|
||
* that associate a user identifier with each side of the session. For PAKE
|
||
* algorithms that associate a single user identifier with the session, call
|
||
* psa_pake_set_user() only.
|
||
*
|
||
* Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
|
||
* values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
|
||
* for more information.
|
||
*
|
||
* \param[in,out] operation The operation object to set the peer ID for. It
|
||
* must have been set up by psa_pake_setup() and
|
||
* not yet in use (neither psa_pake_output() nor
|
||
* psa_pake_input() has been called yet). It must
|
||
* be on operation for which the peer ID hasn't
|
||
* been set (psa_pake_set_peer() hasn't been
|
||
* called yet).
|
||
* \param[in] peer_id The peer's ID to authenticate.
|
||
* \param peer_id_len Size of the \p peer_id buffer in bytes.
|
||
*
|
||
* \retval #PSA_SUCCESS
|
||
* Success.
|
||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||
* \p user_id is not valid for the \p operation's algorithm and cipher
|
||
* suite.
|
||
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||
* The algorithm doesn't associate a second identity with the session.
|
||
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
||
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
||
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
||
* \retval #PSA_ERROR_BAD_STATE
|
||
* Calling psa_pake_set_peer() is invalid with the \p operation's
|
||
* algorithm, the operation state is not valid, or the library has not
|
||
* been previously initialized by psa_crypto_init().
|
||
* It is implementation-dependent whether a failure to initialize
|
||
* results in this error code.
|
||
*/
|
||
psa_status_t psa_pake_set_peer( psa_pake_operation_t *operation,
|
||
const uint8_t *peer_id,
|
||
size_t peer_id_len );
|
||
|
||
/** Set the application role for a password-authenticated key exchange.
|
||
*
|
||
* Not all PAKE algorithms need to differentiate the communicating entities.
|
||
* It is optional to call this function for PAKEs that don't require a role
|
||
* to be specified. For such PAKEs the application role parameter is ignored,
|
||
* or #PSA_PAKE_ROLE_NONE can be passed as \c role.
|
||
*
|
||
* Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX`
|
||
* values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true)
|
||
* for more information.
|
||
*
|
||
* \param[in,out] operation The operation object to specify the
|
||
* application's role for. It must have been set up
|
||
* by psa_pake_setup() and not yet in use (neither
|
||
* psa_pake_output() nor psa_pake_input() has been
|
||
* called yet). It must be on operation for which
|
||
* the application's role hasn't been specified
|
||
* (psa_pake_set_role() hasn't been called yet).
|
||
* \param role A value of type ::psa_pake_role_t indicating the
|
||
* application's role in the PAKE the algorithm
|
||
* that is being set up. For more information see
|
||
* the documentation of \c PSA_PAKE_ROLE_XXX
|
||
* constants.
|
||
*
|
||
* \retval #PSA_SUCCESS
|
||
* Success.
|
||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||
* The \p role is not a valid PAKE role in the \p operation’s algorithm.
|
||
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||
* The \p role for this algorithm is not supported or is not valid.
|
||
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
||
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
||
* \retval #PSA_ERROR_BAD_STATE
|
||
* The operation state is not valid, or
|
||
* the library has not been previously initialized by psa_crypto_init().
|
||
* It is implementation-dependent whether a failure to initialize
|
||
* results in this error code.
|
||
*/
|
||
psa_status_t psa_pake_set_role( psa_pake_operation_t *operation,
|
||
psa_pake_role_t role );
|
||
|
||
/** Get output for a step of a password-authenticated key exchange.
|
||
*
|
||
* Depending on the algorithm being executed, you might need to call this
|
||
* function several times or you might not need to call this at all.
|
||
*
|
||
* The exact sequence of calls to perform a password-authenticated key
|
||
* exchange depends on the algorithm in use. Refer to the documentation of
|
||
* individual PAKE algorithm types (`PSA_ALG_XXX` values of type
|
||
* ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
|
||
* information.
|
||
*
|
||
* If this function returns an error status, the operation enters an error
|
||
* state and must be aborted by calling psa_pake_abort().
|
||
*
|
||
* \param[in,out] operation Active PAKE operation.
|
||
* \param step The step of the algorithm for which the output is
|
||
* requested.
|
||
* \param[out] output Buffer where the output is to be written in the
|
||
* format appropriate for this \p step. Refer to
|
||
* the documentation of the individual
|
||
* \c PSA_PAKE_STEP_XXX constants for more
|
||
* information.
|
||
* \param output_size Size of the \p output buffer in bytes. This must
|
||
* be at least #PSA_PAKE_OUTPUT_SIZE(\p alg, \p
|
||
* primitive, \p step) where \p alg and
|
||
* \p primitive are the PAKE algorithm and primitive
|
||
* in the operation's cipher suite, and \p step is
|
||
* the output step.
|
||
*
|
||
* \param[out] output_length On success, the number of bytes of the returned
|
||
* output.
|
||
*
|
||
* \retval #PSA_SUCCESS
|
||
* Success.
|
||
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
||
* The size of the \p output buffer is too small.
|
||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||
* \p step is not compatible with the operation's algorithm.
|
||
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||
* \p step is not supported with the operation's algorithm.
|
||
* \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
|
||
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
||
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
||
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
||
* \retval #PSA_ERROR_STORAGE_FAILURE
|
||
* \retval #PSA_ERROR_DATA_CORRUPT
|
||
* \retval #PSA_ERROR_DATA_INVALID
|
||
* \retval #PSA_ERROR_BAD_STATE
|
||
* The operation state is not valid (it must be active, and fully set
|
||
* up, and this call must conform to the algorithm's requirements
|
||
* for ordering of input and output steps), or
|
||
* the library has not been previously initialized by psa_crypto_init().
|
||
* It is implementation-dependent whether a failure to initialize
|
||
* results in this error code.
|
||
*/
|
||
psa_status_t psa_pake_output( psa_pake_operation_t *operation,
|
||
psa_pake_step_t step,
|
||
uint8_t *output,
|
||
size_t output_size,
|
||
size_t *output_length );
|
||
|
||
/** Provide input for a step of a password-authenticated key exchange.
|
||
*
|
||
* Depending on the algorithm being executed, you might need to call this
|
||
* function several times or you might not need to call this at all.
|
||
*
|
||
* The exact sequence of calls to perform a password-authenticated key
|
||
* exchange depends on the algorithm in use. Refer to the documentation of
|
||
* individual PAKE algorithm types (`PSA_ALG_XXX` values of type
|
||
* ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
|
||
* information.
|
||
*
|
||
* If this function returns an error status, the operation enters an error
|
||
* state and must be aborted by calling psa_pake_abort().
|
||
*
|
||
* \param[in,out] operation Active PAKE operation.
|
||
* \param step The step for which the input is provided.
|
||
* \param[in] input Buffer containing the input in the format
|
||
* appropriate for this \p step. Refer to the
|
||
* documentation of the individual
|
||
* \c PSA_PAKE_STEP_XXX constants for more
|
||
* information.
|
||
* \param input_length Size of the \p input buffer in bytes.
|
||
*
|
||
* \retval #PSA_SUCCESS
|
||
* Success.
|
||
* \retval #PSA_ERROR_INVALID_SIGNATURE
|
||
* The verification fails for a #PSA_PAKE_STEP_ZK_PROOF input step.
|
||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||
* \p is not compatible with the \p operation’s algorithm, or the
|
||
* \p input is not valid for the \p operation's algorithm, cipher suite
|
||
* or \p step.
|
||
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||
* \p step p is not supported with the \p operation's algorithm, or the
|
||
* \p input is not supported for the \p operation's algorithm, cipher
|
||
* suite or \p step.
|
||
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
||
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
||
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
||
* \retval #PSA_ERROR_STORAGE_FAILURE
|
||
* \retval #PSA_ERROR_DATA_CORRUPT
|
||
* \retval #PSA_ERROR_DATA_INVALID
|
||
* \retval #PSA_ERROR_BAD_STATE
|
||
* The operation state is not valid (it must be active, and fully set
|
||
* up, and this call must conform to the algorithm's requirements
|
||
* for ordering of input and output steps), or
|
||
* the library has not been previously initialized by psa_crypto_init().
|
||
* It is implementation-dependent whether a failure to initialize
|
||
* results in this error code.
|
||
*/
|
||
psa_status_t psa_pake_input( psa_pake_operation_t *operation,
|
||
psa_pake_step_t step,
|
||
const uint8_t *input,
|
||
size_t input_length );
|
||
|
||
/** Get implicitly confirmed shared secret from a PAKE.
|
||
*
|
||
* At this point there is a cryptographic guarantee that only the authenticated
|
||
* party who used the same password is able to compute the key. But there is no
|
||
* guarantee that the peer is the party it claims to be and was able to do so.
|
||
*
|
||
* That is, the authentication is only implicit. Since the peer is not
|
||
* authenticated yet, no action should be taken yet that assumes that the peer
|
||
* is who it claims to be. For example, do not access restricted files on the
|
||
* peer's behalf until an explicit authentication has succeeded.
|
||
*
|
||
* This function can be called after the key exchange phase of the operation
|
||
* has completed. It imports the shared secret output of the PAKE into the
|
||
* provided derivation operation. The input step
|
||
* #PSA_KEY_DERIVATION_INPUT_SECRET is used when placing the shared key
|
||
* material in the key derivation operation.
|
||
*
|
||
* The exact sequence of calls to perform a password-authenticated key
|
||
* exchange depends on the algorithm in use. Refer to the documentation of
|
||
* individual PAKE algorithm types (`PSA_ALG_XXX` values of type
|
||
* ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
|
||
* information.
|
||
*
|
||
* When this function returns successfully, \p operation becomes inactive.
|
||
* If this function returns an error status, both \p operation
|
||
* and \p key_derivation operations enter an error state and must be aborted by
|
||
* calling psa_pake_abort() and psa_key_derivation_abort() respectively.
|
||
*
|
||
* \param[in,out] operation Active PAKE operation.
|
||
* \param[out] output A key derivation operation that is ready
|
||
* for an input step of type
|
||
* #PSA_KEY_DERIVATION_INPUT_SECRET.
|
||
*
|
||
* \retval #PSA_SUCCESS
|
||
* Success.
|
||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||
* #PSA_KEY_DERIVATION_INPUT_SECRET is not compatible with the
|
||
* algorithm in the \p output key derivation operation.
|
||
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||
* Input from a PAKE is not supported by the algorithm in the \p output
|
||
* key derivation operation.
|
||
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
||
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
||
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
||
* \retval #PSA_ERROR_STORAGE_FAILURE
|
||
* \retval #PSA_ERROR_DATA_CORRUPT
|
||
* \retval #PSA_ERROR_DATA_INVALID
|
||
* \retval #PSA_ERROR_BAD_STATE
|
||
* The PAKE operation state is not valid (it must be active, but beyond
|
||
* that validity is specific to the algorithm), or
|
||
* the library has not been previously initialized by psa_crypto_init(),
|
||
* or the state of \p output is not valid for
|
||
* the #PSA_KEY_DERIVATION_INPUT_SECRET step. This can happen if the
|
||
* step is out of order or the application has done this step already
|
||
* and it may not be repeated.
|
||
* It is implementation-dependent whether a failure to initialize
|
||
* results in this error code.
|
||
*/
|
||
psa_status_t psa_pake_get_implicit_key( psa_pake_operation_t *operation,
|
||
psa_key_derivation_operation_t *output );
|
||
|
||
/** Abort a PAKE operation.
|
||
*
|
||
* Aborting an operation frees all associated resources except for the \c
|
||
* operation structure itself. Once aborted, the operation object can be reused
|
||
* for another operation by calling psa_pake_setup() again.
|
||
*
|
||
* This function may be called at any time after the operation
|
||
* object has been initialized as described in #psa_pake_operation_t.
|
||
*
|
||
* In particular, calling psa_pake_abort() after the operation has been
|
||
* terminated by a call to psa_pake_abort() or psa_pake_get_implicit_key()
|
||
* is safe and has no effect.
|
||
*
|
||
* \param[in,out] operation The operation to abort.
|
||
*
|
||
* \retval #PSA_SUCCESS
|
||
* Success.
|
||
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
||
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
||
* \retval #PSA_ERROR_BAD_STATE
|
||
* The library has not been previously initialized by psa_crypto_init().
|
||
* It is implementation-dependent whether a failure to initialize
|
||
* results in this error code.
|
||
*/
|
||
psa_status_t psa_pake_abort( psa_pake_operation_t * operation );
|
||
|
||
/**@}*/
|
||
|
||
/** A sufficient output buffer size for psa_pake_output().
|
||
*
|
||
* If the size of the output buffer is at least this large, it is guaranteed
|
||
* that psa_pake_output() will not fail due to an insufficient output buffer
|
||
* size. The actual size of the output might be smaller in any given call.
|
||
*
|
||
* See also #PSA_PAKE_OUTPUT_MAX_SIZE
|
||
*
|
||
* \param alg A PAKE algorithm (\c PSA_ALG_XXX value such that
|
||
* #PSA_ALG_IS_PAKE(\p alg) is true).
|
||
* \param primitive A primitive of type ::psa_pake_primitive_t that is
|
||
* compatible with algorithm \p alg.
|
||
* \param output_step A value of type ::psa_pake_step_t that is valid for the
|
||
* algorithm \p alg.
|
||
* \return A sufficient output buffer size for the specified
|
||
* PAKE algorithm, primitive, and output step. If the
|
||
* PAKE algorithm, primitive, or output step is not
|
||
* recognized, or the parameters are incompatible,
|
||
* return 0.
|
||
*/
|
||
#define PSA_PAKE_OUTPUT_SIZE(alg, primitive, output_step) 0
|
||
|
||
/** A sufficient input buffer size for psa_pake_input().
|
||
*
|
||
* The value returned by this macro is guaranteed to be large enough for any
|
||
* valid input to psa_pake_input() in an operation with the specified
|
||
* parameters.
|
||
*
|
||
* See also #PSA_PAKE_INPUT_MAX_SIZE
|
||
*
|
||
* \param alg A PAKE algorithm (\c PSA_ALG_XXX value such that
|
||
* #PSA_ALG_IS_PAKE(\p alg) is true).
|
||
* \param primitive A primitive of type ::psa_pake_primitive_t that is
|
||
* compatible with algorithm \p alg.
|
||
* \param input_step A value of type ::psa_pake_step_t that is valid for the
|
||
* algorithm \p alg.
|
||
* \return A sufficient input buffer size for the specified
|
||
* input, cipher suite and algorithm. If the cipher suite,
|
||
* the input type or PAKE algorithm is not recognized, or
|
||
* the parameters are incompatible, return 0.
|
||
*/
|
||
#define PSA_PAKE_INPUT_SIZE(alg, primitive, input_step) 0
|
||
|
||
/** Output buffer size for psa_pake_output() for any of the supported PAKE
|
||
* algorithm and primitive suites and output step.
|
||
*
|
||
* This macro must expand to a compile-time constant integer.
|
||
*
|
||
* See also #PSA_PAKE_OUTPUT_SIZE(\p alg, \p primitive, \p step).
|
||
*/
|
||
#define PSA_PAKE_OUTPUT_MAX_SIZE 0
|
||
|
||
/** Input buffer size for psa_pake_input() for any of the supported PAKE
|
||
* algorithm and primitive suites and input step.
|
||
*
|
||
* This macro must expand to a compile-time constant integer.
|
||
*
|
||
* See also #PSA_PAKE_INPUT_SIZE(\p alg, \p primitive, \p step).
|
||
*/
|
||
#define PSA_PAKE_INPUT_MAX_SIZE 0
|
||
|
||
/** Returns a suitable initializer for a PAKE cipher suite object of type
|
||
* psa_pake_cipher_suite_t.
|
||
*/
|
||
#define PSA_PAKE_CIPHER_SUITE_INIT {PSA_ALG_NONE, 0, 0, 0, PSA_ALG_NONE}
|
||
|
||
/** Returns a suitable initializer for a PAKE operation object of type
|
||
* psa_pake_operation_t.
|
||
*/
|
||
#define PSA_PAKE_OPERATION_INIT {PSA_ALG_NONE, {0}}
|
||
|
||
struct psa_pake_cipher_suite_s
|
||
{
|
||
psa_algorithm_t algorithm;
|
||
psa_pake_primitive_type_t type;
|
||
psa_pake_family_t family;
|
||
uint16_t bits;
|
||
psa_algorithm_t hash;
|
||
};
|
||
|
||
static inline psa_algorithm_t psa_pake_cs_get_algorithm(
|
||
const psa_pake_cipher_suite_t *cipher_suite )
|
||
{
|
||
return( cipher_suite->algorithm );
|
||
}
|
||
|
||
static inline void psa_pake_cs_set_algorithm(
|
||
psa_pake_cipher_suite_t *cipher_suite,
|
||
psa_algorithm_t algorithm)
|
||
{
|
||
if( !PSA_ALG_IS_PAKE( algorithm ) )
|
||
cipher_suite->algorithm = 0;
|
||
else
|
||
cipher_suite->algorithm = algorithm;
|
||
}
|
||
|
||
static inline psa_pake_primitive_t psa_pake_cs_get_primitive(
|
||
const psa_pake_cipher_suite_t *cipher_suite )
|
||
{
|
||
return( PSA_PAKE_PRIMITIVE( cipher_suite->type, cipher_suite->family,
|
||
cipher_suite->bits ) );
|
||
}
|
||
|
||
static inline void psa_pake_cs_set_primitive(
|
||
psa_pake_cipher_suite_t *cipher_suite,
|
||
psa_pake_primitive_t primitive )
|
||
{
|
||
cipher_suite->type = (psa_pake_primitive_type_t) (primitive >> 24);
|
||
cipher_suite->family = (psa_pake_family_t) (0xFF & (primitive >> 16));
|
||
cipher_suite->bits = (uint16_t) (0xFFFF & primitive);
|
||
}
|
||
|
||
static inline psa_pake_family_t psa_pake_cs_get_family(
|
||
const psa_pake_cipher_suite_t *cipher_suite )
|
||
{
|
||
return( cipher_suite->family );
|
||
}
|
||
|
||
static inline uint16_t psa_pake_cs_get_bits(
|
||
const psa_pake_cipher_suite_t *cipher_suite )
|
||
{
|
||
return( cipher_suite->bits );
|
||
}
|
||
|
||
static inline psa_algorithm_t psa_pake_cs_get_hash(
|
||
const psa_pake_cipher_suite_t *cipher_suite )
|
||
{
|
||
return( cipher_suite->hash );
|
||
}
|
||
|
||
static inline void psa_pake_cs_set_hash( psa_pake_cipher_suite_t *cipher_suite,
|
||
psa_algorithm_t hash )
|
||
{
|
||
if( !PSA_ALG_IS_HASH( hash ) )
|
||
cipher_suite->hash = 0;
|
||
else
|
||
cipher_suite->hash = hash;
|
||
}
|
||
|
||
struct psa_pake_operation_s
|
||
{
|
||
psa_algorithm_t alg;
|
||
union
|
||
{
|
||
/* Make the union non-empty even with no supported algorithms. */
|
||
uint8_t dummy;
|
||
} ctx;
|
||
};
|
||
|
||
static inline struct psa_pake_cipher_suite_s psa_pake_cipher_suite_init( void )
|
||
{
|
||
const struct psa_pake_cipher_suite_s v = PSA_PAKE_CIPHER_SUITE_INIT;
|
||
return( v );
|
||
}
|
||
|
||
static inline struct psa_pake_operation_s psa_pake_operation_init( void )
|
||
{
|
||
const struct psa_pake_operation_s v = PSA_PAKE_OPERATION_INIT;
|
||
return( v );
|
||
}
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* PSA_CRYPTO_EXTRA_H */
|