include/mbedtls/psa_util.h - mirror/mbed-tls - TrustedFirmware Git Browser

 /**
  * \file psa_util.h
  *
  * \brief Utility functions for the use of the PSA Crypto library.
  *
  * \warning These functions are not part of the public API and may
  *          change at any time.
  */
 /*
  *  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 MBEDTLS_PSA_UTIL_H
 #define MBEDTLS_PSA_UTIL_H
 #include "mbedtls/private_access.h"

 #include "mbedtls/build_info.h"

 #include "mbedtls/platform_util.h"

 #if defined(MBEDTLS_PSA_CRYPTO_C)

 #include "psa/crypto.h"

 #include "mbedtls/ecp.h"
 #include "mbedtls/md.h"
 #include "mbedtls/pk.h"
 #include "mbedtls/oid.h"
 #include "mbedtls/error.h"
 #include <string.h>

 /* Translations for ECC. */

 #define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH \
     PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)

 #define MBEDTLS_PSA_MAX_EC_KEY_PAIR_LENGTH \
     PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)

 #define MBEDTLS_PSA_MAX_FFDH_PUBKEY_LENGTH \
     PSA_KEY_EXPORT_FFDH_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_FFDH_MAX_KEY_BITS)

 /* Expose whatever RNG the PSA subsystem uses to applications using the
  * mbedtls_xxx API. The declarations and definitions here need to be
  * consistent with the implementation in library/psa_crypto_random_impl.h.
  * See that file for implementation documentation. */


 /* The type of a `f_rng` random generator function that many library functions
  * take.
  *
  * This type name is not part of the Mbed TLS stable API. It may be renamed
  * or moved without warning.
  */
 typedef int mbedtls_f_rng_t(void *p_rng, unsigned char *output, size_t output_size);

 #if defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)

 /** The random generator function for the PSA subsystem.
  *
  * This function is suitable as the `f_rng` random generator function
  * parameter of many `mbedtls_xxx` functions. Use #MBEDTLS_PSA_RANDOM_STATE
  * to obtain the \p p_rng parameter.
  *
  * The implementation of this function depends on the configuration of the
  * library.
  *
  * \note Depending on the configuration, this may be a function or
  *       a pointer to a function.
  *
  * \note This function may only be used if the PSA crypto subsystem is active.
  *       This means that you must call psa_crypto_init() before any call to
  *       this function, and you must not call this function after calling
  *       mbedtls_psa_crypto_free().
  *
  * \param p_rng         The random generator context. This must be
  *                      #MBEDTLS_PSA_RANDOM_STATE. No other state is
  *                      supported.
  * \param output        The buffer to fill. It must have room for
  *                      \c output_size bytes.
  * \param output_size   The number of bytes to write to \p output.
  *                      This function may fail if \p output_size is too
  *                      large. It is guaranteed to accept any output size
  *                      requested by Mbed TLS library functions. The
  *                      maximum request size depends on the library
  *                      configuration.
  *
  * \return              \c 0 on success.
  * \return              An `MBEDTLS_ERR_ENTROPY_xxx`,
  *                      `MBEDTLS_ERR_PLATFORM_xxx,
  *                      `MBEDTLS_ERR_CTR_DRBG_xxx` or
  *                      `MBEDTLS_ERR_HMAC_DRBG_xxx` on error.
  */
 int mbedtls_psa_get_random(void *p_rng,
                            unsigned char *output,
                            size_t output_size);

 /** The random generator state for the PSA subsystem.
  *
  * This macro expands to an expression which is suitable as the `p_rng`
  * random generator state parameter of many `mbedtls_xxx` functions.
  * It must be used in combination with the random generator function
  * mbedtls_psa_get_random().
  *
  * The implementation of this macro depends on the configuration of the
  * library. Do not make any assumption on its nature.
  */
 #define MBEDTLS_PSA_RANDOM_STATE NULL

 #else /* !defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) */

 #if defined(MBEDTLS_CTR_DRBG_C)
 #include "mbedtls/ctr_drbg.h"
 typedef mbedtls_ctr_drbg_context mbedtls_psa_drbg_context_t;
 static mbedtls_f_rng_t *const mbedtls_psa_get_random = mbedtls_ctr_drbg_random;
 #elif defined(MBEDTLS_HMAC_DRBG_C)
 #include "mbedtls/hmac_drbg.h"
 typedef mbedtls_hmac_drbg_context mbedtls_psa_drbg_context_t;
 static mbedtls_f_rng_t *const mbedtls_psa_get_random = mbedtls_hmac_drbg_random;
 #endif
 extern mbedtls_psa_drbg_context_t *const mbedtls_psa_random_state;

 #define MBEDTLS_PSA_RANDOM_STATE mbedtls_psa_random_state

 #endif /* !defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) */

 typedef struct {
     /* Error codes used by PSA crypto are in -255..-128, fitting in 16 bits. */
     int16_t psa_status;
     /* Error codes used by Mbed TLS are in one of the ranges
      * -127..-1 (low-level) or -32767..-4096 (high-level with a low-level
      * code optionally added), fitting in 16 bits. */
     int16_t mbedtls_error;
 } mbedtls_error_pair_t;

 #if defined(MBEDTLS_MD_LIGHT)
 extern const mbedtls_error_pair_t psa_to_md_errors[4];
 #endif

 #if defined(MBEDTLS_LMS_C)
 extern const mbedtls_error_pair_t psa_to_lms_errors[3];
 #endif

 #if defined(MBEDTLS_USE_PSA_CRYPTO) || defined(MBEDTLS_SSL_PROTO_TLS1_3)
 extern const mbedtls_error_pair_t psa_to_ssl_errors[7];
 #endif

 #if defined(PSA_WANT_KEY_TYPE_RSA_PUBLIC_KEY) ||    \
     defined(MBEDTLS_PSA_WANT_KEY_TYPE_RSA_KEY_PAIR_LEGACY)
 extern const mbedtls_error_pair_t psa_to_pk_rsa_errors[8];
 #endif

 #if defined(MBEDTLS_USE_PSA_CRYPTO) && \
     defined(PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY)
 extern const mbedtls_error_pair_t psa_to_pk_ecdsa_errors[7];
 #endif

 /* Generic fallback function for error translation,
  * when the received state was not module-specific. */
 int psa_generic_status_to_mbedtls(psa_status_t status);

 /* This function iterates over provided local error translations,
  * and if no match was found - calls the fallback error translation function. */
 int psa_status_to_mbedtls(psa_status_t status,
                           const mbedtls_error_pair_t *local_translations,
                           size_t local_errors_num,
                           int (*fallback_f)(psa_status_t));

 /* The second out of three-stage error handling functions of the pk module,
  * acts as a fallback after RSA / ECDSA error translation, and if no match
  * is found, it itself calls psa_generic_status_to_mbedtls. */
 int psa_pk_status_to_mbedtls(psa_status_t status);

 /* Utility macro to shorten the defines of error translator in modules. */
 #define PSA_TO_MBEDTLS_ERR_LIST(status, error_list, fallback_f)       \
     psa_status_to_mbedtls(status, error_list,                         \
                           sizeof(error_list)/sizeof(error_list[0]),   \
                           fallback_f)

 #endif /* MBEDTLS_PSA_CRYPTO_C */
 #endif /* MBEDTLS_PSA_UTIL_H */
	/**
	* \file psa_util.h
	*
	* \brief Utility functions for the use of the PSA Crypto library.
	*
	* \warning These functions are not part of the public API and may
	* change at any time.
	*/
	/*
	* 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 MBEDTLS_PSA_UTIL_H
	#define MBEDTLS_PSA_UTIL_H
	#include "mbedtls/private_access.h"

	#include "mbedtls/build_info.h"

	#include "mbedtls/platform_util.h"

	#if defined(MBEDTLS_PSA_CRYPTO_C)

	#include "psa/crypto.h"

	#include "mbedtls/ecp.h"
	#include "mbedtls/md.h"
	#include "mbedtls/pk.h"
	#include "mbedtls/oid.h"
	#include "mbedtls/error.h"
	#include <string.h>

	/* Translations for ECC. */

	#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH \
	PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)

	#define MBEDTLS_PSA_MAX_EC_KEY_PAIR_LENGTH \
	PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)

	#define MBEDTLS_PSA_MAX_FFDH_PUBKEY_LENGTH \
	PSA_KEY_EXPORT_FFDH_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_FFDH_MAX_KEY_BITS)

	/* Expose whatever RNG the PSA subsystem uses to applications using the
	* mbedtls_xxx API. The declarations and definitions here need to be
	* consistent with the implementation in library/psa_crypto_random_impl.h.
	* See that file for implementation documentation. */


	/* The type of a `f_rng` random generator function that many library functions
	* take.
	*
	* This type name is not part of the Mbed TLS stable API. It may be renamed
	* or moved without warning.
	*/
	typedef int mbedtls_f_rng_t(void p_rng, unsigned char output, size_t output_size);

	#if defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)

	/** The random generator function for the PSA subsystem.
	*
	* This function is suitable as the `f_rng` random generator function
	* parameter of many `mbedtls_xxx` functions. Use #MBEDTLS_PSA_RANDOM_STATE
	* to obtain the \p p_rng parameter.
	*
	* The implementation of this function depends on the configuration of the
	* library.
	*
	* \note Depending on the configuration, this may be a function or
	* a pointer to a function.
	*
	* \note This function may only be used if the PSA crypto subsystem is active.
	* This means that you must call psa_crypto_init() before any call to
	* this function, and you must not call this function after calling
	* mbedtls_psa_crypto_free().
	*
	* \param p_rng The random generator context. This must be
	* #MBEDTLS_PSA_RANDOM_STATE. No other state is
	* supported.
	* \param output The buffer to fill. It must have room for
	* \c output_size bytes.
	* \param output_size The number of bytes to write to \p output.
	* This function may fail if \p output_size is too
	* large. It is guaranteed to accept any output size
	* requested by Mbed TLS library functions. The
	* maximum request size depends on the library
	* configuration.
	*
	* \return \c 0 on success.
	* \return An `MBEDTLS_ERR_ENTROPY_xxx`,
	* `MBEDTLS_ERR_PLATFORM_xxx,
	* `MBEDTLS_ERR_CTR_DRBG_xxx` or
	* `MBEDTLS_ERR_HMAC_DRBG_xxx` on error.
	*/
	int mbedtls_psa_get_random(void *p_rng,
	unsigned char *output,
	size_t output_size);

	/** The random generator state for the PSA subsystem.
	*
	* This macro expands to an expression which is suitable as the `p_rng`
	* random generator state parameter of many `mbedtls_xxx` functions.
	* It must be used in combination with the random generator function
	* mbedtls_psa_get_random().
	*
	* The implementation of this macro depends on the configuration of the
	* library. Do not make any assumption on its nature.
	*/
	#define MBEDTLS_PSA_RANDOM_STATE NULL

	#else /* !defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) */

	#if defined(MBEDTLS_CTR_DRBG_C)
	#include "mbedtls/ctr_drbg.h"
	typedef mbedtls_ctr_drbg_context mbedtls_psa_drbg_context_t;
	static mbedtls_f_rng_t *const mbedtls_psa_get_random = mbedtls_ctr_drbg_random;
	#elif defined(MBEDTLS_HMAC_DRBG_C)
	#include "mbedtls/hmac_drbg.h"
	typedef mbedtls_hmac_drbg_context mbedtls_psa_drbg_context_t;
	static mbedtls_f_rng_t *const mbedtls_psa_get_random = mbedtls_hmac_drbg_random;
	#endif
	extern mbedtls_psa_drbg_context_t *const mbedtls_psa_random_state;

	#define MBEDTLS_PSA_RANDOM_STATE mbedtls_psa_random_state

	#endif /* !defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) */

	typedef struct {
	/* Error codes used by PSA crypto are in -255..-128, fitting in 16 bits. */
	int16_t psa_status;
	/* Error codes used by Mbed TLS are in one of the ranges
	* -127..-1 (low-level) or -32767..-4096 (high-level with a low-level
	* code optionally added), fitting in 16 bits. */
	int16_t mbedtls_error;
	} mbedtls_error_pair_t;

	#if defined(MBEDTLS_MD_LIGHT)
	extern const mbedtls_error_pair_t psa_to_md_errors[4];
	#endif

	#if defined(MBEDTLS_LMS_C)
	extern const mbedtls_error_pair_t psa_to_lms_errors[3];
	#endif

	#if defined(MBEDTLS_USE_PSA_CRYPTO) \|\| defined(MBEDTLS_SSL_PROTO_TLS1_3)
	extern const mbedtls_error_pair_t psa_to_ssl_errors[7];
	#endif

	#if defined(PSA_WANT_KEY_TYPE_RSA_PUBLIC_KEY) \|\| \
	defined(MBEDTLS_PSA_WANT_KEY_TYPE_RSA_KEY_PAIR_LEGACY)
	extern const mbedtls_error_pair_t psa_to_pk_rsa_errors[8];
	#endif

	#if defined(MBEDTLS_USE_PSA_CRYPTO) && \
	defined(PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY)
	extern const mbedtls_error_pair_t psa_to_pk_ecdsa_errors[7];
	#endif

	/* Generic fallback function for error translation,
	* when the received state was not module-specific. */
	int psa_generic_status_to_mbedtls(psa_status_t status);

	/* This function iterates over provided local error translations,
	* and if no match was found - calls the fallback error translation function. */
	int psa_status_to_mbedtls(psa_status_t status,
	const mbedtls_error_pair_t *local_translations,
	size_t local_errors_num,
	int (*fallback_f)(psa_status_t));

	/* The second out of three-stage error handling functions of the pk module,
	* acts as a fallback after RSA / ECDSA error translation, and if no match
	* is found, it itself calls psa_generic_status_to_mbedtls. */
	int psa_pk_status_to_mbedtls(psa_status_t status);

	/* Utility macro to shorten the defines of error translator in modules. */
	#define PSA_TO_MBEDTLS_ERR_LIST(status, error_list, fallback_f) \
	psa_status_to_mbedtls(status, error_list, \
	sizeof(error_list)/sizeof(error_list[0]), \
	fallback_f)

	#endif /* MBEDTLS_PSA_CRYPTO_C */
	#endif /* MBEDTLS_PSA_UTIL_H */