Merge remote-tracking branch 'upstream-crypto/development' into psa-api-beta2-merge-development
Merge the Mbed Crypto development branch a little after
mbedcrypto-1.0.0 into the PSA Crypto API 1.0 beta branch a little
after beta 2.
Summary of merge conflicts:
* Some features (psa_copy_key, public key format without
SubjectPublicKeyInfo wrapping) went into both sides, but with a few
improvements on the implementation side. For those, take the
implementation side.
* The key derivation API changed considerably on the API side. This
merge commit generally goes with the updated API except in the tests
where it keeps some aspects of the implementation.
Due to the divergence between the two branches on key derivation and
key agreement, test_suite_psa_crypto does not compile. This will be
resolved in subsequent commits.
diff --git a/include/CMakeLists.txt b/include/CMakeLists.txt
index 67c66c8..dac97f4 100644
--- a/include/CMakeLists.txt
+++ b/include/CMakeLists.txt
@@ -15,7 +15,8 @@
endif(INSTALL_MBEDTLS_HEADERS)
-# Make config.h available in an out-of-source build. ssl-opt.sh requires it.
+# Make config.h available in an out-of-source build.
if (NOT ${CMAKE_CURRENT_BINARY_DIR} STREQUAL ${CMAKE_CURRENT_SOURCE_DIR})
link_to_source(mbedtls)
+ link_to_source(psa)
endif()
diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h
index cfb20c4..94e7282 100644
--- a/include/mbedtls/aes.h
+++ b/include/mbedtls/aes.h
@@ -121,7 +121,7 @@
* It must be the first API called before using
* the context.
*
- * \param ctx The AES context to initialize.
+ * \param ctx The AES context to initialize. This must not be \c NULL.
*/
void mbedtls_aes_init( mbedtls_aes_context *ctx );
@@ -129,6 +129,8 @@
* \brief This function releases and clears the specified AES context.
*
* \param ctx The AES context to clear.
+ * If this is \c NULL, this function does nothing.
+ * Otherwise, the context must have been at least initialized.
*/
void mbedtls_aes_free( mbedtls_aes_context *ctx );
@@ -139,7 +141,7 @@
* It must be the first API called before using
* the context.
*
- * \param ctx The AES XTS context to initialize.
+ * \param ctx The AES XTS context to initialize. This must not be \c NULL.
*/
void mbedtls_aes_xts_init( mbedtls_aes_xts_context *ctx );
@@ -147,6 +149,8 @@
* \brief This function releases and clears the specified AES XTS context.
*
* \param ctx The AES XTS context to clear.
+ * If this is \c NULL, this function does nothing.
+ * Otherwise, the context must have been at least initialized.
*/
void mbedtls_aes_xts_free( mbedtls_aes_xts_context *ctx );
#endif /* MBEDTLS_CIPHER_MODE_XTS */
@@ -155,7 +159,9 @@
* \brief This function sets the encryption key.
*
* \param ctx The AES context to which the key should be bound.
+ * It must be initialized.
* \param key The encryption key.
+ * This must be a readable buffer of size \p keybits bits.
* \param keybits The size of data passed in bits. Valid options are:
* <ul><li>128 bits</li>
* <li>192 bits</li>
@@ -171,7 +177,9 @@
* \brief This function sets the decryption key.
*
* \param ctx The AES context to which the key should be bound.
+ * It must be initialized.
* \param key The decryption key.
+ * This must be a readable buffer of size \p keybits bits.
* \param keybits The size of data passed. Valid options are:
* <ul><li>128 bits</li>
* <li>192 bits</li>
@@ -189,8 +197,10 @@
* sets the encryption key.
*
* \param ctx The AES XTS context to which the key should be bound.
+ * It must be initialized.
* \param key The encryption key. This is comprised of the XTS key1
* concatenated with the XTS key2.
+ * This must be a readable buffer of size \p keybits bits.
* \param keybits The size of \p key passed in bits. Valid options are:
* <ul><li>256 bits (each of key1 and key2 is a 128-bit key)</li>
* <li>512 bits (each of key1 and key2 is a 256-bit key)</li></ul>
@@ -207,8 +217,10 @@
* sets the decryption key.
*
* \param ctx The AES XTS context to which the key should be bound.
+ * It must be initialized.
* \param key The decryption key. This is comprised of the XTS key1
* concatenated with the XTS key2.
+ * This must be a readable buffer of size \p keybits bits.
* \param keybits The size of \p key passed in bits. Valid options are:
* <ul><li>256 bits (each of key1 and key2 is a 128-bit key)</li>
* <li>512 bits (each of key1 and key2 is a 256-bit key)</li></ul>
@@ -234,10 +246,13 @@
* call to this API with the same context.
*
* \param ctx The AES context to use for encryption or decryption.
+ * It must be initialized and bound to a key.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT.
- * \param input The 16-Byte buffer holding the input data.
- * \param output The 16-Byte buffer holding the output data.
+ * \param input The buffer holding the input data.
+ * It must be readable and at least \c 16 Bytes long.
+ * \param output The buffer where the output data will be written.
+ * It must be writeable and at least \c 16 Bytes long.
* \return \c 0 on success.
*/
@@ -260,8 +275,8 @@
* mbedtls_aes_setkey_enc() or mbedtls_aes_setkey_dec() must be called
* before the first call to this API with the same context.
*
- * \note This function operates on aligned blocks, that is, the input size
- * must be a multiple of the AES block size of 16 Bytes.
+ * \note This function operates on full blocks, that is, the input size
+ * must be a multiple of the AES block size of \c 16 Bytes.
*
* \note Upon exit, the content of the IV is updated so that you can
* call the same function again on the next
@@ -272,13 +287,17 @@
*
*
* \param ctx The AES context to use for encryption or decryption.
+ * It must be initialized and bound to a key.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT.
* \param length The length of the input data in Bytes. This must be a
- * multiple of the block size (16 Bytes).
+ * multiple of the block size (\c 16 Bytes).
* \param iv Initialization vector (updated after use).
+ * It must be a readable and writeable buffer of \c 16 Bytes.
* \param input The buffer holding the input data.
+ * It must be readable and of size \p length Bytes.
* \param output The buffer holding the output data.
+ * It must be writeable and of size \p length Bytes.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
@@ -306,9 +325,10 @@
* returns #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH.
*
* \param ctx The AES XTS context to use for AES XTS operations.
+ * It must be initialized and bound to a key.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT.
- * \param length The length of a data unit in bytes. This can be any
+ * \param length The length of a data unit in Bytes. This can be any
* length between 16 bytes and 2^24 bytes inclusive
* (between 1 and 2^20 block cipher blocks).
* \param data_unit The address of the data unit encoded as an array of 16
@@ -316,15 +336,15 @@
* is typically the index of the block device sector that
* contains the data.
* \param input The buffer holding the input data (which is an entire
- * data unit). This function reads \p length bytes from \p
+ * data unit). This function reads \p length Bytes from \p
* input.
* \param output The buffer holding the output data (which is an entire
- * data unit). This function writes \p length bytes to \p
+ * data unit). This function writes \p length Bytes to \p
* output.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH if \p length is
- * smaller than an AES block in size (16 bytes) or if \p
+ * smaller than an AES block in size (16 Bytes) or if \p
* length is larger than 2^20 blocks (16 MiB).
*/
int mbedtls_aes_crypt_xts( mbedtls_aes_xts_context *ctx,
@@ -360,13 +380,18 @@
*
*
* \param ctx The AES context to use for encryption or decryption.
+ * It must be initialized and bound to a key.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT.
- * \param length The length of the input data.
+ * \param length The length of the input data in Bytes.
* \param iv_off The offset in IV (updated after use).
+ * It must point to a valid \c size_t.
* \param iv The initialization vector (updated after use).
+ * It must be a readable and writeable buffer of \c 16 Bytes.
* \param input The buffer holding the input data.
+ * It must be readable and of size \p length Bytes.
* \param output The buffer holding the output data.
+ * It must be writeable and of size \p length Bytes.
*
* \return \c 0 on success.
*/
@@ -401,12 +426,16 @@
*
*
* \param ctx The AES context to use for encryption or decryption.
+ * It must be initialized and bound to a key.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT
* \param length The length of the input data.
* \param iv The initialization vector (updated after use).
+ * It must be a readable and writeable buffer of \c 16 Bytes.
* \param input The buffer holding the input data.
+ * It must be readable and of size \p length Bytes.
* \param output The buffer holding the output data.
+ * It must be writeable and of size \p length Bytes.
*
* \return \c 0 on success.
*/
@@ -451,11 +480,16 @@
* will compromise security.
*
* \param ctx The AES context to use for encryption or decryption.
+ * It must be initialized and bound to a key.
* \param length The length of the input data.
* \param iv_off The offset in IV (updated after use).
+ * It must point to a valid \c size_t.
* \param iv The initialization vector (updated after use).
+ * It must be a readable and writeable buffer of \c 16 Bytes.
* \param input The buffer holding the input data.
+ * It must be readable and of size \p length Bytes.
* \param output The buffer holding the output data.
+ * It must be writeable and of size \p length Bytes.
*
* \return \c 0 on success.
*/
@@ -527,15 +561,21 @@
* securely discarded as soon as it's no longer needed.
*
* \param ctx The AES context to use for encryption or decryption.
+ * It must be initialized and bound to a key.
* \param length The length of the input data.
* \param nc_off The offset in the current \p stream_block, for
* resuming within the current cipher stream. The
* offset pointer should be 0 at the start of a stream.
+ * It must point to a valid \c size_t.
* \param nonce_counter The 128-bit nonce and counter.
+ * It must be a readable-writeable buffer of \c 16 Bytes.
* \param stream_block The saved stream block for resuming. This is
* overwritten by the function.
+ * It must be a readable-writeable buffer of \c 16 Bytes.
* \param input The buffer holding the input data.
+ * It must be readable and of size \p length Bytes.
* \param output The buffer holding the output data.
+ * It must be writeable and of size \p length Bytes.
*
* \return \c 0 on success.
*/
@@ -588,7 +628,7 @@
* \brief Deprecated internal AES block encryption function
* without return value.
*
- * \deprecated Superseded by mbedtls_aes_encrypt_ext() in 2.5.0.
+ * \deprecated Superseded by mbedtls_internal_aes_encrypt()
*
* \param ctx The AES context to use for encryption.
* \param input Plaintext block.
@@ -602,7 +642,7 @@
* \brief Deprecated internal AES block decryption function
* without return value.
*
- * \deprecated Superseded by mbedtls_aes_decrypt_ext() in 2.5.0.
+ * \deprecated Superseded by mbedtls_internal_aes_decrypt()
*
* \param ctx The AES context to use for decryption.
* \param input Ciphertext block.
@@ -615,6 +655,8 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+
+#if defined(MBEDTLS_SELF_TEST)
/**
* \brief Checkup routine.
*
@@ -623,6 +665,8 @@
*/
int mbedtls_aes_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/aesni.h b/include/mbedtls/aesni.h
index 746baa0..a4ca012 100644
--- a/include/mbedtls/aesni.h
+++ b/include/mbedtls/aesni.h
@@ -2,6 +2,9 @@
* \file aesni.h
*
* \brief AES-NI for hardware AES acceleration on some Intel processors
+ *
+ * \warning These functions are only for internal use by other library
+ * functions; you must not call them directly.
*/
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
@@ -24,6 +27,12 @@
#ifndef MBEDTLS_AESNI_H
#define MBEDTLS_AESNI_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "aes.h"
#define MBEDTLS_AESNI_AES 0x02000000u
@@ -42,7 +51,10 @@
#endif
/**
- * \brief AES-NI features detection routine
+ * \brief Internal function to detect the AES-NI feature in CPUs.
+ *
+ * \note This function is only for internal use by other library
+ * functions; you must not call it directly.
*
* \param what The feature to detect
* (MBEDTLS_AESNI_AES or MBEDTLS_AESNI_CLMUL)
@@ -52,7 +64,10 @@
int mbedtls_aesni_has_support( unsigned int what );
/**
- * \brief AES-NI AES-ECB block en(de)cryption
+ * \brief Internal AES-NI AES-ECB block encryption and decryption
+ *
+ * \note This function is only for internal use by other library
+ * functions; you must not call it directly.
*
* \param ctx AES context
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
@@ -62,12 +77,15 @@
* \return 0 on success (cannot fail)
*/
int mbedtls_aesni_crypt_ecb( mbedtls_aes_context *ctx,
- int mode,
- const unsigned char input[16],
- unsigned char output[16] );
+ int mode,
+ const unsigned char input[16],
+ unsigned char output[16] );
/**
- * \brief GCM multiplication: c = a * b in GF(2^128)
+ * \brief Internal GCM multiplication: c = a * b in GF(2^128)
+ *
+ * \note This function is only for internal use by other library
+ * functions; you must not call it directly.
*
* \param c Result
* \param a First operand
@@ -77,21 +95,29 @@
* elements of GF(2^128) as per the GCM spec.
*/
void mbedtls_aesni_gcm_mult( unsigned char c[16],
- const unsigned char a[16],
- const unsigned char b[16] );
+ const unsigned char a[16],
+ const unsigned char b[16] );
/**
- * \brief Compute decryption round keys from encryption round keys
+ * \brief Internal round key inversion. This function computes
+ * decryption round keys from the encryption round keys.
+ *
+ * \note This function is only for internal use by other library
+ * functions; you must not call it directly.
*
* \param invkey Round keys for the equivalent inverse cipher
* \param fwdkey Original round keys (for encryption)
* \param nr Number of rounds (that is, number of round keys minus one)
*/
void mbedtls_aesni_inverse_key( unsigned char *invkey,
- const unsigned char *fwdkey, int nr );
+ const unsigned char *fwdkey,
+ int nr );
/**
- * \brief Perform key expansion (for encryption)
+ * \brief Internal key expansion for encryption
+ *
+ * \note This function is only for internal use by other library
+ * functions; you must not call it directly.
*
* \param rk Destination buffer where the round keys are written
* \param key Encryption key
@@ -100,8 +126,8 @@
* \return 0 if successful, or MBEDTLS_ERR_AES_INVALID_KEY_LENGTH
*/
int mbedtls_aesni_setkey_enc( unsigned char *rk,
- const unsigned char *key,
- size_t bits );
+ const unsigned char *key,
+ size_t bits );
#ifdef __cplusplus
}
diff --git a/include/mbedtls/arc4.h b/include/mbedtls/arc4.h
index c43f406..fb044d5 100644
--- a/include/mbedtls/arc4.h
+++ b/include/mbedtls/arc4.h
@@ -123,6 +123,8 @@
int mbedtls_arc4_crypt( mbedtls_arc4_context *ctx, size_t length, const unsigned char *input,
unsigned char *output );
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief Checkup routine
*
@@ -135,6 +137,8 @@
*/
int mbedtls_arc4_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/aria.h b/include/mbedtls/aria.h
index 483d4c2..1e8956e 100644
--- a/include/mbedtls/aria.h
+++ b/include/mbedtls/aria.h
@@ -39,6 +39,8 @@
#include <stddef.h>
#include <stdint.h>
+#include "platform_util.h"
+
#define MBEDTLS_ARIA_ENCRYPT 1 /**< ARIA encryption. */
#define MBEDTLS_ARIA_DECRYPT 0 /**< ARIA decryption. */
@@ -46,8 +48,12 @@
#define MBEDTLS_ARIA_MAX_ROUNDS 16 /**< Maxiumum number of rounds in ARIA. */
#define MBEDTLS_ARIA_MAX_KEYSIZE 32 /**< Maximum size of an ARIA key in bytes. */
-#define MBEDTLS_ERR_ARIA_INVALID_KEY_LENGTH -0x005C /**< Invalid key length. */
-#define MBEDTLS_ERR_ARIA_INVALID_INPUT_LENGTH -0x005E /**< Invalid data input length. */
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define MBEDTLS_ERR_ARIA_INVALID_KEY_LENGTH MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( -0x005C )
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+#define MBEDTLS_ERR_ARIA_BAD_INPUT_DATA -0x005C /**< Bad input data. */
+
+#define MBEDTLS_ERR_ARIA_INVALID_INPUT_LENGTH -0x005E /**< Invalid data input length. */
/* MBEDTLS_ERR_ARIA_FEATURE_UNAVAILABLE is deprecated and should not be used.
*/
@@ -85,14 +91,16 @@
* It must be the first API called before using
* the context.
*
- * \param ctx The ARIA context to initialize.
+ * \param ctx The ARIA context to initialize. This must not be \c NULL.
*/
void mbedtls_aria_init( mbedtls_aria_context *ctx );
/**
* \brief This function releases and clears the specified ARIA context.
*
- * \param ctx The ARIA context to clear.
+ * \param ctx The ARIA context to clear. This may be \c NULL, in which
+ * case this function returns immediately. If it is not \c NULL,
+ * it must point to an initialized ARIA context.
*/
void mbedtls_aria_free( mbedtls_aria_context *ctx );
@@ -100,14 +108,16 @@
* \brief This function sets the encryption key.
*
* \param ctx The ARIA context to which the key should be bound.
- * \param key The encryption key.
- * \param keybits The size of data passed in bits. Valid options are:
+ * This must be initialized.
+ * \param key The encryption key. This must be a readable buffer
+ * of size \p keybits Bits.
+ * \param keybits The size of \p key in Bits. Valid options are:
* <ul><li>128 bits</li>
* <li>192 bits</li>
* <li>256 bits</li></ul>
*
- * \return \c 0 on success or #MBEDTLS_ERR_ARIA_INVALID_KEY_LENGTH
- * on failure.
+ * \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_aria_setkey_enc( mbedtls_aria_context *ctx,
const unsigned char *key,
@@ -117,13 +127,16 @@
* \brief This function sets the decryption key.
*
* \param ctx The ARIA context to which the key should be bound.
- * \param key The decryption key.
+ * This must be initialized.
+ * \param key The decryption key. This must be a readable buffer
+ * of size \p keybits Bits.
* \param keybits The size of data passed. Valid options are:
* <ul><li>128 bits</li>
* <li>192 bits</li>
* <li>256 bits</li></ul>
*
- * \return \c 0 on success, or #MBEDTLS_ERR_ARIA_INVALID_KEY_LENGTH on failure.
+ * \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_aria_setkey_dec( mbedtls_aria_context *ctx,
const unsigned char *key,
@@ -142,10 +155,12 @@
* call to this API with the same context.
*
* \param ctx The ARIA context to use for encryption or decryption.
+ * This must be initialized and bound to a key.
* \param input The 16-Byte buffer holding the input data.
* \param output The 16-Byte buffer holding the output data.
* \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_aria_crypt_ecb( mbedtls_aria_context *ctx,
const unsigned char input[MBEDTLS_ARIA_BLOCKSIZE],
@@ -177,16 +192,21 @@
*
*
* \param ctx The ARIA context to use for encryption or decryption.
- * \param mode The ARIA operation: #MBEDTLS_ARIA_ENCRYPT or
- * #MBEDTLS_ARIA_DECRYPT.
+ * This must be initialized and bound to a key.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_ARIA_ENCRYPT for encryption, or
+ * #MBEDTLS_ARIA_DECRYPT for decryption.
* \param length The length of the input data in Bytes. This must be a
* multiple of the block size (16 Bytes).
* \param iv Initialization vector (updated after use).
- * \param input The buffer holding the input data.
- * \param output The buffer holding the output data.
+ * This must be a readable buffer of size 16 Bytes.
+ * \param input The buffer holding the input data. This must
+ * be a readable buffer of length \p length Bytes.
+ * \param output The buffer holding the output data. This must
+ * be a writable buffer of length \p length Bytes.
*
- * \return \c 0 on success, or #MBEDTLS_ERR_ARIA_INVALID_INPUT_LENGTH
- * on failure.
+ * \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_aria_crypt_cbc( mbedtls_aria_context *ctx,
int mode,
@@ -221,15 +241,22 @@
*
*
* \param ctx The ARIA context to use for encryption or decryption.
- * \param mode The ARIA operation: #MBEDTLS_ARIA_ENCRYPT or
- * #MBEDTLS_ARIA_DECRYPT.
- * \param length The length of the input data.
+ * This must be initialized and bound to a key.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_ARIA_ENCRYPT for encryption, or
+ * #MBEDTLS_ARIA_DECRYPT for decryption.
+ * \param length The length of the input data \p input in Bytes.
* \param iv_off The offset in IV (updated after use).
+ * This must not be larger than 15.
* \param iv The initialization vector (updated after use).
- * \param input The buffer holding the input data.
- * \param output The buffer holding the output data.
+ * This must be a readable buffer of size 16 Bytes.
+ * \param input The buffer holding the input data. This must
+ * be a readable buffer of length \p length Bytes.
+ * \param output The buffer holding the output data. This must
+ * be a writable buffer of length \p length Bytes.
*
* \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_aria_crypt_cfb128( mbedtls_aria_context *ctx,
int mode,
@@ -299,17 +326,24 @@
* securely discarded as soon as it's no longer needed.
*
* \param ctx The ARIA context to use for encryption or decryption.
- * \param length The length of the input data.
- * \param nc_off The offset in the current \p stream_block, for
- * resuming within the current cipher stream. The
- * offset pointer should be 0 at the start of a stream.
- * \param nonce_counter The 128-bit nonce and counter.
- * \param stream_block The saved stream block for resuming. This is
- * overwritten by the function.
- * \param input The buffer holding the input data.
- * \param output The buffer holding the output data.
+ * This must be initialized and bound to a key.
+ * \param length The length of the input data \p input in Bytes.
+ * \param nc_off The offset in Bytes in the current \p stream_block,
+ * for resuming within the current cipher stream. The
+ * offset pointer should be \c 0 at the start of a
+ * stream. This must not be larger than \c 15 Bytes.
+ * \param nonce_counter The 128-bit nonce and counter. This must point to
+ * a read/write buffer of length \c 16 bytes.
+ * \param stream_block The saved stream block for resuming. This must
+ * point to a read/write buffer of length \c 16 bytes.
+ * This is overwritten by the function.
+ * \param input The buffer holding the input data. This must
+ * be a readable buffer of length \p length Bytes.
+ * \param output The buffer holding the output data. This must
+ * be a writable buffer of length \p length Bytes.
*
- * \return \c 0 on success.
+ * \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_aria_crypt_ctr( mbedtls_aria_context *ctx,
size_t length,
diff --git a/include/mbedtls/asn1.h b/include/mbedtls/asn1.h
index 96c1c9a..f80acd7 100644
--- a/include/mbedtls/asn1.h
+++ b/include/mbedtls/asn1.h
@@ -66,7 +66,7 @@
* - 0x02 -- tag indicating INTEGER
* - 0x01 -- length in octets
* - 0x05 -- value
- * Such sequences are typically read into \c ::mbedtls_x509_buf.
+ * Such sequences are typically read into Mbed TLS's \c mbedtls_x509_buf.
* \{
*/
#define MBEDTLS_ASN1_BOOLEAN 0x01
diff --git a/include/mbedtls/asn1write.h b/include/mbedtls/asn1write.h
index 76c1780..dc81782 100644
--- a/include/mbedtls/asn1write.h
+++ b/include/mbedtls/asn1write.h
@@ -24,6 +24,12 @@
#ifndef MBEDTLS_ASN1_WRITE_H
#define MBEDTLS_ASN1_WRITE_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "asn1.h"
#define MBEDTLS_ASN1_CHK_ADD(g, f) \
@@ -277,6 +283,28 @@
const unsigned char *buf, size_t bits );
/**
+ * \brief This function writes a named bitstring tag
+ * (#MBEDTLS_ASN1_BIT_STRING) and value in ASN.1 format.
+ *
+ * As stated in RFC 5280 Appendix B, trailing zeroes are
+ * omitted when encoding named bitstrings in DER.
+ *
+ * \note This function works backwards within the data buffer.
+ *
+ * \param p The reference to the current position pointer.
+ * \param start The start of the buffer which is used for bounds-checking.
+ * \param buf The bitstring to write.
+ * \param bits The total number of bits in the bitstring.
+ *
+ * \return The number of bytes written to \p p on success.
+ * \return A negative error code on failure.
+ */
+int mbedtls_asn1_write_named_bitstring( unsigned char **p,
+ unsigned char *start,
+ const unsigned char *buf,
+ size_t bits );
+
+/**
* \brief Write an octet string tag (#MBEDTLS_ASN1_OCTET_STRING)
* and value in ASN.1 format.
*
diff --git a/include/mbedtls/base64.h b/include/mbedtls/base64.h
index 7a64f52..0d02416 100644
--- a/include/mbedtls/base64.h
+++ b/include/mbedtls/base64.h
@@ -24,6 +24,12 @@
#ifndef MBEDTLS_BASE64_H
#define MBEDTLS_BASE64_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include <stddef.h>
#define MBEDTLS_ERR_BASE64_BUFFER_TOO_SMALL -0x002A /**< Output buffer too small. */
@@ -75,6 +81,7 @@
int mbedtls_base64_decode( unsigned char *dst, size_t dlen, size_t *olen,
const unsigned char *src, size_t slen );
+#if defined(MBEDTLS_SELF_TEST)
/**
* \brief Checkup routine
*
@@ -82,6 +89,8 @@
*/
int mbedtls_base64_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h
index 40cfab4..c4d7686 100644
--- a/include/mbedtls/bignum.h
+++ b/include/mbedtls/bignum.h
@@ -186,96 +186,115 @@
mbedtls_mpi;
/**
- * \brief Initialize one MPI (make internal references valid)
- * This just makes it ready to be set or freed,
+ * \brief Initialize an MPI context.
+ *
+ * This makes the MPI ready to be set or freed,
* but does not define a value for the MPI.
*
- * \param X One MPI to initialize.
+ * \param X The MPI context to initialize. This must not be \c NULL.
*/
void mbedtls_mpi_init( mbedtls_mpi *X );
/**
- * \brief Unallocate one MPI
+ * \brief This function frees the components of an MPI context.
*
- * \param X One MPI to unallocate.
+ * \param X The MPI context to be cleared. This may be \c NULL,
+ * in which case this function is a no-op. If it is
+ * not \c NULL, it must point to an initialized MPI.
*/
void mbedtls_mpi_free( mbedtls_mpi *X );
/**
- * \brief Enlarge to the specified number of limbs
+ * \brief Enlarge an MPI to the specified number of limbs.
*
- * This function does nothing if the MPI is already large enough.
+ * \note This function does nothing if the MPI is
+ * already large enough.
*
- * \param X MPI to grow
- * \param nblimbs The target number of limbs
+ * \param X The MPI to grow. It must be initialized.
+ * \param nblimbs The target number of limbs.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return Another negative error code on other kinds of failure.
*/
int mbedtls_mpi_grow( mbedtls_mpi *X, size_t nblimbs );
/**
- * \brief Resize down, keeping at least the specified number of limbs
+ * \brief This function resizes an MPI downwards, keeping at least the
+ * specified number of limbs.
*
* If \c X is smaller than \c nblimbs, it is resized up
* instead.
*
- * \param X MPI to shrink
- * \param nblimbs The minimum number of limbs to keep
+ * \param X The MPI to shrink. This must point to an initialized MPI.
+ * \param nblimbs The minimum number of limbs to keep.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
* (this can only happen when resizing up).
+ * \return Another negative error code on other kinds of failure.
*/
int mbedtls_mpi_shrink( mbedtls_mpi *X, size_t nblimbs );
/**
- * \brief Copy the contents of Y into X
+ * \brief Make a copy of an MPI.
*
- * \param X Destination MPI. It is enlarged if necessary.
- * \param Y Source MPI.
+ * \param X The destination MPI. This must point to an initialized MPI.
+ * \param Y The source MPI. This must point to an initialized MPI.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \note The limb-buffer in the destination MPI is enlarged
+ * if necessary to hold the value in the source MPI.
+ *
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return Another negative error code on other kinds of failure.
*/
int mbedtls_mpi_copy( mbedtls_mpi *X, const mbedtls_mpi *Y );
/**
- * \brief Swap the contents of X and Y
+ * \brief Swap the contents of two MPIs.
*
- * \param X First MPI value
- * \param Y Second MPI value
+ * \param X The first MPI. It must be initialized.
+ * \param Y The second MPI. It must be initialized.
*/
void mbedtls_mpi_swap( mbedtls_mpi *X, mbedtls_mpi *Y );
/**
- * \brief Safe conditional assignement X = Y if assign is 1
+ * \brief Perform a safe conditional copy of MPI which doesn't
+ * reveal whether the condition was true or not.
*
- * \param X MPI to conditionally assign to
- * \param Y Value to be assigned
- * \param assign 1: perform the assignment, 0: keep X's original value
- *
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
+ * \param X The MPI to conditionally assign to. This must point
+ * to an initialized MPI.
+ * \param Y The MPI to be assigned from. This must point to an
+ * initialized MPI.
+ * \param assign The condition deciding whether to perform the
+ * assignment or not. Possible values:
+ * * \c 1: Perform the assignment `X = Y`.
+ * * \c 0: Keep the original value of \p X.
*
* \note This function is equivalent to
- * if( assign ) mbedtls_mpi_copy( X, Y );
+ * `if( assign ) mbedtls_mpi_copy( X, Y );`
* except that it avoids leaking any information about whether
* the assignment was done or not (the above code may leak
* information through branch prediction and/or memory access
* patterns analysis).
+ *
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return Another negative error code on other kinds of failure.
*/
int mbedtls_mpi_safe_cond_assign( mbedtls_mpi *X, const mbedtls_mpi *Y, unsigned char assign );
/**
- * \brief Safe conditional swap X <-> Y if swap is 1
+ * \brief Perform a safe conditional swap which doesn't
+ * reveal whether the condition was true or not.
*
- * \param X First mbedtls_mpi value
- * \param Y Second mbedtls_mpi value
- * \param assign 1: perform the swap, 0: keep X and Y's original values
- *
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
+ * \param X The first MPI. This must be initialized.
+ * \param Y The second MPI. This must be initialized.
+ * \param assign The condition deciding whether to perform
+ * the swap or not. Possible values:
+ * * \c 1: Swap the values of \p X and \p Y.
+ * * \c 0: Keep the original values of \p X and \p Y.
*
* \note This function is equivalent to
* if( assign ) mbedtls_mpi_swap( X, Y );
@@ -283,415 +302,546 @@
* the assignment was done or not (the above code may leak
* information through branch prediction and/or memory access
* patterns analysis).
+ *
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return Another negative error code on other kinds of failure.
+ *
*/
int mbedtls_mpi_safe_cond_swap( mbedtls_mpi *X, mbedtls_mpi *Y, unsigned char assign );
/**
- * \brief Set value from integer
+ * \brief Store integer value in MPI.
*
- * \param X MPI to set
- * \param z Value to use
+ * \param X The MPI to set. This must be initialized.
+ * \param z The value to use.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return Another negative error code on other kinds of failure.
*/
int mbedtls_mpi_lset( mbedtls_mpi *X, mbedtls_mpi_sint z );
/**
- * \brief Get a specific bit from X
+ * \brief Get a specific bit from an MPI.
*
- * \param X MPI to use
- * \param pos Zero-based index of the bit in X
+ * \param X The MPI to query. This must be initialized.
+ * \param pos Zero-based index of the bit to query.
*
- * \return Either a 0 or a 1
+ * \return \c 0 or \c 1 on success, depending on whether bit \c pos
+ * of \c X is unset or set.
+ * \return A negative error code on failure.
*/
int mbedtls_mpi_get_bit( const mbedtls_mpi *X, size_t pos );
/**
- * \brief Set a bit of X to a specific value of 0 or 1
+ * \brief Modify a specific bit in an MPI.
*
- * \note Will grow X if necessary to set a bit to 1 in a not yet
- * existing limb. Will not grow if bit should be set to 0
+ * \note This function will grow the target MPI if necessary to set a
+ * bit to \c 1 in a not yet existing limb. It will not grow if
+ * the bit should be set to \c 0.
*
- * \param X MPI to use
- * \param pos Zero-based index of the bit in X
- * \param val The value to set the bit to (0 or 1)
+ * \param X The MPI to modify. This must be initialized.
+ * \param pos Zero-based index of the bit to modify.
+ * \param val The desired value of bit \c pos: \c 0 or \c 1.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- * MBEDTLS_ERR_MPI_BAD_INPUT_DATA if val is not 0 or 1
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return Another negative error code on other kinds of failure.
*/
int mbedtls_mpi_set_bit( mbedtls_mpi *X, size_t pos, unsigned char val );
/**
- * \brief Return the number of zero-bits before the least significant
- * '1' bit
+ * \brief Return the number of bits of value \c 0 before the
+ * least significant bit of value \c 1.
*
- * Note: Thus also the zero-based index of the least significant '1' bit
+ * \note This is the same as the zero-based index of
+ * the least significant bit of value \c 1.
*
- * \param X MPI to use
+ * \param X The MPI to query.
+ *
+ * \return The number of bits of value \c 0 before the least significant
+ * bit of value \c 1 in \p X.
*/
size_t mbedtls_mpi_lsb( const mbedtls_mpi *X );
/**
* \brief Return the number of bits up to and including the most
- * significant '1' bit'
+ * significant bit of value \c 1.
*
- * Note: Thus also the one-based index of the most significant '1' bit
+ * * \note This is same as the one-based index of the most
+ * significant bit of value \c 1.
*
- * \param X MPI to use
+ * \param X The MPI to query. This must point to an initialized MPI.
+ *
+ * \return The number of bits up to and including the most
+ * significant bit of value \c 1.
*/
size_t mbedtls_mpi_bitlen( const mbedtls_mpi *X );
/**
- * \brief Return the total size in bytes
+ * \brief Return the total size of an MPI value in bytes.
*
- * \param X MPI to use
+ * \param X The MPI to use. This must point to an initialized MPI.
+ *
+ * \note The value returned by this function may be less than
+ * the number of bytes used to store \p X internally.
+ * This happens if and only if there are trailing bytes
+ * of value zero.
+ *
+ * \return The least number of bytes capable of storing
+ * the absolute value of \p X.
*/
size_t mbedtls_mpi_size( const mbedtls_mpi *X );
/**
- * \brief Import from an ASCII string
+ * \brief Import an MPI from an ASCII string.
*
- * \param X Destination MPI
- * \param radix Input numeric base
- * \param s Null-terminated string buffer
+ * \param X The destination MPI. This must point to an initialized MPI.
+ * \param radix The numeric base of the input string.
+ * \param s Null-terminated string buffer.
*
- * \return 0 if successful, or a MBEDTLS_ERR_MPI_XXX error code
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
int mbedtls_mpi_read_string( mbedtls_mpi *X, int radix, const char *s );
/**
- * \brief Export into an ASCII string
+ * \brief Export an MPI to an ASCII string.
*
- * \param X Source MPI
- * \param radix Output numeric base
- * \param buf Buffer to write the string to
- * \param buflen Length of buf
- * \param olen Length of the string written, including final NUL byte
+ * \param X The source MPI. This must point to an initialized MPI.
+ * \param radix The numeric base of the output string.
+ * \param buf The buffer to write the string to. This must be writable
+ * buffer of length \p buflen Bytes.
+ * \param buflen The available size in Bytes of \p buf.
+ * \param olen The address at which to store the length of the string
+ * written, including the final \c NULL byte. This must
+ * not be \c NULL.
*
- * \return 0 if successful, or a MBEDTLS_ERR_MPI_XXX error code.
- * *olen is always updated to reflect the amount
- * of data that has (or would have) been written.
+ * \note You can call this function with `buflen == 0` to obtain the
+ * minimum required buffer size in `*olen`.
*
- * \note Call this function with buflen = 0 to obtain the
- * minimum required buffer size in *olen.
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if the target buffer \p buf
+ * is too small to hold the value of \p X in the desired base.
+ * In this case, `*olen` is nonetheless updated to contain the
+ * size of \p buf required for a successful call.
+ * \return Another negative error code on different kinds of failure.
*/
int mbedtls_mpi_write_string( const mbedtls_mpi *X, int radix,
char *buf, size_t buflen, size_t *olen );
#if defined(MBEDTLS_FS_IO)
/**
- * \brief Read MPI from a line in an opened file
+ * \brief Read an MPI from a line in an opened file.
*
- * \param X Destination MPI
- * \param radix Input numeric base
- * \param fin Input file handle
- *
- * \return 0 if successful, MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if
- * the file read buffer is too small or a
- * MBEDTLS_ERR_MPI_XXX error code
+ * \param X The destination MPI. This must point to an initialized MPI.
+ * \param radix The numeric base of the string representation used
+ * in the source line.
+ * \param fin The input file handle to use. This must not be \c NULL.
*
* \note On success, this function advances the file stream
* to the end of the current line or to EOF.
*
- * The function returns 0 on an empty line.
+ * The function returns \c 0 on an empty line.
*
* Leading whitespaces are ignored, as is a
- * '0x' prefix for radix 16.
+ * '0x' prefix for radix \c 16.
*
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if the file read buffer
+ * is too small.
+ * \return Another negative error code on failure.
*/
int mbedtls_mpi_read_file( mbedtls_mpi *X, int radix, FILE *fin );
/**
- * \brief Write X into an opened file, or stdout if fout is NULL
+ * \brief Export an MPI into an opened file.
*
- * \param p Prefix, can be NULL
- * \param X Source MPI
- * \param radix Output numeric base
- * \param fout Output file handle (can be NULL)
+ * \param p A string prefix to emit prior to the MPI data.
+ * For example, this might be a label, or "0x" when
+ * printing in base \c 16. This may be \c NULL if no prefix
+ * is needed.
+ * \param X The source MPI. This must point to an initialized MPI.
+ * \param radix The numeric base to be used in the emitted string.
+ * \param fout The output file handle. This may be \c NULL, in which case
+ * the output is written to \c stdout.
*
- * \return 0 if successful, or a MBEDTLS_ERR_MPI_XXX error code
- *
- * \note Set fout == NULL to print X on the console.
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
-int mbedtls_mpi_write_file( const char *p, const mbedtls_mpi *X, int radix, FILE *fout );
+int mbedtls_mpi_write_file( const char *p, const mbedtls_mpi *X,
+ int radix, FILE *fout );
#endif /* MBEDTLS_FS_IO */
/**
- * \brief Import X from unsigned binary data, big endian
+ * \brief Import an MPI from unsigned big endian binary data.
*
- * \param X Destination MPI
- * \param buf Input buffer
- * \param buflen Input buffer size
+ * \param X The destination MPI. This must point to an initialized MPI.
+ * \param buf The input buffer. This must be a readable buffer of length
+ * \p buflen Bytes.
+ * \param buflen The length of the input buffer \p p in Bytes.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return Another negative error code on different kinds of failure.
*/
-int mbedtls_mpi_read_binary( mbedtls_mpi *X, const unsigned char *buf, size_t buflen );
+int mbedtls_mpi_read_binary( mbedtls_mpi *X, const unsigned char *buf,
+ size_t buflen );
+
+/**
+ * \brief Import X from unsigned binary data, little endian
+ *
+ * \param X The destination MPI. This must point to an initialized MPI.
+ * \param buf The input buffer. This must be a readable buffer of length
+ * \p buflen Bytes.
+ * \param buflen The length of the input buffer \p p in Bytes.
+ *
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return Another negative error code on different kinds of failure.
+ */
+int mbedtls_mpi_read_binary_le( mbedtls_mpi *X,
+ const unsigned char *buf, size_t buflen );
/**
* \brief Export X into unsigned binary data, big endian.
* Always fills the whole buffer, which will start with zeros
* if the number is smaller.
*
- * \param X Source MPI
- * \param buf Output buffer
- * \param buflen Output buffer size
+ * \param X The source MPI. This must point to an initialized MPI.
+ * \param buf The output buffer. This must be a writable buffer of length
+ * \p buflen Bytes.
+ * \param buflen The size of the output buffer \p buf in Bytes.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if buf isn't large enough
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p buf isn't
+ * large enough to hold the value of \p X.
+ * \return Another negative error code on different kinds of failure.
*/
-int mbedtls_mpi_write_binary( const mbedtls_mpi *X, unsigned char *buf, size_t buflen );
+int mbedtls_mpi_write_binary( const mbedtls_mpi *X, unsigned char *buf,
+ size_t buflen );
/**
- * \brief Left-shift: X <<= count
+ * \brief Export X into unsigned binary data, little endian.
+ * Always fills the whole buffer, which will end with zeros
+ * if the number is smaller.
*
- * \param X MPI to shift
- * \param count Amount to shift
+ * \param X The source MPI. This must point to an initialized MPI.
+ * \param buf The output buffer. This must be a writable buffer of length
+ * \p buflen Bytes.
+ * \param buflen The size of the output buffer \p buf in Bytes.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p buf isn't
+ * large enough to hold the value of \p X.
+ * \return Another negative error code on different kinds of failure.
+ */
+int mbedtls_mpi_write_binary_le( const mbedtls_mpi *X,
+ unsigned char *buf, size_t buflen );
+
+/**
+ * \brief Perform a left-shift on an MPI: X <<= count
+ *
+ * \param X The MPI to shift. This must point to an initialized MPI.
+ * \param count The number of bits to shift by.
+ *
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return Another negative error code on different kinds of failure.
*/
int mbedtls_mpi_shift_l( mbedtls_mpi *X, size_t count );
/**
- * \brief Right-shift: X >>= count
+ * \brief Perform a right-shift on an MPI: X >>= count
*
- * \param X MPI to shift
- * \param count Amount to shift
+ * \param X The MPI to shift. This must point to an initialized MPI.
+ * \param count The number of bits to shift by.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return Another negative error code on different kinds of failure.
*/
int mbedtls_mpi_shift_r( mbedtls_mpi *X, size_t count );
/**
- * \brief Compare unsigned values
+ * \brief Compare the absolute values of two MPIs.
*
- * \param X Left-hand MPI
- * \param Y Right-hand MPI
+ * \param X The left-hand MPI. This must point to an initialized MPI.
+ * \param Y The right-hand MPI. This must point to an initialized MPI.
*
- * \return 1 if |X| is greater than |Y|,
- * -1 if |X| is lesser than |Y| or
- * 0 if |X| is equal to |Y|
+ * \return \c 1 if `|X|` is greater than `|Y|`.
+ * \return \c -1 if `|X|` is lesser than `|Y|`.
+ * \return \c 0 if `|X|` is equal to `|Y|`.
*/
int mbedtls_mpi_cmp_abs( const mbedtls_mpi *X, const mbedtls_mpi *Y );
/**
- * \brief Compare signed values
+ * \brief Compare two MPIs.
*
- * \param X Left-hand MPI
- * \param Y Right-hand MPI
+ * \param X The left-hand MPI. This must point to an initialized MPI.
+ * \param Y The right-hand MPI. This must point to an initialized MPI.
*
- * \return 1 if X is greater than Y,
- * -1 if X is lesser than Y or
- * 0 if X is equal to Y
+ * \return \c 1 if \p X is greater than \p Y.
+ * \return \c -1 if \p X is lesser than \p Y.
+ * \return \c 0 if \p X is equal to \p Y.
*/
int mbedtls_mpi_cmp_mpi( const mbedtls_mpi *X, const mbedtls_mpi *Y );
/**
- * \brief Compare signed values
+ * \brief Compare an MPI with an integer.
*
- * \param X Left-hand MPI
- * \param z The integer value to compare to
+ * \param X The left-hand MPI. This must point to an initialized MPI.
+ * \param z The integer value to compare \p X to.
*
- * \return 1 if X is greater than z,
- * -1 if X is lesser than z or
- * 0 if X is equal to z
+ * \return \c 1 if \p X is greater than \p z.
+ * \return \c -1 if \p X is lesser than \p z.
+ * \return \c 0 if \p X is equal to \p z.
*/
int mbedtls_mpi_cmp_int( const mbedtls_mpi *X, mbedtls_mpi_sint z );
/**
- * \brief Unsigned addition: X = |A| + |B|
+ * \brief Perform an unsigned addition of MPIs: X = |A| + |B|
*
- * \param X Destination MPI
- * \param A Left-hand MPI
- * \param B Right-hand MPI
+ * \param X The destination MPI. This must point to an initialized MPI.
+ * \param A The first summand. This must point to an initialized MPI.
+ * \param B The second summand. This must point to an initialized MPI.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return Another negative error code on different kinds of failure.
*/
-int mbedtls_mpi_add_abs( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B );
+int mbedtls_mpi_add_abs( mbedtls_mpi *X, const mbedtls_mpi *A,
+ const mbedtls_mpi *B );
/**
- * \brief Unsigned subtraction: X = |A| - |B|
+ * \brief Perform an unsigned subtraction of MPIs: X = |A| - |B|
*
- * \param X Destination MPI
- * \param A Left-hand MPI
- * \param B Right-hand MPI
+ * \param X The destination MPI. This must point to an initialized MPI.
+ * \param A The minuend. This must point to an initialized MPI.
+ * \param B The subtrahend. This must point to an initialized MPI.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_NEGATIVE_VALUE if B is greater than A
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if \p B is greater than \p A.
+ * \return Another negative error code on different kinds of failure.
+ *
*/
-int mbedtls_mpi_sub_abs( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B );
+int mbedtls_mpi_sub_abs( mbedtls_mpi *X, const mbedtls_mpi *A,
+ const mbedtls_mpi *B );
/**
- * \brief Signed addition: X = A + B
+ * \brief Perform a signed addition of MPIs: X = A + B
*
- * \param X Destination MPI
- * \param A Left-hand MPI
- * \param B Right-hand MPI
+ * \param X The destination MPI. This must point to an initialized MPI.
+ * \param A The first summand. This must point to an initialized MPI.
+ * \param B The second summand. This must point to an initialized MPI.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return Another negative error code on different kinds of failure.
*/
-int mbedtls_mpi_add_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B );
+int mbedtls_mpi_add_mpi( mbedtls_mpi *X, const mbedtls_mpi *A,
+ const mbedtls_mpi *B );
/**
- * \brief Signed subtraction: X = A - B
+ * \brief Perform a signed subtraction of MPIs: X = A - B
*
- * \param X Destination MPI
- * \param A Left-hand MPI
- * \param B Right-hand MPI
+ * \param X The destination MPI. This must point to an initialized MPI.
+ * \param A The minuend. This must point to an initialized MPI.
+ * \param B The subtrahend. This must point to an initialized MPI.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return Another negative error code on different kinds of failure.
*/
-int mbedtls_mpi_sub_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B );
+int mbedtls_mpi_sub_mpi( mbedtls_mpi *X, const mbedtls_mpi *A,
+ const mbedtls_mpi *B );
/**
- * \brief Signed addition: X = A + b
+ * \brief Perform a signed addition of an MPI and an integer: X = A + b
*
- * \param X Destination MPI
- * \param A Left-hand MPI
- * \param b The integer value to add
+ * \param X The destination MPI. This must point to an initialized MPI.
+ * \param A The first summand. This must point to an initialized MPI.
+ * \param b The second summand.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return Another negative error code on different kinds of failure.
*/
-int mbedtls_mpi_add_int( mbedtls_mpi *X, const mbedtls_mpi *A, mbedtls_mpi_sint b );
+int mbedtls_mpi_add_int( mbedtls_mpi *X, const mbedtls_mpi *A,
+ mbedtls_mpi_sint b );
/**
- * \brief Signed subtraction: X = A - b
+ * \brief Perform a signed subtraction of an MPI and an integer:
+ * X = A - b
*
- * \param X Destination MPI
- * \param A Left-hand MPI
- * \param b The integer value to subtract
+ * \param X The destination MPI. This must point to an initialized MPI.
+ * \param A The minuend. This must point to an initialized MPI.
+ * \param b The subtrahend.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return Another negative error code on different kinds of failure.
*/
-int mbedtls_mpi_sub_int( mbedtls_mpi *X, const mbedtls_mpi *A, mbedtls_mpi_sint b );
+int mbedtls_mpi_sub_int( mbedtls_mpi *X, const mbedtls_mpi *A,
+ mbedtls_mpi_sint b );
/**
- * \brief Baseline multiplication: X = A * B
+ * \brief Perform a multiplication of two MPIs: X = A * B
*
- * \param X Destination MPI
- * \param A Left-hand MPI
- * \param B Right-hand MPI
+ * \param X The destination MPI. This must point to an initialized MPI.
+ * \param A The first factor. This must point to an initialized MPI.
+ * \param B The second factor. This must point to an initialized MPI.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return Another negative error code on different kinds of failure.
+ *
*/
-int mbedtls_mpi_mul_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B );
+int mbedtls_mpi_mul_mpi( mbedtls_mpi *X, const mbedtls_mpi *A,
+ const mbedtls_mpi *B );
/**
- * \brief Baseline multiplication: X = A * b
+ * \brief Perform a multiplication of an MPI with an unsigned integer:
+ * X = A * b
*
- * \param X Destination MPI
- * \param A Left-hand MPI
- * \param b The unsigned integer value to multiply with
+ * \param X The destination MPI. This must point to an initialized MPI.
+ * \param A The first factor. This must point to an initialized MPI.
+ * \param b The second factor.
*
- * \note b is unsigned
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return Another negative error code on different kinds of failure.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
*/
-int mbedtls_mpi_mul_int( mbedtls_mpi *X, const mbedtls_mpi *A, mbedtls_mpi_uint b );
+int mbedtls_mpi_mul_int( mbedtls_mpi *X, const mbedtls_mpi *A,
+ mbedtls_mpi_uint b );
/**
- * \brief Division by mbedtls_mpi: A = Q * B + R
+ * \brief Perform a division with remainder of two MPIs:
+ * A = Q * B + R
*
- * \param Q Destination MPI for the quotient
- * \param R Destination MPI for the rest value
- * \param A Left-hand MPI
- * \param B Right-hand MPI
+ * \param Q The destination MPI for the quotient.
+ * This may be \c NULL if the value of the
+ * quotient is not needed.
+ * \param R The destination MPI for the remainder value.
+ * This may be \c NULL if the value of the
+ * remainder is not needed.
+ * \param A The dividend. This must point to an initialized MPi.
+ * \param B The divisor. This must point to an initialized MPI.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- * MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if B == 0
- *
- * \note Either Q or R can be NULL.
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p B equals zero.
+ * \return Another negative error code on different kinds of failure.
*/
-int mbedtls_mpi_div_mpi( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, const mbedtls_mpi *B );
+int mbedtls_mpi_div_mpi( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A,
+ const mbedtls_mpi *B );
/**
- * \brief Division by int: A = Q * b + R
+ * \brief Perform a division with remainder of an MPI by an integer:
+ * A = Q * b + R
*
- * \param Q Destination MPI for the quotient
- * \param R Destination MPI for the rest value
- * \param A Left-hand MPI
- * \param b Integer to divide by
+ * \param Q The destination MPI for the quotient.
+ * This may be \c NULL if the value of the
+ * quotient is not needed.
+ * \param R The destination MPI for the remainder value.
+ * This may be \c NULL if the value of the
+ * remainder is not needed.
+ * \param A The dividend. This must point to an initialized MPi.
+ * \param b The divisor.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- * MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if b == 0
- *
- * \note Either Q or R can be NULL.
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p b equals zero.
+ * \return Another negative error code on different kinds of failure.
*/
-int mbedtls_mpi_div_int( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, mbedtls_mpi_sint b );
+int mbedtls_mpi_div_int( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A,
+ mbedtls_mpi_sint b );
/**
- * \brief Modulo: R = A mod B
+ * \brief Perform a modular reduction. R = A mod B
*
- * \param R Destination MPI for the rest value
- * \param A Left-hand MPI
- * \param B Right-hand MPI
+ * \param R The destination MPI for the residue value.
+ * This must point to an initialized MPI.
+ * \param A The MPI to compute the residue of.
+ * This must point to an initialized MPI.
+ * \param B The base of the modular reduction.
+ * This must point to an initialized MPI.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- * MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if B == 0,
- * MBEDTLS_ERR_MPI_NEGATIVE_VALUE if B < 0
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p B equals zero.
+ * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if \p B is negative.
+ * \return Another negative error code on different kinds of failure.
+ *
*/
-int mbedtls_mpi_mod_mpi( mbedtls_mpi *R, const mbedtls_mpi *A, const mbedtls_mpi *B );
+int mbedtls_mpi_mod_mpi( mbedtls_mpi *R, const mbedtls_mpi *A,
+ const mbedtls_mpi *B );
/**
- * \brief Modulo: r = A mod b
+ * \brief Perform a modular reduction with respect to an integer.
+ * r = A mod b
*
- * \param r Destination mbedtls_mpi_uint
- * \param A Left-hand MPI
- * \param b Integer to divide by
+ * \param r The address at which to store the residue.
+ * This must not be \c NULL.
+ * \param A The MPI to compute the residue of.
+ * This must point to an initialized MPi.
+ * \param b The integer base of the modular reduction.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- * MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if b == 0,
- * MBEDTLS_ERR_MPI_NEGATIVE_VALUE if b < 0
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p b equals zero.
+ * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if \p b is negative.
+ * \return Another negative error code on different kinds of failure.
*/
-int mbedtls_mpi_mod_int( mbedtls_mpi_uint *r, const mbedtls_mpi *A, mbedtls_mpi_sint b );
+int mbedtls_mpi_mod_int( mbedtls_mpi_uint *r, const mbedtls_mpi *A,
+ mbedtls_mpi_sint b );
/**
- * \brief Sliding-window exponentiation: X = A^E mod N
+ * \brief Perform a sliding-window exponentiation: X = A^E mod N
*
- * \param X Destination MPI
- * \param A Left-hand MPI
- * \param E Exponent MPI
- * \param N Modular MPI
- * \param _RR Speed-up MPI used for recalculations
+ * \param X The destination MPI. This must point to an initialized MPI.
+ * \param A The base of the exponentiation.
+ * This must point to an initialized MPI.
+ * \param E The exponent MPI. This must point to an initialized MPI.
+ * \param N The base for the modular reduction. This must point to an
+ * initialized MPI.
+ * \param _RR A helper MPI depending solely on \p N which can be used to
+ * speed-up multiple modular exponentiations for the same value
+ * of \p N. This may be \c NULL. If it is not \c NULL, it must
+ * point to an initialized MPI. If it hasn't been used after
+ * the call to mbedtls_mpi_init(), this function will compute
+ * the helper value and store it in \p _RR for reuse on
+ * subsequent calls to this function. Otherwise, the function
+ * will assume that \p _RR holds the helper value set by a
+ * previous call to mbedtls_mpi_exp_mod(), and reuse it.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- * MBEDTLS_ERR_MPI_BAD_INPUT_DATA if N is negative or even or
- * if E is negative
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \c N is negative or
+ * even, or if \c E is negative.
+ * \return Another negative error code on different kinds of failures.
*
- * \note _RR is used to avoid re-computing R*R mod N across
- * multiple calls, which speeds up things a bit. It can
- * be set to NULL if the extra performance is unneeded.
*/
-int mbedtls_mpi_exp_mod( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *E, const mbedtls_mpi *N, mbedtls_mpi *_RR );
+int mbedtls_mpi_exp_mod( mbedtls_mpi *X, const mbedtls_mpi *A,
+ const mbedtls_mpi *E, const mbedtls_mpi *N,
+ mbedtls_mpi *_RR );
/**
- * \brief Fill an MPI X with size bytes of random
+ * \brief Fill an MPI with a number of random bytes.
*
- * \param X Destination MPI
- * \param size Size in bytes
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \param X The destination MPI. This must point to an initialized MPI.
+ * \param size The number of random bytes to generate.
+ * \param f_rng The RNG function to use. This must not be \c NULL.
+ * \param p_rng The RNG parameter to be passed to \p f_rng. This may be
+ * \c NULL if \p f_rng doesn't need a context argument.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return Another negative error code on failure.
*
- * \note The bytes obtained from the PRNG are interpreted
+ * \note The bytes obtained from the RNG are interpreted
* as a big-endian representation of an MPI; this can
* be relevant in applications like deterministic ECDSA.
*/
@@ -700,30 +850,37 @@
void *p_rng );
/**
- * \brief Greatest common divisor: G = gcd(A, B)
+ * \brief Compute the greatest common divisor: G = gcd(A, B)
*
- * \param G Destination MPI
- * \param A Left-hand MPI
- * \param B Right-hand MPI
+ * \param G The destination MPI. This must point to an initialized MPI.
+ * \param A The first operand. This must point to an initialized MPI.
+ * \param B The second operand. This must point to an initialized MPI.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return Another negative error code on different kinds of failure.
*/
-int mbedtls_mpi_gcd( mbedtls_mpi *G, const mbedtls_mpi *A, const mbedtls_mpi *B );
+int mbedtls_mpi_gcd( mbedtls_mpi *G, const mbedtls_mpi *A,
+ const mbedtls_mpi *B );
/**
- * \brief Modular inverse: X = A^-1 mod N
+ * \brief Compute the modular inverse: X = A^-1 mod N
*
- * \param X Destination MPI
- * \param A Left-hand MPI
- * \param N Right-hand MPI
+ * \param X The destination MPI. This must point to an initialized MPI.
+ * \param A The MPI to calculate the modular inverse of. This must point
+ * to an initialized MPI.
+ * \param N The base of the modular inversion. This must point to an
+ * initialized MPI.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- * MBEDTLS_ERR_MPI_BAD_INPUT_DATA if N is <= 1,
- MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if A has no inverse mod N.
+ * \return \c 0 if successful.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \p N is less than
+ * or equal to one.
+ * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p has no modular inverse
+ * with respect to \p N.
*/
-int mbedtls_mpi_inv_mod( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *N );
+int mbedtls_mpi_inv_mod( mbedtls_mpi *X, const mbedtls_mpi *A,
+ const mbedtls_mpi *N );
#if !defined(MBEDTLS_DEPRECATED_REMOVED)
#if defined(MBEDTLS_DEPRECATED_WARNING)
@@ -732,19 +889,23 @@
#define MBEDTLS_DEPRECATED
#endif
/**
- * \brief Miller-Rabin primality test with error probability of
- * 2<sup>-80</sup>
+ * \brief Perform a Miller-Rabin primality test with error
+ * probability of 2<sup>-80</sup>.
*
* \deprecated Superseded by mbedtls_mpi_is_prime_ext() which allows
* specifying the number of Miller-Rabin rounds.
*
- * \param X MPI to check
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \param X The MPI to check for primality.
+ * This must point to an initialized MPI.
+ * \param f_rng The RNG function to use. This must not be \c NULL.
+ * \param p_rng The RNG parameter to be passed to \p f_rng.
+ * This may be \c NULL if \p f_rng doesn't use a
+ * context parameter.
*
- * \return 0 if successful (probably prime),
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- * MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if X is not prime
+ * \return \c 0 if successful, i.e. \p X is probably prime.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p X is not prime.
+ * \return Another negative error code on other kinds of failure.
*/
MBEDTLS_DEPRECATED int mbedtls_mpi_is_prime( const mbedtls_mpi *X,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -764,16 +925,20 @@
* case when mbedtls_mpi_gen_prime calls this function), then
* \p rounds can be much lower.
*
- * \param X MPI to check
- * \param rounds Number of bases to perform Miller-Rabin primality test for.
- * The probability of returning 0 on a composite is at most
- * 2<sup>-2*\p rounds</sup>.
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \param X The MPI to check for primality.
+ * This must point to an initialized MPI.
+ * \param rounds The number of bases to perform the Miller-Rabin primality
+ * test for. The probability of returning 0 on a composite is
+ * at most 2<sup>-2*\p rounds</sup>.
+ * \param f_rng The RNG function to use. This must not be \c NULL.
+ * \param p_rng The RNG parameter to be passed to \p f_rng.
+ * This may be \c NULL if \p f_rng doesn't use
+ * a context parameter.
*
- * \return 0 if successful (probably prime),
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- * MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if X is not prime
+ * \return \c 0 if successful, i.e. \p X is probably prime.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p X is not prime.
+ * \return Another negative error code on other kinds of failure.
*/
int mbedtls_mpi_is_prime_ext( const mbedtls_mpi *X, int rounds,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -790,23 +955,30 @@
} mbedtls_mpi_gen_prime_flag_t;
/**
- * \brief Prime number generation
+ * \brief Generate a prime number.
*
- * \param X Destination MPI
- * \param nbits Required size of X in bits
- * ( 3 <= nbits <= MBEDTLS_MPI_MAX_BITS )
- * \param flags Mask of flags of type #mbedtls_mpi_gen_prime_flag_t
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \param X The destination MPI to store the generated prime in.
+ * This must point to an initialized MPi.
+ * \param nbits The required size of the destination MPI in bits.
+ * This must be between \c 3 and #MBEDTLS_MPI_MAX_BITS.
+ * \param flags A mask of flags of type #mbedtls_mpi_gen_prime_flag_t.
+ * \param f_rng The RNG function to use. This must not be \c NULL.
+ * \param p_rng The RNG parameter to be passed to \p f_rng.
+ * This may be \c NULL if \p f_rng doesn't use
+ * a context parameter.
*
- * \return 0 if successful (probably prime),
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- * MBEDTLS_ERR_MPI_BAD_INPUT_DATA if nbits is < 3
+ * \return \c 0 if successful, in which case \p X holds a
+ * probably prime number.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if `nbits` is not between
+ * \c 3 and #MBEDTLS_MPI_MAX_BITS.
*/
int mbedtls_mpi_gen_prime( mbedtls_mpi *X, size_t nbits, int flags,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng );
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief Checkup routine
*
@@ -814,6 +986,8 @@
*/
int mbedtls_mpi_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/blowfish.h b/include/mbedtls/blowfish.h
index 82b772a..f01573d 100644
--- a/include/mbedtls/blowfish.h
+++ b/include/mbedtls/blowfish.h
@@ -33,6 +33,8 @@
#include <stddef.h>
#include <stdint.h>
+#include "platform_util.h"
+
#define MBEDTLS_BLOWFISH_ENCRYPT 1
#define MBEDTLS_BLOWFISH_DECRYPT 0
#define MBEDTLS_BLOWFISH_MAX_KEY_BITS 448
@@ -40,14 +42,17 @@
#define MBEDTLS_BLOWFISH_ROUNDS 16 /**< Rounds to use. When increasing this value, make sure to extend the initialisation vectors */
#define MBEDTLS_BLOWFISH_BLOCKSIZE 8 /* Blowfish uses 64 bit blocks */
-#define MBEDTLS_ERR_BLOWFISH_INVALID_KEY_LENGTH -0x0016 /**< Invalid key length. */
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define MBEDTLS_ERR_BLOWFISH_INVALID_KEY_LENGTH MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( -0x0016 )
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+#define MBEDTLS_ERR_BLOWFISH_BAD_INPUT_DATA -0x0016 /**< Bad input data. */
+
+#define MBEDTLS_ERR_BLOWFISH_INVALID_INPUT_LENGTH -0x0018 /**< Invalid data input length. */
/* MBEDTLS_ERR_BLOWFISH_HW_ACCEL_FAILED is deprecated and should not be used.
*/
#define MBEDTLS_ERR_BLOWFISH_HW_ACCEL_FAILED -0x0017 /**< Blowfish hardware accelerator failed. */
-#define MBEDTLS_ERR_BLOWFISH_INVALID_INPUT_LENGTH -0x0018 /**< Invalid data input length. */
-
#ifdef __cplusplus
extern "C" {
#endif
@@ -71,40 +76,53 @@
#endif /* MBEDTLS_BLOWFISH_ALT */
/**
- * \brief Initialize Blowfish context
+ * \brief Initialize a Blowfish context.
*
- * \param ctx Blowfish context to be initialized
+ * \param ctx The Blowfish context to be initialized.
+ * This must not be \c NULL.
*/
void mbedtls_blowfish_init( mbedtls_blowfish_context *ctx );
/**
- * \brief Clear Blowfish context
+ * \brief Clear a Blowfish context.
*
- * \param ctx Blowfish context to be cleared
+ * \param ctx The Blowfish context to be cleared.
+ * This may be \c NULL, in which case this function
+ * returns immediately. If it is not \c NULL, it must
+ * point to an initialized Blowfish context.
*/
void mbedtls_blowfish_free( mbedtls_blowfish_context *ctx );
/**
- * \brief Blowfish key schedule
+ * \brief Perform a Blowfish key schedule operation.
*
- * \param ctx Blowfish context to be initialized
- * \param key encryption key
- * \param keybits must be between 32 and 448 bits
+ * \param ctx The Blowfish context to perform the key schedule on.
+ * \param key The encryption key. This must be a readable buffer of
+ * length \p keybits Bits.
+ * \param keybits The length of \p key in Bits. This must be between
+ * \c 32 and \c 448 and a multiple of \c 8.
*
- * \return 0 if successful, or MBEDTLS_ERR_BLOWFISH_INVALID_KEY_LENGTH
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
int mbedtls_blowfish_setkey( mbedtls_blowfish_context *ctx, const unsigned char *key,
unsigned int keybits );
/**
- * \brief Blowfish-ECB block encryption/decryption
+ * \brief Perform a Blowfish-ECB block encryption/decryption operation.
*
- * \param ctx Blowfish context
- * \param mode MBEDTLS_BLOWFISH_ENCRYPT or MBEDTLS_BLOWFISH_DECRYPT
- * \param input 8-byte input block
- * \param output 8-byte output block
+ * \param ctx The Blowfish context to use. This must be initialized
+ * and bound to a key.
+ * \param mode The mode of operation. Possible values are
+ * #MBEDTLS_BLOWFISH_ENCRYPT for encryption, or
+ * #MBEDTLS_BLOWFISH_DECRYPT for decryption.
+ * \param input The input block. This must be a readable buffer
+ * of size \c 8 Bytes.
+ * \param output The output block. This must be a writable buffer
+ * of size \c 8 Bytes.
*
- * \return 0 if successful
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
int mbedtls_blowfish_crypt_ecb( mbedtls_blowfish_context *ctx,
int mode,
@@ -113,9 +131,7 @@
#if defined(MBEDTLS_CIPHER_MODE_CBC)
/**
- * \brief Blowfish-CBC buffer encryption/decryption
- * Length should be a multiple of the block
- * size (8 bytes)
+ * \brief Perform a Blowfish-CBC buffer encryption/decryption operation.
*
* \note Upon exit, the content of the IV is updated so that you can
* call the function same function again on the following
@@ -125,15 +141,22 @@
* IV, you should either save it manually or use the cipher
* module instead.
*
- * \param ctx Blowfish context
- * \param mode MBEDTLS_BLOWFISH_ENCRYPT or MBEDTLS_BLOWFISH_DECRYPT
- * \param length length of the input data
- * \param iv initialization vector (updated after use)
- * \param input buffer holding the input data
- * \param output buffer holding the output data
+ * \param ctx The Blowfish context to use. This must be initialized
+ * and bound to a key.
+ * \param mode The mode of operation. Possible values are
+ * #MBEDTLS_BLOWFISH_ENCRYPT for encryption, or
+ * #MBEDTLS_BLOWFISH_DECRYPT for decryption.
+ * \param length The length of the input data in Bytes. This must be
+ * multiple of \c 8.
+ * \param iv The initialization vector. This must be a read/write buffer
+ * of length \c 8 Bytes. It is updated by this function.
+ * \param input The input data. This must be a readable buffer of length
+ * \p length Bytes.
+ * \param output The output data. This must be a writable buffer of length
+ * \p length Bytes.
*
- * \return 0 if successful, or
- * MBEDTLS_ERR_BLOWFISH_INVALID_INPUT_LENGTH
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
int mbedtls_blowfish_crypt_cbc( mbedtls_blowfish_context *ctx,
int mode,
@@ -145,7 +168,7 @@
#if defined(MBEDTLS_CIPHER_MODE_CFB)
/**
- * \brief Blowfish CFB buffer encryption/decryption.
+ * \brief Perform a Blowfish CFB buffer encryption/decryption operation.
*
* \note Upon exit, the content of the IV is updated so that you can
* call the function same function again on the following
@@ -155,15 +178,25 @@
* IV, you should either save it manually or use the cipher
* module instead.
*
- * \param ctx Blowfish context
- * \param mode MBEDTLS_BLOWFISH_ENCRYPT or MBEDTLS_BLOWFISH_DECRYPT
- * \param length length of the input data
- * \param iv_off offset in IV (updated after use)
- * \param iv initialization vector (updated after use)
- * \param input buffer holding the input data
- * \param output buffer holding the output data
+ * \param ctx The Blowfish context to use. This must be initialized
+ * and bound to a key.
+ * \param mode The mode of operation. Possible values are
+ * #MBEDTLS_BLOWFISH_ENCRYPT for encryption, or
+ * #MBEDTLS_BLOWFISH_DECRYPT for decryption.
+ * \param length The length of the input data in Bytes.
+ * \param iv_off The offset in the initialiation vector.
+ * The value pointed to must be smaller than \c 8 Bytes.
+ * It is updated by this function to support the aforementioned
+ * streaming usage.
+ * \param iv The initialization vector. This must be a read/write buffer
+ * of size \c 8 Bytes. It is updated after use.
+ * \param input The input data. This must be a readable buffer of length
+ * \p length Bytes.
+ * \param output The output data. This must be a writable buffer of length
+ * \p length Bytes.
*
- * \return 0 if successful
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
int mbedtls_blowfish_crypt_cfb64( mbedtls_blowfish_context *ctx,
int mode,
@@ -176,7 +209,7 @@
#if defined(MBEDTLS_CIPHER_MODE_CTR)
/**
- * \brief Blowfish-CTR buffer encryption/decryption
+ * \brief Perform a Blowfish-CTR buffer encryption/decryption operation.
*
* \warning You must never reuse a nonce value with the same key. Doing so
* would void the encryption for the two messages encrypted with
@@ -219,18 +252,24 @@
* content must not be written to insecure storage and should be
* securely discarded as soon as it's no longer needed.
*
- * \param ctx Blowfish context
- * \param length The length of the data
+ * \param ctx The Blowfish context to use. This must be initialized
+ * and bound to a key.
+ * \param length The length of the input data in Bytes.
* \param nc_off The offset in the current stream_block (for resuming
- * within current cipher stream). The offset pointer to
- * should be 0 at the start of a stream.
- * \param nonce_counter The 64-bit nonce and counter.
- * \param stream_block The saved stream-block for resuming. Is overwritten
- * by the function.
- * \param input The input data stream
- * \param output The output data stream
+ * within current cipher stream). The offset pointer
+ * should be \c 0 at the start of a stream and must be
+ * smaller than \c 8. It is updated by this function.
+ * \param nonce_counter The 64-bit nonce and counter. This must point to a
+ * read/write buffer of length \c 8 Bytes.
+ * \param stream_block The saved stream-block for resuming. This must point to
+ * a read/write buffer of length \c 8 Bytes.
+ * \param input The input data. This must be a readable buffer of
+ * length \p length Bytes.
+ * \param output The output data. This must be a writable buffer of
+ * length \p length Bytes.
*
- * \return 0 if successful
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
int mbedtls_blowfish_crypt_ctr( mbedtls_blowfish_context *ctx,
size_t length,
diff --git a/include/mbedtls/bn_mul.h b/include/mbedtls/bn_mul.h
index 0af694c..c33bd8d 100644
--- a/include/mbedtls/bn_mul.h
+++ b/include/mbedtls/bn_mul.h
@@ -38,6 +38,12 @@
#ifndef MBEDTLS_BN_MUL_H
#define MBEDTLS_BN_MUL_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "bignum.h"
#if defined(MBEDTLS_HAVE_ASM)
@@ -170,19 +176,19 @@
#define MULADDC_INIT \
asm( \
- "xorq %%r8, %%r8 \n\t"
+ "xorq %%r8, %%r8\n"
#define MULADDC_CORE \
- "movq (%%rsi), %%rax \n\t" \
- "mulq %%rbx \n\t" \
- "addq $8, %%rsi \n\t" \
- "addq %%rcx, %%rax \n\t" \
- "movq %%r8, %%rcx \n\t" \
- "adcq $0, %%rdx \n\t" \
- "nop \n\t" \
- "addq %%rax, (%%rdi) \n\t" \
- "adcq %%rdx, %%rcx \n\t" \
- "addq $8, %%rdi \n\t"
+ "movq (%%rsi), %%rax\n" \
+ "mulq %%rbx\n" \
+ "addq $8, %%rsi\n" \
+ "addq %%rcx, %%rax\n" \
+ "movq %%r8, %%rcx\n" \
+ "adcq $0, %%rdx\n" \
+ "nop \n" \
+ "addq %%rax, (%%rdi)\n" \
+ "adcq %%rdx, %%rcx\n" \
+ "addq $8, %%rdi\n"
#define MULADDC_STOP \
: "+c" (c), "+D" (d), "+S" (s) \
@@ -750,7 +756,7 @@
"sw $10, %2 \n\t" \
: "=m" (c), "=m" (d), "=m" (s) \
: "m" (s), "m" (d), "m" (c), "m" (b) \
- : "$9", "$10", "$11", "$12", "$13", "$14", "$15" \
+ : "$9", "$10", "$11", "$12", "$13", "$14", "$15", "lo", "hi" \
);
#endif /* MIPS */
diff --git a/include/mbedtls/camellia.h b/include/mbedtls/camellia.h
index 1555867..3eeb663 100644
--- a/include/mbedtls/camellia.h
+++ b/include/mbedtls/camellia.h
@@ -33,11 +33,17 @@
#include <stddef.h>
#include <stdint.h>
+#include "platform_util.h"
+
#define MBEDTLS_CAMELLIA_ENCRYPT 1
#define MBEDTLS_CAMELLIA_DECRYPT 0
-#define MBEDTLS_ERR_CAMELLIA_INVALID_KEY_LENGTH -0x0024 /**< Invalid key length. */
-#define MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH -0x0026 /**< Invalid data input length. */
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define MBEDTLS_ERR_CAMELLIA_INVALID_KEY_LENGTH MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( -0x0024 )
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+#define MBEDTLS_ERR_CAMELLIA_BAD_INPUT_DATA -0x0024 /**< Bad input data. */
+
+#define MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH -0x0026 /**< Invalid data input length. */
/* MBEDTLS_ERR_CAMELLIA_HW_ACCEL_FAILED is deprecated and should not be used.
*/
@@ -66,52 +72,68 @@
#endif /* MBEDTLS_CAMELLIA_ALT */
/**
- * \brief Initialize CAMELLIA context
+ * \brief Initialize a CAMELLIA context.
*
- * \param ctx CAMELLIA context to be initialized
+ * \param ctx The CAMELLIA context to be initialized.
+ * This must not be \c NULL.
*/
void mbedtls_camellia_init( mbedtls_camellia_context *ctx );
/**
- * \brief Clear CAMELLIA context
+ * \brief Clear a CAMELLIA context.
*
- * \param ctx CAMELLIA context to be cleared
+ * \param ctx The CAMELLIA context to be cleared. This may be \c NULL,
+ * in which case this function returns immediately. If it is not
+ * \c NULL, it must be initialized.
*/
void mbedtls_camellia_free( mbedtls_camellia_context *ctx );
/**
- * \brief CAMELLIA key schedule (encryption)
+ * \brief Perform a CAMELLIA key schedule operation for encryption.
*
- * \param ctx CAMELLIA context to be initialized
- * \param key encryption key
- * \param keybits must be 128, 192 or 256
+ * \param ctx The CAMELLIA context to use. This must be initialized.
+ * \param key The encryption key to use. This must be a readable buffer
+ * of size \p keybits Bits.
+ * \param keybits The length of \p key in Bits. This must be either \c 128,
+ * \c 192 or \c 256.
*
- * \return 0 if successful, or MBEDTLS_ERR_CAMELLIA_INVALID_KEY_LENGTH
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
-int mbedtls_camellia_setkey_enc( mbedtls_camellia_context *ctx, const unsigned char *key,
- unsigned int keybits );
+int mbedtls_camellia_setkey_enc( mbedtls_camellia_context *ctx,
+ const unsigned char *key,
+ unsigned int keybits );
/**
- * \brief CAMELLIA key schedule (decryption)
+ * \brief Perform a CAMELLIA key schedule operation for decryption.
*
- * \param ctx CAMELLIA context to be initialized
- * \param key decryption key
- * \param keybits must be 128, 192 or 256
+ * \param ctx The CAMELLIA context to use. This must be initialized.
+ * \param key The decryption key. This must be a readable buffer
+ * of size \p keybits Bits.
+ * \param keybits The length of \p key in Bits. This must be either \c 128,
+ * \c 192 or \c 256.
*
- * \return 0 if successful, or MBEDTLS_ERR_CAMELLIA_INVALID_KEY_LENGTH
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
-int mbedtls_camellia_setkey_dec( mbedtls_camellia_context *ctx, const unsigned char *key,
- unsigned int keybits );
+int mbedtls_camellia_setkey_dec( mbedtls_camellia_context *ctx,
+ const unsigned char *key,
+ unsigned int keybits );
/**
- * \brief CAMELLIA-ECB block encryption/decryption
+ * \brief Perform a CAMELLIA-ECB block encryption/decryption operation.
*
- * \param ctx CAMELLIA context
- * \param mode MBEDTLS_CAMELLIA_ENCRYPT or MBEDTLS_CAMELLIA_DECRYPT
- * \param input 16-byte input block
- * \param output 16-byte output block
+ * \param ctx The CAMELLIA context to use. This must be initialized
+ * and bound to a key.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
+ * \param input The input block. This must be a readable buffer
+ * of size \c 16 Bytes.
+ * \param output The output block. This must be a writable buffer
+ * of size \c 16 Bytes.
*
- * \return 0 if successful
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
int mbedtls_camellia_crypt_ecb( mbedtls_camellia_context *ctx,
int mode,
@@ -120,9 +142,7 @@
#if defined(MBEDTLS_CIPHER_MODE_CBC)
/**
- * \brief CAMELLIA-CBC buffer encryption/decryption
- * Length should be a multiple of the block
- * size (16 bytes)
+ * \brief Perform a CAMELLIA-CBC buffer encryption/decryption operation.
*
* \note Upon exit, the content of the IV is updated so that you can
* call the function same function again on the following
@@ -132,15 +152,22 @@
* IV, you should either save it manually or use the cipher
* module instead.
*
- * \param ctx CAMELLIA context
- * \param mode MBEDTLS_CAMELLIA_ENCRYPT or MBEDTLS_CAMELLIA_DECRYPT
- * \param length length of the input data
- * \param iv initialization vector (updated after use)
- * \param input buffer holding the input data
- * \param output buffer holding the output data
+ * \param ctx The CAMELLIA context to use. This must be initialized
+ * and bound to a key.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
+ * \param length The length in Bytes of the input data \p input.
+ * This must be a multiple of \c 16 Bytes.
+ * \param iv The initialization vector. This must be a read/write buffer
+ * of length \c 16 Bytes. It is updated to allow streaming
+ * use as explained above.
+ * \param input The buffer holding the input data. This must point to a
+ * readable buffer of length \p length Bytes.
+ * \param output The buffer holding the output data. This must point to a
+ * writable buffer of length \p length Bytes.
*
- * \return 0 if successful, or
- * MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
int mbedtls_camellia_crypt_cbc( mbedtls_camellia_context *ctx,
int mode,
@@ -152,11 +179,14 @@
#if defined(MBEDTLS_CIPHER_MODE_CFB)
/**
- * \brief CAMELLIA-CFB128 buffer encryption/decryption
+ * \brief Perform a CAMELLIA-CFB128 buffer encryption/decryption
+ * operation.
*
- * Note: Due to the nature of CFB you should use the same key schedule for
- * both encryption and decryption. So a context initialized with
- * mbedtls_camellia_setkey_enc() for both MBEDTLS_CAMELLIA_ENCRYPT and CAMELLIE_DECRYPT.
+ * \note Due to the nature of CFB mode, you should use the same
+ * key for both encryption and decryption. In particular, calls
+ * to this function should be preceded by a key-schedule via
+ * mbedtls_camellia_setkey_enc() regardless of whether \p mode
+ * is #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
*
* \note Upon exit, the content of the IV is updated so that you can
* call the function same function again on the following
@@ -166,16 +196,24 @@
* IV, you should either save it manually or use the cipher
* module instead.
*
- * \param ctx CAMELLIA context
- * \param mode MBEDTLS_CAMELLIA_ENCRYPT or MBEDTLS_CAMELLIA_DECRYPT
- * \param length length of the input data
- * \param iv_off offset in IV (updated after use)
- * \param iv initialization vector (updated after use)
- * \param input buffer holding the input data
- * \param output buffer holding the output data
+ * \param ctx The CAMELLIA context to use. This must be initialized
+ * and bound to a key.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
+ * \param length The length of the input data \p input. Any value is allowed.
+ * \param iv_off The current offset in the IV. This must be smaller
+ * than \c 16 Bytes. It is updated after this call to allow
+ * the aforementioned streaming usage.
+ * \param iv The initialization vector. This must be a read/write buffer
+ * of length \c 16 Bytes. It is updated after this call to
+ * allow the aforementioned streaming usage.
+ * \param input The buffer holding the input data. This must be a readable
+ * buffer of size \p length Bytes.
+ * \param output The buffer to hold the output data. This must be a writable
+ * buffer of length \p length Bytes.
*
- * \return 0 if successful, or
- * MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
int mbedtls_camellia_crypt_cfb128( mbedtls_camellia_context *ctx,
int mode,
@@ -188,11 +226,13 @@
#if defined(MBEDTLS_CIPHER_MODE_CTR)
/**
- * \brief CAMELLIA-CTR buffer encryption/decryption
+ * \brief Perform a CAMELLIA-CTR buffer encryption/decryption operation.
*
- * Note: Due to the nature of CTR you should use the same key schedule for
- * both encryption and decryption. So a context initialized with
- * mbedtls_camellia_setkey_enc() for both MBEDTLS_CAMELLIA_ENCRYPT and MBEDTLS_CAMELLIA_DECRYPT.
+ * *note Due to the nature of CTR mode, you should use the same
+ * key for both encryption and decryption. In particular, calls
+ * to this function should be preceded by a key-schedule via
+ * mbedtls_camellia_setkey_enc() regardless of whether \p mode
+ * is #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
*
* \warning You must never reuse a nonce value with the same key. Doing so
* would void the encryption for the two messages encrypted with
@@ -215,41 +255,49 @@
* per-message nonce, handled by yourself, and the second one
* updated by this function internally.
*
- * For example, you might reserve the first 12 bytes for the
- * per-message nonce, and the last 4 bytes for internal use. In that
- * case, before calling this function on a new message you need to
- * set the first 12 bytes of \p nonce_counter to your chosen nonce
- * value, the last 4 to 0, and \p nc_off to 0 (which will cause \p
- * stream_block to be ignored). That way, you can encrypt at most
- * 2**96 messages of up to 2**32 blocks each with the same key.
+ * For example, you might reserve the first \c 12 Bytes for the
+ * per-message nonce, and the last \c 4 Bytes for internal use.
+ * In that case, before calling this function on a new message you
+ * need to set the first \c 12 Bytes of \p nonce_counter to your
+ * chosen nonce value, the last four to \c 0, and \p nc_off to \c 0
+ * (which will cause \p stream_block to be ignored). That way, you
+ * can encrypt at most \c 2**96 messages of up to \c 2**32 blocks
+ * each with the same key.
*
* The per-message nonce (or information sufficient to reconstruct
- * it) needs to be communicated with the ciphertext and must be unique.
- * The recommended way to ensure uniqueness is to use a message
- * counter. An alternative is to generate random nonces, but this
- * limits the number of messages that can be securely encrypted:
- * for example, with 96-bit random nonces, you should not encrypt
- * more than 2**32 messages with the same key.
+ * it) needs to be communicated with the ciphertext and must be
+ * unique. The recommended way to ensure uniqueness is to use a
+ * message counter. An alternative is to generate random nonces,
+ * but this limits the number of messages that can be securely
+ * encrypted: for example, with 96-bit random nonces, you should
+ * not encrypt more than 2**32 messages with the same key.
*
* Note that for both stategies, sizes are measured in blocks and
- * that a CAMELLIA block is 16 bytes.
+ * that a CAMELLIA block is \c 16 Bytes.
*
* \warning Upon return, \p stream_block contains sensitive data. Its
* content must not be written to insecure storage and should be
* securely discarded as soon as it's no longer needed.
*
- * \param ctx CAMELLIA context
- * \param length The length of the data
- * \param nc_off The offset in the current stream_block (for resuming
+ * \param ctx The CAMELLIA context to use. This must be initialized
+ * and bound to a key.
+ * \param length The length of the input data \p input in Bytes.
+ * Any value is allowed.
+ * \param nc_off The offset in the current \p stream_block (for resuming
* within current cipher stream). The offset pointer to
- * should be 0 at the start of a stream.
- * \param nonce_counter The 128-bit nonce and counter.
- * \param stream_block The saved stream-block for resuming. Is overwritten
- * by the function.
- * \param input The input data stream
- * \param output The output data stream
+ * should be \c 0 at the start of a stream. It is updated
+ * at the end of this call.
+ * \param nonce_counter The 128-bit nonce and counter. This must be a read/write
+ * buffer of length \c 16 Bytes.
+ * \param stream_block The saved stream-block for resuming. This must be a
+ * read/write buffer of length \c 16 Bytes.
+ * \param input The input data stream. This must be a readable buffer of
+ * size \p length Bytes.
+ * \param output The output data stream. This must be a writable buffer
+ * of size \p length Bytes.
*
- * \return 0 if successful
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
int mbedtls_camellia_crypt_ctr( mbedtls_camellia_context *ctx,
size_t length,
@@ -260,6 +308,8 @@
unsigned char *output );
#endif /* MBEDTLS_CIPHER_MODE_CTR */
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief Checkup routine
*
@@ -267,6 +317,8 @@
*/
int mbedtls_camellia_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h
index dfb1b5e..f03e3b5 100644
--- a/include/mbedtls/ccm.h
+++ b/include/mbedtls/ccm.h
@@ -49,6 +49,12 @@
#ifndef MBEDTLS_CCM_H
#define MBEDTLS_CCM_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "cipher.h"
#define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D /**< Bad input parameters to the function. */
@@ -57,7 +63,6 @@
/* MBEDTLS_ERR_CCM_HW_ACCEL_FAILED is deprecated and should not be used. */
#define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */
-
#ifdef __cplusplus
extern "C" {
#endif
@@ -85,7 +90,7 @@
* to make references valid, and prepare the context
* for mbedtls_ccm_setkey() or mbedtls_ccm_free().
*
- * \param ctx The CCM context to initialize.
+ * \param ctx The CCM context to initialize. This must not be \c NULL.
*/
void mbedtls_ccm_init( mbedtls_ccm_context *ctx );
@@ -93,9 +98,10 @@
* \brief This function initializes the CCM context set in the
* \p ctx parameter and sets the encryption key.
*
- * \param ctx The CCM context to initialize.
+ * \param ctx The CCM context to initialize. This must be an initialized
+ * context.
* \param cipher The 128-bit block cipher to use.
- * \param key The encryption key.
+ * \param key The encryption key. This must not be \c NULL.
* \param keybits The key size in bits. This must be acceptable by the cipher.
*
* \return \c 0 on success.
@@ -110,7 +116,8 @@
* \brief This function releases and clears the specified CCM context
* and underlying cipher sub-context.
*
- * \param ctx The CCM context to clear.
+ * \param ctx The CCM context to clear. If this is \c NULL, the function
+ * has no effect. Otherwise, this must be initialized.
*/
void mbedtls_ccm_free( mbedtls_ccm_context *ctx );
@@ -123,19 +130,27 @@
* \p tag = \p output + \p length, and make sure that the
* output buffer is at least \p length + \p tag_len wide.
*
- * \param ctx The CCM context to use for encryption.
+ * \param ctx The CCM context to use for encryption. This must be
+ * initialized and bound to a key.
* \param length The length of the input data in Bytes.
- * \param iv Initialization vector (nonce).
+ * \param iv The initialization vector (nonce). This must be a readable
+ * buffer of at least \p iv_len Bytes.
* \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
* or 13. The length L of the message length field is
* 15 - \p iv_len.
- * \param add The additional data field.
+ * \param add The additional data field. If \p add_len is greater than
+ * zero, \p add must be a readable buffer of at least that
+ * length.
* \param add_len The length of additional data in Bytes.
- * Must be less than 2^16 - 2^8.
- * \param input The buffer holding the input data.
- * \param output The buffer holding the output data.
- * Must be at least \p length Bytes wide.
- * \param tag The buffer holding the authentication field.
+ * This must be less than `2^16 - 2^8`.
+ * \param input The buffer holding the input data. If \p length is greater
+ * than zero, \p input must be a readable buffer of at least
+ * that length.
+ * \param output The buffer holding the output data. If \p length is greater
+ * than zero, \p output must be a writable buffer of at least
+ * that length.
+ * \param tag The buffer holding the authentication field. This must be a
+ * readable buffer of at least \p tag_len Bytes.
* \param tag_len The length of the authentication field to generate in Bytes:
* 4, 6, 8, 10, 12, 14 or 16.
*
@@ -161,23 +176,30 @@
* the tag length has to be encoded into the \p iv passed to
* this function.
*
- * \param ctx The CCM context to use for encryption.
+ * \param ctx The CCM context to use for encryption. This must be
+ * initialized and bound to a key.
* \param length The length of the input data in Bytes.
- * \param iv Initialization vector (nonce).
+ * \param iv The initialization vector (nonce). This must be a readable
+ * buffer of at least \p iv_len Bytes.
* \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
* or 13. The length L of the message length field is
* 15 - \p iv_len.
- * \param add The additional data field.
+ * \param add The additional data field. This must be a readable buffer of
+ * at least \p add_len Bytes.
* \param add_len The length of additional data in Bytes.
- * Must be less than 2^16 - 2^8.
- * \param input The buffer holding the input data.
- * \param output The buffer holding the output data.
- * Must be at least \p length Bytes wide.
- * \param tag The buffer holding the authentication field.
+ * This must be less than 2^16 - 2^8.
+ * \param input The buffer holding the input data. If \p length is greater
+ * than zero, \p input must be a readable buffer of at least
+ * that length.
+ * \param output The buffer holding the output data. If \p length is greater
+ * than zero, \p output must be a writable buffer of at least
+ * that length.
+ * \param tag The buffer holding the authentication field. This must be a
+ * readable buffer of at least \p tag_len Bytes.
* \param tag_len The length of the authentication field to generate in Bytes:
* 0, 4, 6, 8, 10, 12, 14 or 16.
*
- * \warning Passing 0 as \p tag_len means that the message is no
+ * \warning Passing \c 0 as \p tag_len means that the message is no
* longer authenticated.
*
* \return \c 0 on success.
@@ -193,20 +215,27 @@
* \brief This function performs a CCM authenticated decryption of a
* buffer.
*
- * \param ctx The CCM context to use for decryption.
+ * \param ctx The CCM context to use for decryption. This must be
+ * initialized and bound to a key.
* \param length The length of the input data in Bytes.
- * \param iv Initialization vector (nonce).
+ * \param iv The initialization vector (nonce). This must be a readable
+ * buffer of at least \p iv_len Bytes.
* \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
* or 13. The length L of the message length field is
* 15 - \p iv_len.
- * \param add The additional data field.
+ * \param add The additional data field. This must be a readable buffer
+ * of at least that \p add_len Bytes..
* \param add_len The length of additional data in Bytes.
- * Must be less than 2^16 - 2^8.
- * \param input The buffer holding the input data.
- * \param output The buffer holding the output data.
- * Must be at least \p length Bytes wide.
- * \param tag The buffer holding the authentication field.
- * \param tag_len The length of the authentication field in Bytes.
+ * This must be less than 2^16 - 2^8.
+ * \param input The buffer holding the input data. If \p length is greater
+ * than zero, \p input must be a readable buffer of at least
+ * that length.
+ * \param output The buffer holding the output data. If \p length is greater
+ * than zero, \p output must be a writable buffer of at least
+ * that length.
+ * \param tag The buffer holding the authentication field. This must be a
+ * readable buffer of at least \p tag_len Bytes.
+ * \param tag_len The length of the authentication field to generate in Bytes:
* 4, 6, 8, 10, 12, 14 or 16.
*
* \return \c 0 on success. This indicates that the message is authentic.
@@ -228,23 +257,30 @@
* this function as \p tag_len. (\p tag needs to be adjusted
* accordingly.)
*
- * \param ctx The CCM context to use for decryption.
+ * \param ctx The CCM context to use for decryption. This must be
+ * initialized and bound to a key.
* \param length The length of the input data in Bytes.
- * \param iv Initialization vector (nonce).
+ * \param iv The initialization vector (nonce). This must be a readable
+ * buffer of at least \p iv_len Bytes.
* \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
* or 13. The length L of the message length field is
* 15 - \p iv_len.
- * \param add The additional data field.
+ * \param add The additional data field. This must be a readable buffer of
+ * at least that \p add_len Bytes.
* \param add_len The length of additional data in Bytes.
- * Must be less than 2^16 - 2^8.
- * \param input The buffer holding the input data.
- * \param output The buffer holding the output data.
- * Must be at least \p length Bytes wide.
- * \param tag The buffer holding the authentication field.
+ * This must be less than 2^16 - 2^8.
+ * \param input The buffer holding the input data. If \p length is greater
+ * than zero, \p input must be a readable buffer of at least
+ * that length.
+ * \param output The buffer holding the output data. If \p length is greater
+ * than zero, \p output must be a writable buffer of at least
+ * that length.
+ * \param tag The buffer holding the authentication field. This must be a
+ * readable buffer of at least \p tag_len Bytes.
* \param tag_len The length of the authentication field in Bytes.
* 0, 4, 6, 8, 10, 12, 14 or 16.
*
- * \warning Passing 0 as \p tag_len means that the message is no
+ * \warning Passing \c 0 as \p tag_len means that the message is nos
* longer authenticated.
*
* \return \c 0 on success.
diff --git a/include/mbedtls/certs.h b/include/mbedtls/certs.h
index 8dab7b5..b7c5708 100644
--- a/include/mbedtls/certs.h
+++ b/include/mbedtls/certs.h
@@ -24,6 +24,12 @@
#ifndef MBEDTLS_CERTS_H
#define MBEDTLS_CERTS_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include <stddef.h>
#ifdef __cplusplus
diff --git a/include/mbedtls/chacha20.h b/include/mbedtls/chacha20.h
index 529f22d..2ae5e6e 100644
--- a/include/mbedtls/chacha20.h
+++ b/include/mbedtls/chacha20.h
@@ -83,13 +83,18 @@
* \c mbedtls_chacha20_free().
*
* \param ctx The ChaCha20 context to initialize.
+ * This must not be \c NULL.
*/
void mbedtls_chacha20_init( mbedtls_chacha20_context *ctx );
/**
- * \brief This function releases and clears the specified ChaCha20 context.
+ * \brief This function releases and clears the specified
+ * ChaCha20 context.
*
- * \param ctx The ChaCha20 context to clear.
+ * \param ctx The ChaCha20 context to clear. This may be \c NULL,
+ * in which case this function is a no-op. If it is not
+ * \c NULL, it must point to an initialized context.
+ *
*/
void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx );
@@ -102,7 +107,9 @@
* \c mbedtls_chacha_update().
*
* \param ctx The ChaCha20 context to which the key should be bound.
- * \param key The encryption/decryption key. Must be 32 bytes in length.
+ * It must be initialized.
+ * \param key The encryption/decryption key. This must be \c 32 Bytes
+ * in length.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL.
@@ -121,8 +128,9 @@
* messages encrypted with the same nonce and key.
*
* \param ctx The ChaCha20 context to which the nonce should be bound.
- * \param nonce The nonce. Must be 12 bytes in size.
- * \param counter The initial counter value. This is usually 0.
+ * It must be initialized and bound to a key.
+ * \param nonce The nonce. This must be \c 12 Bytes in size.
+ * \param counter The initial counter value. This is usually \c 0.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is
@@ -150,16 +158,16 @@
* key and nonce.
*
* \param ctx The ChaCha20 context to use for encryption or decryption.
- * \param size The length of the input data in bytes.
+ * It must be initialized and bound to a key and nonce.
+ * \param size The length of the input data in Bytes.
* \param input The buffer holding the input data.
- * This pointer can be NULL if size == 0.
+ * This pointer can be \c NULL if `size == 0`.
* \param output The buffer holding the output data.
- * Must be able to hold \p size bytes.
- * This pointer can be NULL if size == 0.
+ * This must be able to hold \p size Bytes.
+ * This pointer can be \c NULL if `size == 0`.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if the ctx, input, or
- * output pointers are NULL.
+ * \return A negative error code on failure.
*/
int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx,
size_t size,
@@ -180,19 +188,19 @@
* \note The \p input and \p output pointers must either be equal or
* point to non-overlapping buffers.
*
- * \param key The encryption/decryption key. Must be 32 bytes in length.
- * \param nonce The nonce. Must be 12 bytes in size.
- * \param counter The initial counter value. This is usually 0.
- * \param size The length of the input data in bytes.
+ * \param key The encryption/decryption key.
+ * This must be \c 32 Bytes in length.
+ * \param nonce The nonce. This must be \c 12 Bytes in size.
+ * \param counter The initial counter value. This is usually \c 0.
+ * \param size The length of the input data in Bytes.
* \param input The buffer holding the input data.
- * This pointer can be NULL if size == 0.
+ * This pointer can be \c NULL if `size == 0`.
* \param output The buffer holding the output data.
- * Must be able to hold \p size bytes.
- * This pointer can be NULL if size == 0.
+ * This must be able to hold \p size Bytes.
+ * This pointer can be \c NULL if `size == 0`.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if key, nonce, input,
- * or output is NULL.
+ * \return A negative error code on failure.
*/
int mbedtls_chacha20_crypt( const unsigned char key[32],
const unsigned char nonce[12],
diff --git a/include/mbedtls/chachapoly.h b/include/mbedtls/chachapoly.h
index 7de6f4e..49e615d 100644
--- a/include/mbedtls/chachapoly.h
+++ b/include/mbedtls/chachapoly.h
@@ -115,27 +115,29 @@
* all previous outputs of \c mbedtls_chachapoly_update(),
* otherwise you can now safely use the plaintext.
*
- * \param ctx The ChachaPoly context to initialize.
+ * \param ctx The ChachaPoly context to initialize. Must not be \c NULL.
*/
void mbedtls_chachapoly_init( mbedtls_chachapoly_context *ctx );
/**
- * \brief This function releases and clears the specified ChaCha20-Poly1305 context.
+ * \brief This function releases and clears the specified
+ * ChaCha20-Poly1305 context.
*
- * \param ctx The ChachaPoly context to clear.
+ * \param ctx The ChachaPoly context to clear. This may be \c NULL, in which
+ * case this function is a no-op.
*/
void mbedtls_chachapoly_free( mbedtls_chachapoly_context *ctx );
/**
- * \brief This function sets the ChaCha20-Poly1305 symmetric encryption key.
+ * \brief This function sets the ChaCha20-Poly1305
+ * symmetric encryption key.
*
* \param ctx The ChaCha20-Poly1305 context to which the key should be
- * bound.
- * \param key The 256-bit (32 bytes) key.
+ * bound. This must be initialized.
+ * \param key The \c 256 Bit (\c 32 Bytes) key.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- * if \p ctx or \p key are NULL.
+ * \return A negative error code on failure.
*/
int mbedtls_chachapoly_setkey( mbedtls_chachapoly_context *ctx,
const unsigned char key[32] );
@@ -155,14 +157,15 @@
* \warning Decryption with the piecewise API is discouraged, see the
* warning on \c mbedtls_chachapoly_init().
*
- * \param ctx The ChaCha20-Poly1305 context.
- * \param nonce The nonce/IV to use for the message. Must be 12 bytes.
+ * \param ctx The ChaCha20-Poly1305 context. This must be initialized
+ * and bound to a key.
+ * \param nonce The nonce/IV to use for the message.
+ * This must be a redable buffer of length \c 12 Bytes.
* \param mode The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or
* #MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning).
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- * if \p ctx or \p mac are NULL.
+ * \return A negative error code on failure.
*/
int mbedtls_chachapoly_starts( mbedtls_chachapoly_context *ctx,
const unsigned char nonce[12],
@@ -193,11 +196,12 @@
* \warning Decryption with the piecewise API is discouraged, see the
* warning on \c mbedtls_chachapoly_init().
*
- * \param ctx The ChaCha20-Poly1305 context to use.
- * \param aad_len The length (in bytes) of the AAD. The length has no
+ * \param ctx The ChaCha20-Poly1305 context. This must be initialized
+ * and bound to a key.
+ * \param aad_len The length in Bytes of the AAD. The length has no
* restrictions.
* \param aad Buffer containing the AAD.
- * This pointer can be NULL if aad_len == 0.
+ * This pointer can be \c NULL if `aad_len == 0`.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
@@ -227,20 +231,19 @@
* \warning Decryption with the piecewise API is discouraged, see the
* warning on \c mbedtls_chachapoly_init().
*
- * \param ctx The ChaCha20-Poly1305 context to use.
+ * \param ctx The ChaCha20-Poly1305 context to use. This must be initialized.
* \param len The length (in bytes) of the data to encrypt or decrypt.
* \param input The buffer containing the data to encrypt or decrypt.
- * This pointer can be NULL if len == 0.
- * \param output The buffer to where the encrypted or decrypted data is written.
- * Must be able to hold \p len bytes.
- * This pointer can be NULL if len == 0.
+ * This pointer can be \c NULL if `len == 0`.
+ * \param output The buffer to where the encrypted or decrypted data is
+ * written. This must be able to hold \p len bytes.
+ * This pointer can be \c NULL if `len == 0`.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- * if \p ctx, \p input, or \p output are NULL.
* \return #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
* if the operation has not been started or has been
* finished.
+ * \return Another negative error code on other kinds of failure.
*/
int mbedtls_chachapoly_update( mbedtls_chachapoly_context *ctx,
size_t len,
@@ -251,18 +254,17 @@
* \brief This function finished the ChaCha20-Poly1305 operation and
* generates the MAC (authentication tag).
*
- * \param ctx The ChaCha20-Poly1305 context to use.
+ * \param ctx The ChaCha20-Poly1305 context to use. This must be initialized.
* \param mac The buffer to where the 128-bit (16 bytes) MAC is written.
*
* \warning Decryption with the piecewise API is discouraged, see the
* warning on \c mbedtls_chachapoly_init().
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- * if \p ctx or \p mac are NULL.
* \return #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
* if the operation has not been started or has been
* finished.
+ * \return Another negative error code on other kinds of failure.
*/
int mbedtls_chachapoly_finish( mbedtls_chachapoly_context *ctx,
unsigned char mac[16] );
@@ -280,20 +282,21 @@
* and key.
*
* \param ctx The ChaCha20-Poly1305 context to use (holds the key).
+ * This must be initialized.
* \param length The length (in bytes) of the data to encrypt or decrypt.
* \param nonce The 96-bit (12 bytes) nonce/IV to use.
- * \param aad The buffer containing the additional authenticated data (AAD).
- * This pointer can be NULL if aad_len == 0.
+ * \param aad The buffer containing the additional authenticated
+ * data (AAD). This pointer can be \c NULL if `aad_len == 0`.
* \param aad_len The length (in bytes) of the AAD data to process.
* \param input The buffer containing the data to encrypt or decrypt.
- * This pointer can be NULL if ilen == 0.
- * \param output The buffer to where the encrypted or decrypted data is written.
- * This pointer can be NULL if ilen == 0.
- * \param tag The buffer to where the computed 128-bit (16 bytes) MAC is written.
+ * This pointer can be \c NULL if `ilen == 0`.
+ * \param output The buffer to where the encrypted or decrypted data
+ * is written. This pointer can be \c NULL if `ilen == 0`.
+ * \param tag The buffer to where the computed 128-bit (16 bytes) MAC
+ * is written. This must not be \c NULL.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- * if one or more of the required parameters are NULL.
+ * \return A negative error code on failure.
*/
int mbedtls_chachapoly_encrypt_and_tag( mbedtls_chachapoly_context *ctx,
size_t length,
@@ -312,22 +315,22 @@
* \c mbedtls_chachapoly_setkey().
*
* \param ctx The ChaCha20-Poly1305 context to use (holds the key).
- * \param length The length (in bytes) of the data to decrypt.
- * \param nonce The 96-bit (12 bytes) nonce/IV to use.
+ * \param length The length (in Bytes) of the data to decrypt.
+ * \param nonce The \c 96 Bit (\c 12 bytes) nonce/IV to use.
* \param aad The buffer containing the additional authenticated data (AAD).
- * This pointer can be NULL if aad_len == 0.
+ * This pointer can be \c NULL if `aad_len == 0`.
* \param aad_len The length (in bytes) of the AAD data to process.
* \param tag The buffer holding the authentication tag.
+ * This must be a readable buffer of length \c 16 Bytes.
* \param input The buffer containing the data to decrypt.
- * This pointer can be NULL if ilen == 0.
+ * This pointer can be \c NULL if `ilen == 0`.
* \param output The buffer to where the decrypted data is written.
- * This pointer can be NULL if ilen == 0.
+ * This pointer can be \c NULL if `ilen == 0`.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- * if one or more of the required parameters are NULL.
* \return #MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED
* if the data was not authentic.
+ * \return Another negative error code on other kinds of failure.
*/
int mbedtls_chachapoly_auth_decrypt( mbedtls_chachapoly_context *ctx,
size_t length,
diff --git a/include/mbedtls/check_config.h b/include/mbedtls/check_config.h
index 508c00a..0fa74f0 100644
--- a/include/mbedtls/check_config.h
+++ b/include/mbedtls/check_config.h
@@ -50,6 +50,11 @@
!defined(MBEDTLS_PLATFORM_SNPRINTF_MACRO)
#define MBEDTLS_PLATFORM_SNPRINTF_ALT
#endif
+
+#if !defined(MBEDTLS_PLATFORM_VSNPRINTF_ALT) && \
+ !defined(MBEDTLS_PLATFORM_VSNPRINTF_MACRO)
+#define MBEDTLS_PLATFORM_VSNPRINTF_ALT
+#endif
#endif /* _WIN32 */
#if defined(TARGET_LIKE_MBED) && \
@@ -109,13 +114,20 @@
#endif
#if defined(MBEDTLS_ECP_RESTARTABLE) && \
- ( defined(MBEDTLS_ECDH_COMPUTE_SHARED_ALT) || \
+ ( defined(MBEDTLS_USE_PSA_CRYPTO) || \
+ defined(MBEDTLS_ECDH_COMPUTE_SHARED_ALT) || \
defined(MBEDTLS_ECDH_GEN_PUBLIC_ALT) || \
defined(MBEDTLS_ECDSA_SIGN_ALT) || \
defined(MBEDTLS_ECDSA_VERIFY_ALT) || \
defined(MBEDTLS_ECDSA_GENKEY_ALT) || \
+ defined(MBEDTLS_ECP_INTERNAL_ALT) || \
defined(MBEDTLS_ECP_ALT) )
-#error "MBEDTLS_ECP_RESTARTABLE defined, but it cannot coexist with an alternative ECP implementation"
+#error "MBEDTLS_ECP_RESTARTABLE defined, but it cannot coexist with an alternative or PSA-based ECP implementation"
+#endif
+
+#if defined(MBEDTLS_ECP_RESTARTABLE) && \
+ ! defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
+#error "MBEDTLS_ECP_RESTARTABLE defined, but not MBEDTLS_ECDH_LEGACY_CONTEXT"
#endif
#if defined(MBEDTLS_ECDSA_DETERMINISTIC) && !defined(MBEDTLS_HMAC_DRBG_C)
@@ -137,6 +149,10 @@
#error "MBEDTLS_ECP_C defined, but not all prerequisites"
#endif
+#if defined(MBEDTLS_PK_PARSE_C) && !defined(MBEDTLS_ASN1_PARSE_C)
+#error "MBEDTLS_PK_PARSE_C defined, but not all prerequesites"
+#endif
+
#if defined(MBEDTLS_ENTROPY_C) && (!defined(MBEDTLS_SHA512_C) && \
!defined(MBEDTLS_SHA256_C))
#error "MBEDTLS_ENTROPY_C defined, but not all prerequisites"
@@ -269,6 +285,14 @@
#error "MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED defined, but not all prerequisites"
#endif
+#if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED) && \
+ !defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE) && \
+ ( !defined(MBEDTLS_SHA256_C) && \
+ !defined(MBEDTLS_SHA512_C) && \
+ !defined(MBEDTLS_SHA1_C) )
+#error "!MBEDTLS_SSL_KEEP_PEER_CERTIFICATE requires MBEDTLS_SHA512_C, MBEDTLS_SHA256_C or MBEDTLS_SHA1_C"
+#endif
+
#if defined(MBEDTLS_MEMORY_BUFFER_ALLOC_C) && \
( !defined(MBEDTLS_PLATFORM_C) || !defined(MBEDTLS_PLATFORM_MEMORY) )
#error "MBEDTLS_MEMORY_BUFFER_ALLOC_C defined, but not all prerequisites"
@@ -506,26 +530,25 @@
#error "MBEDTLS_PSA_CRYPTO_SPM defined, but not all prerequisites"
#endif
-#if defined(MBEDTLS_PSA_CRYPTO_STORAGE_FILE_C) && defined(MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C)
-#error "Only one of MBEDTLS_PSA_CRYPTO_STORAGE_FILE_C or MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C can be defined"
-#endif
-
#if defined(MBEDTLS_PSA_CRYPTO_STORAGE_C) && \
- !( defined(MBEDTLS_PSA_CRYPTO_C) && \
- ( defined(MBEDTLS_PSA_CRYPTO_STORAGE_FILE_C) || \
- defined(MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C) ) )
+ ! defined(MBEDTLS_PSA_CRYPTO_C)
#error "MBEDTLS_PSA_CRYPTO_STORAGE_C defined, but not all prerequisites"
#endif
-#if defined(MBEDTLS_PSA_CRYPTO_STORAGE_FILE_C) && \
- !( defined(MBEDTLS_PSA_CRYPTO_STORAGE_C) && \
- defined(MBEDTLS_FS_IO) )
-#error "MBEDTLS_PSA_CRYPTO_STORAGE_FILE_C defined, but not all prerequisites"
+#if defined(MBEDTLS_PSA_INJECT_ENTROPY) && \
+ !( defined(MBEDTLS_PSA_CRYPTO_STORAGE_C) && \
+ defined(MBEDTLS_ENTROPY_NV_SEED) )
+#error "MBEDTLS_PSA_INJECT_ENTROPY defined, but not all prerequisites"
#endif
-#if defined(MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C) && \
- ! defined(MBEDTLS_PSA_CRYPTO_STORAGE_C)
-#error "MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C defined, but not all prerequisites"
+#if defined(MBEDTLS_PSA_INJECT_ENTROPY) && \
+ !defined(MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES)
+#error "MBEDTLS_PSA_INJECT_ENTROPY is not compatible with actual entropy sources"
+#endif
+
+#if defined(MBEDTLS_PSA_ITS_FILE_C) && \
+ !defined(MBEDTLS_FS_IO)
+#error "MBEDTLS_PSA_ITS_FILE_C defined, but not all prerequisites"
#endif
#if defined(MBEDTLS_RSA_C) && ( !defined(MBEDTLS_BIGNUM_C) || \
@@ -722,7 +745,7 @@
/*
* Avoid warning from -pedantic. This is a convenient place for this
* workaround since this is included by every single file before the
- * #if defined(MBEDTLS_xxx_C) that results in emtpy translation units.
+ * #if defined(MBEDTLS_xxx_C) that results in empty translation units.
*/
typedef int mbedtls_iso_c_forbids_empty_translation_units;
diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h
index d6ecac6..2d609db 100644
--- a/include/mbedtls/cipher.h
+++ b/include/mbedtls/cipher.h
@@ -36,6 +36,7 @@
#endif
#include <stddef.h>
+#include "platform_util.h"
#if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
#define MBEDTLS_CIPHER_MODE_AEAD
@@ -354,11 +355,12 @@
* \brief This function retrieves the cipher-information
* structure associated with the given cipher name.
*
- * \param cipher_name Name of the cipher to search for.
+ * \param cipher_name Name of the cipher to search for. This must not be
+ * \c NULL.
*
* \return The cipher information structure associated with the
* given \p cipher_name.
- * \return NULL if the associated cipher information is not found.
+ * \return \c NULL if the associated cipher information is not found.
*/
const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name );
@@ -370,7 +372,7 @@
*
* \return The cipher information structure associated with the
* given \p cipher_type.
- * \return NULL if the associated cipher information is not found.
+ * \return \c NULL if the associated cipher information is not found.
*/
const mbedtls_cipher_info_t *mbedtls_cipher_info_from_type( const mbedtls_cipher_type_t cipher_type );
@@ -386,7 +388,7 @@
*
* \return The cipher information structure associated with the
* given \p cipher_id.
- * \return NULL if the associated cipher information is not found.
+ * \return \c NULL if the associated cipher information is not found.
*/
const mbedtls_cipher_info_t *mbedtls_cipher_info_from_values( const mbedtls_cipher_id_t cipher_id,
int key_bitlen,
@@ -394,6 +396,8 @@
/**
* \brief This function initializes a \p cipher_context as NONE.
+ *
+ * \param ctx The context to be initialized. This must not be \c NULL.
*/
void mbedtls_cipher_init( mbedtls_cipher_context_t *ctx );
@@ -401,6 +405,10 @@
* \brief This function frees and clears the cipher-specific
* context of \p ctx. Freeing \p ctx itself remains the
* responsibility of the caller.
+ *
+ * \param ctx The context to be freed. If this is \c NULL, the
+ * function has no effect, otherwise this must point to an
+ * initialized context.
*/
void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx );
@@ -409,7 +417,7 @@
* \brief This function initializes a cipher context for
* use with the given cipher primitive.
*
- * \param ctx The context to initialize. May not be NULL.
+ * \param ctx The context to initialize. This must be initialized.
* \param cipher_info The cipher to use.
*
* \return \c 0 on success.
@@ -455,15 +463,16 @@
/**
* \brief This function returns the block size of the given cipher.
*
- * \param ctx The context of the cipher. Must be initialized.
+ * \param ctx The context of the cipher. This must be initialized.
*
- * \return The size of the blocks of the cipher.
- * \return 0 if \p ctx has not been initialized.
+ * \return The block size of the underlying cipher.
+ * \return \c 0 if \p ctx has not been initialized.
*/
static inline unsigned int mbedtls_cipher_get_block_size(
const mbedtls_cipher_context_t *ctx )
{
- if( NULL == ctx || NULL == ctx->cipher_info )
+ MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, 0 );
+ if( ctx->cipher_info == NULL )
return 0;
return ctx->cipher_info->block_size;
@@ -473,7 +482,7 @@
* \brief This function returns the mode of operation for
* the cipher. For example, MBEDTLS_MODE_CBC.
*
- * \param ctx The context of the cipher. Must be initialized.
+ * \param ctx The context of the cipher. This must be initialized.
*
* \return The mode of operation.
* \return #MBEDTLS_MODE_NONE if \p ctx has not been initialized.
@@ -481,7 +490,8 @@
static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode(
const mbedtls_cipher_context_t *ctx )
{
- if( NULL == ctx || NULL == ctx->cipher_info )
+ MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, MBEDTLS_MODE_NONE );
+ if( ctx->cipher_info == NULL )
return MBEDTLS_MODE_NONE;
return ctx->cipher_info->mode;
@@ -491,7 +501,7 @@
* \brief This function returns the size of the IV or nonce
* of the cipher, in Bytes.
*
- * \param ctx The context of the cipher. Must be initialized.
+ * \param ctx The context of the cipher. This must be initialized.
*
* \return The recommended IV size if no IV has been set.
* \return \c 0 for ciphers not using an IV or a nonce.
@@ -500,7 +510,8 @@
static inline int mbedtls_cipher_get_iv_size(
const mbedtls_cipher_context_t *ctx )
{
- if( NULL == ctx || NULL == ctx->cipher_info )
+ MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, 0 );
+ if( ctx->cipher_info == NULL )
return 0;
if( ctx->iv_size != 0 )
@@ -512,7 +523,7 @@
/**
* \brief This function returns the type of the given cipher.
*
- * \param ctx The context of the cipher. Must be initialized.
+ * \param ctx The context of the cipher. This must be initialized.
*
* \return The type of the cipher.
* \return #MBEDTLS_CIPHER_NONE if \p ctx has not been initialized.
@@ -520,7 +531,9 @@
static inline mbedtls_cipher_type_t mbedtls_cipher_get_type(
const mbedtls_cipher_context_t *ctx )
{
- if( NULL == ctx || NULL == ctx->cipher_info )
+ MBEDTLS_INTERNAL_VALIDATE_RET(
+ ctx != NULL, MBEDTLS_CIPHER_NONE );
+ if( ctx->cipher_info == NULL )
return MBEDTLS_CIPHER_NONE;
return ctx->cipher_info->type;
@@ -530,7 +543,7 @@
* \brief This function returns the name of the given cipher
* as a string.
*
- * \param ctx The context of the cipher. Must be initialized.
+ * \param ctx The context of the cipher. This must be initialized.
*
* \return The name of the cipher.
* \return NULL if \p ctx has not been not initialized.
@@ -538,7 +551,8 @@
static inline const char *mbedtls_cipher_get_name(
const mbedtls_cipher_context_t *ctx )
{
- if( NULL == ctx || NULL == ctx->cipher_info )
+ MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, 0 );
+ if( ctx->cipher_info == NULL )
return 0;
return ctx->cipher_info->name;
@@ -547,7 +561,7 @@
/**
* \brief This function returns the key length of the cipher.
*
- * \param ctx The context of the cipher. Must be initialized.
+ * \param ctx The context of the cipher. This must be initialized.
*
* \return The key length of the cipher in bits.
* \return #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been
@@ -556,7 +570,9 @@
static inline int mbedtls_cipher_get_key_bitlen(
const mbedtls_cipher_context_t *ctx )
{
- if( NULL == ctx || NULL == ctx->cipher_info )
+ MBEDTLS_INTERNAL_VALIDATE_RET(
+ ctx != NULL, MBEDTLS_KEY_LENGTH_NONE );
+ if( ctx->cipher_info == NULL )
return MBEDTLS_KEY_LENGTH_NONE;
return (int) ctx->cipher_info->key_bitlen;
@@ -565,7 +581,7 @@
/**
* \brief This function returns the operation of the given cipher.
*
- * \param ctx The context of the cipher. Must be initialized.
+ * \param ctx The context of the cipher. This must be initialized.
*
* \return The type of operation: #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT.
* \return #MBEDTLS_OPERATION_NONE if \p ctx has not been initialized.
@@ -573,7 +589,9 @@
static inline mbedtls_operation_t mbedtls_cipher_get_operation(
const mbedtls_cipher_context_t *ctx )
{
- if( NULL == ctx || NULL == ctx->cipher_info )
+ MBEDTLS_INTERNAL_VALIDATE_RET(
+ ctx != NULL, MBEDTLS_OPERATION_NONE );
+ if( ctx->cipher_info == NULL )
return MBEDTLS_OPERATION_NONE;
return ctx->operation;
@@ -582,11 +600,11 @@
/**
* \brief This function sets the key to use with the given context.
*
- * \param ctx The generic cipher context. May not be NULL. Must have
- * been initialized using mbedtls_cipher_info_from_type()
- * or mbedtls_cipher_info_from_string().
- * \param key The key to use.
- * \param key_bitlen The key length to use, in bits.
+ * \param ctx The generic cipher context. This must be initialized and
+ * bound to a cipher information structure.
+ * \param key The key to use. This must be a readable buffer of at
+ * least \p key_bitlen Bits.
+ * \param key_bitlen The key length to use, in Bits.
* \param operation The operation that the key will be used for:
* #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT.
*
@@ -607,7 +625,8 @@
*
* The default passing mode is PKCS7 padding.
*
- * \param ctx The generic cipher context.
+ * \param ctx The generic cipher context. This must be initialized and
+ * bound to a cipher information structure.
* \param mode The padding mode.
*
* \return \c 0 on success.
@@ -627,8 +646,10 @@
* \note Some ciphers do not use IVs nor nonce. For these
* ciphers, this function has no effect.
*
- * \param ctx The generic cipher context.
- * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
+ * \param ctx The generic cipher context. This must be initialized and
+ * bound to a cipher information structure.
+ * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. This
+ * must be a readable buffer of at least \p iv_len Bytes.
* \param iv_len The IV length for ciphers with variable-size IV.
* This parameter is discarded by ciphers with fixed-size IV.
*
@@ -637,12 +658,13 @@
* parameter-verification failure.
*/
int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx,
- const unsigned char *iv, size_t iv_len );
+ const unsigned char *iv,
+ size_t iv_len );
/**
* \brief This function resets the cipher state.
*
- * \param ctx The generic cipher context.
+ * \param ctx The generic cipher context. This must be initialized.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
@@ -652,16 +674,18 @@
#if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
/**
- * \brief This function adds additional data for AEAD ciphers.
- * Currently supported with GCM and ChaCha20+Poly1305.
- * Must be called exactly once, after mbedtls_cipher_reset().
+ * \brief This function adds additional data for AEAD ciphers.
+ * Currently supported with GCM and ChaCha20+Poly1305.
+ * This must be called exactly once, after
+ * mbedtls_cipher_reset().
*
- * \param ctx The generic cipher context.
- * \param ad The additional data to use.
- * \param ad_len the Length of \p ad.
+ * \param ctx The generic cipher context. This must be initialized.
+ * \param ad The additional data to use. This must be a readable
+ * buffer of at least \p ad_len Bytes.
+ * \param ad_len The length of \p ad in Bytes.
*
- * \return \c 0 on success.
- * \return A specific error code on failure.
+ * \return \c 0 on success.
+ * \return A specific error code on failure.
*/
int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx,
const unsigned char *ad, size_t ad_len );
@@ -682,14 +706,17 @@
* mbedtls_cipher_finish(), must have \p ilen as a
* multiple of the block size of the cipher.
*
- * \param ctx The generic cipher context.
- * \param input The buffer holding the input data.
+ * \param ctx The generic cipher context. This must be initialized and
+ * bound to a key.
+ * \param input The buffer holding the input data. This must be a
+ * readable buffer of at least \p ilen Bytes.
* \param ilen The length of the input data.
- * \param output The buffer for the output data. Must be able to hold at
- * least \p ilen + block_size. Must not be the same buffer
- * as input.
+ * \param output The buffer for the output data. This must be able to
+ * hold at least `ilen + block_size`. This must not be the
+ * same buffer as \p input.
* \param olen The length of the output data, to be updated with the
- * actual number of Bytes written.
+ * actual number of Bytes written. This must not be
+ * \c NULL.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
@@ -709,9 +736,12 @@
* contained in it is padded to the size of
* the last block, and written to the \p output buffer.
*
- * \param ctx The generic cipher context.
- * \param output The buffer to write data to. Needs block_size available.
+ * \param ctx The generic cipher context. This must be initialized and
+ * bound to a key.
+ * \param output The buffer to write data to. This needs to be a writable
+ * buffer of at least \p block_size Bytes.
* \param olen The length of the data written to the \p output buffer.
+ * This may not be \c NULL.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
@@ -729,10 +759,14 @@
/**
* \brief This function writes a tag for AEAD ciphers.
* Currently supported with GCM and ChaCha20+Poly1305.
- * Must be called after mbedtls_cipher_finish().
+ * This must be called after mbedtls_cipher_finish().
*
- * \param ctx The generic cipher context.
- * \param tag The buffer to write the tag to.
+ * \param ctx The generic cipher context. This must be initialized,
+ * bound to a key, and have just completed a cipher
+ * operation through mbedtls_cipher_finish() the tag for
+ * which should be written.
+ * \param tag The buffer to write the tag to. This must be a writable
+ * buffer of at least \p tag_len Bytes.
* \param tag_len The length of the tag to write.
*
* \return \c 0 on success.
@@ -744,10 +778,11 @@
/**
* \brief This function checks the tag for AEAD ciphers.
* Currently supported with GCM and ChaCha20+Poly1305.
- * Must be called after mbedtls_cipher_finish().
+ * This must be called after mbedtls_cipher_finish().
*
- * \param ctx The generic cipher context.
- * \param tag The buffer holding the tag.
+ * \param ctx The generic cipher context. This must be initialized.
+ * \param tag The buffer holding the tag. This must be a readable
+ * buffer of at least \p tag_len Bytes.
* \param tag_len The length of the tag to check.
*
* \return \c 0 on success.
@@ -761,18 +796,22 @@
* \brief The generic all-in-one encryption/decryption function,
* for all ciphers except AEAD constructs.
*
- * \param ctx The generic cipher context.
+ * \param ctx The generic cipher context. This must be initialized.
* \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
+ * This must be a readable buffer of at least \p iv_len
+ * Bytes.
* \param iv_len The IV length for ciphers with variable-size IV.
* This parameter is discarded by ciphers with fixed-size
* IV.
- * \param input The buffer holding the input data.
- * \param ilen The length of the input data.
- * \param output The buffer for the output data. Must be able to hold at
- * least \p ilen + block_size. Must not be the same buffer
- * as input.
+ * \param input The buffer holding the input data. This must be a
+ * readable buffer of at least \p ilen Bytes.
+ * \param ilen The length of the input data in Bytes.
+ * \param output The buffer for the output data. This must be able to
+ * hold at least `ilen + block_size`. This must not be the
+ * same buffer as \p input.
* \param olen The length of the output data, to be updated with the
- * actual number of Bytes written.
+ * actual number of Bytes written. This must not be
+ * \c NULL.
*
* \note Some ciphers do not use IVs nor nonce. For these
* ciphers, use \p iv = NULL and \p iv_len = 0.
@@ -793,27 +832,34 @@
#if defined(MBEDTLS_CIPHER_MODE_AEAD)
/**
- * \brief The generic autenticated encryption (AEAD) function.
+ * \brief The generic autenticated encryption (AEAD) function.
*
- * \param ctx The generic cipher context.
- * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
- * \param iv_len The IV length for ciphers with variable-size IV.
- * This parameter is discarded by ciphers with fixed-size IV.
- * \param ad The additional data to authenticate.
- * \param ad_len The length of \p ad.
- * \param input The buffer holding the input data.
- * \param ilen The length of the input data.
- * \param output The buffer for the output data.
- * Must be able to hold at least \p ilen.
- * \param olen The length of the output data, to be updated with the
- * actual number of Bytes written.
- * \param tag The buffer for the authentication tag.
- * \param tag_len The desired length of the authentication tag.
+ * \param ctx The generic cipher context. This must be initialized and
+ * bound to a key.
+ * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
+ * This must be a readable buffer of at least \p iv_len
+ * Bytes.
+ * \param iv_len The IV length for ciphers with variable-size IV.
+ * This parameter is discarded by ciphers with fixed-size IV.
+ * \param ad The additional data to authenticate. This must be a
+ * readable buffer of at least \p ad_len Bytes.
+ * \param ad_len The length of \p ad.
+ * \param input The buffer holding the input data. This must be a
+ * readable buffer of at least \p ilen Bytes.
+ * \param ilen The length of the input data.
+ * \param output The buffer for the output data. This must be able to
+ * hold at least \p ilen Bytes.
+ * \param olen The length of the output data, to be updated with the
+ * actual number of Bytes written. This must not be
+ * \c NULL.
+ * \param tag The buffer for the authentication tag. This must be a
+ * writable buffer of at least \p tag_len Bytes.
+ * \param tag_len The desired length of the authentication tag.
*
- * \return \c 0 on success.
- * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
- * parameter-verification failure.
- * \return A cipher-specific error code on failure.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ * parameter-verification failure.
+ * \return A cipher-specific error code on failure.
*/
int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx,
const unsigned char *iv, size_t iv_len,
@@ -823,32 +869,39 @@
unsigned char *tag, size_t tag_len );
/**
- * \brief The generic autenticated decryption (AEAD) function.
+ * \brief The generic autenticated decryption (AEAD) function.
*
- * \note If the data is not authentic, then the output buffer
- * is zeroed out to prevent the unauthentic plaintext being
- * used, making this interface safer.
+ * \note If the data is not authentic, then the output buffer
+ * is zeroed out to prevent the unauthentic plaintext being
+ * used, making this interface safer.
*
- * \param ctx The generic cipher context.
- * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
- * \param iv_len The IV length for ciphers with variable-size IV.
- * This parameter is discarded by ciphers with fixed-size IV.
- * \param ad The additional data to be authenticated.
- * \param ad_len The length of \p ad.
- * \param input The buffer holding the input data.
- * \param ilen The length of the input data.
- * \param output The buffer for the output data.
- * Must be able to hold at least \p ilen.
- * \param olen The length of the output data, to be updated with the
- * actual number of Bytes written.
- * \param tag The buffer holding the authentication tag.
- * \param tag_len The length of the authentication tag.
+ * \param ctx The generic cipher context. This must be initialized and
+ * and bound to a key.
+ * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
+ * This must be a readable buffer of at least \p iv_len
+ * Bytes.
+ * \param iv_len The IV length for ciphers with variable-size IV.
+ * This parameter is discarded by ciphers with fixed-size IV.
+ * \param ad The additional data to be authenticated. This must be a
+ * readable buffer of at least \p ad_len Bytes.
+ * \param ad_len The length of \p ad.
+ * \param input The buffer holding the input data. This must be a
+ * readable buffer of at least \p ilen Bytes.
+ * \param ilen The length of the input data.
+ * \param output The buffer for the output data.
+ * This must be able to hold at least \p ilen Bytes.
+ * \param olen The length of the output data, to be updated with the
+ * actual number of Bytes written. This must not be
+ * \c NULL.
+ * \param tag The buffer holding the authentication tag. This must be
+ * a readable buffer of at least \p tag_len Bytes.
+ * \param tag_len The length of the authentication tag.
*
- * \return \c 0 on success.
- * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
- * parameter-verification failure.
- * \return #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic.
- * \return A cipher-specific error code on failure.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ * parameter-verification failure.
+ * \return #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic.
+ * \return A cipher-specific error code on failure.
*/
int mbedtls_cipher_auth_decrypt( mbedtls_cipher_context_t *ctx,
const unsigned char *iv, size_t iv_len,
diff --git a/include/mbedtls/cipher_internal.h b/include/mbedtls/cipher_internal.h
index 6687b36..d711339 100644
--- a/include/mbedtls/cipher_internal.h
+++ b/include/mbedtls/cipher_internal.h
@@ -137,7 +137,7 @@
typedef struct
{
psa_algorithm_t alg;
- psa_key_slot_t slot;
+ psa_key_handle_t slot;
mbedtls_cipher_psa_key_ownership slot_state;
} mbedtls_cipher_context_psa;
#endif /* MBEDTLS_USE_PSA_CRYPTO */
diff --git a/include/mbedtls/cmac.h b/include/mbedtls/cmac.h
index c196793..9d42b3f 100644
--- a/include/mbedtls/cmac.h
+++ b/include/mbedtls/cmac.h
@@ -28,6 +28,12 @@
#ifndef MBEDTLS_CMAC_H
#define MBEDTLS_CMAC_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "cipher.h"
#ifdef __cplusplus
diff --git a/include/mbedtls/compat-1.3.h b/include/mbedtls/compat-1.3.h
index 213b691..a58b4724 100644
--- a/include/mbedtls/compat-1.3.h
+++ b/include/mbedtls/compat-1.3.h
@@ -25,6 +25,12 @@
* This file is part of mbed TLS (https://tls.mbed.org)
*/
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
#if defined(MBEDTLS_DEPRECATED_WARNING)
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index 1f37d08..de63146 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -139,7 +139,7 @@
*
* System has time.h, time(), and an implementation for
* mbedtls_platform_gmtime_r() (see below).
- * The time needs to be correct (not necesarily very accurate, but at least
+ * The time needs to be correct (not necessarily very accurate, but at least
* the date should be correct). This is used to verify the validity period of
* X.509 certificates.
*
@@ -226,6 +226,7 @@
//#define MBEDTLS_PLATFORM_FPRINTF_ALT
//#define MBEDTLS_PLATFORM_PRINTF_ALT
//#define MBEDTLS_PLATFORM_SNPRINTF_ALT
+//#define MBEDTLS_PLATFORM_VSNPRINTF_ALT
//#define MBEDTLS_PLATFORM_NV_SEED_ALT
//#define MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT
@@ -256,6 +257,48 @@
*/
//#define MBEDTLS_DEPRECATED_REMOVED
+/**
+ * \def MBEDTLS_CHECK_PARAMS
+ *
+ * This configuration option controls whether the library validates more of
+ * the parameters passed to it.
+ *
+ * When this flag is not defined, the library only attempts to validate an
+ * input parameter if: (1) they may come from the outside world (such as the
+ * network, the filesystem, etc.) or (2) not validating them could result in
+ * internal memory errors such as overflowing a buffer controlled by the
+ * library. On the other hand, it doesn't attempt to validate parameters whose
+ * values are fully controlled by the application (such as pointers).
+ *
+ * When this flag is defined, the library additionally attempts to validate
+ * parameters that are fully controlled by the application, and should always
+ * be valid if the application code is fully correct and trusted.
+ *
+ * For example, when a function accepts as input a pointer to a buffer that may
+ * contain untrusted data, and its documentation mentions that this pointer
+ * must not be NULL:
+ * - the pointer is checked to be non-NULL only if this option is enabled
+ * - the content of the buffer is always validated
+ *
+ * When this flag is defined, if a library function receives a parameter that
+ * is invalid, it will:
+ * - invoke the macro MBEDTLS_PARAM_FAILED() which by default expands to a
+ * call to the function mbedtls_param_failed()
+ * - immediately return (with a specific error code unless the function
+ * returns void and can't communicate an error).
+ *
+ * When defining this flag, you also need to:
+ * - either provide a definition of the function mbedtls_param_failed() in
+ * your application (see platform_util.h for its prototype) as the library
+ * calls that function, but does not provide a default definition for it,
+ * - or provide a different definition of the macro MBEDTLS_PARAM_FAILED()
+ * below if the above mechanism is not flexible enough to suit your needs.
+ * See the documentation of this macro later in this file.
+ *
+ * Uncomment to enable validation of application-controlled parameters.
+ */
+//#define MBEDTLS_CHECK_PARAMS
+
/* \} name SECTION: System support */
/**
@@ -359,7 +402,7 @@
* \note Because of a signature change, the core AES encryption and decryption routines are
* currently named mbedtls_aes_internal_encrypt and mbedtls_aes_internal_decrypt,
* respectively. When setting up alternative implementations, these functions should
- * be overriden, but the wrapper functions mbedtls_aes_decrypt and mbedtls_aes_encrypt
+ * be overridden, but the wrapper functions mbedtls_aes_decrypt and mbedtls_aes_encrypt
* must stay untouched.
*
* \note If you use the AES_xxx_ALT macros, then is is recommended to also set
@@ -414,11 +457,11 @@
* unsigned char mbedtls_internal_ecp_grp_capable(
* const mbedtls_ecp_group *grp )
* int mbedtls_internal_ecp_init( const mbedtls_ecp_group *grp )
- * void mbedtls_internal_ecp_deinit( const mbedtls_ecp_group *grp )
+ * void mbedtls_internal_ecp_free( const mbedtls_ecp_group *grp )
* The mbedtls_internal_ecp_grp_capable function should return 1 if the
* replacement functions implement arithmetic for the given group and 0
* otherwise.
- * The functions mbedtls_internal_ecp_init and mbedtls_internal_ecp_deinit are
+ * The functions mbedtls_internal_ecp_init and mbedtls_internal_ecp_free are
* called before and after each point operation and provide an opportunity to
* implement optimized set up and tear down instructions.
*
@@ -645,6 +688,26 @@
#define MBEDTLS_REMOVE_ARC4_CIPHERSUITES
/**
+ * \def MBEDTLS_REMOVE_3DES_CIPHERSUITES
+ *
+ * Remove 3DES ciphersuites by default in SSL / TLS.
+ * This flag removes the ciphersuites based on 3DES from the default list as
+ * returned by mbedtls_ssl_list_ciphersuites(). However, it is still possible
+ * to enable (some of) them with mbedtls_ssl_conf_ciphersuites() by including
+ * them explicitly.
+ *
+ * A man-in-the-browser attacker can recover authentication tokens sent through
+ * a TLS connection using a 3DES based cipher suite (see "On the Practical
+ * (In-)Security of 64-bit Block Ciphers" by Karthikeyan Bhargavan and Gaëtan
+ * Leurent, see https://sweet32.info/SWEET32_CCS16.pdf). If this attack falls
+ * in your threat model or you are unsure, then you should keep this option
+ * enabled to remove 3DES based cipher suites.
+ *
+ * Comment this macro to keep 3DES in the default ciphersuite list.
+ */
+#define MBEDTLS_REMOVE_3DES_CIPHERSUITES
+
+/**
* \def MBEDTLS_ECP_DP_SECP192R1_ENABLED
*
* MBEDTLS_ECP_XXXX_ENABLED: Enables specific curves within the Elliptic Curve
@@ -683,11 +746,11 @@
* Enable "non-blocking" ECC operations that can return early and be resumed.
*
* This allows various functions to pause by returning
- * #MBEDTLS_ERR_ECP_IN_PROGRESS (or, for functions in the SSL module,
- * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS) and then be called later again in
- * order to further progress and eventually complete their operation. This is
- * controlled through mbedtls_ecp_set_max_ops() which limits the maximum
- * number of ECC operations a function may perform before pausing; see
+ * #MBEDTLS_ERR_ECP_IN_PROGRESS (or, for functions in Mbed TLS's SSL module,
+ * MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS) and then be called later again in order
+ * to further progress and eventually complete their operation. This is
+ * controlled through mbedtls_ecp_set_max_ops() which limits the maximum number
+ * of ECC operations a function may perform before pausing; see
* mbedtls_ecp_set_max_ops() for more information.
*
* This is useful in non-threaded environments if you want to avoid blocking
@@ -697,11 +760,40 @@
*
* \note This option only works with the default software implementation of
* elliptic curve functionality. It is incompatible with
- * MBEDTLS_ECP_ALT, MBEDTLS_ECDH_XXX_ALT and MBEDTLS_ECDSA_XXX_ALT.
+ * MBEDTLS_ECP_ALT, MBEDTLS_ECDH_XXX_ALT, MBEDTLS_ECDSA_XXX_ALT
+ * and MBEDTLS_ECDH_LEGACY_CONTEXT.
*/
//#define MBEDTLS_ECP_RESTARTABLE
/**
+ * \def MBEDTLS_ECDH_LEGACY_CONTEXT
+ *
+ * Use a backward compatible ECDH context.
+ *
+ * Mbed TLS supports two formats for ECDH contexts (#mbedtls_ecdh_context
+ * defined in `ecdh.h`). For most applications, the choice of format makes
+ * no difference, since all library functions can work with either format,
+ * except that the new format is incompatible with MBEDTLS_ECP_RESTARTABLE.
+
+ * The new format used when this option is disabled is smaller
+ * (56 bytes on a 32-bit platform). In future versions of the library, it
+ * will support alternative implementations of ECDH operations.
+ * The new format is incompatible with applications that access
+ * context fields directly and with restartable ECP operations.
+ *
+ * Define this macro if you enable MBEDTLS_ECP_RESTARTABLE or if you
+ * want to access ECDH context fields directly. Otherwise you should
+ * comment out this macro definition.
+ *
+ * This option has no effect if #MBEDTLS_ECDH_C is not enabled.
+ *
+ * \note This configuration option is experimental. Future versions of the
+ * library may modify the way the ECDH context layout is configured
+ * and may modify the layout of the new context type.
+ */
+#define MBEDTLS_ECDH_LEGACY_CONTEXT
+
+/**
* \def MBEDTLS_ECDSA_DETERMINISTIC
*
* Enable deterministic ECDSA (RFC 6979).
@@ -1103,15 +1195,20 @@
*/
//#define MBEDTLS_ENTROPY_NV_SEED
-/**
- * \def MBEDTLS_PSA_HAS_ITS_IO
+/* MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER
*
- * Enable the non-volatile secure storage usage.
+ * In PSA key storage, encode the owner of the key.
*
- * This is crucial on systems that do not have a HW TRNG support.
+ * This is only meaningful when building the library as part of a
+ * multi-client service. When you activate this option, you must provide
+ * an implementation of the type psa_key_owner_id_t and a translation
+ * from psa_key_file_id_t to file name in all the storage backends that
+ * you wish to support.
*
+ * Note that this option is meant for internal use only and may be removed
+ * without notice.
*/
-//#define MBEDTLS_PSA_HAS_ITS_IO
+//#define MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER
/**
* \def MBEDTLS_MEMORY_DEBUG
@@ -1184,14 +1281,17 @@
//#define MBEDTLS_PSA_CRYPTO_SPM
/**
- * \def MBEDTLS_PSA_HAS_ITS_IO
+ * \def MBEDTLS_PSA_INJECT_ENTROPY
*
- * Enable the non-volatile secure storage usage.
+ * Enable support for entropy injection at first boot. This feature is
+ * required on systems that do not have a built-in entropy source (TRNG).
+ * This feature is currently not supported on systems that have a built-in
+ * entropy source.
*
- * This is crucial on systems that do not have a HW TRNG support.
+ * Requires: MBEDTLS_PSA_CRYPTO_STORAGE_C, MBEDTLS_ENTROPY_NV_SEED
*
*/
-//#define MBEDTLS_PSA_HAS_ITS_IO
+//#define MBEDTLS_PSA_INJECT_ENTROPY
/**
* \def MBEDTLS_RSA_NO_CRT
@@ -1322,6 +1422,28 @@
#define MBEDTLS_SSL_FALLBACK_SCSV
/**
+ * \def MBEDTLS_SSL_KEEP_PEER_CERTIFICATE
+ *
+ * This option controls the availability of the API mbedtls_ssl_get_peer_cert()
+ * giving access to the peer's certificate after completion of the handshake.
+ *
+ * Unless you need mbedtls_ssl_peer_cert() in your application, it is
+ * recommended to disable this option for reduced RAM usage.
+ *
+ * \note If this option is disabled, mbedtls_ssl_get_peer_cert() is still
+ * defined, but always returns \c NULL.
+ *
+ * \note This option has no influence on the protection against the
+ * triple handshake attack. Even if it is disabled, Mbed TLS will
+ * still ensure that certificates do not change during renegotiation,
+ * for exaple by keeping a hash of the peer's certificate.
+ *
+ * Comment this macro to disable storing the peer's certificate
+ * after the handshake.
+ */
+#define MBEDTLS_SSL_KEEP_PEER_CERTIFICATE
+
+/**
* \def MBEDTLS_SSL_HW_RECORD_ACCEL
*
* Enable hooking functions in SSL module for hardware acceleration of
@@ -1530,7 +1652,7 @@
* \def MBEDTLS_SSL_SESSION_TICKETS
*
* Enable support for RFC 5077 session tickets in SSL.
- * Client-side, provides full support for session tickets (maintainance of a
+ * Client-side, provides full support for session tickets (maintenance of a
* session store remains the responsibility of the application, though).
* Server-side, you also need to provide callbacks for writing and parsing
* tickets, including authenticated encryption and key management. Example
@@ -1714,7 +1836,7 @@
*
* \warning TLS-level compression MAY REDUCE SECURITY! See for example the
* CRIME attack. Before enabling this option, you should examine with care if
- * CRIME or similar exploits may be a applicable to your use case.
+ * CRIME or similar exploits may be applicable to your use case.
*
* \note Currently compression can't be used with DTLS.
*
@@ -2661,38 +2783,23 @@
*
* Module: library/psa_crypto_storage.c
*
- * Requires: MBEDTLS_PSA_CRYPTO_C and one of either
- * MBEDTLS_PSA_CRYPTO_STORAGE_FILE_C or MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C
- * (but not both)
- *
+ * Requires: MBEDTLS_PSA_CRYPTO_C,
+ * either MBEDTLS_PSA_ITS_FILE_C or a native implementation of
+ * the PSA ITS interface
*/
#define MBEDTLS_PSA_CRYPTO_STORAGE_C
/**
- * \def MBEDTLS_PSA_CRYPTO_STORAGE_FILE_C
+ * \def MBEDTLS_PSA_ITS_FILE_C
*
- * Enable persistent key storage over files for the
- * Platform Security Architecture cryptography API.
+ * Enable the emulation of the Platform Security Architecture
+ * Internal Trusted Storage (PSA ITS) over files.
*
- * Module: library/psa_crypto_storage_file.c
+ * Module: library/psa_its_file.c
*
- * Requires: MBEDTLS_PSA_CRYPTO_C, MBEDTLS_FS_IO
- *
+ * Requires: MBEDTLS_FS_IO
*/
-#define MBEDTLS_PSA_CRYPTO_STORAGE_FILE_C
-
-/**
- * \def MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C
- *
- * Enable persistent key storage over PSA ITS for the
- * Platform Security Architecture cryptography API.
- *
- * Module: library/psa_crypto_storage_its.c
- *
- * Requires: MBEDTLS_PSA_CRYPTO_C, MBEDTLS_PSA_HAS_ITS_IO
- *
- */
-//#define MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C
+#define MBEDTLS_PSA_ITS_FILE_C
/**
* \def MBEDTLS_RIPEMD160_C
@@ -3078,7 +3185,7 @@
//#define MBEDTLS_PLATFORM_STD_TIME time /**< Default time to use, can be undefined. MBEDTLS_HAVE_TIME must be enabled */
//#define MBEDTLS_PLATFORM_STD_FPRINTF fprintf /**< Default fprintf to use, can be undefined */
//#define MBEDTLS_PLATFORM_STD_PRINTF printf /**< Default printf to use, can be undefined */
-/* Note: your snprintf must correclty zero-terminate the buffer! */
+/* Note: your snprintf must correctly zero-terminate the buffer! */
//#define MBEDTLS_PLATFORM_STD_SNPRINTF snprintf /**< Default snprintf to use, can be undefined */
//#define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS 0 /**< Default exit value to use, can be undefined */
//#define MBEDTLS_PLATFORM_STD_EXIT_FAILURE 1 /**< Default exit value to use, can be undefined */
@@ -3095,11 +3202,42 @@
//#define MBEDTLS_PLATFORM_TIME_TYPE_MACRO time_t /**< Default time macro to use, can be undefined. MBEDTLS_HAVE_TIME must be enabled */
//#define MBEDTLS_PLATFORM_FPRINTF_MACRO fprintf /**< Default fprintf macro to use, can be undefined */
//#define MBEDTLS_PLATFORM_PRINTF_MACRO printf /**< Default printf macro to use, can be undefined */
-/* Note: your snprintf must correclty zero-terminate the buffer! */
+/* Note: your snprintf must correctly zero-terminate the buffer! */
//#define MBEDTLS_PLATFORM_SNPRINTF_MACRO snprintf /**< Default snprintf macro to use, can be undefined */
+//#define MBEDTLS_PLATFORM_VSNPRINTF_MACRO vsnprintf /**< Default vsnprintf macro to use, can be undefined */
//#define MBEDTLS_PLATFORM_NV_SEED_READ_MACRO mbedtls_platform_std_nv_seed_read /**< Default nv_seed_read function to use, can be undefined */
//#define MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO mbedtls_platform_std_nv_seed_write /**< Default nv_seed_write function to use, can be undefined */
+/**
+ * \brief This macro is invoked by the library when an invalid parameter
+ * is detected that is only checked with MBEDTLS_CHECK_PARAMS
+ * (see the documentation of that option for context).
+ *
+ * When you leave this undefined here, a default definition is
+ * provided that invokes the function mbedtls_param_failed(),
+ * which is declared in platform_util.h for the benefit of the
+ * library, but that you need to define in your application.
+ *
+ * When you define this here, this replaces the default
+ * definition in platform_util.h (which no longer declares the
+ * function mbedtls_param_failed()) and it is your responsibility
+ * to make sure this macro expands to something suitable (in
+ * particular, that all the necessary declarations are visible
+ * from within the library - you can ensure that by providing
+ * them in this file next to the macro definition).
+ *
+ * Note that you may define this macro to expand to nothing, in
+ * which case you don't have to worry about declarations or
+ * definitions. However, you will then be notified about invalid
+ * parameters only in non-void functions, and void function will
+ * just silently return early on invalid parameters, which
+ * partially negates the benefits of enabling
+ * #MBEDTLS_CHECK_PARAMS in the first place, so is discouraged.
+ *
+ * \param cond The expression that should evaluate to true, but doesn't.
+ */
+//#define MBEDTLS_PARAM_FAILED( cond ) assert( cond )
+
/* SSL Cache options */
//#define MBEDTLS_SSL_CACHE_DEFAULT_TIMEOUT 86400 /**< 1 day */
//#define MBEDTLS_SSL_CACHE_DEFAULT_MAX_ENTRIES 50 /**< Maximum entries in cache */
@@ -3108,31 +3246,65 @@
/** \def MBEDTLS_SSL_MAX_CONTENT_LEN
*
- * Maximum fragment length in bytes.
+ * Maximum length (in bytes) of incoming and outgoing plaintext fragments.
*
- * Determines the size of both the incoming and outgoing TLS I/O buffers.
+ * This determines the size of both the incoming and outgoing TLS I/O buffers
+ * in such a way that both are capable of holding the specified amount of
+ * plaintext data, regardless of the protection mechanism used.
*
- * Uncommenting MBEDTLS_SSL_IN_CONTENT_LEN and/or MBEDTLS_SSL_OUT_CONTENT_LEN
- * will override this length by setting maximum incoming and/or outgoing
- * fragment length, respectively.
+ * To configure incoming and outgoing I/O buffers separately, use
+ * #MBEDTLS_SSL_IN_CONTENT_LEN and #MBEDTLS_SSL_OUT_CONTENT_LEN,
+ * which overwrite the value set by this option.
+ *
+ * \note When using a value less than the default of 16KB on the client, it is
+ * recommended to use the Maximum Fragment Length (MFL) extension to
+ * inform the server about this limitation. On the server, there
+ * is no supported, standardized way of informing the client about
+ * restriction on the maximum size of incoming messages, and unless
+ * the limitation has been communicated by other means, it is recommended
+ * to only change the outgoing buffer size #MBEDTLS_SSL_OUT_CONTENT_LEN
+ * while keeping the default value of 16KB for the incoming buffer.
+ *
+ * Uncomment to set the maximum plaintext size of both
+ * incoming and outgoing I/O buffers.
*/
//#define MBEDTLS_SSL_MAX_CONTENT_LEN 16384
/** \def MBEDTLS_SSL_IN_CONTENT_LEN
*
- * Maximum incoming fragment length in bytes.
+ * Maximum length (in bytes) of incoming plaintext fragments.
*
- * Uncomment to set the size of the inward TLS buffer independently of the
- * outward buffer.
+ * This determines the size of the incoming TLS I/O buffer in such a way
+ * that it is capable of holding the specified amount of plaintext data,
+ * regardless of the protection mechanism used.
+ *
+ * If this option is undefined, it inherits its value from
+ * #MBEDTLS_SSL_MAX_CONTENT_LEN.
+ *
+ * \note When using a value less than the default of 16KB on the client, it is
+ * recommended to use the Maximum Fragment Length (MFL) extension to
+ * inform the server about this limitation. On the server, there
+ * is no supported, standardized way of informing the client about
+ * restriction on the maximum size of incoming messages, and unless
+ * the limitation has been communicated by other means, it is recommended
+ * to only change the outgoing buffer size #MBEDTLS_SSL_OUT_CONTENT_LEN
+ * while keeping the default value of 16KB for the incoming buffer.
+ *
+ * Uncomment to set the maximum plaintext size of the incoming I/O buffer
+ * independently of the outgoing I/O buffer.
*/
//#define MBEDTLS_SSL_IN_CONTENT_LEN 16384
/** \def MBEDTLS_SSL_OUT_CONTENT_LEN
*
- * Maximum outgoing fragment length in bytes.
+ * Maximum length (in bytes) of outgoing plaintext fragments.
*
- * Uncomment to set the size of the outward TLS buffer independently of the
- * inward buffer.
+ * This determines the size of the outgoing TLS I/O buffer in such a way
+ * that it is capable of holding the specified amount of plaintext data,
+ * regardless of the protection mechanism used.
+ *
+ * If this option undefined, it inherits its value from
+ * #MBEDTLS_SSL_MAX_CONTENT_LEN.
*
* It is possible to save RAM by setting a smaller outward buffer, while keeping
* the default inward 16384 byte buffer to conform to the TLS specification.
@@ -3142,11 +3314,8 @@
* The specific size requirement depends on the configured ciphers and any
* certificate data which is sent during the handshake.
*
- * For absolute minimum RAM usage, it's best to enable
- * MBEDTLS_SSL_MAX_FRAGMENT_LENGTH and reduce MBEDTLS_SSL_MAX_CONTENT_LEN. This
- * reduces both incoming and outgoing buffer sizes. However this is only
- * guaranteed if the other end of the connection also supports the TLS
- * max_fragment_len extension. Otherwise the connection may fail.
+ * Uncomment to set the maximum plaintext size of the outgoing I/O buffer
+ * independently of the incoming I/O buffer.
*/
//#define MBEDTLS_SSL_OUT_CONTENT_LEN 16384
diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h
index c91ca58..cc3df7b 100644
--- a/include/mbedtls/ctr_drbg.h
+++ b/include/mbedtls/ctr_drbg.h
@@ -36,6 +36,12 @@
#ifndef MBEDTLS_CTR_DRBG_H
#define MBEDTLS_CTR_DRBG_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "aes.h"
#if defined(MBEDTLS_THREADING_C)
@@ -239,18 +245,20 @@
/**
* \brief This function updates the state of the CTR_DRBG context.
*
- * \note If \p add_len is greater than
- * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first
- * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used.
- * The remaining Bytes are silently discarded.
- *
* \param ctx The CTR_DRBG context.
* \param additional The data to update the state with.
- * \param add_len Length of \p additional data.
+ * \param add_len Length of \p additional in bytes. This must be at
+ * most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
*
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if
+ * \p add_len is more than
+ * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
+ * \return An error from the underlying AES cipher on failure.
*/
-void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx,
- const unsigned char *additional, size_t add_len );
+int mbedtls_ctr_drbg_update_ret( mbedtls_ctr_drbg_context *ctx,
+ const unsigned char *additional,
+ size_t add_len );
/**
* \brief This function updates a CTR_DRBG instance with additional
@@ -290,6 +298,35 @@
int mbedtls_ctr_drbg_random( void *p_rng,
unsigned char *output, size_t output_len );
+
+#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief This function updates the state of the CTR_DRBG context.
+ *
+ * \deprecated Superseded by mbedtls_ctr_drbg_update_ret()
+ * in 2.16.0.
+ *
+ * \note If \p add_len is greater than
+ * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first
+ * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used.
+ * The remaining Bytes are silently discarded.
+ *
+ * \param ctx The CTR_DRBG context.
+ * \param additional The data to update the state with.
+ * \param add_len Length of \p additional data.
+ */
+MBEDTLS_DEPRECATED void mbedtls_ctr_drbg_update(
+ mbedtls_ctr_drbg_context *ctx,
+ const unsigned char *additional,
+ size_t add_len );
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+
#if defined(MBEDTLS_FS_IO)
/**
* \brief This function writes a seed file.
@@ -319,6 +356,8 @@
int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
#endif /* MBEDTLS_FS_IO */
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief The CTR_DRBG checkup routine.
*
@@ -327,6 +366,8 @@
*/
int mbedtls_ctr_drbg_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
/* Internal functions (do not call directly) */
int mbedtls_ctr_drbg_seed_entropy_len( mbedtls_ctr_drbg_context *,
int (*)(void *, unsigned char *, size_t), void *,
diff --git a/include/mbedtls/debug.h b/include/mbedtls/debug.h
index ef8db67..736444b 100644
--- a/include/mbedtls/debug.h
+++ b/include/mbedtls/debug.h
@@ -65,6 +65,11 @@
mbedtls_debug_print_crt( ssl, level, __FILE__, __LINE__, text, crt )
#endif
+#if defined(MBEDTLS_ECDH_C)
+#define MBEDTLS_SSL_DEBUG_ECDH( level, ecdh, attr ) \
+ mbedtls_debug_printf_ecdh( ssl, level, __FILE__, __LINE__, ecdh, attr )
+#endif
+
#else /* MBEDTLS_DEBUG_C */
#define MBEDTLS_SSL_DEBUG_MSG( level, args ) do { } while( 0 )
@@ -73,6 +78,7 @@
#define MBEDTLS_SSL_DEBUG_MPI( level, text, X ) do { } while( 0 )
#define MBEDTLS_SSL_DEBUG_ECP( level, text, X ) do { } while( 0 )
#define MBEDTLS_SSL_DEBUG_CRT( level, text, crt ) do { } while( 0 )
+#define MBEDTLS_SSL_DEBUG_ECDH( level, ecdh, attr ) do { } while( 0 )
#endif /* MBEDTLS_DEBUG_C */
@@ -221,6 +227,36 @@
const char *text, const mbedtls_x509_crt *crt );
#endif
+#if defined(MBEDTLS_ECDH_C)
+typedef enum
+{
+ MBEDTLS_DEBUG_ECDH_Q,
+ MBEDTLS_DEBUG_ECDH_QP,
+ MBEDTLS_DEBUG_ECDH_Z,
+} mbedtls_debug_ecdh_attr;
+
+/**
+ * \brief Print a field of the ECDH structure in the SSL context to the debug
+ * output. This function is always used through the
+ * MBEDTLS_SSL_DEBUG_ECDH() macro, which supplies the ssl context, file
+ * and line number parameters.
+ *
+ * \param ssl SSL context
+ * \param level error level of the debug message
+ * \param file file the error has occurred in
+ * \param line line number the error has occurred in
+ * \param ecdh the ECDH context
+ * \param attr the identifier of the attribute being output
+ *
+ * \attention This function is intended for INTERNAL usage within the
+ * library only.
+ */
+void mbedtls_debug_printf_ecdh( const mbedtls_ssl_context *ssl, int level,
+ const char *file, int line,
+ const mbedtls_ecdh_context *ecdh,
+ mbedtls_debug_ecdh_attr attr );
+#endif
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/des.h b/include/mbedtls/des.h
index d62042d..54e6b78 100644
--- a/include/mbedtls/des.h
+++ b/include/mbedtls/des.h
@@ -338,6 +338,8 @@
void mbedtls_des_setkey( uint32_t SK[32],
const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief Checkup routine
*
@@ -345,6 +347,8 @@
*/
int mbedtls_des_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/dhm.h b/include/mbedtls/dhm.h
index 8e2d020..98cd4e2 100644
--- a/include/mbedtls/dhm.h
+++ b/include/mbedtls/dhm.h
@@ -127,9 +127,15 @@
void mbedtls_dhm_init( mbedtls_dhm_context *ctx );
/**
- * \brief This function parses the ServerKeyExchange parameters.
+ * \brief This function parses the DHM parameters in a
+ * TLS ServerKeyExchange handshake message
+ * (DHM modulus, generator, and public key).
*
- * \param ctx The DHM context.
+ * \note In a TLS handshake, this is the how the client
+ * sets up its DHM context from the server's public
+ * DHM key material.
+ *
+ * \param ctx The DHM context to use. This must be initialized.
* \param p On input, *p must be the start of the input buffer.
* On output, *p is updated to point to the end of the data
* that has been read. On success, this is the first byte
@@ -143,31 +149,37 @@
* \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
*/
int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx,
- unsigned char **p,
- const unsigned char *end );
+ unsigned char **p,
+ const unsigned char *end );
/**
- * \brief This function sets up and writes the ServerKeyExchange
- * parameters.
+ * \brief This function generates a DHM key pair and exports its
+ * public part together with the DHM parameters in the format
+ * used in a TLS ServerKeyExchange handshake message.
*
- * \note The destination buffer must be large enough to hold
- * the reduced binary presentation of the modulus, the generator
- * and the public key, each wrapped with a 2-byte length field.
- * It is the responsibility of the caller to ensure that enough
- * space is available. Refer to \c mbedtls_mpi_size to computing
- * the byte-size of an MPI.
- *
- * \note This function assumes that \c ctx->P and \c ctx->G
- * have already been properly set. For that, use
+ * \note This function assumes that the DHM parameters \c ctx->P
+ * and \c ctx->G have already been properly set. For that, use
* mbedtls_dhm_set_group() below in conjunction with
* mbedtls_mpi_read_binary() and mbedtls_mpi_read_string().
*
- * \param ctx The DHM context.
+ * \note In a TLS handshake, this is the how the server generates
+ * and exports its DHM key material.
+ *
+ * \param ctx The DHM context to use. This must be initialized
+ * and have the DHM parameters set. It may or may not
+ * already have imported the peer's public key.
* \param x_size The private key size in Bytes.
- * \param olen The number of characters written.
- * \param output The destination buffer.
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
+ * \param olen The address at which to store the number of Bytes
+ * written on success. This must not be \c NULL.
+ * \param output The destination buffer. This must be a writable buffer of
+ * sufficient size to hold the reduced binary presentation of
+ * the modulus, the generator and the public key, each wrapped
+ * with a 2-byte length field. It is the responsibility of the
+ * caller to ensure that enough space is available. Refer to
+ * mbedtls_mpi_size() to computing the byte-size of an MPI.
+ * \param f_rng The RNG function. Must not be \c NULL.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be
+ * \c NULL if \p f_rng doesn't need a context parameter.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
@@ -180,12 +192,14 @@
/**
* \brief This function sets the prime modulus and generator.
*
- * \note This function can be used to set \p P, \p G
+ * \note This function can be used to set \c ctx->P, \c ctx->G
* in preparation for mbedtls_dhm_make_params().
*
- * \param ctx The DHM context.
- * \param P The MPI holding the DHM prime modulus.
- * \param G The MPI holding the DHM generator.
+ * \param ctx The DHM context to configure. This must be initialized.
+ * \param P The MPI holding the DHM prime modulus. This must be
+ * an initialized MPI.
+ * \param G The MPI holding the DHM generator. This must be an
+ * initialized MPI.
*
* \return \c 0 if successful.
* \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
@@ -195,11 +209,17 @@
const mbedtls_mpi *G );
/**
- * \brief This function imports the public value of the peer, G^Y.
+ * \brief This function imports the raw public value of the peer.
*
- * \param ctx The DHM context.
- * \param input The input buffer containing the G^Y value of the peer.
- * \param ilen The size of the input buffer.
+ * \note In a TLS handshake, this is the how the server imports
+ * the Client's public DHM key.
+ *
+ * \param ctx The DHM context to use. This must be initialized and have
+ * its DHM parameters set, e.g. via mbedtls_dhm_set_group().
+ * It may or may not already have generated its own private key.
+ * \param input The input buffer containing the \c G^Y value of the peer.
+ * This must be a readable buffer of size \p ilen Bytes.
+ * \param ilen The size of the input buffer \p input in Bytes.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
@@ -208,21 +228,25 @@
const unsigned char *input, size_t ilen );
/**
- * \brief This function creates its own private key, \c X, and
- * exports \c G^X.
+ * \brief This function creates a DHM key pair and exports
+ * the raw public key in big-endian format.
*
* \note The destination buffer is always fully written
* so as to contain a big-endian representation of G^X mod P.
- * If it is larger than ctx->len, it is padded accordingly
+ * If it is larger than \c ctx->len, it is padded accordingly
* with zero-bytes at the beginning.
*
- * \param ctx The DHM context.
+ * \param ctx The DHM context to use. This must be initialized and
+ * have the DHM parameters set. It may or may not already
+ * have imported the peer's public key.
* \param x_size The private key size in Bytes.
- * \param output The destination buffer.
- * \param olen The length of the destination buffer. Must be at least
- * equal to ctx->len (the size of \c P).
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
+ * \param output The destination buffer. This must be a writable buffer of
+ * size \p olen Bytes.
+ * \param olen The length of the destination buffer. This must be at least
+ * equal to `ctx->len` (the size of \c P).
+ * \param f_rng The RNG function. This must not be \c NULL.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL
+ * if \p f_rng doesn't need a context argument.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
@@ -233,22 +257,27 @@
void *p_rng );
/**
- * \brief This function derives and exports the shared secret
- * \c (G^Y)^X mod \c P.
+ * \brief This function derives and exports the shared secret
+ * \c (G^Y)^X mod \c P.
*
- * \note If \p f_rng is not NULL, it is used to blind the input as
- * a countermeasure against timing attacks. Blinding is used
- * only if our private key \c X is re-used, and not used
- * otherwise. We recommend always passing a non-NULL
- * \p f_rng argument.
+ * \note If \p f_rng is not \c NULL, it is used to blind the input as
+ * a countermeasure against timing attacks. Blinding is used
+ * only if our private key \c X is re-used, and not used
+ * otherwise. We recommend always passing a non-NULL
+ * \p f_rng argument.
*
- * \param ctx The DHM context.
- * \param output The destination buffer.
- * \param output_size The size of the destination buffer. Must be at least
- * the size of ctx->len (the size of \c P).
+ * \param ctx The DHM context to use. This must be initialized
+ * and have its own private key generated and the peer's
+ * public key imported.
+ * \param output The buffer to write the generated shared key to. This
+ * must be a writable buffer of size \p output_size Bytes.
+ * \param output_size The size of the destination buffer. This must be at
+ * least the size of \c ctx->len (the size of \c P).
* \param olen On exit, holds the actual number of Bytes written.
- * \param f_rng The RNG function, for blinding purposes.
- * \param p_rng The RNG context.
+ * \param f_rng The RNG function, for blinding purposes. This may
+ * b \c NULL if blinding isn't needed.
+ * \param p_rng The RNG context. This may be \c NULL if \p f_rng
+ * doesn't need a context argument.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
@@ -259,9 +288,12 @@
void *p_rng );
/**
- * \brief This function frees and clears the components of a DHM context.
+ * \brief This function frees and clears the components
+ * of a DHM context.
*
- * \param ctx The DHM context to free and clear.
+ * \param ctx The DHM context to free and clear. This may be \c NULL,
+ * in which case this function is a no-op. If it is not \c NULL,
+ * it must point to an initialized DHM context.
*/
void mbedtls_dhm_free( mbedtls_dhm_context *ctx );
@@ -270,17 +302,19 @@
/**
* \brief This function parses DHM parameters in PEM or DER format.
*
- * \param dhm The DHM context to initialize.
- * \param dhmin The input buffer.
- * \param dhminlen The size of the buffer, including the terminating null
- * Byte for PEM data.
+ * \param dhm The DHM context to import the DHM parameters into.
+ * This must be initialized.
+ * \param dhmin The input buffer. This must be a readable buffer of
+ * length \p dhminlen Bytes.
+ * \param dhminlen The size of the input buffer \p dhmin, including the
+ * terminating \c NULL Byte for PEM data.
*
* \return \c 0 on success.
- * \return An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX error code
- * error code on failure.
+ * \return An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX error
+ * code on failure.
*/
int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin,
- size_t dhminlen );
+ size_t dhminlen );
#if defined(MBEDTLS_FS_IO)
/** \ingroup x509_module */
@@ -288,16 +322,20 @@
* \brief This function loads and parses DHM parameters from a file.
*
* \param dhm The DHM context to load the parameters to.
+ * This must be initialized.
* \param path The filename to read the DHM parameters from.
+ * This must not be \c NULL.
*
* \return \c 0 on success.
- * \return An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX error code
- * error code on failure.
+ * \return An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX
+ * error code on failure.
*/
int mbedtls_dhm_parse_dhmfile( mbedtls_dhm_context *dhm, const char *path );
#endif /* MBEDTLS_FS_IO */
#endif /* MBEDTLS_ASN1_PARSE_C */
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief The DMH checkup routine.
*
@@ -306,16 +344,16 @@
*/
int mbedtls_dhm_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus
}
#endif
/**
- * RFC 3526, RFC 5114 and RFC 7919 standardize a number of
- * Diffie-Hellman groups, some of which are included here
- * for use within the SSL/TLS module and the user's convenience
- * when configuring the Diffie-Hellman parameters by hand
- * through \c mbedtls_ssl_conf_dh_param.
+ * RFC 3526, RFC 5114 and RFC 7919 standardize a number of Diffie-Hellman
+ * groups, some of which are included here for use by Mbed TLS's SSL/TLS module
+ * and the user's convenience when configuring the Diffie-Hellman parameters by
+ * hand through Mbed TLS's \c mbedtls_ssl_conf_dh_param.
*
* The following lists the source of the above groups in the standards:
* - RFC 5114 section 2.2: 2048-bit MODP Group with 224-bit Prime Order Subgroup
@@ -353,15 +391,6 @@
#if !defined(MBEDTLS_DEPRECATED_REMOVED)
-#if defined(MBEDTLS_DEPRECATED_WARNING)
-#define MBEDTLS_DEPRECATED __attribute__((deprecated))
-MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_constant_t;
-#define MBEDTLS_DEPRECATED_STRING_CONSTANT( VAL ) \
- ( (mbedtls_deprecated_constant_t) ( VAL ) )
-#else
-#define MBEDTLS_DEPRECATED_STRING_CONSTANT( VAL ) VAL
-#endif /* ! MBEDTLS_DEPRECATED_WARNING */
-
/**
* \warning The origin of the primes in RFC 5114 is not documented and
* their use therefore constitutes a security risk!
diff --git a/include/mbedtls/ecdh.h b/include/mbedtls/ecdh.h
index 27f2ffc..384c3dc 100644
--- a/include/mbedtls/ecdh.h
+++ b/include/mbedtls/ecdh.h
@@ -34,6 +34,12 @@
#ifndef MBEDTLS_ECDH_H
#define MBEDTLS_ECDH_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "ecp.h"
#ifdef __cplusplus
@@ -49,6 +55,39 @@
MBEDTLS_ECDH_THEIRS, /**< The key of the peer. */
} mbedtls_ecdh_side;
+#if !defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
+/**
+ * Defines the ECDH implementation used.
+ *
+ * Later versions of the library may add new variants, therefore users should
+ * not make any assumptions about them.
+ */
+typedef enum
+{
+ MBEDTLS_ECDH_VARIANT_NONE = 0, /*!< Implementation not defined. */
+ MBEDTLS_ECDH_VARIANT_MBEDTLS_2_0,/*!< The default Mbed TLS implementation */
+} mbedtls_ecdh_variant;
+
+/**
+ * The context used by the default ECDH implementation.
+ *
+ * Later versions might change the structure of this context, therefore users
+ * should not make any assumptions about the structure of
+ * mbedtls_ecdh_context_mbed.
+ */
+typedef struct mbedtls_ecdh_context_mbed
+{
+ mbedtls_ecp_group grp; /*!< The elliptic curve used. */
+ mbedtls_mpi d; /*!< The private key. */
+ mbedtls_ecp_point Q; /*!< The public key. */
+ mbedtls_ecp_point Qp; /*!< The value of the public key of the peer. */
+ mbedtls_mpi z; /*!< The shared secret. */
+#if defined(MBEDTLS_ECP_RESTARTABLE)
+ mbedtls_ecp_restart_ctx rs; /*!< The restart context for EC computations. */
+#endif
+} mbedtls_ecdh_context_mbed;
+#endif
+
/**
*
* \warning Performing multiple operations concurrently on the same
@@ -58,6 +97,7 @@
*/
typedef struct mbedtls_ecdh_context
{
+#if defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
mbedtls_ecp_group grp; /*!< The elliptic curve used. */
mbedtls_mpi d; /*!< The private key. */
mbedtls_ecp_point Q; /*!< The public key. */
@@ -70,7 +110,26 @@
#if defined(MBEDTLS_ECP_RESTARTABLE)
int restart_enabled; /*!< The flag for restartable mode. */
mbedtls_ecp_restart_ctx rs; /*!< The restart context for EC computations. */
-#endif
+#endif /* MBEDTLS_ECP_RESTARTABLE */
+#else
+ uint8_t point_format; /*!< The format of point export in TLS messages
+ as defined in RFC 4492. */
+ mbedtls_ecp_group_id grp_id;/*!< The elliptic curve used. */
+ mbedtls_ecdh_variant var; /*!< The ECDH implementation/structure used. */
+ union
+ {
+ mbedtls_ecdh_context_mbed mbed_ecdh;
+ } ctx; /*!< Implementation-specific context. The
+ context in use is specified by the \c var
+ field. */
+#if defined(MBEDTLS_ECP_RESTARTABLE)
+ uint8_t restart_enabled; /*!< The flag for restartable mode. Functions of
+ an alternative implementation not supporting
+ restartable mode must return
+ MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED error
+ if this flag is set. */
+#endif /* MBEDTLS_ECP_RESTARTABLE */
+#endif /* MBEDTLS_ECDH_LEGACY_CONTEXT */
}
mbedtls_ecdh_context;
@@ -84,11 +143,16 @@
*
* \see ecp.h
*
- * \param grp The ECP group.
+ * \param grp The ECP group to use. This must be initialized and have
+ * domain parameters loaded, for example through
+ * mbedtls_ecp_load() or mbedtls_ecp_tls_read_group().
* \param d The destination MPI (private key).
+ * This must be initialized.
* \param Q The destination point (public key).
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
+ * This must be initialized.
+ * \param f_rng The RNG function to use. This must not be \c NULL.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be
+ * \c NULL in case \p f_rng doesn't need a context argument.
*
* \return \c 0 on success.
* \return Another \c MBEDTLS_ERR_ECP_XXX or
@@ -111,12 +175,22 @@
* countermeasures against side-channel attacks.
* For more information, see mbedtls_ecp_mul().
*
- * \param grp The ECP group.
+ * \param grp The ECP group to use. This must be initialized and have
+ * domain parameters loaded, for example through
+ * mbedtls_ecp_load() or mbedtls_ecp_tls_read_group().
* \param z The destination MPI (shared secret).
+ * This must be initialized.
* \param Q The public key from another party.
+ * This must be initialized.
* \param d Our secret exponent (private key).
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
+ * This must be initialized.
+ * \param f_rng The RNG function. This may be \c NULL if randomization
+ * of intermediate results during the ECP computations is
+ * not needed (discouraged). See the documentation of
+ * mbedtls_ecp_mul() for more.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be
+ * \c NULL if \p f_rng is \c NULL or doesn't need a
+ * context argument.
*
* \return \c 0 on success.
* \return Another \c MBEDTLS_ERR_ECP_XXX or
@@ -130,36 +204,57 @@
/**
* \brief This function initializes an ECDH context.
*
- * \param ctx The ECDH context to initialize.
+ * \param ctx The ECDH context to initialize. This must not be \c NULL.
*/
void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
/**
- * \brief This function frees a context.
+ * \brief This function sets up the ECDH context with the information
+ * given.
*
- * \param ctx The context to free.
- */
-void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
-
-/**
- * \brief This function generates a public key and a TLS
- * ServerKeyExchange payload.
+ * This function should be called after mbedtls_ecdh_init() but
+ * before mbedtls_ecdh_make_params(). There is no need to call
+ * this function before mbedtls_ecdh_read_params().
*
* This is the first function used by a TLS server for ECDHE
* ciphersuites.
*
- * \note This function assumes that the ECP group (grp) of the
- * \p ctx context has already been properly set,
- * for example, using mbedtls_ecp_group_load().
+ * \param ctx The ECDH context to set up. This must be initialized.
+ * \param grp_id The group id of the group to set up the context for.
+ *
+ * \return \c 0 on success.
+ */
+int mbedtls_ecdh_setup( mbedtls_ecdh_context *ctx,
+ mbedtls_ecp_group_id grp_id );
+
+/**
+ * \brief This function frees a context.
+ *
+ * \param ctx The context to free. This may be \c NULL, in which
+ * case this function does nothing. If it is not \c NULL,
+ * it must point to an initialized ECDH context.
+ */
+void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
+
+/**
+ * \brief This function generates an EC key pair and exports its
+ * in the format used in a TLS ServerKeyExchange handshake
+ * message.
+ *
+ * This is the second function used by a TLS server for ECDHE
+ * ciphersuites. (It is called after mbedtls_ecdh_setup().)
*
* \see ecp.h
*
- * \param ctx The ECDH context.
- * \param olen The number of characters written.
- * \param buf The destination buffer.
- * \param blen The length of the destination buffer.
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
+ * \param ctx The ECDH context to use. This must be initialized
+ * and bound to a group, for example via mbedtls_ecdh_setup().
+ * \param olen The address at which to store the number of Bytes written.
+ * \param buf The destination buffer. This must be a writable buffer of
+ * length \p blen Bytes.
+ * \param blen The length of the destination buffer \p buf in Bytes.
+ * \param f_rng The RNG function to use. This must not be \c NULL.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be
+ * \c NULL in case \p f_rng doesn't need a context argument.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
@@ -172,24 +267,32 @@
void *p_rng );
/**
- * \brief This function parses and processes a TLS ServerKeyExhange
- * payload.
+ * \brief This function parses the ECDHE parameters in a
+ * TLS ServerKeyExchange handshake message.
*
- * This is the first function used by a TLS client for ECDHE
- * ciphersuites.
+ * \note In a TLS handshake, this is the how the client
+ * sets up its ECDHE context from the server's public
+ * ECDHE key material.
*
* \see ecp.h
*
- * \param ctx The ECDH context.
- * \param buf The pointer to the start of the input buffer.
- * \param end The address for one Byte past the end of the buffer.
+ * \param ctx The ECDHE context to use. This must be initialized.
+ * \param buf On input, \c *buf must be the start of the input buffer.
+ * On output, \c *buf is updated to point to the end of the
+ * data that has been read. On success, this is the first byte
+ * past the end of the ServerKeyExchange parameters.
+ * On error, this is the point at which an error has been
+ * detected, which is usually not useful except to debug
+ * failures.
+ * \param end The end of the input buffer.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
*
*/
int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
- const unsigned char **buf, const unsigned char *end );
+ const unsigned char **buf,
+ const unsigned char *end );
/**
* \brief This function sets up an ECDH context from an EC key.
@@ -200,33 +303,40 @@
*
* \see ecp.h
*
- * \param ctx The ECDH context to set up.
- * \param key The EC key to use.
- * \param side Defines the source of the key: 1: Our key, or
- * 0: The key of the peer.
+ * \param ctx The ECDH context to set up. This must be initialized.
+ * \param key The EC key to use. This must be initialized.
+ * \param side Defines the source of the key. Possible values are:
+ * - #MBEDTLS_ECDH_OURS: The key is ours.
+ * - #MBEDTLS_ECDH_THEIRS: The key is that of the peer.
*
* \return \c 0 on success.
* \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
*
*/
-int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
- mbedtls_ecdh_side side );
+int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx,
+ const mbedtls_ecp_keypair *key,
+ mbedtls_ecdh_side side );
/**
- * \brief This function generates a public key and a TLS
- * ClientKeyExchange payload.
+ * \brief This function generates a public key and exports it
+ * as a TLS ClientKeyExchange payload.
*
* This is the second function used by a TLS client for ECDH(E)
* ciphersuites.
*
* \see ecp.h
*
- * \param ctx The ECDH context.
- * \param olen The number of Bytes written.
- * \param buf The destination buffer.
- * \param blen The size of the destination buffer.
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
+ * \param ctx The ECDH context to use. This must be initialized
+ * and bound to a group, the latter usually by
+ * mbedtls_ecdh_read_params().
+ * \param olen The address at which to store the number of Bytes written.
+ * This must not be \c NULL.
+ * \param buf The destination buffer. This must be a writable buffer
+ * of length \p blen Bytes.
+ * \param blen The size of the destination buffer \p buf in Bytes.
+ * \param f_rng The RNG function to use. This must not be \c NULL.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be
+ * \c NULL in case \p f_rng doesn't need a context argument.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
@@ -239,23 +349,26 @@
void *p_rng );
/**
- * \brief This function parses and processes a TLS ClientKeyExchange
- * payload.
+ * \brief This function parses and processes the ECDHE payload of a
+ * TLS ClientKeyExchange message.
*
- * This is the second function used by a TLS server for ECDH(E)
- * ciphersuites.
+ * This is the third function used by a TLS server for ECDH(E)
+ * ciphersuites. (It is called after mbedtls_ecdh_setup() and
+ * mbedtls_ecdh_make_params().)
*
* \see ecp.h
*
- * \param ctx The ECDH context.
- * \param buf The start of the input buffer.
- * \param blen The length of the input buffer.
+ * \param ctx The ECDH context to use. This must be initialized
+ * and bound to a group, for example via mbedtls_ecdh_setup().
+ * \param buf The pointer to the ClientKeyExchange payload. This must
+ * be a readable buffer of length \p blen Bytes.
+ * \param blen The length of the input buffer \p buf in Bytes.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
*/
int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
- const unsigned char *buf, size_t blen );
+ const unsigned char *buf, size_t blen );
/**
* \brief This function derives and exports the shared secret.
@@ -268,13 +381,19 @@
* For more information, see mbedtls_ecp_mul().
*
* \see ecp.h
- *
- * \param ctx The ECDH context.
- * \param olen The number of Bytes written.
- * \param buf The destination buffer.
- * \param blen The length of the destination buffer.
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
+
+ * \param ctx The ECDH context to use. This must be initialized
+ * and have its own private key generated and the peer's
+ * public key imported.
+ * \param olen The address at which to store the total number of
+ * Bytes written on success. This must not be \c NULL.
+ * \param buf The buffer to write the generated shared key to. This
+ * must be a writable buffer of size \p blen Bytes.
+ * \param blen The length of the destination buffer \p buf in Bytes.
+ * \param f_rng The RNG function, for blinding purposes. This may
+ * b \c NULL if blinding isn't needed.
+ * \param p_rng The RNG context. This may be \c NULL if \p f_rng
+ * doesn't need a context argument.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
@@ -297,7 +416,7 @@
* computations once enabled, except by free-ing the context,
* which cancels possible in-progress operations.
*
- * \param ctx The ECDH context.
+ * \param ctx The ECDH context to use. This must be initialized.
*/
void mbedtls_ecdh_enable_restart( mbedtls_ecdh_context *ctx );
#endif /* MBEDTLS_ECP_RESTARTABLE */
diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h
index 5245c6e..2943945 100644
--- a/include/mbedtls/ecdsa.h
+++ b/include/mbedtls/ecdsa.h
@@ -32,6 +32,12 @@
#ifndef MBEDTLS_ECDSA_H
#define MBEDTLS_ECDSA_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "ecp.h"
#include "md.h"
@@ -123,7 +129,8 @@
* \brief This function computes the ECDSA signature of a
* previously-hashed message.
*
- * \note The deterministic version is usually preferred.
+ * \note The deterministic version implemented in
+ * mbedtls_ecdsa_sign_det() is usually preferred.
*
* \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated
@@ -133,14 +140,22 @@
*
* \see ecp.h
*
- * \param grp The ECP group.
- * \param r The first output integer.
- * \param s The second output integer.
- * \param d The private signing key.
- * \param buf The message hash.
- * \param blen The length of \p buf.
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
+ * \param grp The context for the elliptic curve to use.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
+ * \param r The MPI context in which to store the first part
+ * the signature. This must be initialized.
+ * \param s The MPI context in which to store the second part
+ * the signature. This must be initialized.
+ * \param d The private signing key. This must be initialized.
+ * \param buf The content to be signed. This is usually the hash of
+ * the original data to be signed. This must be a readable
+ * buffer of length \p blen Bytes. It may be \c NULL if
+ * \p blen is zero.
+ * \param blen The length of \p buf in Bytes.
+ * \param f_rng The RNG function. This must not be \c NULL.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be
+ * \c NULL if \p f_rng doesn't need a context parameter.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX
@@ -167,21 +182,29 @@
*
* \see ecp.h
*
- * \param grp The ECP group.
- * \param r The first output integer.
- * \param s The second output integer.
- * \param d The private signing key.
- * \param buf The message hash.
- * \param blen The length of \p buf.
- * \param md_alg The MD algorithm used to hash the message.
+ * \param grp The context for the elliptic curve to use.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
+ * \param r The MPI context in which to store the first part
+ * the signature. This must be initialized.
+ * \param s The MPI context in which to store the second part
+ * the signature. This must be initialized.
+ * \param d The private signing key. This must be initialized
+ * and setup, for example through mbedtls_ecp_gen_privkey().
+ * \param buf The hashed content to be signed. This must be a readable
+ * buffer of length \p blen Bytes. It may be \c NULL if
+ * \p blen is zero.
+ * \param blen The length of \p buf in Bytes.
+ * \param md_alg The hash algorithm used to hash the original data.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
* error code on failure.
*/
-int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
- const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
- mbedtls_md_type_t md_alg );
+int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r,
+ mbedtls_mpi *s, const mbedtls_mpi *d,
+ const unsigned char *buf, size_t blen,
+ mbedtls_md_type_t md_alg );
#endif /* MBEDTLS_ECDSA_DETERMINISTIC */
/**
@@ -196,12 +219,19 @@
*
* \see ecp.h
*
- * \param grp The ECP group.
- * \param buf The message hash.
- * \param blen The length of \p buf.
- * \param Q The public key to use for verification.
+ * \param grp The ECP group to use.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
+ * \param buf The hashed content that was signed. This must be a readable
+ * buffer of length \p blen Bytes. It may be \c NULL if
+ * \p blen is zero.
+ * \param blen The length of \p buf in Bytes.
+ * \param Q The public key to use for verification. This must be
+ * initialized and setup.
* \param r The first integer of the signature.
+ * This must be initialized.
* \param s The second integer of the signature.
+ * This must be initialized.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature
@@ -210,8 +240,9 @@
* error code on failure for any other reason.
*/
int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
- const unsigned char *buf, size_t blen,
- const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s);
+ const unsigned char *buf, size_t blen,
+ const mbedtls_ecp_point *Q, const mbedtls_mpi *r,
+ const mbedtls_mpi *s);
/**
* \brief This function computes the ECDSA signature and writes it
@@ -228,11 +259,6 @@
* of the Digital Signature Algorithm (DSA) and Elliptic
* Curve Digital Signature Algorithm (ECDSA)</em>.
*
- * \note The \p sig buffer must be at least twice as large as the
- * size of the curve used, plus 9. For example, 73 Bytes if
- * a 256-bit curve is used. A buffer length of
- * #MBEDTLS_ECDSA_MAX_LEN is always safe.
- *
* \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as
* defined in <em>Standards for Efficient Cryptography Group
@@ -241,20 +267,32 @@
*
* \see ecp.h
*
- * \param ctx The ECDSA context.
+ * \param ctx The ECDSA context to use. This must be initialized
+ * and have a group and private key bound to it, for example
+ * via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
* \param md_alg The message digest that was used to hash the message.
- * \param hash The message hash.
- * \param hlen The length of the hash.
- * \param sig The buffer that holds the signature.
- * \param slen The length of the signature written.
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
+ * \param hash The message hash to be signed. This must be a readable
+ * buffer of length \p blen Bytes.
+ * \param hlen The length of the hash \p hash in Bytes.
+ * \param sig The buffer to which to write the signature. This must be a
+ * writable buffer of length at least twice as large as the
+ * size of the curve used, plus 9. For example, 73 Bytes if
+ * a 256-bit curve is used. A buffer length of
+ * #MBEDTLS_ECDSA_MAX_LEN is always safe.
+ * \param slen The address at which to store the actual length of
+ * the signature written. Must not be \c NULL.
+ * \param f_rng The RNG function. This must not be \c NULL if
+ * #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise,
+ * it is unused and may be set to \c NULL.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be
+ * \c NULL if \p f_rng is \c NULL or doesn't use a context.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
* \c MBEDTLS_ERR_ASN1_XXX error code on failure.
*/
-int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
+int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx,
+ mbedtls_md_type_t md_alg,
const unsigned char *hash, size_t hlen,
unsigned char *sig, size_t *slen,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -270,15 +308,28 @@
* but it can return early and restart according to the limit
* set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
*
- * \param ctx The ECDSA context.
+ * \param ctx The ECDSA context to use. This must be initialized
+ * and have a group and private key bound to it, for example
+ * via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
* \param md_alg The message digest that was used to hash the message.
- * \param hash The message hash.
- * \param hlen The length of the hash.
- * \param sig The buffer that holds the signature.
- * \param slen The length of the signature written.
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
- * \param rs_ctx The restart context (NULL disables restart).
+ * \param hash The message hash to be signed. This must be a readable
+ * buffer of length \p blen Bytes.
+ * \param hlen The length of the hash \p hash in Bytes.
+ * \param sig The buffer to which to write the signature. This must be a
+ * writable buffer of length at least twice as large as the
+ * size of the curve used, plus 9. For example, 73 Bytes if
+ * a 256-bit curve is used. A buffer length of
+ * #MBEDTLS_ECDSA_MAX_LEN is always safe.
+ * \param slen The address at which to store the actual length of
+ * the signature written. Must not be \c NULL.
+ * \param f_rng The RNG function. This must not be \c NULL if
+ * #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise,
+ * it is unused and may be set to \c NULL.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be
+ * \c NULL if \p f_rng is \c NULL or doesn't use a context.
+ * \param rs_ctx The restart context to use. This may be \c NULL to disable
+ * restarting. If it is not \c NULL, it must point to an
+ * initialized restart context.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
@@ -314,11 +365,6 @@
* \warning It is not thread-safe to use the same context in
* multiple threads.
*
- * \note The \p sig buffer must be at least twice as large as the
- * size of the curve used, plus 9. For example, 73 Bytes if a
- * 256-bit curve is used. A buffer length of
- * #MBEDTLS_ECDSA_MAX_LEN is always safe.
- *
* \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as
* defined in <em>Standards for Efficient Cryptography Group
@@ -330,12 +376,20 @@
* \deprecated Superseded by mbedtls_ecdsa_write_signature() in
* Mbed TLS version 2.0 and later.
*
- * \param ctx The ECDSA context.
- * \param hash The message hash.
- * \param hlen The length of the hash.
- * \param sig The buffer that holds the signature.
- * \param slen The length of the signature written.
- * \param md_alg The MD algorithm used to hash the message.
+ * \param ctx The ECDSA context to use. This must be initialized
+ * and have a group and private key bound to it, for example
+ * via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
+ * \param hash The message hash to be signed. This must be a readable
+ * buffer of length \p blen Bytes.
+ * \param hlen The length of the hash \p hash in Bytes.
+ * \param sig The buffer to which to write the signature. This must be a
+ * writable buffer of length at least twice as large as the
+ * size of the curve used, plus 9. For example, 73 Bytes if
+ * a 256-bit curve is used. A buffer length of
+ * #MBEDTLS_ECDSA_MAX_LEN is always safe.
+ * \param slen The address at which to store the actual length of
+ * the signature written. Must not be \c NULL.
+ * \param md_alg The message digest that was used to hash the message.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
@@ -360,11 +414,14 @@
*
* \see ecp.h
*
- * \param ctx The ECDSA context.
- * \param hash The message hash.
- * \param hlen The size of the hash.
- * \param sig The signature to read and verify.
- * \param slen The size of \p sig.
+ * \param ctx The ECDSA context to use. This must be initialized
+ * and have a group and public key bound to it.
+ * \param hash The message hash that was signed. This must be a readable
+ * buffer of length \p size Bytes.
+ * \param hlen The size of the hash \p hash.
+ * \param sig The signature to read and verify. This must be a readable
+ * buffer of length \p slen Bytes.
+ * \param slen The size of \p sig in Bytes.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
@@ -387,12 +444,17 @@
* but it can return early and restart according to the limit
* set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
*
- * \param ctx The ECDSA context.
- * \param hash The message hash.
- * \param hlen The size of the hash.
- * \param sig The signature to read and verify.
- * \param slen The size of \p sig.
- * \param rs_ctx The restart context (NULL disables restart).
+ * \param ctx The ECDSA context to use. This must be initialized
+ * and have a group and public key bound to it.
+ * \param hash The message hash that was signed. This must be a readable
+ * buffer of length \p size Bytes.
+ * \param hlen The size of the hash \p hash.
+ * \param sig The signature to read and verify. This must be a readable
+ * buffer of length \p slen Bytes.
+ * \param slen The size of \p sig in Bytes.
+ * \param rs_ctx The restart context to use. This may be \c NULL to disable
+ * restarting. If it is not \c NULL, it must point to an
+ * initialized restart context.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
@@ -414,10 +476,12 @@
* \see ecp.h
*
* \param ctx The ECDSA context to store the keypair in.
+ * This must be initialized.
* \param gid The elliptic curve to use. One of the various
* \c MBEDTLS_ECP_DP_XXX macros depending on configuration.
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
+ * \param f_rng The RNG function to use. This must not be \c NULL.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be
+ * \c NULL if \p f_rng doesn't need a context argument.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX code on failure.
@@ -426,40 +490,55 @@
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
/**
- * \brief This function sets an ECDSA context from an EC key pair.
+ * \brief This function sets up an ECDSA context from an EC key pair.
*
* \see ecp.h
*
- * \param ctx The ECDSA context to set.
- * \param key The EC key to use.
+ * \param ctx The ECDSA context to setup. This must be initialized.
+ * \param key The EC key to use. This must be initialized and hold
+ * a private-public key pair or a public key. In the former
+ * case, the ECDSA context may be used for signature creation
+ * and verification after this call. In the latter case, it
+ * may be used for signature verification.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX code on failure.
*/
-int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key );
+int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx,
+ const mbedtls_ecp_keypair *key );
/**
* \brief This function initializes an ECDSA context.
*
* \param ctx The ECDSA context to initialize.
+ * This must not be \c NULL.
*/
void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx );
/**
* \brief This function frees an ECDSA context.
*
- * \param ctx The ECDSA context to free.
+ * \param ctx The ECDSA context to free. This may be \c NULL,
+ * in which case this function does nothing. If it
+ * is not \c NULL, it must be initialized.
*/
void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );
#if defined(MBEDTLS_ECP_RESTARTABLE)
/**
- * \brief Initialize a restart context
+ * \brief Initialize a restart context.
+ *
+ * \param ctx The restart context to initialize.
+ * This must not be \c NULL.
*/
void mbedtls_ecdsa_restart_init( mbedtls_ecdsa_restart_ctx *ctx );
/**
- * \brief Free the components of a restart context
+ * \brief Free the components of a restart context.
+ *
+ * \param ctx The restart context to free. This may be \c NULL,
+ * in which case this function does nothing. If it
+ * is not \c NULL, it must be initialized.
*/
void mbedtls_ecdsa_restart_free( mbedtls_ecdsa_restart_ctx *ctx );
#endif /* MBEDTLS_ECP_RESTARTABLE */
diff --git a/include/mbedtls/ecjpake.h b/include/mbedtls/ecjpake.h
index 59d12f0..3d8d02a 100644
--- a/include/mbedtls/ecjpake.h
+++ b/include/mbedtls/ecjpake.h
@@ -40,6 +40,11 @@
* The payloads are serialized in a way suitable for use in TLS, but could
* also be use outside TLS.
*/
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
#include "ecp.h"
#include "md.h"
@@ -92,28 +97,33 @@
#endif /* MBEDTLS_ECJPAKE_ALT */
/**
- * \brief Initialize a context
- * (just makes it ready for setup() or free()).
+ * \brief Initialize an ECJPAKE context.
*
- * \param ctx context to initialize
+ * \param ctx The ECJPAKE context to initialize.
+ * This must not be \c NULL.
*/
void mbedtls_ecjpake_init( mbedtls_ecjpake_context *ctx );
/**
- * \brief Set up a context for use
+ * \brief Set up an ECJPAKE context for use.
*
* \note Currently the only values for hash/curve allowed by the
- * standard are MBEDTLS_MD_SHA256/MBEDTLS_ECP_DP_SECP256R1.
+ * standard are #MBEDTLS_MD_SHA256/#MBEDTLS_ECP_DP_SECP256R1.
*
- * \param ctx context to set up
- * \param role Our role: client or server
- * \param hash hash function to use (MBEDTLS_MD_XXX)
- * \param curve elliptic curve identifier (MBEDTLS_ECP_DP_XXX)
- * \param secret pre-shared secret (passphrase)
- * \param len length of the shared secret
+ * \param ctx The ECJPAKE context to set up. This must be initialized.
+ * \param role The role of the caller. This must be either
+ * #MBEDTLS_ECJPAKE_CLIENT or #MBEDTLS_ECJPAKE_SERVER.
+ * \param hash The identifier of the hash function to use,
+ * for example #MBEDTLS_MD_SHA256.
+ * \param curve The identifier of the elliptic curve to use,
+ * for example #MBEDTLS_ECP_DP_SECP256R1.
+ * \param secret The pre-shared secret (passphrase). This must be
+ * a readable buffer of length \p len Bytes. It need
+ * only be valid for the duration of this call.
+ * \param len The length of the pre-shared secret \p secret.
*
- * \return 0 if successfull,
- * a negative error code otherwise
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx,
mbedtls_ecjpake_role role,
@@ -123,29 +133,34 @@
size_t len );
/**
- * \brief Check if a context is ready for use
+ * \brief Check if an ECJPAKE context is ready for use.
*
- * \param ctx Context to check
+ * \param ctx The ECJPAKE context to check. This must be
+ * initialized.
*
- * \return 0 if the context is ready for use,
- * MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise
+ * \return \c 0 if the context is ready for use.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise.
*/
int mbedtls_ecjpake_check( const mbedtls_ecjpake_context *ctx );
/**
* \brief Generate and write the first round message
* (TLS: contents of the Client/ServerHello extension,
- * excluding extension type and length bytes)
+ * excluding extension type and length bytes).
*
- * \param ctx Context to use
- * \param buf Buffer to write the contents to
- * \param len Buffer size
- * \param olen Will be updated with the number of bytes written
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \param ctx The ECJPAKE context to use. This must be
+ * initialized and set up.
+ * \param buf The buffer to write the contents to. This must be a
+ * writable buffer of length \p len Bytes.
+ * \param len The length of \p buf in Bytes.
+ * \param olen The address at which to store the total number
+ * of Bytes written to \p buf. This must not be \c NULL.
+ * \param f_rng The RNG function to use. This must not be \c NULL.
+ * \param p_rng The RNG parameter to be passed to \p f_rng. This
+ * may be \c NULL if \p f_rng doesn't use a context.
*
- * \return 0 if successfull,
- * a negative error code otherwise
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx,
unsigned char *buf, size_t len, size_t *olen,
@@ -155,14 +170,16 @@
/**
* \brief Read and process the first round message
* (TLS: contents of the Client/ServerHello extension,
- * excluding extension type and length bytes)
+ * excluding extension type and length bytes).
*
- * \param ctx Context to use
- * \param buf Pointer to extension contents
- * \param len Extension length
+ * \param ctx The ECJPAKE context to use. This must be initialized
+ * and set up.
+ * \param buf The buffer holding the first round message. This must
+ * be a readable buffer of length \p len Bytes.
+ * \param len The length in Bytes of \p buf.
*
- * \return 0 if successfull,
- * a negative error code otherwise
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx,
const unsigned char *buf,
@@ -170,17 +187,21 @@
/**
* \brief Generate and write the second round message
- * (TLS: contents of the Client/ServerKeyExchange)
+ * (TLS: contents of the Client/ServerKeyExchange).
*
- * \param ctx Context to use
- * \param buf Buffer to write the contents to
- * \param len Buffer size
- * \param olen Will be updated with the number of bytes written
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \param ctx The ECJPAKE context to use. This must be initialized,
+ * set up, and already have performed round one.
+ * \param buf The buffer to write the round two contents to.
+ * This must be a writable buffer of length \p len Bytes.
+ * \param len The size of \p buf in Bytes.
+ * \param olen The address at which to store the total number of Bytes
+ * written to \p buf. This must not be \c NULL.
+ * \param f_rng The RNG function to use. This must not be \c NULL.
+ * \param p_rng The RNG parameter to be passed to \p f_rng. This
+ * may be \c NULL if \p f_rng doesn't use a context.
*
- * \return 0 if successfull,
- * a negative error code otherwise
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx,
unsigned char *buf, size_t len, size_t *olen,
@@ -189,14 +210,16 @@
/**
* \brief Read and process the second round message
- * (TLS: contents of the Client/ServerKeyExchange)
+ * (TLS: contents of the Client/ServerKeyExchange).
*
- * \param ctx Context to use
- * \param buf Pointer to the message
- * \param len Message length
+ * \param ctx The ECJPAKE context to use. This must be initialized
+ * and set up and already have performed round one.
+ * \param buf The buffer holding the second round message. This must
+ * be a readable buffer of length \p len Bytes.
+ * \param len The length in Bytes of \p buf.
*
- * \return 0 if successfull,
- * a negative error code otherwise
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
const unsigned char *buf,
@@ -204,17 +227,21 @@
/**
* \brief Derive the shared secret
- * (TLS: Pre-Master Secret)
+ * (TLS: Pre-Master Secret).
*
- * \param ctx Context to use
- * \param buf Buffer to write the contents to
- * \param len Buffer size
- * \param olen Will be updated with the number of bytes written
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \param ctx The ECJPAKE context to use. This must be initialized,
+ * set up and have performed both round one and two.
+ * \param buf The buffer to write the derived secret to. This must
+ * be a writable buffer of length \p len Bytes.
+ * \param len The length of \p buf in Bytes.
+ * \param olen The address at which to store the total number of Bytes
+ * written to \p buf. This must not be \c NULL.
+ * \param f_rng The RNG function to use. This must not be \c NULL.
+ * \param p_rng The RNG parameter to be passed to \p f_rng. This
+ * may be \c NULL if \p f_rng doesn't use a context.
*
- * \return 0 if successfull,
- * a negative error code otherwise
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
unsigned char *buf, size_t len, size_t *olen,
@@ -222,14 +249,15 @@
void *p_rng );
/**
- * \brief Free a context's content
+ * \brief This clears an ECJPAKE context and frees any
+ * embedded data structure.
*
- * \param ctx context to free
+ * \param ctx The ECJPAKE context to free. This may be \c NULL,
+ * in which case this function does nothing. If it is not
+ * \c NULL, it must point to an initialized ECJPAKE context.
*/
void mbedtls_ecjpake_free( mbedtls_ecjpake_context *ctx );
-
-
#if defined(MBEDTLS_SELF_TEST)
/**
diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h
index 2fb1af4..1a6ec13 100644
--- a/include/mbedtls/ecp.h
+++ b/include/mbedtls/ecp.h
@@ -36,6 +36,12 @@
#ifndef MBEDTLS_ECP_H
#define MBEDTLS_ECP_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "bignum.h"
/*
@@ -93,6 +99,16 @@
*/
#define MBEDTLS_ECP_DP_MAX 12
+/*
+ * Curve types
+ */
+typedef enum
+{
+ MBEDTLS_ECP_TYPE_NONE = 0,
+ MBEDTLS_ECP_TYPE_SHORT_WEIERSTRASS, /* y^2 = x^3 + a x + b */
+ MBEDTLS_ECP_TYPE_MONTGOMERY, /* y^2 = x^3 + a x^2 + x */
+} mbedtls_ecp_curve_type;
+
/**
* Curve information, for use by other modules.
*/
@@ -159,6 +175,10 @@
* additions or subtractions. Therefore, it is only an approximative modular
* reduction. It must return 0 on success and non-zero on failure.
*
+ * \note Alternative implementations must keep the group IDs distinct. If
+ * two group structures have the same ID, then they must be
+ * identical.
+ *
*/
typedef struct mbedtls_ecp_group
{
@@ -185,6 +205,68 @@
}
mbedtls_ecp_group;
+/**
+ * \name SECTION: Module settings
+ *
+ * The configuration options you can set for this module are in this section.
+ * Either change them in config.h, or define them using the compiler command line.
+ * \{
+ */
+
+#if !defined(MBEDTLS_ECP_MAX_BITS)
+/**
+ * The maximum size of the groups, that is, of \c N and \c P.
+ */
+#define MBEDTLS_ECP_MAX_BITS 521 /**< The maximum size of groups, in bits. */
+#endif
+
+#define MBEDTLS_ECP_MAX_BYTES ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 )
+#define MBEDTLS_ECP_MAX_PT_LEN ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 )
+
+#if !defined(MBEDTLS_ECP_WINDOW_SIZE)
+/*
+ * Maximum "window" size used for point multiplication.
+ * Default: 6.
+ * Minimum value: 2. Maximum value: 7.
+ *
+ * Result is an array of at most ( 1 << ( MBEDTLS_ECP_WINDOW_SIZE - 1 ) )
+ * points used for point multiplication. This value is directly tied to EC
+ * peak memory usage, so decreasing it by one should roughly cut memory usage
+ * by two (if large curves are in use).
+ *
+ * Reduction in size may reduce speed, but larger curves are impacted first.
+ * Sample performances (in ECDHE handshakes/s, with FIXED_POINT_OPTIM = 1):
+ * w-size: 6 5 4 3 2
+ * 521 145 141 135 120 97
+ * 384 214 209 198 177 146
+ * 256 320 320 303 262 226
+ * 224 475 475 453 398 342
+ * 192 640 640 633 587 476
+ */
+#define MBEDTLS_ECP_WINDOW_SIZE 6 /**< The maximum window size used. */
+#endif /* MBEDTLS_ECP_WINDOW_SIZE */
+
+#if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM)
+/*
+ * Trade memory for speed on fixed-point multiplication.
+ *
+ * This speeds up repeated multiplication of the generator (that is, the
+ * multiplication in ECDSA signatures, and half of the multiplications in
+ * ECDSA verification and ECDHE) by a factor roughly 3 to 4.
+ *
+ * The cost is increasing EC peak memory usage by a factor roughly 2.
+ *
+ * Change this value to 0 to reduce peak memory usage.
+ */
+#define MBEDTLS_ECP_FIXED_POINT_OPTIM 1 /**< Enable fixed-point speed-up. */
+#endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */
+
+/* \} name SECTION: Module settings */
+
+#else /* MBEDTLS_ECP_ALT */
+#include "ecp_alt.h"
+#endif /* MBEDTLS_ECP_ALT */
+
#if defined(MBEDTLS_ECP_RESTARTABLE)
/**
@@ -250,68 +332,6 @@
#endif /* MBEDTLS_ECP_RESTARTABLE */
/**
- * \name SECTION: Module settings
- *
- * The configuration options you can set for this module are in this section.
- * Either change them in config.h, or define them using the compiler command line.
- * \{
- */
-
-#if !defined(MBEDTLS_ECP_MAX_BITS)
-/**
- * The maximum size of the groups, that is, of \c N and \c P.
- */
-#define MBEDTLS_ECP_MAX_BITS 521 /**< The maximum size of groups, in bits. */
-#endif
-
-#define MBEDTLS_ECP_MAX_BYTES ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 )
-#define MBEDTLS_ECP_MAX_PT_LEN ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 )
-
-#if !defined(MBEDTLS_ECP_WINDOW_SIZE)
-/*
- * Maximum "window" size used for point multiplication.
- * Default: 6.
- * Minimum value: 2. Maximum value: 7.
- *
- * Result is an array of at most ( 1 << ( MBEDTLS_ECP_WINDOW_SIZE - 1 ) )
- * points used for point multiplication. This value is directly tied to EC
- * peak memory usage, so decreasing it by one should roughly cut memory usage
- * by two (if large curves are in use).
- *
- * Reduction in size may reduce speed, but larger curves are impacted first.
- * Sample performances (in ECDHE handshakes/s, with FIXED_POINT_OPTIM = 1):
- * w-size: 6 5 4 3 2
- * 521 145 141 135 120 97
- * 384 214 209 198 177 146
- * 256 320 320 303 262 226
- * 224 475 475 453 398 342
- * 192 640 640 633 587 476
- */
-#define MBEDTLS_ECP_WINDOW_SIZE 6 /**< The maximum window size used. */
-#endif /* MBEDTLS_ECP_WINDOW_SIZE */
-
-#if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM)
-/*
- * Trade memory for speed on fixed-point multiplication.
- *
- * This speeds up repeated multiplication of the generator (that is, the
- * multiplication in ECDSA signatures, and half of the multiplications in
- * ECDSA verification and ECDHE) by a factor roughly 3 to 4.
- *
- * The cost is increasing EC peak memory usage by a factor roughly 2.
- *
- * Change this value to 0 to reduce peak memory usage.
- */
-#define MBEDTLS_ECP_FIXED_POINT_OPTIM 1 /**< Enable fixed-point speed-up. */
-#endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */
-
-/* \} name SECTION: Module settings */
-
-#else /* MBEDTLS_ECP_ALT */
-#include "ecp_alt.h"
-#endif /* MBEDTLS_ECP_ALT */
-
-/**
* \brief The ECP key-pair structure.
*
* A generic key-pair that may be used for ECDSA and fixed ECDH, for example.
@@ -355,19 +375,19 @@
* same; they must not be used until the function finally
* returns 0.
*
- * This only applies to functions whose documentation
- * mentions they may return #MBEDTLS_ERR_ECP_IN_PROGRESS (or
- * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS for functions in the
- * SSL module). For functions that accept a "restart context"
- * argument, passing NULL disables restart and makes the
- * function equivalent to the function with the same name
+ * This only applies to functions whose documentation mentions
+ * they may return #MBEDTLS_ERR_ECP_IN_PROGRESS (or
+ * `MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS` for functions in the
+ * Mbed TLS SSL module). For functions that accept a "restart
+ * context" argument, passing NULL disables restart and makes
+ * the function equivalent to the function with the same name
* with \c _restartable removed. For functions in the ECDH
- * module, restart is disabled unless the function accepts
- * an "ECDH context" argument and
- * mbedtls_ecdh_enable_restart() was previously called on
- * that context. For function in the SSL module, restart is
- * only enabled for specific sides and key exchanges
- * (currently only for clients and ECDHE-ECDSA).
+ * module, restart is disabled unless the function accepts an
+ * "ECDH context" argument and mbedtls_ecdh_enable_restart()
+ * was previously called on that context. For function in the
+ * Mbed TLS SSL module, restart is only enabled for specific
+ * sides and key exchanges (currently only for clients and
+ * ECDHE-ECDSA).
*
* \param max_ops Maximum number of basic operations done in a row.
* Default: 0 (unlimited).
@@ -407,6 +427,11 @@
int mbedtls_ecp_restart_is_enabled( void );
#endif /* MBEDTLS_ECP_RESTARTABLE */
+/*
+ * Get the type of a curve
+ */
+mbedtls_ecp_curve_type mbedtls_ecp_get_type( const mbedtls_ecp_group *grp );
+
/**
* \brief This function retrieves the information defined in
* mbedtls_ecp_curve_info() for all supported curves in order
@@ -472,7 +497,7 @@
*
* \note After this function is called, domain parameters
* for various ECP groups can be loaded through the
- * mbedtls_ecp_load() or mbedtls_ecp_tls_read_group()
+ * mbedtls_ecp_group_load() or mbedtls_ecp_tls_read_group()
* functions.
*/
void mbedtls_ecp_group_init( mbedtls_ecp_group *grp );
@@ -493,24 +518,37 @@
/**
* \brief This function frees the components of an ECP group.
- * \param grp The group to free.
+ *
+ * \param grp The group to free. This may be \c NULL, in which
+ * case this function returns immediately. If it is not
+ * \c NULL, it must point to an initialized ECP group.
*/
void mbedtls_ecp_group_free( mbedtls_ecp_group *grp );
/**
* \brief This function frees the components of a key pair.
- * \param key The key pair to free.
+ *
+ * \param key The key pair to free. This may be \c NULL, in which
+ * case this function returns immediately. If it is not
+ * \c NULL, it must point to an initialized ECP key pair.
*/
void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key );
#if defined(MBEDTLS_ECP_RESTARTABLE)
/**
- * \brief Initialize a restart context
+ * \brief Initialize a restart context.
+ *
+ * \param ctx The restart context to initialize. This must
+ * not be \c NULL.
*/
void mbedtls_ecp_restart_init( mbedtls_ecp_restart_ctx *ctx );
/**
- * \brief Free the components of a restart context
+ * \brief Free the components of a restart context.
+ *
+ * \param ctx The restart context to free. This may be \c NULL, in which
+ * case this function returns immediately. If it is not
+ * \c NULL, it must point to an initialized restart context.
*/
void mbedtls_ecp_restart_free( mbedtls_ecp_restart_ctx *ctx );
#endif /* MBEDTLS_ECP_RESTARTABLE */
@@ -519,11 +557,12 @@
* \brief This function copies the contents of point \p Q into
* point \p P.
*
- * \param P The destination point.
- * \param Q The source point.
+ * \param P The destination point. This must be initialized.
+ * \param Q The source point. This must be initialized.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
+ * \return Another negative error code for other kinds of failure.
*/
int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q );
@@ -531,31 +570,35 @@
* \brief This function copies the contents of group \p src into
* group \p dst.
*
- * \param dst The destination group.
- * \param src The source group.
+ * \param dst The destination group. This must be initialized.
+ * \param src The source group. This must be initialized.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
+ * \return Another negative error code on other kinds of failure.
*/
-int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src );
+int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst,
+ const mbedtls_ecp_group *src );
/**
- * \brief This function sets a point to zero.
+ * \brief This function sets a point to the point at infinity.
*
- * \param pt The point to set.
+ * \param pt The point to set. This must be initialized.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
+ * \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt );
/**
- * \brief This function checks if a point is zero.
+ * \brief This function checks if a point is the point at infinity.
*
- * \param pt The point to test.
+ * \param pt The point to test. This must be initialized.
*
* \return \c 1 if the point is zero.
* \return \c 0 if the point is non-zero.
+ * \return A negative error code on failure.
*/
int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt );
@@ -565,8 +608,8 @@
* \note This assumes that the points are normalized. Otherwise,
* they may compare as "not equal" even if they are.
*
- * \param P The first point to compare.
- * \param Q The second point to compare.
+ * \param P The first point to compare. This must be initialized.
+ * \param Q The second point to compare. This must be initialized.
*
* \return \c 0 if the points are equal.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal.
@@ -578,7 +621,7 @@
* \brief This function imports a non-zero point from two ASCII
* strings.
*
- * \param P The destination point.
+ * \param P The destination point. This must be initialized.
* \param radix The numeric base of the input.
* \param x The first affine coordinate, as a null-terminated string.
* \param y The second affine coordinate, as a null-terminated string.
@@ -593,19 +636,31 @@
* \brief This function exports a point into unsigned binary data.
*
* \param grp The group to which the point should belong.
- * \param P The point to export.
- * \param format The point format. Should be an \c MBEDTLS_ECP_PF_XXX macro.
- * \param olen The length of the output.
- * \param buf The output buffer.
- * \param buflen The length of the output buffer.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
+ * \param P The point to export. This must be initialized.
+ * \param format The point format. This must be either
+ * #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
+ * (For groups without these formats, this parameter is
+ * ignored. But it still has to be either of the above
+ * values.)
+ * \param olen The address at which to store the length of
+ * the output in Bytes. This must not be \c NULL.
+ * \param buf The output buffer. This must be a writable buffer
+ * of length \p buflen Bytes.
+ * \param buflen The length of the output buffer \p buf in Bytes.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA
- * or #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
+ * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output buffer
+ * is too small to hold the point.
+ * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
+ * or the export for the given group is not implemented.
+ * \return Another negative error code on other kinds of failure.
*/
-int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *P,
- int format, size_t *olen,
- unsigned char *buf, size_t buflen );
+int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp,
+ const mbedtls_ecp_point *P,
+ int format, size_t *olen,
+ unsigned char *buf, size_t buflen );
/**
* \brief This function imports a point from unsigned binary data.
@@ -615,108 +670,158 @@
* for that.
*
* \param grp The group to which the point should belong.
- * \param P The point to import.
- * \param buf The input buffer.
- * \param ilen The length of the input.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
+ * \param P The destination context to import the point to.
+ * This must be initialized.
+ * \param buf The input buffer. This must be a readable buffer
+ * of length \p ilen Bytes.
+ * \param ilen The length of the input buffer \p buf in Bytes.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
- * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
- * is not implemented.
- *
+ * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the import for the
+ * given group is not implemented.
*/
-int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_point *P,
- const unsigned char *buf, size_t ilen );
+int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp,
+ mbedtls_ecp_point *P,
+ const unsigned char *buf, size_t ilen );
/**
* \brief This function imports a point from a TLS ECPoint record.
*
- * \note On function return, \p buf is updated to point to immediately
+ * \note On function return, \p *buf is updated to point immediately
* after the ECPoint record.
*
- * \param grp The ECP group used.
+ * \param grp The ECP group to use.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
* \param pt The destination point.
* \param buf The address of the pointer to the start of the input buffer.
* \param len The length of the buffer.
*
* \return \c 0 on success.
- * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure.
+ * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization
+ * failure.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
*/
-int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point *pt,
- const unsigned char **buf, size_t len );
+int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp,
+ mbedtls_ecp_point *pt,
+ const unsigned char **buf, size_t len );
/**
- * \brief This function exports a point as a TLS ECPoint record.
+ * \brief This function exports a point as a TLS ECPoint record
+ * defined in RFC 4492, Section 5.4.
*
- * \param grp The ECP group used.
- * \param pt The point format to export to. The point format is an
- * \c MBEDTLS_ECP_PF_XXX constant.
- * \param format The export format.
- * \param olen The length of the data written.
- * \param buf The buffer to write to.
- * \param blen The length of the buffer.
+ * \param grp The ECP group to use.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
+ * \param pt The point to be exported. This must be initialized.
+ * \param format The point format to use. This must be either
+ * #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
+ * \param olen The address at which to store the length in Bytes
+ * of the data written.
+ * \param buf The target buffer. This must be a writable buffer of
+ * length \p blen Bytes.
+ * \param blen The length of the target buffer \p buf in Bytes.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA or
- * #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
+ * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the target buffer
+ * is too small to hold the exported point.
+ * \return Another negative error code on other kinds of failure.
*/
-int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt,
- int format, size_t *olen,
- unsigned char *buf, size_t blen );
+int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp,
+ const mbedtls_ecp_point *pt,
+ int format, size_t *olen,
+ unsigned char *buf, size_t blen );
/**
- * \brief This function sets a group using standardized domain parameters.
+ * \brief This function sets up an ECP group context
+ * from a standardized set of domain parameters.
*
* \note The index should be a value of the NamedCurve enum,
* as defined in <em>RFC-4492: Elliptic Curve Cryptography
* (ECC) Cipher Suites for Transport Layer Security (TLS)</em>,
* usually in the form of an \c MBEDTLS_ECP_DP_XXX macro.
*
- * \param grp The destination group.
+ * \param grp The group context to setup. This must be initialized.
* \param id The identifier of the domain parameter set to load.
*
- * \return \c 0 on success,
- * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure.
- * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups.
-
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if \p id doesn't
+ * correspond to a known group.
+ * \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id );
/**
- * \brief This function sets a group from a TLS ECParameters record.
+ * \brief This function sets up an ECP group context from a TLS
+ * ECParameters record as defined in RFC 4492, Section 5.4.
*
- * \note \p buf is updated to point right after the ECParameters record
- * on exit.
+ * \note The read pointer \p buf is updated to point right after
+ * the ECParameters record on exit.
*
- * \param grp The destination group.
+ * \param grp The group context to setup. This must be initialized.
* \param buf The address of the pointer to the start of the input buffer.
- * \param len The length of the buffer.
+ * \param len The length of the input buffer \c *buf in Bytes.
*
* \return \c 0 on success.
- * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
+ * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not
+ * recognized.
+ * \return Another negative error code on other kinds of failure.
*/
-int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp, const unsigned char **buf, size_t len );
+int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp,
+ const unsigned char **buf, size_t len );
/**
- * \brief This function writes the TLS ECParameters record for a group.
+ * \brief This function extracts an elliptic curve group ID from a
+ * TLS ECParameters record as defined in RFC 4492, Section 5.4.
*
- * \param grp The ECP group used.
- * \param olen The number of Bytes written.
- * \param buf The buffer to write to.
- * \param blen The length of the buffer.
+ * \note The read pointer \p buf is updated to point right after
+ * the ECParameters record on exit.
+ *
+ * \param grp The address at which to store the group id.
+ * This must not be \c NULL.
+ * \param buf The address of the pointer to the start of the input buffer.
+ * \param len The length of the input buffer \c *buf in Bytes.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
+ * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not
+ * recognized.
+ * \return Another negative error code on other kinds of failure.
*/
-int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen,
- unsigned char *buf, size_t blen );
+int mbedtls_ecp_tls_read_group_id( mbedtls_ecp_group_id *grp,
+ const unsigned char **buf,
+ size_t len );
+/**
+ * \brief This function exports an elliptic curve as a TLS
+ * ECParameters record as defined in RFC 4492, Section 5.4.
+ *
+ * \param grp The ECP group to be exported.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
+ * \param olen The address at which to store the number of Bytes written.
+ * This must not be \c NULL.
+ * \param buf The buffer to write to. This must be a writable buffer
+ * of length \p blen Bytes.
+ * \param blen The length of the output buffer \p buf in Bytes.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output
+ * buffer is too small to hold the exported group.
+ * \return Another negative error code on other kinds of failure.
+ */
+int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp,
+ size_t *olen,
+ unsigned char *buf, size_t blen );
/**
- * \brief This function performs multiplication of a point by
- * an integer: \p R = \p m * \p P.
+ * \brief This function performs a scalar multiplication of a point
+ * by an integer: \p R = \p m * \p P.
*
* It is not thread-safe to use same group in multiple threads.
*
@@ -730,17 +835,22 @@
* targeting these results. We recommend always providing
* a non-NULL \p f_rng. The overhead is negligible.
*
- * \param grp The ECP group.
- * \param R The destination point.
- * \param m The integer by which to multiply.
- * \param P The point to multiply.
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
+ * \param grp The ECP group to use.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
+ * \param R The point in which to store the result of the calculation.
+ * This must be initialized.
+ * \param m The integer by which to multiply. This must be initialized.
+ * \param P The point to multiply. This must be initialized.
+ * \param f_rng The RNG function. This may be \c NULL if randomization
+ * of intermediate results isn't desired (discouraged).
+ * \param p_rng The RNG context to be passed to \p p_rng.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
* key, or \p P is not a valid public key.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
+ * \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
const mbedtls_mpi *m, const mbedtls_ecp_point *P,
@@ -756,12 +866,16 @@
* it can return early and restart according to the limit set
* with \c mbedtls_ecp_set_max_ops() to reduce blocking.
*
- * \param grp The ECP group.
- * \param R The destination point.
- * \param m The integer by which to multiply.
- * \param P The point to multiply.
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
+ * \param grp The ECP group to use.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
+ * \param R The point in which to store the result of the calculation.
+ * This must be initialized.
+ * \param m The integer by which to multiply. This must be initialized.
+ * \param P The point to multiply. This must be initialized.
+ * \param f_rng The RNG function. This may be \c NULL if randomization
+ * of intermediate results isn't desired (discouraged).
+ * \param p_rng The RNG context to be passed to \p p_rng.
* \param rs_ctx The restart context (NULL disables restart).
*
* \return \c 0 on success.
@@ -770,6 +884,7 @@
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
* operations was reached: see \c mbedtls_ecp_set_max_ops().
+ * \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_mul_restartable( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
const mbedtls_mpi *m, const mbedtls_ecp_point *P,
@@ -785,18 +900,25 @@
* \note In contrast to mbedtls_ecp_mul(), this function does not
* guarantee a constant execution flow and timing.
*
- * \param grp The ECP group.
- * \param R The destination point.
+ * \param grp The ECP group to use.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
+ * \param R The point in which to store the result of the calculation.
+ * This must be initialized.
* \param m The integer by which to multiply \p P.
- * \param P The point to multiply by \p m.
+ * This must be initialized.
+ * \param P The point to multiply by \p m. This must be initialized.
* \param n The integer by which to multiply \p Q.
+ * This must be initialized.
* \param Q The point to be multiplied by \p n.
+ * This must be initialized.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
* valid private keys, or \p P or \p Q are not valid public
* keys.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
+ * \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
const mbedtls_mpi *m, const mbedtls_ecp_point *P,
@@ -813,12 +935,18 @@
* but it can return early and restart according to the limit
* set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
*
- * \param grp The ECP group.
- * \param R The destination point.
+ * \param grp The ECP group to use.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
+ * \param R The point in which to store the result of the calculation.
+ * This must be initialized.
* \param m The integer by which to multiply \p P.
- * \param P The point to multiply by \p m.
+ * This must be initialized.
+ * \param P The point to multiply by \p m. This must be initialized.
* \param n The integer by which to multiply \p Q.
+ * This must be initialized.
* \param Q The point to be multiplied by \p n.
+ * This must be initialized.
* \param rs_ctx The restart context (NULL disables restart).
*
* \return \c 0 on success.
@@ -828,6 +956,7 @@
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
* operations was reached: see \c mbedtls_ecp_set_max_ops().
+ * \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_muladd_restartable(
mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
@@ -852,38 +981,51 @@
* structures, such as ::mbedtls_ecdh_context or
* ::mbedtls_ecdsa_context.
*
- * \param grp The curve the point should lie on.
- * \param pt The point to check.
+ * \param grp The ECP group the point should belong to.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
+ * \param pt The point to check. This must be initialized.
*
* \return \c 0 if the point is a valid public key.
- * \return #MBEDTLS_ERR_ECP_INVALID_KEY on failure.
+ * \return #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not
+ * a valid public key for the given curve.
+ * \return Another negative error code on other kinds of failure.
*/
-int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt );
+int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp,
+ const mbedtls_ecp_point *pt );
/**
- * \brief This function checks that an \p mbedtls_mpi is a valid private
- * key for this curve.
+ * \brief This function checks that an \p mbedtls_mpi is a
+ * valid private key for this curve.
*
* \note This function uses bare components rather than an
* ::mbedtls_ecp_keypair structure to ease use with other
* structures, such as ::mbedtls_ecdh_context or
* ::mbedtls_ecdsa_context.
*
- * \param grp The group used.
- * \param d The integer to check.
+ * \param grp The ECP group the private key should belong to.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
+ * \param d The integer to check. This must be initialized.
*
* \return \c 0 if the point is a valid private key.
- * \return #MBEDTLS_ERR_ECP_INVALID_KEY on failure.
+ * \return #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not a valid
+ * private key for the given curve.
+ * \return Another negative error code on other kinds of failure.
*/
-int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d );
+int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp,
+ const mbedtls_mpi *d );
/**
* \brief This function generates a private key.
*
- * \param grp The ECP group.
- * \param d The destination MPI (secret part).
- * \param f_rng The RNG function.
- * \param p_rng The RNG parameter.
+ * \param grp The ECP group to generate a private key for.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
+ * \param d The destination MPI (secret part). This must be initialized.
+ * \param f_rng The RNG function. This must not be \c NULL.
+ * \param p_rng The RNG parameter to be passed to \p f_rng. This may be
+ * \c NULL if \p f_rng doesn't need a context argument.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
@@ -903,22 +1045,29 @@
* structures, such as ::mbedtls_ecdh_context or
* ::mbedtls_ecdsa_context.
*
- * \param grp The ECP group.
- * \param G The chosen base point.
+ * \param grp The ECP group to generate a key pair for.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
+ * \param G The base point to use. This must be initialized
+ * and belong to \p grp. It replaces the default base
+ * point \c grp->G used by mbedtls_ecp_gen_keypair().
* \param d The destination MPI (secret part).
+ * This must be initialized.
* \param Q The destination point (public part).
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
+ * This must be initialized.
+ * \param f_rng The RNG function. This must not be \c NULL.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may
+ * be \c NULL if \p f_rng doesn't need a context argument.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
* on failure.
*/
int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp,
- const mbedtls_ecp_point *G,
- mbedtls_mpi *d, mbedtls_ecp_point *Q,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng );
+ const mbedtls_ecp_point *G,
+ mbedtls_mpi *d, mbedtls_ecp_point *Q,
+ int (*f_rng)(void *, unsigned char *, size_t),
+ void *p_rng );
/**
* \brief This function generates an ECP keypair.
@@ -928,51 +1077,82 @@
* structures, such as ::mbedtls_ecdh_context or
* ::mbedtls_ecdsa_context.
*
- * \param grp The ECP group.
+ * \param grp The ECP group to generate a key pair for.
+ * This must be initialized and have group parameters
+ * set, for example through mbedtls_ecp_group_load().
* \param d The destination MPI (secret part).
+ * This must be initialized.
* \param Q The destination point (public part).
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
+ * This must be initialized.
+ * \param f_rng The RNG function. This must not be \c NULL.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may
+ * be \c NULL if \p f_rng doesn't need a context argument.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
* on failure.
*/
-int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng );
+int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d,
+ mbedtls_ecp_point *Q,
+ int (*f_rng)(void *, unsigned char *, size_t),
+ void *p_rng );
/**
* \brief This function generates an ECP key.
*
* \param grp_id The ECP group identifier.
- * \param key The destination key.
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
+ * \param key The destination key. This must be initialized.
+ * \param f_rng The RNG function to use. This must not be \c NULL.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may
+ * be \c NULL if \p f_rng doesn't need a context argument.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
* on failure.
*/
int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
- int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
+ int (*f_rng)(void *, unsigned char *, size_t),
+ void *p_rng );
/**
+ * \brief This function reads an elliptic curve private key.
+ *
+ * \param grp_id The ECP group identifier.
+ * \param key The destination key.
+ * \param buf The the buffer containing the binary representation of the
+ * key. (Big endian integer for Weierstrass curves, byte
+ * string for Montgomery curves.)
+ * \param buflen The length of the buffer in bytes.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_INVALID_KEY error if the key is
+ * invalid.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the operation for
+ * the group is not implemented.
+ * \return Another negative error code on different kinds of failure.
+ */
+int mbedtls_ecp_read_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
+ const unsigned char *buf, size_t buflen );
+/**
* \brief This function checks that the keypair objects
* \p pub and \p prv have the same group and the
* same public point, and that the private key in
* \p prv is consistent with the public key.
*
- * \param pub The keypair structure holding the public key.
- * If it contains a private key, that part is ignored.
+ * \param pub The keypair structure holding the public key. This
+ * must be initialized. If it contains a private key, that
+ * part is ignored.
* \param prv The keypair structure holding the full keypair.
+ * This must be initialized.
*
* \return \c 0 on success, meaning that the keys are valid and match.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match.
* \return An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX
* error code on calculation failure.
*/
-int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv );
+int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub,
+ const mbedtls_ecp_keypair *prv );
#if defined(MBEDTLS_SELF_TEST)
diff --git a/include/mbedtls/ecp_internal.h b/include/mbedtls/ecp_internal.h
index 1804069..7625ed4 100644
--- a/include/mbedtls/ecp_internal.h
+++ b/include/mbedtls/ecp_internal.h
@@ -61,6 +61,12 @@
#ifndef MBEDTLS_ECP_INTERNAL_H
#define MBEDTLS_ECP_INTERNAL_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#if defined(MBEDTLS_ECP_INTERNAL_ALT)
/**
diff --git a/include/mbedtls/error.h b/include/mbedtls/error.h
index 0c38889..bee0fe4 100644
--- a/include/mbedtls/error.h
+++ b/include/mbedtls/error.h
@@ -24,6 +24,12 @@
#ifndef MBEDTLS_ERROR_H
#define MBEDTLS_ERROR_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include <stddef.h>
/**
@@ -74,9 +80,9 @@
* MD4 1 0x002D-0x002D
* MD5 1 0x002F-0x002F
* RIPEMD160 1 0x0031-0x0031
- * SHA1 1 0x0035-0x0035
- * SHA256 1 0x0037-0x0037
- * SHA512 1 0x0039-0x0039
+ * SHA1 1 0x0035-0x0035 0x0073-0x0073
+ * SHA256 1 0x0037-0x0037 0x0074-0x0074
+ * SHA512 1 0x0039-0x0039 0x0075-0x0075
* CHACHA20 3 0x0051-0x0055
* POLY1305 3 0x0057-0x005B
* CHACHAPOLY 2 0x0054-0x0056
diff --git a/include/mbedtls/gcm.h b/include/mbedtls/gcm.h
index 93d15ee..fd130ab 100644
--- a/include/mbedtls/gcm.h
+++ b/include/mbedtls/gcm.h
@@ -33,6 +33,12 @@
#ifndef MBEDTLS_GCM_H
#define MBEDTLS_GCM_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "cipher.h"
#include <stdint.h>
@@ -85,7 +91,7 @@
* cipher, nor set the key. For this purpose, use
* mbedtls_gcm_setkey().
*
- * \param ctx The GCM context to initialize.
+ * \param ctx The GCM context to initialize. This must not be \c NULL.
*/
void mbedtls_gcm_init( mbedtls_gcm_context *ctx );
@@ -93,9 +99,10 @@
* \brief This function associates a GCM context with a
* cipher algorithm and a key.
*
- * \param ctx The GCM context to initialize.
+ * \param ctx The GCM context. This must be initialized.
* \param cipher The 128-bit block cipher to use.
- * \param key The encryption key.
+ * \param key The encryption key. This must be a readable buffer of at
+ * least \p keybits bits.
* \param keybits The key size in bits. Valid options are:
* <ul><li>128 bits</li>
* <li>192 bits</li>
@@ -122,7 +129,8 @@
* authentic. You should use this function to perform encryption
* only. For decryption, use mbedtls_gcm_auth_decrypt() instead.
*
- * \param ctx The GCM context to use for encryption or decryption.
+ * \param ctx The GCM context to use for encryption or decryption. This
+ * must be initialized.
* \param mode The operation to perform:
* - #MBEDTLS_GCM_ENCRYPT to perform authenticated encryption.
* The ciphertext is written to \p output and the
@@ -136,21 +144,27 @@
* calling this function in decryption mode.
* \param length The length of the input data, which is equal to the length
* of the output data.
- * \param iv The initialization vector.
+ * \param iv The initialization vector. This must be a readable buffer of
+ * at least \p iv_len Bytes.
* \param iv_len The length of the IV.
- * \param add The buffer holding the additional data.
+ * \param add The buffer holding the additional data. This must be of at
+ * least that size in Bytes.
* \param add_len The length of the additional data.
- * \param input The buffer holding the input data. Its size is \b length.
- * \param output The buffer for holding the output data. It must have room
- * for \b length bytes.
+ * \param input The buffer holding the input data. If \p length is greater
+ * than zero, this must be a readable buffer of at least that
+ * size in Bytes.
+ * \param output The buffer for holding the output data. If \p length is greater
+ * than zero, this must be a writable buffer of at least that
+ * size in Bytes.
* \param tag_len The length of the tag to generate.
- * \param tag The buffer for holding the tag.
+ * \param tag The buffer for holding the tag. This must be a readable
+ * buffer of at least \p tag_len Bytes.
*
* \return \c 0 if the encryption or decryption was performed
* successfully. Note that in #MBEDTLS_GCM_DECRYPT mode,
* this does not indicate that the data is authentic.
- * \return #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths are not valid or
- * a cipher-specific error code if the encryption
+ * \return #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths or pointers are
+ * not valid or a cipher-specific error code if the encryption
* or decryption failed.
*/
int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
@@ -173,23 +187,30 @@
* input buffer. If the buffers overlap, the output buffer
* must trail at least 8 Bytes behind the input buffer.
*
- * \param ctx The GCM context.
+ * \param ctx The GCM context. This must be initialized.
* \param length The length of the ciphertext to decrypt, which is also
* the length of the decrypted plaintext.
- * \param iv The initialization vector.
+ * \param iv The initialization vector. This must be a readable buffer
+ * of at least \p iv_len Bytes.
* \param iv_len The length of the IV.
- * \param add The buffer holding the additional data.
+ * \param add The buffer holding the additional data. This must be of at
+ * least that size in Bytes.
* \param add_len The length of the additional data.
- * \param tag The buffer holding the tag to verify.
+ * \param tag The buffer holding the tag to verify. This must be a
+ * readable buffer of at least \p tag_len Bytes.
* \param tag_len The length of the tag to verify.
- * \param input The buffer holding the ciphertext. Its size is \b length.
- * \param output The buffer for holding the decrypted plaintext. It must
- * have room for \b length bytes.
+ * \param input The buffer holding the ciphertext. If \p length is greater
+ * than zero, this must be a readable buffer of at least that
+ * size.
+ * \param output The buffer for holding the decrypted plaintext. If \p length
+ * is greater than zero, this must be a writable buffer of at
+ * least that size.
*
* \return \c 0 if successful and authenticated.
* \return #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match.
- * \return #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths are not valid or
- * a cipher-specific error code if the decryption failed.
+ * \return #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths or pointers are
+ * not valid or a cipher-specific error code if the decryption
+ * failed.
*/
int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
size_t length,
@@ -206,15 +227,16 @@
* \brief This function starts a GCM encryption or decryption
* operation.
*
- * \param ctx The GCM context.
+ * \param ctx The GCM context. This must be initialized.
* \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or
* #MBEDTLS_GCM_DECRYPT.
- * \param iv The initialization vector.
+ * \param iv The initialization vector. This must be a readable buffer of
+ * at least \p iv_len Bytes.
* \param iv_len The length of the IV.
- * \param add The buffer holding the additional data, or NULL
- * if \p add_len is 0.
- * \param add_len The length of the additional data. If 0,
- * \p add is NULL.
+ * \param add The buffer holding the additional data, or \c NULL
+ * if \p add_len is \c 0.
+ * \param add_len The length of the additional data. If \c 0,
+ * \p add may be \c NULL.
*
* \return \c 0 on success.
*/
@@ -237,11 +259,15 @@
* input buffer. If the buffers overlap, the output buffer
* must trail at least 8 Bytes behind the input buffer.
*
- * \param ctx The GCM context.
+ * \param ctx The GCM context. This must be initialized.
* \param length The length of the input data. This must be a multiple of
* 16 except in the last call before mbedtls_gcm_finish().
- * \param input The buffer holding the input data.
- * \param output The buffer for holding the output data.
+ * \param input The buffer holding the input data. If \p length is greater
+ * than zero, this must be a readable buffer of at least that
+ * size in Bytes.
+ * \param output The buffer for holding the output data. If \p length is
+ * greater than zero, this must be a writable buffer of at
+ * least that size in Bytes.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
@@ -258,9 +284,11 @@
* It wraps up the GCM stream, and generates the
* tag. The tag can have a maximum length of 16 Bytes.
*
- * \param ctx The GCM context.
- * \param tag The buffer for holding the tag.
- * \param tag_len The length of the tag to generate. Must be at least four.
+ * \param ctx The GCM context. This must be initialized.
+ * \param tag The buffer for holding the tag. This must be a readable
+ * buffer of at least \p tag_len Bytes.
+ * \param tag_len The length of the tag to generate. This must be at least
+ * four.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
@@ -273,10 +301,13 @@
* \brief This function clears a GCM context and the underlying
* cipher sub-context.
*
- * \param ctx The GCM context to clear.
+ * \param ctx The GCM context to clear. If this is \c NULL, the call has
+ * no effect. Otherwise, this must be initialized.
*/
void mbedtls_gcm_free( mbedtls_gcm_context *ctx );
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief The GCM checkup routine.
*
@@ -285,6 +316,8 @@
*/
int mbedtls_gcm_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/havege.h b/include/mbedtls/havege.h
index 57e8c40..4c1c860 100644
--- a/include/mbedtls/havege.h
+++ b/include/mbedtls/havege.h
@@ -24,6 +24,12 @@
#ifndef MBEDTLS_HAVEGE_H
#define MBEDTLS_HAVEGE_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include <stddef.h>
#define MBEDTLS_HAVEGE_COLLECT_SIZE 1024
diff --git a/include/mbedtls/hkdf.h b/include/mbedtls/hkdf.h
index e6ed7cd..40ee64e 100644
--- a/include/mbedtls/hkdf.h
+++ b/include/mbedtls/hkdf.h
@@ -27,6 +27,12 @@
#ifndef MBEDTLS_HKDF_H
#define MBEDTLS_HKDF_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "md.h"
/**
diff --git a/include/mbedtls/hmac_drbg.h b/include/mbedtls/hmac_drbg.h
index 3bc675e..f1289cb 100644
--- a/include/mbedtls/hmac_drbg.h
+++ b/include/mbedtls/hmac_drbg.h
@@ -24,6 +24,12 @@
#ifndef MBEDTLS_HMAC_DRBG_H
#define MBEDTLS_HMAC_DRBG_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "md.h"
#if defined(MBEDTLS_THREADING_C)
@@ -76,7 +82,7 @@
*/
typedef struct mbedtls_hmac_drbg_context
{
- /* Working state: the key K is not stored explicitely,
+ /* Working state: the key K is not stored explicitly,
* but is implied by the HMAC context */
mbedtls_md_context_t md_ctx; /*!< HMAC context (inc. K) */
unsigned char V[MBEDTLS_MD_MAX_SIZE]; /*!< V in the spec */
@@ -195,10 +201,13 @@
* \param additional Additional data to update state with, or NULL
* \param add_len Length of additional data, or 0
*
+ * \return \c 0 on success, or an error from the underlying
+ * hash calculation.
+ *
* \note Additional data is optional, pass NULL and 0 as second
* third argument if no additional data is being used.
*/
-void mbedtls_hmac_drbg_update( mbedtls_hmac_drbg_context *ctx,
+int mbedtls_hmac_drbg_update_ret( mbedtls_hmac_drbg_context *ctx,
const unsigned char *additional, size_t add_len );
/**
@@ -257,6 +266,31 @@
*/
void mbedtls_hmac_drbg_free( mbedtls_hmac_drbg_context *ctx );
+#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief HMAC_DRBG update state
+ *
+ * \deprecated Superseded by mbedtls_hmac_drbg_update_ret()
+ * in 2.16.0.
+ *
+ * \param ctx HMAC_DRBG context
+ * \param additional Additional data to update state with, or NULL
+ * \param add_len Length of additional data, or 0
+ *
+ * \note Additional data is optional, pass NULL and 0 as second
+ * third argument if no additional data is being used.
+ */
+MBEDTLS_DEPRECATED void mbedtls_hmac_drbg_update(
+ mbedtls_hmac_drbg_context *ctx,
+ const unsigned char *additional, size_t add_len );
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+
#if defined(MBEDTLS_FS_IO)
/**
* \brief Write a seed file
diff --git a/include/mbedtls/md2.h b/include/mbedtls/md2.h
index f9bd98f..fe97cf0 100644
--- a/include/mbedtls/md2.h
+++ b/include/mbedtls/md2.h
@@ -283,6 +283,8 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief Checkup routine
*
@@ -295,6 +297,8 @@
*/
int mbedtls_md2_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/md4.h b/include/mbedtls/md4.h
index dc3c048..ce703c0 100644
--- a/include/mbedtls/md4.h
+++ b/include/mbedtls/md4.h
@@ -288,6 +288,8 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief Checkup routine
*
@@ -300,6 +302,8 @@
*/
int mbedtls_md4_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/md5.h b/include/mbedtls/md5.h
index 6c3354f..6eed6cc 100644
--- a/include/mbedtls/md5.h
+++ b/include/mbedtls/md5.h
@@ -288,6 +288,8 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief Checkup routine
*
@@ -300,6 +302,8 @@
*/
int mbedtls_md5_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/net.h b/include/mbedtls/net.h
index 6c13b53..8cead58 100644
--- a/include/mbedtls/net.h
+++ b/include/mbedtls/net.h
@@ -23,6 +23,11 @@
*
* This file is part of mbed TLS (https://tls.mbed.org)
*/
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
#if !defined(MBEDTLS_DEPRECATED_REMOVED)
#include "net_sockets.h"
diff --git a/include/mbedtls/nist_kw.h b/include/mbedtls/nist_kw.h
index 5a0f656..3b67b59 100644
--- a/include/mbedtls/nist_kw.h
+++ b/include/mbedtls/nist_kw.h
@@ -37,6 +37,12 @@
#ifndef MBEDTLS_NIST_KW_H
#define MBEDTLS_NIST_KW_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "cipher.h"
#ifdef __cplusplus
diff --git a/include/mbedtls/oid.h b/include/mbedtls/oid.h
index 6fbd018..342ef75 100644
--- a/include/mbedtls/oid.h
+++ b/include/mbedtls/oid.h
@@ -43,13 +43,31 @@
#include "md.h"
#endif
-#if defined(MBEDTLS_X509_USE_C) || defined(MBEDTLS_X509_CREATE_C)
-#include "x509.h"
-#endif
-
#define MBEDTLS_ERR_OID_NOT_FOUND -0x002E /**< OID is not found. */
#define MBEDTLS_ERR_OID_BUF_TOO_SMALL -0x000B /**< output buffer is too small */
+/* This is for the benefit of X.509, but defined here in order to avoid
+ * having a "backwards" include of x.509.h here */
+/*
+ * X.509 extension types (internal, arbitrary values for bitsets)
+ */
+#define MBEDTLS_OID_X509_EXT_AUTHORITY_KEY_IDENTIFIER (1 << 0)
+#define MBEDTLS_OID_X509_EXT_SUBJECT_KEY_IDENTIFIER (1 << 1)
+#define MBEDTLS_OID_X509_EXT_KEY_USAGE (1 << 2)
+#define MBEDTLS_OID_X509_EXT_CERTIFICATE_POLICIES (1 << 3)
+#define MBEDTLS_OID_X509_EXT_POLICY_MAPPINGS (1 << 4)
+#define MBEDTLS_OID_X509_EXT_SUBJECT_ALT_NAME (1 << 5)
+#define MBEDTLS_OID_X509_EXT_ISSUER_ALT_NAME (1 << 6)
+#define MBEDTLS_OID_X509_EXT_SUBJECT_DIRECTORY_ATTRS (1 << 7)
+#define MBEDTLS_OID_X509_EXT_BASIC_CONSTRAINTS (1 << 8)
+#define MBEDTLS_OID_X509_EXT_NAME_CONSTRAINTS (1 << 9)
+#define MBEDTLS_OID_X509_EXT_POLICY_CONSTRAINTS (1 << 10)
+#define MBEDTLS_OID_X509_EXT_EXTENDED_KEY_USAGE (1 << 11)
+#define MBEDTLS_OID_X509_EXT_CRL_DISTRIBUTION_POINTS (1 << 12)
+#define MBEDTLS_OID_X509_EXT_INIHIBIT_ANYPOLICY (1 << 13)
+#define MBEDTLS_OID_X509_EXT_FRESHEST_CRL (1 << 14)
+#define MBEDTLS_OID_X509_EXT_NS_CERT_TYPE (1 << 16)
+
/*
* Top level OID tuples
*/
@@ -150,6 +168,11 @@
#define MBEDTLS_OID_FRESHEST_CRL MBEDTLS_OID_ID_CE "\x2E" /**< id-ce-freshestCRL OBJECT IDENTIFIER ::= { id-ce 46 } */
/*
+ * Certificate policies
+ */
+#define MBEDTLS_OID_ANY_POLICY MBEDTLS_OID_CERTIFICATE_POLICIES "\x00" /**< anyPolicy OBJECT IDENTIFIER ::= { id-ce-certificatePolicies 0 } */
+
+/*
* Netscape certificate extensions
*/
#define MBEDTLS_OID_NS_CERT MBEDTLS_OID_NETSCAPE "\x01"
@@ -424,7 +447,6 @@
*/
int mbedtls_oid_get_numeric_string( char *buf, size_t size, const mbedtls_asn1_buf *oid );
-#if defined(MBEDTLS_X509_USE_C) || defined(MBEDTLS_X509_CREATE_C)
/**
* \brief Translate an X.509 extension OID into local values
*
@@ -434,7 +456,6 @@
* \return 0 if successful, or MBEDTLS_ERR_OID_NOT_FOUND
*/
int mbedtls_oid_get_x509_ext_type( const mbedtls_asn1_buf *oid, int *ext_type );
-#endif
/**
* \brief Translate an X.509 attribute type OID into the short name
@@ -561,6 +582,16 @@
int mbedtls_oid_get_extended_key_usage( const mbedtls_asn1_buf *oid, const char **desc );
/**
+ * \brief Translate certificate policies OID into description
+ *
+ * \param oid OID to use
+ * \param desc place to store string pointer
+ *
+ * \return 0 if successful, or MBEDTLS_ERR_OID_NOT_FOUND
+ */
+int mbedtls_oid_get_certificate_policies( const mbedtls_asn1_buf *oid, const char **desc );
+
+/**
* \brief Translate md_type into hash algorithm OID
*
* \param md_alg message digest algorithm
diff --git a/include/mbedtls/padlock.h b/include/mbedtls/padlock.h
index 677936e..f05b72b 100644
--- a/include/mbedtls/padlock.h
+++ b/include/mbedtls/padlock.h
@@ -3,6 +3,9 @@
*
* \brief VIA PadLock ACE for HW encryption/decryption supported by some
* processors
+ *
+ * \warning These functions are only for internal use by other library
+ * functions; you must not call them directly.
*/
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
@@ -25,6 +28,12 @@
#ifndef MBEDTLS_PADLOCK_H
#define MBEDTLS_PADLOCK_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "aes.h"
#define MBEDTLS_ERR_PADLOCK_DATA_MISALIGNED -0x0030 /**< Input data should be aligned. */
@@ -57,7 +66,10 @@
#endif
/**
- * \brief PadLock detection routine
+ * \brief Internal PadLock detection routine
+ *
+ * \note This function is only for internal use by other library
+ * functions; you must not call it directly.
*
* \param feature The feature to detect
*
@@ -66,7 +78,10 @@
int mbedtls_padlock_has_support( int feature );
/**
- * \brief PadLock AES-ECB block en(de)cryption
+ * \brief Internal PadLock AES-ECB block en(de)cryption
+ *
+ * \note This function is only for internal use by other library
+ * functions; you must not call it directly.
*
* \param ctx AES context
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
@@ -76,12 +91,15 @@
* \return 0 if success, 1 if operation failed
*/
int mbedtls_padlock_xcryptecb( mbedtls_aes_context *ctx,
- int mode,
- const unsigned char input[16],
- unsigned char output[16] );
+ int mode,
+ const unsigned char input[16],
+ unsigned char output[16] );
/**
- * \brief PadLock AES-CBC buffer en(de)cryption
+ * \brief Internal PadLock AES-CBC buffer en(de)cryption
+ *
+ * \note This function is only for internal use by other library
+ * functions; you must not call it directly.
*
* \param ctx AES context
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
@@ -93,11 +111,11 @@
* \return 0 if success, 1 if operation failed
*/
int mbedtls_padlock_xcryptcbc( mbedtls_aes_context *ctx,
- int mode,
- size_t length,
- unsigned char iv[16],
- const unsigned char *input,
- unsigned char *output );
+ int mode,
+ size_t length,
+ unsigned char iv[16],
+ const unsigned char *input,
+ unsigned char *output );
#ifdef __cplusplus
}
diff --git a/include/mbedtls/pem.h b/include/mbedtls/pem.h
index fa82f7b..a29e9ce 100644
--- a/include/mbedtls/pem.h
+++ b/include/mbedtls/pem.h
@@ -24,6 +24,12 @@
#ifndef MBEDTLS_PEM_H
#define MBEDTLS_PEM_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include <stddef.h>
/**
diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h
index 862065e..24951a6 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -202,12 +202,18 @@
const mbedtls_pk_info_t *mbedtls_pk_info_from_type( mbedtls_pk_type_t pk_type );
/**
- * \brief Initialize a mbedtls_pk_context (as NONE)
+ * \brief Initialize a #mbedtls_pk_context (as NONE).
+ *
+ * \param ctx The context to initialize.
+ * This must not be \c NULL.
*/
void mbedtls_pk_init( mbedtls_pk_context *ctx );
/**
- * \brief Free a mbedtls_pk_context
+ * \brief Free the components of a #mbedtls_pk_context.
+ *
+ * \param ctx The context to clear. It must have been initialized.
+ * If this is \c NULL, this function does nothing.
*
* \note For contexts that have been set up with
* mbedtls_pk_setup_opaque(), this does not free the underlying
@@ -219,11 +225,17 @@
#if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
/**
* \brief Initialize a restart context
+ *
+ * \param ctx The context to initialize.
+ * This must not be \c NULL.
*/
void mbedtls_pk_restart_init( mbedtls_pk_restart_ctx *ctx );
/**
* \brief Free the components of a restart context
+ *
+ * \param ctx The context to clear. It must have been initialized.
+ * If this is \c NULL, this function does nothing.
*/
void mbedtls_pk_restart_free( mbedtls_pk_restart_ctx *ctx );
#endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
@@ -232,7 +244,8 @@
* \brief Initialize a PK context with the information given
* and allocates the type-specific PK subcontext.
*
- * \param ctx Context to initialize. Must be empty (type NONE).
+ * \param ctx Context to initialize. It must not have been set
+ * up yet (type #MBEDTLS_PK_NONE).
* \param info Information to use
*
* \return 0 on success,
@@ -273,14 +286,15 @@
* ECC key pair.
* \return #MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
*/
-int mbedtls_pk_setup_opaque( mbedtls_pk_context *ctx, const psa_key_slot_t key );
+int mbedtls_pk_setup_opaque( mbedtls_pk_context *ctx, const psa_key_handle_t key );
#endif /* MBEDTLS_USE_PSA_CRYPTO */
#if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
/**
* \brief Initialize an RSA-alt context
*
- * \param ctx Context to initialize. Must be empty (type NONE).
+ * \param ctx Context to initialize. It must not have been set
+ * up yet (type #MBEDTLS_PK_NONE).
* \param key RSA key pointer
* \param decrypt_func Decryption function
* \param sign_func Signing function
@@ -300,7 +314,7 @@
/**
* \brief Get the size in bits of the underlying key
*
- * \param ctx Context to use
+ * \param ctx The context to query. It must have been initialized.
*
* \return Key size in bits, or 0 on error
*/
@@ -308,7 +322,8 @@
/**
* \brief Get the length in bytes of the underlying key
- * \param ctx Context to use
+ *
+ * \param ctx The context to query. It must have been initialized.
*
* \return Key length in bytes, or 0 on error
*/
@@ -320,18 +335,21 @@
/**
* \brief Tell if a context can do the operation given by type
*
- * \param ctx Context to test
- * \param type Target type
+ * \param ctx The context to query. It must have been initialized.
+ * \param type The desired type.
*
- * \return 0 if context can't do the operations,
- * 1 otherwise.
+ * \return 1 if the context can do operations on the given type.
+ * \return 0 if the context cannot do the operations on the given
+ * type. This is always the case for a context that has
+ * been initialized but not set up, or that has been
+ * cleared with mbedtls_pk_free().
*/
int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type );
/**
* \brief Verify signature (including padding if relevant).
*
- * \param ctx PK context to use
+ * \param ctx The PK context to use. It must have been set up.
* \param md_alg Hash algorithm used (see notes)
* \param hash Hash of the message to sign
* \param hash_len Hash length or 0 (see notes)
@@ -364,7 +382,7 @@
* \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
* operations. For RSA, same as \c mbedtls_pk_verify().
*
- * \param ctx PK context to use
+ * \param ctx The PK context to use. It must have been set up.
* \param md_alg Hash algorithm used (see notes)
* \param hash Hash of the message to sign
* \param hash_len Hash length or 0 (see notes)
@@ -388,7 +406,7 @@
*
* \param type Signature type (inc. possible padding type) to verify
* \param options Pointer to type-specific options, or NULL
- * \param ctx PK context to use
+ * \param ctx The PK context to use. It must have been set up.
* \param md_alg Hash algorithm used (see notes)
* \param hash Hash of the message to sign
* \param hash_len Hash length or 0 (see notes)
@@ -419,7 +437,8 @@
/**
* \brief Make signature, including padding if relevant.
*
- * \param ctx PK context to use - must hold a private key
+ * \param ctx The PK context to use. It must have been set up
+ * with a private key.
* \param md_alg Hash algorithm used (see notes)
* \param hash Hash of the message to sign
* \param hash_len Hash length or 0 (see notes)
@@ -453,7 +472,8 @@
* \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
* operations. For RSA, same as \c mbedtls_pk_sign().
*
- * \param ctx PK context to use - must hold a private key
+ * \param ctx The PK context to use. It must have been set up
+ * with a private key.
* \param md_alg Hash algorithm used (see notes)
* \param hash Hash of the message to sign
* \param hash_len Hash length or 0 (see notes)
@@ -477,7 +497,8 @@
/**
* \brief Decrypt message (including padding if relevant).
*
- * \param ctx PK context to use - must hold a private key
+ * \param ctx The PK context to use. It must have been set up
+ * with a private key.
* \param input Input to decrypt
* \param ilen Input size
* \param output Decrypted output
@@ -498,7 +519,7 @@
/**
* \brief Encrypt message (including padding if relevant).
*
- * \param ctx PK context to use
+ * \param ctx The PK context to use. It must have been set up.
* \param input Message to encrypt
* \param ilen Message size
* \param output Encrypted output
@@ -533,7 +554,7 @@
/**
* \brief Export debug information
*
- * \param ctx Context to use
+ * \param ctx The PK context to use. It must have been initialized.
* \param items Place to write debug items
*
* \return 0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
@@ -543,7 +564,7 @@
/**
* \brief Access the type name
*
- * \param ctx Context to use
+ * \param ctx The PK context to use. It must have been initialized.
*
* \return Type name on success, or "invalid PK"
*/
@@ -552,9 +573,10 @@
/**
* \brief Get the key type
*
- * \param ctx Context to use
+ * \param ctx The PK context to use. It must have been initialized.
*
- * \return Type on success, or MBEDTLS_PK_NONE
+ * \return Type on success.
+ * \return #MBEDTLS_PK_NONE for a context that has not been set up.
*/
mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx );
@@ -563,12 +585,22 @@
/**
* \brief Parse a private key in PEM or DER format
*
- * \param ctx key to be initialized
- * \param key input buffer
- * \param keylen size of the buffer
- * (including the terminating null byte for PEM data)
- * \param pwd password for decryption (optional)
- * \param pwdlen size of the password
+ * \param ctx The PK context to fill. It must have been initialized
+ * but not set up.
+ * \param key Input buffer to parse.
+ * The buffer must contain the input exactly, with no
+ * extra trailing material. For PEM, the buffer must
+ * contain a null-terminated string.
+ * \param keylen Size of \b key in bytes.
+ * For PEM data, this includes the terminating null byte,
+ * so \p keylen must be equal to `strlen(key) + 1`.
+ * \param pwd Optional password for decryption.
+ * Pass \c NULL if expecting a non-encrypted key.
+ * Pass a string of \p pwdlen bytes if expecting an encrypted
+ * key; a non-encrypted key will also be accepted.
+ * The empty password is not supported.
+ * \param pwdlen Size of the password in bytes.
+ * Ignored if \p pwd is \c NULL.
*
* \note On entry, ctx must be empty, either freshly initialised
* with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
@@ -586,10 +618,15 @@
/**
* \brief Parse a public key in PEM or DER format
*
- * \param ctx key to be initialized
- * \param key input buffer
- * \param keylen size of the buffer
- * (including the terminating null byte for PEM data)
+ * \param ctx The PK context to fill. It must have been initialized
+ * but not set up.
+ * \param key Input buffer to parse.
+ * The buffer must contain the input exactly, with no
+ * extra trailing material. For PEM, the buffer must
+ * contain a null-terminated string.
+ * \param keylen Size of \b key in bytes.
+ * For PEM data, this includes the terminating null byte,
+ * so \p keylen must be equal to `strlen(key) + 1`.
*
* \note On entry, ctx must be empty, either freshly initialised
* with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
@@ -607,9 +644,14 @@
/**
* \brief Load and parse a private key
*
- * \param ctx key to be initialized
+ * \param ctx The PK context to fill. It must have been initialized
+ * but not set up.
* \param path filename to read the private key from
- * \param password password to decrypt the file (can be NULL)
+ * \param password Optional password to decrypt the file.
+ * Pass \c NULL if expecting a non-encrypted key.
+ * Pass a null-terminated string if expecting an encrypted
+ * key; a non-encrypted key will also be accepted.
+ * The empty password is not supported.
*
* \note On entry, ctx must be empty, either freshly initialised
* with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
@@ -626,7 +668,8 @@
/**
* \brief Load and parse a public key
*
- * \param ctx key to be initialized
+ * \param ctx The PK context to fill. It must have been initialized
+ * but not set up.
* \param path filename to read the public key from
*
* \note On entry, ctx must be empty, either freshly initialised
@@ -649,7 +692,7 @@
* return value to determine where you should start
* using the buffer
*
- * \param ctx private to write away
+ * \param ctx PK context which must contain a valid private key.
* \param buf buffer to write to
* \param size size of the buffer
*
@@ -664,7 +707,7 @@
* return value to determine where you should start
* using the buffer
*
- * \param ctx public key to write away
+ * \param ctx PK context which must contain a valid public or private key.
* \param buf buffer to write to
* \param size size of the buffer
*
@@ -677,9 +720,10 @@
/**
* \brief Write a public key to a PEM string
*
- * \param ctx public key to write away
- * \param buf buffer to write to
- * \param size size of the buffer
+ * \param ctx PK context which must contain a valid public or private key.
+ * \param buf Buffer to write to. The output includes a
+ * terminating null byte.
+ * \param size Size of the buffer in bytes.
*
* \return 0 if successful, or a specific error code
*/
@@ -688,9 +732,10 @@
/**
* \brief Write a private key to a PKCS#1 or SEC1 PEM string
*
- * \param ctx private to write away
- * \param buf buffer to write to
- * \param size size of the buffer
+ * \param ctx PK context which must contain a valid private key.
+ * \param buf Buffer to write to. The output includes a
+ * terminating null byte.
+ * \param size Size of the buffer in bytes.
*
* \return 0 if successful, or a specific error code
*/
@@ -709,7 +754,8 @@
*
* \param p the position in the ASN.1 data
* \param end end of the buffer
- * \param pk the key to fill
+ * \param pk The PK context to fill. It must have been initialized
+ * but not set up.
*
* \return 0 if successful, or a specific PK error code
*/
@@ -724,7 +770,7 @@
*
* \param p reference to current position pointer
* \param start start of the buffer (for bounds-checking)
- * \param key public key to write away
+ * \param key PK context which must contain a valid public or private key.
*
* \return the length written or a negative error code
*/
@@ -761,7 +807,7 @@
* \return An Mbed TLS error code otherwise.
*/
int mbedtls_pk_wrap_as_opaque( mbedtls_pk_context *pk,
- psa_key_slot_t *slot,
+ psa_key_handle_t *slot,
psa_algorithm_t hash_alg );
#endif /* MBEDTLS_USE_PSA_CRYPTO */
diff --git a/include/mbedtls/pkcs12.h b/include/mbedtls/pkcs12.h
index a621ef5..d441357 100644
--- a/include/mbedtls/pkcs12.h
+++ b/include/mbedtls/pkcs12.h
@@ -24,6 +24,12 @@
#ifndef MBEDTLS_PKCS12_H
#define MBEDTLS_PKCS12_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "md.h"
#include "cipher.h"
#include "asn1.h"
@@ -46,6 +52,8 @@
extern "C" {
#endif
+#if defined(MBEDTLS_ASN1_PARSE_C)
+
/**
* \brief PKCS12 Password Based function (encryption / decryption)
* for pbeWithSHAAnd128BitRC4
@@ -87,6 +95,8 @@
const unsigned char *input, size_t len,
unsigned char *output );
+#endif /* MBEDTLS_ASN1_PARSE_C */
+
/**
* \brief The PKCS#12 derivation function uses a password and a salt
* to produce pseudo-random bits for a particular "purpose".
diff --git a/include/mbedtls/pkcs5.h b/include/mbedtls/pkcs5.h
index 9a3c9fd..c92185f 100644
--- a/include/mbedtls/pkcs5.h
+++ b/include/mbedtls/pkcs5.h
@@ -26,6 +26,12 @@
#ifndef MBEDTLS_PKCS5_H
#define MBEDTLS_PKCS5_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "asn1.h"
#include "md.h"
@@ -44,6 +50,8 @@
extern "C" {
#endif
+#if defined(MBEDTLS_ASN1_PARSE_C)
+
/**
* \brief PKCS#5 PBES2 function
*
@@ -62,6 +70,8 @@
const unsigned char *data, size_t datalen,
unsigned char *output );
+#endif /* MBEDTLS_ASN1_PARSE_C */
+
/**
* \brief PKCS#5 PBKDF2 using HMAC
*
@@ -81,6 +91,8 @@
unsigned int iteration_count,
uint32_t key_length, unsigned char *output );
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief Checkup routine
*
@@ -88,6 +100,8 @@
*/
int mbedtls_pkcs5_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h
index 89fe8a7..801a948 100644
--- a/include/mbedtls/platform.h
+++ b/include/mbedtls/platform.h
@@ -58,17 +58,33 @@
* \{
*/
+/* The older Microsoft Windows common runtime provides non-conforming
+ * implementations of some standard library functions, including snprintf
+ * and vsnprintf. This affects MSVC and MinGW builds.
+ */
+#if defined(__MINGW32__) || (defined(_MSC_VER) && _MSC_VER <= 1900)
+#define MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF
+#define MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF
+#endif
+
#if !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS)
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
#if !defined(MBEDTLS_PLATFORM_STD_SNPRINTF)
-#if defined(_WIN32)
+#if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF)
#define MBEDTLS_PLATFORM_STD_SNPRINTF mbedtls_platform_win32_snprintf /**< The default \c snprintf function to use. */
#else
#define MBEDTLS_PLATFORM_STD_SNPRINTF snprintf /**< The default \c snprintf function to use. */
#endif
#endif
+#if !defined(MBEDTLS_PLATFORM_STD_VSNPRINTF)
+#if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF)
+#define MBEDTLS_PLATFORM_STD_VSNPRINTF mbedtls_platform_win32_vsnprintf /**< The default \c vsnprintf function to use. */
+#else
+#define MBEDTLS_PLATFORM_STD_VSNPRINTF vsnprintf /**< The default \c vsnprintf function to use. */
+#endif
+#endif
#if !defined(MBEDTLS_PLATFORM_STD_PRINTF)
#define MBEDTLS_PLATFORM_STD_PRINTF printf /**< The default \c printf function to use. */
#endif
@@ -204,7 +220,7 @@
* - however it is acceptable to return -1 instead of the required length when
* the destination buffer is too short.
*/
-#if defined(_WIN32)
+#if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF)
/* For Windows (inc. MSYS2), we provide our own fixed implementation */
int mbedtls_platform_win32_snprintf( char *s, size_t n, const char *fmt, ... );
#endif
@@ -231,6 +247,41 @@
#endif /* MBEDTLS_PLATFORM_SNPRINTF_ALT */
/*
+ * The function pointers for vsnprintf
+ *
+ * The vsnprintf implementation should conform to C99:
+ * - it *must* always correctly zero-terminate the buffer
+ * (except when n == 0, then it must leave the buffer untouched)
+ * - however it is acceptable to return -1 instead of the required length when
+ * the destination buffer is too short.
+ */
+#if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF)
+/* For Older Windows (inc. MSYS2), we provide our own fixed implementation */
+int mbedtls_platform_win32_vsnprintf( char *s, size_t n, const char *fmt, va_list arg );
+#endif
+
+#if defined(MBEDTLS_PLATFORM_VSNPRINTF_ALT)
+#include <stdarg.h>
+extern int (*mbedtls_vsnprintf)( char * s, size_t n, const char * format, va_list arg );
+
+/**
+ * \brief Set your own snprintf function pointer
+ *
+ * \param vsnprintf_func The \c vsnprintf function implementation
+ *
+ * \return \c 0
+ */
+int mbedtls_platform_set_vsnprintf( int (*vsnprintf_func)( char * s, size_t n,
+ const char * format, va_list arg ) );
+#else /* MBEDTLS_PLATFORM_VSNPRINTF_ALT */
+#if defined(MBEDTLS_PLATFORM_VSNPRINTF_MACRO)
+#define mbedtls_vsnprintf MBEDTLS_PLATFORM_VSNPRINTF_MACRO
+#else
+#define mbedtls_vsnprintf vsnprintf
+#endif /* MBEDTLS_PLATFORM_VSNPRINTF_MACRO */
+#endif /* MBEDTLS_PLATFORM_VSNPRINTF_ALT */
+
+/*
* The function pointers for exit
*/
#if defined(MBEDTLS_PLATFORM_EXIT_ALT)
diff --git a/include/mbedtls/platform_util.h b/include/mbedtls/platform_util.h
index 164a1a0..dba6d45 100644
--- a/include/mbedtls/platform_util.h
+++ b/include/mbedtls/platform_util.h
@@ -26,14 +26,14 @@
#define MBEDTLS_PLATFORM_UTIL_H
#if !defined(MBEDTLS_CONFIG_FILE)
-#include "mbedtls/config.h"
+#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#include <stddef.h>
#if defined(MBEDTLS_HAVE_TIME_DATE)
-#include "mbedtls/platform_time.h"
+#include "platform_time.h"
#include <time.h>
#endif /* MBEDTLS_HAVE_TIME_DATE */
@@ -41,6 +41,88 @@
extern "C" {
#endif
+#if defined(MBEDTLS_CHECK_PARAMS)
+
+#if defined(MBEDTLS_PARAM_FAILED)
+/** An alternative definition of MBEDTLS_PARAM_FAILED has been set in config.h.
+ *
+ * This flag can be used to check whether it is safe to assume that
+ * MBEDTLS_PARAM_FAILED() will expand to a call to mbedtls_param_failed().
+ */
+#define MBEDTLS_PARAM_FAILED_ALT
+#else /* MBEDTLS_PARAM_FAILED */
+#define MBEDTLS_PARAM_FAILED( cond ) \
+ mbedtls_param_failed( #cond, __FILE__, __LINE__ )
+
+/**
+ * \brief User supplied callback function for parameter validation failure.
+ * See #MBEDTLS_CHECK_PARAMS for context.
+ *
+ * This function will be called unless an alternative treatement
+ * is defined through the #MBEDTLS_PARAM_FAILED macro.
+ *
+ * This function can return, and the operation will be aborted, or
+ * alternatively, through use of setjmp()/longjmp() can resume
+ * execution in the application code.
+ *
+ * \param failure_condition The assertion that didn't hold.
+ * \param file The file where the assertion failed.
+ * \param line The line in the file where the assertion failed.
+ */
+void mbedtls_param_failed( const char *failure_condition,
+ const char *file,
+ int line );
+#endif /* MBEDTLS_PARAM_FAILED */
+
+/* Internal macro meant to be called only from within the library. */
+#define MBEDTLS_INTERNAL_VALIDATE_RET( cond, ret ) \
+ do { \
+ if( !(cond) ) \
+ { \
+ MBEDTLS_PARAM_FAILED( cond ); \
+ return( ret ); \
+ } \
+ } while( 0 )
+
+/* Internal macro meant to be called only from within the library. */
+#define MBEDTLS_INTERNAL_VALIDATE( cond ) \
+ do { \
+ if( !(cond) ) \
+ { \
+ MBEDTLS_PARAM_FAILED( cond ); \
+ return; \
+ } \
+ } while( 0 )
+
+#else /* MBEDTLS_CHECK_PARAMS */
+
+/* Internal macros meant to be called only from within the library. */
+#define MBEDTLS_INTERNAL_VALIDATE_RET( cond, ret ) do { } while( 0 )
+#define MBEDTLS_INTERNAL_VALIDATE( cond ) do { } while( 0 )
+
+#endif /* MBEDTLS_CHECK_PARAMS */
+
+/* Internal helper macros for deprecating API constants. */
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+/* Deliberately don't (yet) export MBEDTLS_DEPRECATED here
+ * to avoid conflict with other headers which define and use
+ * it, too. We might want to move all these definitions here at
+ * some point for uniformity. */
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_string_constant_t;
+#define MBEDTLS_DEPRECATED_STRING_CONSTANT( VAL ) \
+ ( (mbedtls_deprecated_string_constant_t) ( VAL ) )
+MBEDTLS_DEPRECATED typedef int mbedtls_deprecated_numeric_constant_t;
+#define MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( VAL ) \
+ ( (mbedtls_deprecated_numeric_constant_t) ( VAL ) )
+#undef MBEDTLS_DEPRECATED
+#else /* MBEDTLS_DEPRECATED_WARNING */
+#define MBEDTLS_DEPRECATED_STRING_CONSTANT( VAL ) VAL
+#define MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( VAL ) VAL
+#endif /* MBEDTLS_DEPRECATED_WARNING */
+#endif /* MBEDTLS_DEPRECATED_REMOVED */
+
/**
* \brief Securely zeroize a buffer
*
diff --git a/include/mbedtls/poly1305.h b/include/mbedtls/poly1305.h
index b02f968..f0ec44c 100644
--- a/include/mbedtls/poly1305.h
+++ b/include/mbedtls/poly1305.h
@@ -34,7 +34,7 @@
#define MBEDTLS_POLY1305_H
#if !defined(MBEDTLS_CONFIG_FILE)
-#include "mbedtls/config.h"
+#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
@@ -84,14 +84,18 @@
* \c mbedtls_poly1305_finish(), then finally
* \c mbedtls_poly1305_free().
*
- * \param ctx The Poly1305 context to initialize.
+ * \param ctx The Poly1305 context to initialize. This must
+ * not be \c NULL.
*/
void mbedtls_poly1305_init( mbedtls_poly1305_context *ctx );
/**
- * \brief This function releases and clears the specified Poly1305 context.
+ * \brief This function releases and clears the specified
+ * Poly1305 context.
*
- * \param ctx The Poly1305 context to clear.
+ * \param ctx The Poly1305 context to clear. This may be \c NULL, in which
+ * case this function is a no-op. If it is not \c NULL, it must
+ * point to an initialized Poly1305 context.
*/
void mbedtls_poly1305_free( mbedtls_poly1305_context *ctx );
@@ -102,11 +106,11 @@
* invocation of Poly1305.
*
* \param ctx The Poly1305 context to which the key should be bound.
- * \param key The buffer containing the 256-bit key.
+ * This must be initialized.
+ * \param key The buffer containing the \c 32 Byte (\c 256 Bit) key.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- * if ctx or key are NULL.
+ * \return A negative error code on failure.
*/
int mbedtls_poly1305_starts( mbedtls_poly1305_context *ctx,
const unsigned char key[32] );
@@ -120,13 +124,14 @@
* It can be called repeatedly to process a stream of data.
*
* \param ctx The Poly1305 context to use for the Poly1305 operation.
- * \param ilen The length of the input data (in bytes). Any value is accepted.
+ * This must be initialized and bound to a key.
+ * \param ilen The length of the input data in Bytes.
+ * Any value is accepted.
* \param input The buffer holding the input data.
- * This pointer can be NULL if ilen == 0.
+ * This pointer can be \c NULL if `ilen == 0`.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- * if ctx or input are NULL.
+ * \return A negative error code on failure.
*/
int mbedtls_poly1305_update( mbedtls_poly1305_context *ctx,
const unsigned char *input,
@@ -137,12 +142,12 @@
* Authentication Code (MAC).
*
* \param ctx The Poly1305 context to use for the Poly1305 operation.
- * \param mac The buffer to where the MAC is written. Must be big enough
- * to hold the 16-byte MAC.
+ * This must be initialized and bound to a key.
+ * \param mac The buffer to where the MAC is written. This must
+ * be a writable buffer of length \c 16 Bytes.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- * if ctx or mac are NULL.
+ * \return A negative error code on failure.
*/
int mbedtls_poly1305_finish( mbedtls_poly1305_context *ctx,
unsigned char mac[16] );
@@ -154,16 +159,16 @@
* \warning The key must be unique and unpredictable for each
* invocation of Poly1305.
*
- * \param key The buffer containing the 256-bit key.
- * \param ilen The length of the input data (in bytes). Any value is accepted.
+ * \param key The buffer containing the \c 32 Byte (\c 256 Bit) key.
+ * \param ilen The length of the input data in Bytes.
+ * Any value is accepted.
* \param input The buffer holding the input data.
- * This pointer can be NULL if ilen == 0.
- * \param mac The buffer to where the MAC is written. Must be big enough
- * to hold the 16-byte MAC.
+ * This pointer can be \c NULL if `ilen == 0`.
+ * \param mac The buffer to where the MAC is written. This must be
+ * a writable buffer of length \c 16 Bytes.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- * if key, input, or mac are NULL.
+ * \return A negative error code on failure.
*/
int mbedtls_poly1305_mac( const unsigned char key[32],
const unsigned char *input,
diff --git a/include/mbedtls/psa_util.h b/include/mbedtls/psa_util.h
index 5766133..b0c0428 100644
--- a/include/mbedtls/psa_util.h
+++ b/include/mbedtls/psa_util.h
@@ -41,21 +41,9 @@
#include "ecp.h"
#include "md.h"
#include "pk.h"
+#include "oid.h"
-/* Slot allocation */
-
-static inline psa_status_t mbedtls_psa_get_free_key_slot( psa_key_slot_t *key )
-{
- for( psa_key_slot_t slot = 1; slot <= 32; slot++ )
- {
- if( psa_get_key_information( slot, NULL, NULL ) == PSA_ERROR_EMPTY_SLOT )
- {
- *key = slot;
- return( PSA_SUCCESS );
- }
- }
- return( PSA_ERROR_INSUFFICIENT_MEMORY );
-}
+#include <string.h>
/* Translations for symmetric crypto. */
@@ -105,6 +93,7 @@
if( taglen == 0 )
return( PSA_ALG_CBC_NO_PADDING );
/* Intentional fallthrough for taglen != 0 */
+ /* fallthrough */
default:
return( 0 );
}
@@ -170,6 +159,162 @@
/* Translations for ECC. */
+static inline int mbedtls_psa_get_ecc_oid_from_id(
+ psa_ecc_curve_t curve, char const **oid, size_t *oid_len )
+{
+ switch( curve )
+ {
+#if defined(MBEDTLS_ECP_DP_SECP192R1_ENABLED)
+ case PSA_ECC_CURVE_SECP192R1:
+ *oid = MBEDTLS_OID_EC_GRP_SECP192R1;
+ *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_SECP192R1 );
+ return( 0 );
+#endif /* MBEDTLS_ECP_DP_SECP192R1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_SECP224R1_ENABLED)
+ case PSA_ECC_CURVE_SECP224R1:
+ *oid = MBEDTLS_OID_EC_GRP_SECP224R1;
+ *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_SECP224R1 );
+ return( 0 );
+#endif /* MBEDTLS_ECP_DP_SECP224R1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_SECP256R1_ENABLED)
+ case PSA_ECC_CURVE_SECP256R1:
+ *oid = MBEDTLS_OID_EC_GRP_SECP256R1;
+ *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_SECP256R1 );
+ return( 0 );
+#endif /* MBEDTLS_ECP_DP_SECP256R1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_SECP384R1_ENABLED)
+ case PSA_ECC_CURVE_SECP384R1:
+ *oid = MBEDTLS_OID_EC_GRP_SECP384R1;
+ *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_SECP384R1 );
+ return( 0 );
+#endif /* MBEDTLS_ECP_DP_SECP384R1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_SECP521R1_ENABLED)
+ case PSA_ECC_CURVE_SECP521R1:
+ *oid = MBEDTLS_OID_EC_GRP_SECP521R1;
+ *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_SECP521R1 );
+ return( 0 );
+#endif /* MBEDTLS_ECP_DP_SECP521R1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_SECP192K1_ENABLED)
+ case PSA_ECC_CURVE_SECP192K1:
+ *oid = MBEDTLS_OID_EC_GRP_SECP192K1;
+ *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_SECP192K1 );
+ return( 0 );
+#endif /* MBEDTLS_ECP_DP_SECP192K1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_SECP224K1_ENABLED)
+ case PSA_ECC_CURVE_SECP224K1:
+ *oid = MBEDTLS_OID_EC_GRP_SECP224K1;
+ *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_SECP224K1 );
+ return( 0 );
+#endif /* MBEDTLS_ECP_DP_SECP224K1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_SECP256K1_ENABLED)
+ case PSA_ECC_CURVE_SECP256K1:
+ *oid = MBEDTLS_OID_EC_GRP_SECP256K1;
+ *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_SECP256K1 );
+ return( 0 );
+#endif /* MBEDTLS_ECP_DP_SECP256K1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_BP256R1_ENABLED)
+ case PSA_ECC_CURVE_BRAINPOOL_P256R1:
+ *oid = MBEDTLS_OID_EC_GRP_BP256R1;
+ *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_BP256R1 );
+ return( 0 );
+#endif /* MBEDTLS_ECP_DP_BP256R1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_BP384R1_ENABLED)
+ case PSA_ECC_CURVE_BRAINPOOL_P384R1:
+ *oid = MBEDTLS_OID_EC_GRP_BP384R1;
+ *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_BP384R1 );
+ return( 0 );
+#endif /* MBEDTLS_ECP_DP_BP384R1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_BP512R1_ENABLED)
+ case PSA_ECC_CURVE_BRAINPOOL_P512R1:
+ *oid = MBEDTLS_OID_EC_GRP_BP512R1;
+ *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_BP512R1 );
+ return( 0 );
+#endif /* MBEDTLS_ECP_DP_BP512R1_ENABLED */
+ }
+
+ return( -1 );
+}
+
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH 1
+
+#if defined(MBEDTLS_ECP_DP_SECP192R1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 192 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 192 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_SECP192R1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_SECP224R1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 224 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 224 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_SECP224R1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_SECP256R1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 256 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 256 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_SECP256R1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_SECP384R1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 384 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 384 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_SECP384R1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_SECP521R1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 521 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 521 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_SECP521R1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_SECP192K1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 192 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 192 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_SECP192K1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_SECP224K1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 224 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 224 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_SECP224K1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_SECP256K1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 256 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 256 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_SECP256K1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_BP256R1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 256 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 256 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_BP256R1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_BP384R1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 384 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 384 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_BP384R1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_BP512R1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 512 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 512 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_BP512R1_ENABLED */
+
+
static inline psa_ecc_curve_t mbedtls_psa_translate_ecc_group( mbedtls_ecp_group_id grpid )
{
switch( grpid )
@@ -231,6 +376,24 @@
}
}
+
+#define MBEDTLS_PSA_ECC_KEY_BITS_OF_CURVE( curve ) \
+ ( curve == PSA_ECC_CURVE_SECP192R1 ? 192 : \
+ curve == PSA_ECC_CURVE_SECP224R1 ? 224 : \
+ curve == PSA_ECC_CURVE_SECP256R1 ? 256 : \
+ curve == PSA_ECC_CURVE_SECP384R1 ? 384 : \
+ curve == PSA_ECC_CURVE_SECP521R1 ? 521 : \
+ curve == PSA_ECC_CURVE_SECP192K1 ? 192 : \
+ curve == PSA_ECC_CURVE_SECP224K1 ? 224 : \
+ curve == PSA_ECC_CURVE_SECP256K1 ? 256 : \
+ curve == PSA_ECC_CURVE_BRAINPOOL_P256R1 ? 256 : \
+ curve == PSA_ECC_CURVE_BRAINPOOL_P384R1 ? 384 : \
+ curve == PSA_ECC_CURVE_BRAINPOOL_P512R1 ? 512 : \
+ 0 )
+
+#define MBEDTLS_PSA_ECC_KEY_BYTES_OF_CURVE( curve ) \
+ ( ( MBEDTLS_PSA_ECC_KEY_BITS_OF_CURVE( curve ) + 7 ) / 8 )
+
/* Translations for PK layer */
static inline int mbedtls_psa_err_translate_pk( psa_status_t status )
@@ -259,6 +422,61 @@
}
}
+/* Translations for ECC */
+
+/* This function transforms an ECC group identifier from
+ * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8
+ * into a PSA ECC group identifier. */
+static inline psa_ecc_curve_t mbedtls_psa_parse_tls_ecc_group(
+ uint16_t tls_ecc_grp_reg_id )
+{
+ /* The PSA identifiers are currently aligned with those from
+ * the TLS Supported Groups registry, so no conversion is necessary. */
+ return( (psa_ecc_curve_t) tls_ecc_grp_reg_id );
+}
+
+/* This function takes a buffer holding an EC public key
+ * exported through psa_export_public_key(), and converts
+ * it into an ECPoint structure to be put into a ClientKeyExchange
+ * message in an ECDHE exchange.
+ *
+ * Both the present and the foreseeable future format of EC public keys
+ * used by PSA have the ECPoint structure contained in the exported key
+ * as a subbuffer, and the function merely selects this subbuffer instead
+ * of making a copy.
+ */
+static inline int mbedtls_psa_tls_psa_ec_to_ecpoint( unsigned char *src,
+ size_t srclen,
+ unsigned char **dst,
+ size_t *dstlen )
+{
+ *dst = src;
+ *dstlen = srclen;
+ return( 0 );
+}
+
+/* This function takes a buffer holding an ECPoint structure
+ * (as contained in a TLS ServerKeyExchange message for ECDHE
+ * exchanges) and converts it into a format that the PSA key
+ * agreement API understands.
+ */
+static inline int mbedtls_psa_tls_ecpoint_to_psa_ec( psa_ecc_curve_t curve,
+ unsigned char const *src,
+ size_t srclen,
+ unsigned char *dst,
+ size_t dstlen,
+ size_t *olen )
+{
+ ((void) curve);
+
+ if( srclen > dstlen )
+ return( MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL );
+
+ memcpy( dst, src, srclen );
+ *olen = srclen;
+ return( 0 );
+}
+
#endif /* MBEDTLS_USE_PSA_CRYPTO */
#endif /* MBEDTLS_PSA_UTIL_H */
diff --git a/include/mbedtls/ripemd160.h b/include/mbedtls/ripemd160.h
index c74b7d2..b42f6d2 100644
--- a/include/mbedtls/ripemd160.h
+++ b/include/mbedtls/ripemd160.h
@@ -219,6 +219,8 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief Checkup routine
*
@@ -226,6 +228,8 @@
*/
int mbedtls_ripemd160_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h
index 406a317..489f2ed 100644
--- a/include/mbedtls/rsa.h
+++ b/include/mbedtls/rsa.h
@@ -150,23 +150,24 @@
* \note The choice of padding mode is strictly enforced for private key
* operations, since there might be security concerns in
* mixing padding modes. For public key operations it is
- * a default value, which can be overriden by calling specific
+ * a default value, which can be overridden by calling specific
* \c rsa_rsaes_xxx or \c rsa_rsassa_xxx functions.
*
* \note The hash selected in \p hash_id is always used for OEAP
* encryption. For PSS signatures, it is always used for
- * making signatures, but can be overriden for verifying them.
- * If set to #MBEDTLS_MD_NONE, it is always overriden.
+ * making signatures, but can be overridden for verifying them.
+ * If set to #MBEDTLS_MD_NONE, it is always overridden.
*
- * \param ctx The RSA context to initialize.
- * \param padding Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
- * #MBEDTLS_RSA_PKCS_V21.
- * \param hash_id The hash identifier of #mbedtls_md_type_t type, if
- * \p padding is #MBEDTLS_RSA_PKCS_V21.
+ * \param ctx The RSA context to initialize. This must not be \c NULL.
+ * \param padding The padding mode to use. This must be either
+ * #MBEDTLS_RSA_PKCS_V15 or #MBEDTLS_RSA_PKCS_V21.
+ * \param hash_id The hash identifier of ::mbedtls_md_type_t type, if
+ * \p padding is #MBEDTLS_RSA_PKCS_V21. It is unused
+ * otherwise.
*/
void mbedtls_rsa_init( mbedtls_rsa_context *ctx,
int padding,
- int hash_id);
+ int hash_id );
/**
* \brief This function imports a set of core parameters into an
@@ -188,11 +189,11 @@
* for the lifetime of the RSA context being set up.
*
* \param ctx The initialized RSA context to store the parameters in.
- * \param N The RSA modulus, or NULL.
- * \param P The first prime factor of \p N, or NULL.
- * \param Q The second prime factor of \p N, or NULL.
- * \param D The private exponent, or NULL.
- * \param E The public exponent, or NULL.
+ * \param N The RSA modulus. This may be \c NULL.
+ * \param P The first prime factor of \p N. This may be \c NULL.
+ * \param Q The second prime factor of \p N. This may be \c NULL.
+ * \param D The private exponent. This may be \c NULL.
+ * \param E The public exponent. This may be \c NULL.
*
* \return \c 0 on success.
* \return A non-zero error code on failure.
@@ -222,16 +223,16 @@
* for the lifetime of the RSA context being set up.
*
* \param ctx The initialized RSA context to store the parameters in.
- * \param N The RSA modulus, or NULL.
- * \param N_len The Byte length of \p N, ignored if \p N == NULL.
- * \param P The first prime factor of \p N, or NULL.
- * \param P_len The Byte length of \p P, ignored if \p P == NULL.
- * \param Q The second prime factor of \p N, or NULL.
- * \param Q_len The Byte length of \p Q, ignored if \p Q == NULL.
- * \param D The private exponent, or NULL.
- * \param D_len The Byte length of \p D, ignored if \p D == NULL.
- * \param E The public exponent, or NULL.
- * \param E_len The Byte length of \p E, ignored if \p E == NULL.
+ * \param N The RSA modulus. This may be \c NULL.
+ * \param N_len The Byte length of \p N; it is ignored if \p N == NULL.
+ * \param P The first prime factor of \p N. This may be \c NULL.
+ * \param P_len The Byte length of \p P; it ns ignored if \p P == NULL.
+ * \param Q The second prime factor of \p N. This may be \c NULL.
+ * \param Q_len The Byte length of \p Q; it is ignored if \p Q == NULL.
+ * \param D The private exponent. This may be \c NULL.
+ * \param D_len The Byte length of \p D; it is ignored if \p D == NULL.
+ * \param E The public exponent. This may be \c NULL.
+ * \param E_len The Byte length of \p E; it is ignored if \p E == NULL.
*
* \return \c 0 on success.
* \return A non-zero error code on failure.
@@ -299,11 +300,16 @@
* the RSA context stays intact and remains usable.
*
* \param ctx The initialized RSA context.
- * \param N The MPI to hold the RSA modulus, or NULL.
- * \param P The MPI to hold the first prime factor of \p N, or NULL.
- * \param Q The MPI to hold the second prime factor of \p N, or NULL.
- * \param D The MPI to hold the private exponent, or NULL.
- * \param E The MPI to hold the public exponent, or NULL.
+ * \param N The MPI to hold the RSA modulus.
+ * This may be \c NULL if this field need not be exported.
+ * \param P The MPI to hold the first prime factor of \p N.
+ * This may be \c NULL if this field need not be exported.
+ * \param Q The MPI to hold the second prime factor of \p N.
+ * This may be \c NULL if this field need not be exported.
+ * \param D The MPI to hold the private exponent.
+ * This may be \c NULL if this field need not be exported.
+ * \param E The MPI to hold the public exponent.
+ * This may be \c NULL if this field need not be exported.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED if exporting the
@@ -341,17 +347,20 @@
* buffer pointers are NULL.
*
* \param ctx The initialized RSA context.
- * \param N The Byte array to store the RSA modulus, or NULL.
+ * \param N The Byte array to store the RSA modulus,
+ * or \c NULL if this field need not be exported.
* \param N_len The size of the buffer for the modulus.
- * \param P The Byte array to hold the first prime factor of \p N, or
- * NULL.
+ * \param P The Byte array to hold the first prime factor of \p N,
+ * or \c NULL if this field need not be exported.
* \param P_len The size of the buffer for the first prime factor.
- * \param Q The Byte array to hold the second prime factor of \p N, or
- * NULL.
+ * \param Q The Byte array to hold the second prime factor of \p N,
+ * or \c NULL if this field need not be exported.
* \param Q_len The size of the buffer for the second prime factor.
- * \param D The Byte array to hold the private exponent, or NULL.
+ * \param D The Byte array to hold the private exponent,
+ * or \c NULL if this field need not be exported.
* \param D_len The size of the buffer for the private exponent.
- * \param E The Byte array to hold the public exponent, or NULL.
+ * \param E The Byte array to hold the public exponent,
+ * or \c NULL if this field need not be exported.
* \param E_len The size of the buffer for the public exponent.
*
* \return \c 0 on success.
@@ -375,9 +384,12 @@
* mbedtls_rsa_deduce_opt().
*
* \param ctx The initialized RSA context.
- * \param DP The MPI to hold D modulo P-1, or NULL.
- * \param DQ The MPI to hold D modulo Q-1, or NULL.
- * \param QP The MPI to hold modular inverse of Q modulo P, or NULL.
+ * \param DP The MPI to hold \c D modulo `P-1`,
+ * or \c NULL if it need not be exported.
+ * \param DQ The MPI to hold \c D modulo `Q-1`,
+ * or \c NULL if it need not be exported.
+ * \param QP The MPI to hold modular inverse of \c Q modulo \c P,
+ * or \c NULL if it need not be exported.
*
* \return \c 0 on success.
* \return A non-zero error code on failure.
@@ -390,13 +402,13 @@
* \brief This function sets padding for an already initialized RSA
* context. See mbedtls_rsa_init() for details.
*
- * \param ctx The RSA context to be set.
- * \param padding Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
- * #MBEDTLS_RSA_PKCS_V21.
+ * \param ctx The initialized RSA context to be configured.
+ * \param padding The padding mode to use. This must be either
+ * #MBEDTLS_RSA_PKCS_V15 or #MBEDTLS_RSA_PKCS_V21.
* \param hash_id The #MBEDTLS_RSA_PKCS_V21 hash identifier.
*/
void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding,
- int hash_id);
+ int hash_id );
/**
* \brief This function retrieves the length of RSA modulus in Bytes.
@@ -414,11 +426,14 @@
* \note mbedtls_rsa_init() must be called before this function,
* to set up the RSA context.
*
- * \param ctx The RSA context used to hold the key.
- * \param f_rng The RNG function.
- * \param p_rng The RNG context.
+ * \param ctx The initialized RSA context used to hold the key.
+ * \param f_rng The RNG function to be used for key generation.
+ * This must not be \c NULL.
+ * \param p_rng The RNG context to be passed to \p f_rng.
+ * This may be \c NULL if \p f_rng doesn't need a context.
* \param nbits The size of the public key in bits.
- * \param exponent The public exponent. For example, 65537.
+ * \param exponent The public exponent to use. For example, \c 65537.
+ * This must be odd and greater than \c 1.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -436,7 +451,7 @@
* enough information is present to perform an RSA public key
* operation using mbedtls_rsa_public().
*
- * \param ctx The RSA context to check.
+ * \param ctx The initialized RSA context to check.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -475,7 +490,7 @@
* parameters, which goes beyond what is effectively checkable
* by the library.</li></ul>
*
- * \param ctx The RSA context to check.
+ * \param ctx The initialized RSA context to check.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -487,8 +502,8 @@
*
* It checks each of the contexts, and makes sure they match.
*
- * \param pub The RSA context holding the public key.
- * \param prv The RSA context holding the private key.
+ * \param pub The initialized RSA context holding the public key.
+ * \param prv The initialized RSA context holding the private key.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -499,18 +514,19 @@
/**
* \brief This function performs an RSA public key operation.
*
+ * \param ctx The initialized RSA context to use.
+ * \param input The input buffer. This must be a readable buffer
+ * of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
+ * \param output The output buffer. This must be a writable buffer
+ * of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
+ *
* \note This function does not handle message padding.
*
* \note Make sure to set \p input[0] = 0 or ensure that
* input is smaller than \p N.
*
- * \note The input and output buffers must be large
- * enough. For example, 128 Bytes if RSA-1024 is used.
- *
- * \param ctx The RSA context.
- * \param input The input buffer.
- * \param output The output buffer.
- *
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
@@ -521,9 +537,6 @@
/**
* \brief This function performs an RSA private key operation.
*
- * \note The input and output buffers must be large
- * enough. For example, 128 Bytes if RSA-1024 is used.
- *
* \note Blinding is used if and only if a PRNG is provided.
*
* \note If blinding is used, both the base of exponentation
@@ -535,11 +548,18 @@
* Future versions of the library may enforce the presence
* of a PRNG.
*
- * \param ctx The RSA context.
- * \param f_rng The RNG function. Needed for blinding.
- * \param p_rng The RNG context.
- * \param input The input buffer.
- * \param output The output buffer.
+ * \param ctx The initialized RSA context to use.
+ * \param f_rng The RNG function, used for blinding. It is discouraged
+ * and deprecated to pass \c NULL here, in which case
+ * blinding will be omitted.
+ * \param p_rng The RNG context to pass to \p f_rng. This may be \c NULL
+ * if \p f_rng is \c NULL or if \p f_rng doesn't need a context.
+ * \param input The input buffer. This must be a readable buffer
+ * of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
+ * \param output The output buffer. This must be a writable buffer
+ * of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -558,9 +578,6 @@
* It is the generic wrapper for performing a PKCS#1 encryption
* operation using the \p mode from the context.
*
- * \note The input and output buffers must be as large as the size
- * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
- *
* \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
* are likely to remove the \p mode argument and have it
@@ -570,14 +587,25 @@
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead
* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
*
- * \param ctx The RSA context.
- * \param f_rng The RNG function. Needed for padding, PKCS#1 v2.1
- * encoding, and #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG context.
- * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
- * \param ilen The length of the plaintext.
- * \param input The buffer holding the data to encrypt.
- * \param output The buffer used to hold the ciphertext.
+ * \param ctx The initialized RSA context to use.
+ * \param f_rng The RNG to use. It is mandatory for PKCS#1 v2.1 padding
+ * encoding, and for PKCS#1 v1.5 padding encoding when used
+ * with \p mode set to #MBEDTLS_RSA_PUBLIC. For PKCS#1 v1.5
+ * padding encoding and \p mode set to #MBEDTLS_RSA_PRIVATE,
+ * it is used for blinding and should be provided in this
+ * case; see mbedtls_rsa_private() for more.
+ * \param p_rng The RNG context to be passed to \p f_rng. May be
+ * \c NULL if \p f_rng is \c NULL or if \p f_rng doesn't
+ * need a context argument.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
+ * \param ilen The length of the plaintext in Bytes.
+ * \param input The input data to encrypt. This must be a readable
+ * buffer of size \p ilen Bytes. It may be \c NULL if
+ * `ilen == 0`.
+ * \param output The output buffer. This must be a writable buffer
+ * of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -593,9 +621,6 @@
* \brief This function performs a PKCS#1 v1.5 encryption operation
* (RSAES-PKCS1-v1_5-ENCRYPT).
*
- * \note The output buffer must be as large as the size
- * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
- *
* \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
* are likely to remove the \p mode argument and have it
@@ -605,14 +630,23 @@
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead
* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
*
- * \param ctx The RSA context.
- * \param f_rng The RNG function. Needed for padding and
- * #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG context.
- * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
- * \param ilen The length of the plaintext.
- * \param input The buffer holding the data to encrypt.
- * \param output The buffer used to hold the ciphertext.
+ * \param ctx The initialized RSA context to use.
+ * \param f_rng The RNG function to use. It is needed for padding generation
+ * if \p mode is #MBEDTLS_RSA_PUBLIC. If \p mode is
+ * #MBEDTLS_RSA_PRIVATE (discouraged), it is used for
+ * blinding and should be provided; see mbedtls_rsa_private().
+ * \param p_rng The RNG context to be passed to \p f_rng. This may
+ * be \c NULL if \p f_rng is \c NULL or if \p f_rng
+ * doesn't need a context argument.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
+ * \param ilen The length of the plaintext in Bytes.
+ * \param input The input data to encrypt. This must be a readable
+ * buffer of size \p ilen Bytes. It may be \c NULL if
+ * `ilen == 0`.
+ * \param output The output buffer. This must be a writable buffer
+ * of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -640,16 +674,24 @@
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead
* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
*
- * \param ctx The RSA context.
- * \param f_rng The RNG function. Needed for padding and PKCS#1 v2.1
- * encoding and #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG context.
- * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ctx The initnialized RSA context to use.
+ * \param f_rng The RNG function to use. This is needed for padding
+ * generation and must be provided.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may
+ * be \c NULL if \p f_rng doesn't need a context argument.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
* \param label The buffer holding the custom label to use.
- * \param label_len The length of the label.
- * \param ilen The length of the plaintext.
- * \param input The buffer holding the data to encrypt.
- * \param output The buffer used to hold the ciphertext.
+ * This must be a readable buffer of length \p label_len
+ * Bytes. It may be \c NULL if \p label_len is \c 0.
+ * \param label_len The length of the label in Bytes.
+ * \param ilen The length of the plaintext buffer \p input in Bytes.
+ * \param input The input data to encrypt. This must be a readable
+ * buffer of size \p ilen Bytes. It may be \c NULL if
+ * `ilen == 0`.
+ * \param output The output buffer. This must be a writable buffer
+ * of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -677,9 +719,6 @@
* hold the decryption of the particular ciphertext provided,
* the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
*
- * \note The input buffer must be as large as the size
- * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
- *
* \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
* are likely to remove the \p mode argument and have it
@@ -689,14 +728,23 @@
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
*
- * \param ctx The RSA context.
- * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG context.
- * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
- * \param olen The length of the plaintext.
- * \param input The buffer holding the encrypted data.
- * \param output The buffer used to hold the plaintext.
- * \param output_max_len The maximum length of the output buffer.
+ * \param ctx The initialized RSA context to use.
+ * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,
+ * this is used for blinding and should be provided; see
+ * mbedtls_rsa_private() for more. If \p mode is
+ * #MBEDTLS_RSA_PUBLIC, it is ignored.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be
+ * \c NULL if \p f_rng is \c NULL or doesn't need a context.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
+ * \param olen The address at which to store the length of
+ * the plaintext. This must not be \c NULL.
+ * \param input The ciphertext buffer. This must be a readable buffer
+ * of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
+ * \param output The buffer used to hold the plaintext. This must
+ * be a writable buffer of length \p output_max_len Bytes.
+ * \param output_max_len The length in Bytes of the output buffer \p output.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -720,9 +768,6 @@
* hold the decryption of the particular ciphertext provided,
* the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
*
- * \note The input buffer must be as large as the size
- * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
- *
* \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
* are likely to remove the \p mode argument and have it
@@ -732,14 +777,23 @@
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
*
- * \param ctx The RSA context.
- * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG context.
- * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
- * \param olen The length of the plaintext.
- * \param input The buffer holding the encrypted data.
- * \param output The buffer to hold the plaintext.
- * \param output_max_len The maximum length of the output buffer.
+ * \param ctx The initialized RSA context to use.
+ * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,
+ * this is used for blinding and should be provided; see
+ * mbedtls_rsa_private() for more. If \p mode is
+ * #MBEDTLS_RSA_PUBLIC, it is ignored.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be
+ * \c NULL if \p f_rng is \c NULL or doesn't need a context.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
+ * \param olen The address at which to store the length of
+ * the plaintext. This must not be \c NULL.
+ * \param input The ciphertext buffer. This must be a readable buffer
+ * of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
+ * \param output The buffer used to hold the plaintext. This must
+ * be a writable buffer of length \p output_max_len Bytes.
+ * \param output_max_len The length in Bytes of the output buffer \p output.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -765,9 +819,6 @@
* ciphertext provided, the function returns
* #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
*
- * \note The input buffer must be as large as the size
- * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
- *
* \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
* are likely to remove the \p mode argument and have it
@@ -777,16 +828,27 @@
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
*
- * \param ctx The RSA context.
- * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG context.
- * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ctx The initialized RSA context to use.
+ * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,
+ * this is used for blinding and should be provided; see
+ * mbedtls_rsa_private() for more. If \p mode is
+ * #MBEDTLS_RSA_PUBLIC, it is ignored.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be
+ * \c NULL if \p f_rng is \c NULL or doesn't need a context.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
* \param label The buffer holding the custom label to use.
- * \param label_len The length of the label.
- * \param olen The length of the plaintext.
- * \param input The buffer holding the encrypted data.
- * \param output The buffer to hold the plaintext.
- * \param output_max_len The maximum length of the output buffer.
+ * This must be a readable buffer of length \p label_len
+ * Bytes. It may be \c NULL if \p label_len is \c 0.
+ * \param label_len The length of the label in Bytes.
+ * \param olen The address at which to store the length of
+ * the plaintext. This must not be \c NULL.
+ * \param input The ciphertext buffer. This must be a readable buffer
+ * of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
+ * \param output The buffer used to hold the plaintext. This must
+ * be a writable buffer of length \p output_max_len Bytes.
+ * \param output_max_len The length in Bytes of the output buffer \p output.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -824,16 +886,28 @@
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
*
- * \param ctx The RSA context.
- * \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for
- * #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG context.
- * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ctx The initialized RSA context to use.
+ * \param f_rng The RNG function to use. If the padding mode is PKCS#1 v2.1,
+ * this must be provided. If the padding mode is PKCS#1 v1.5 and
+ * \p mode is #MBEDTLS_RSA_PRIVATE, it is used for blinding
+ * and should be provided; see mbedtls_rsa_private() for more
+ * more. It is ignored otherwise.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL
+ * if \p f_rng is \c NULL or doesn't need a context argument.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
* \param md_alg The message-digest algorithm used to hash the original data.
* Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash The buffer holding the message digest.
- * \param sig The buffer to hold the ciphertext.
+ * \param hashlen The length of the message digest.
+ * Ths is only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash The buffer holding the message digest or raw data.
+ * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
+ * buffer of length \p hashlen Bytes. If \p md_alg is not
+ * #MBEDTLS_MD_NONE, it must be a readable buffer of length
+ * the size of the hash corresponding to \p md_alg.
+ * \param sig The buffer to hold the signature. This must be a writable
+ * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
*
* \return \c 0 if the signing operation was successful.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -851,9 +925,6 @@
* \brief This function performs a PKCS#1 v1.5 signature
* operation (RSASSA-PKCS1-v1_5-SIGN).
*
- * \note The \p sig buffer must be as large as the size
- * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
- *
* \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
* are likely to remove the \p mode argument and have it
@@ -863,15 +934,27 @@
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
*
- * \param ctx The RSA context.
- * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG context.
- * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ctx The initialized RSA context to use.
+ * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,
+ * this is used for blinding and should be provided; see
+ * mbedtls_rsa_private() for more. If \p mode is
+ * #MBEDTLS_RSA_PUBLIC, it is ignored.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL
+ * if \p f_rng is \c NULL or doesn't need a context argument.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
* \param md_alg The message-digest algorithm used to hash the original data.
* Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash The buffer holding the message digest.
- * \param sig The buffer to hold the ciphertext.
+ * \param hashlen The length of the message digest.
+ * Ths is only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash The buffer holding the message digest or raw data.
+ * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
+ * buffer of length \p hashlen Bytes. If \p md_alg is not
+ * #MBEDTLS_MD_NONE, it must be a readable buffer of length
+ * the size of the hash corresponding to \p md_alg.
+ * \param sig The buffer to hold the signature. This must be a writable
+ * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
*
* \return \c 0 if the signing operation was successful.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -889,9 +972,6 @@
* \brief This function performs a PKCS#1 v2.1 PSS signature
* operation (RSASSA-PSS-SIGN).
*
- * \note The \p sig buffer must be as large as the size
- * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
- *
* \note The \p hash_id in the RSA context is the one used for the
* encoding. \p md_alg in the function call is the type of hash
* that is encoded. According to <em>RFC-3447: Public-Key
@@ -918,16 +998,24 @@
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
*
- * \param ctx The RSA context.
- * \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for
- * #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG context.
- * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ctx The initialized RSA context to use.
+ * \param f_rng The RNG function. It must not be \c NULL.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL
+ * if \p f_rng doesn't need a context argument.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
* \param md_alg The message-digest algorithm used to hash the original data.
* Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash The buffer holding the message digest.
- * \param sig The buffer to hold the ciphertext.
+ * \param hashlen The length of the message digest.
+ * Ths is only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash The buffer holding the message digest or raw data.
+ * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
+ * buffer of length \p hashlen Bytes. If \p md_alg is not
+ * #MBEDTLS_MD_NONE, it must be a readable buffer of length
+ * the size of the hash corresponding to \p md_alg.
+ * \param sig The buffer to hold the signature. This must be a writable
+ * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
*
* \return \c 0 if the signing operation was successful.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -948,9 +1036,6 @@
* This is the generic wrapper for performing a PKCS#1
* verification using the mode from the context.
*
- * \note The \p sig buffer must be as large as the size
- * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
- *
* \note For PKCS#1 v2.1 encoding, see comments on
* mbedtls_rsa_rsassa_pss_verify() about \p md_alg and
* \p hash_id.
@@ -964,15 +1049,26 @@
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead
* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
*
- * \param ctx The RSA public key context.
- * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG context.
- * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ctx The initialized RSA public key context to use.
+ * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
+ * this is used for blinding and should be provided; see
+ * mbedtls_rsa_private() for more. Otherwise, it is ignored.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be
+ * \c NULL if \p f_rng is \c NULL or doesn't need a context.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
* \param md_alg The message-digest algorithm used to hash the original data.
* Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash The buffer holding the message digest.
- * \param sig The buffer holding the ciphertext.
+ * \param hashlen The length of the message digest.
+ * This is only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash The buffer holding the message digest or raw data.
+ * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
+ * buffer of length \p hashlen Bytes. If \p md_alg is not
+ * #MBEDTLS_MD_NONE, it must be a readable buffer of length
+ * the size of the hash corresponding to \p md_alg.
+ * \param sig The buffer holding the signature. This must be a readable
+ * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
*
* \return \c 0 if the verify operation was successful.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -990,9 +1086,6 @@
* \brief This function performs a PKCS#1 v1.5 verification
* operation (RSASSA-PKCS1-v1_5-VERIFY).
*
- * \note The \p sig buffer must be as large as the size
- * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
- *
* \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
* are likely to remove the \p mode argument and have it
@@ -1002,15 +1095,26 @@
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead
* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
*
- * \param ctx The RSA public key context.
- * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG context.
- * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ctx The initialized RSA public key context to use.
+ * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
+ * this is used for blinding and should be provided; see
+ * mbedtls_rsa_private() for more. Otherwise, it is ignored.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be
+ * \c NULL if \p f_rng is \c NULL or doesn't need a context.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
* \param md_alg The message-digest algorithm used to hash the original data.
* Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash The buffer holding the message digest.
- * \param sig The buffer holding the ciphertext.
+ * \param hashlen The length of the message digest.
+ * This is only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash The buffer holding the message digest or raw data.
+ * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
+ * buffer of length \p hashlen Bytes. If \p md_alg is not
+ * #MBEDTLS_MD_NONE, it must be a readable buffer of length
+ * the size of the hash corresponding to \p md_alg.
+ * \param sig The buffer holding the signature. This must be a readable
+ * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
*
* \return \c 0 if the verify operation was successful.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -1031,9 +1135,6 @@
* The hash function for the MGF mask generating function
* is that specified in the RSA context.
*
- * \note The \p sig buffer must be as large as the size
- * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
- *
* \note The \p hash_id in the RSA context is the one used for the
* verification. \p md_alg in the function call is the type of
* hash that is verified. According to <em>RFC-3447: Public-Key
@@ -1051,15 +1152,26 @@
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead
* return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
*
- * \param ctx The RSA public key context.
- * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG context.
- * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ctx The initialized RSA public key context to use.
+ * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
+ * this is used for blinding and should be provided; see
+ * mbedtls_rsa_private() for more. Otherwise, it is ignored.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be
+ * \c NULL if \p f_rng is \c NULL or doesn't need a context.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
* \param md_alg The message-digest algorithm used to hash the original data.
* Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash The buffer holding the message digest.
- * \param sig The buffer holding the ciphertext.
+ * \param hashlen The length of the message digest.
+ * This is only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash The buffer holding the message digest or raw data.
+ * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
+ * buffer of length \p hashlen Bytes. If \p md_alg is not
+ * #MBEDTLS_MD_NONE, it must be a readable buffer of length
+ * the size of the hash corresponding to \p md_alg.
+ * \param sig The buffer holding the signature. This must be a readable
+ * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
*
* \return \c 0 if the verify operation was successful.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -1085,19 +1197,29 @@
*
* \note The \p hash_id in the RSA context is ignored.
*
- * \param ctx The RSA public key context.
- * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG context.
- * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ctx The initialized RSA public key context to use.
+ * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
+ * this is used for blinding and should be provided; see
+ * mbedtls_rsa_private() for more. Otherwise, it is ignored.
+ * \param p_rng The RNG context to be passed to \p f_rng. This may be
+ * \c NULL if \p f_rng is \c NULL or doesn't need a context.
+ * \param mode The mode of operation. This must be either
+ * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
* \param md_alg The message-digest algorithm used to hash the original data.
* Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen The length of the message digest. Only used if \p md_alg is
- * #MBEDTLS_MD_NONE.
- * \param hash The buffer holding the message digest.
- * \param mgf1_hash_id The message digest used for mask generation.
- * \param expected_salt_len The length of the salt used in padding. Use
- * #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.
- * \param sig The buffer holding the ciphertext.
+ * \param hashlen The length of the message digest.
+ * This is only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash The buffer holding the message digest or raw data.
+ * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
+ * buffer of length \p hashlen Bytes. If \p md_alg is not
+ * #MBEDTLS_MD_NONE, it must be a readable buffer of length
+ * the size of the hash corresponding to \p md_alg.
+ * \param mgf1_hash_id The message digest used for mask generation.
+ * \param expected_salt_len The length of the salt used in padding. Use
+ * #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.
+ * \param sig The buffer holding the signature. This must be a readable
+ * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
+ * for an 2048-bit RSA modulus.
*
* \return \c 0 if the verify operation was successful.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -1116,8 +1238,8 @@
/**
* \brief This function copies the components of an RSA context.
*
- * \param dst The destination context.
- * \param src The source context.
+ * \param dst The destination context. This must be initialized.
+ * \param src The source context. This must be initialized.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure.
@@ -1127,10 +1249,14 @@
/**
* \brief This function frees the components of an RSA key.
*
- * \param ctx The RSA Context to free.
+ * \param ctx The RSA context to free. May be \c NULL, in which case
+ * this function is a no-op. If it is not \c NULL, it must
+ * point to an initialized RSA context.
*/
void mbedtls_rsa_free( mbedtls_rsa_context *ctx );
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief The RSA checkup routine.
*
@@ -1139,6 +1265,8 @@
*/
int mbedtls_rsa_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/sha1.h b/include/mbedtls/sha1.h
index bcaeab5..bb6ecf0 100644
--- a/include/mbedtls/sha1.h
+++ b/include/mbedtls/sha1.h
@@ -42,6 +42,7 @@
/* MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED is deprecated and should not be used. */
#define MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED -0x0035 /**< SHA-1 hardware accelerator failed */
+#define MBEDTLS_ERR_SHA1_BAD_INPUT_DATA -0x0073 /**< SHA-1 input data was malformed. */
#ifdef __cplusplus
extern "C" {
@@ -79,6 +80,7 @@
* stronger message digests instead.
*
* \param ctx The SHA-1 context to initialize.
+ * This must not be \c NULL.
*
*/
void mbedtls_sha1_init( mbedtls_sha1_context *ctx );
@@ -90,7 +92,10 @@
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
- * \param ctx The SHA-1 context to clear.
+ * \param ctx The SHA-1 context to clear. This may be \c NULL,
+ * in which case this function does nothing. If it is
+ * not \c NULL, it must point to an initialized
+ * SHA-1 context.
*
*/
void mbedtls_sha1_free( mbedtls_sha1_context *ctx );
@@ -102,8 +107,8 @@
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
- * \param dst The SHA-1 context to clone to.
- * \param src The SHA-1 context to clone from.
+ * \param dst The SHA-1 context to clone to. This must be initialized.
+ * \param src The SHA-1 context to clone from. This must be initialized.
*
*/
void mbedtls_sha1_clone( mbedtls_sha1_context *dst,
@@ -116,9 +121,10 @@
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
- * \param ctx The SHA-1 context to initialize.
+ * \param ctx The SHA-1 context to initialize. This must be initialized.
*
* \return \c 0 on success.
+ * \return A negative error code on failure.
*
*/
int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx );
@@ -131,11 +137,14 @@
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
- * \param ctx The SHA-1 context.
+ * \param ctx The SHA-1 context. This must be initialized
+ * and have a hash operation started.
* \param input The buffer holding the input data.
- * \param ilen The length of the input data.
+ * This must be a readable buffer of length \p ilen Bytes.
+ * \param ilen The length of the input data \p input in Bytes.
*
* \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx,
const unsigned char *input,
@@ -149,10 +158,13 @@
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
- * \param ctx The SHA-1 context.
- * \param output The SHA-1 checksum result.
+ * \param ctx The SHA-1 context to use. This must be initialized and
+ * have a hash operation started.
+ * \param output The SHA-1 checksum result. This must be a writable
+ * buffer of length \c 20 Bytes.
*
* \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx,
unsigned char output[20] );
@@ -164,10 +176,12 @@
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
- * \param ctx The SHA-1 context.
- * \param data The data block being processed.
+ * \param ctx The SHA-1 context to use. This must be initialized.
+ * \param data The data block being processed. This must be a
+ * readable buffer of length \c 64 Bytes.
*
* \return \c 0 on success.
+ * \return A negative error code on failure.
*
*/
int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx,
@@ -188,7 +202,7 @@
*
* \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0.
*
- * \param ctx The SHA-1 context to initialize.
+ * \param ctx The SHA-1 context to initialize. This must be initialized.
*
*/
MBEDTLS_DEPRECATED void mbedtls_sha1_starts( mbedtls_sha1_context *ctx );
@@ -203,9 +217,11 @@
*
* \deprecated Superseded by mbedtls_sha1_update_ret() in 2.7.0.
*
- * \param ctx The SHA-1 context.
+ * \param ctx The SHA-1 context. This must be initialized and
+ * have a hash operation started.
* \param input The buffer holding the input data.
- * \param ilen The length of the input data.
+ * This must be a readable buffer of length \p ilen Bytes.
+ * \param ilen The length of the input data \p input in Bytes.
*
*/
MBEDTLS_DEPRECATED void mbedtls_sha1_update( mbedtls_sha1_context *ctx,
@@ -222,9 +238,10 @@
*
* \deprecated Superseded by mbedtls_sha1_finish_ret() in 2.7.0.
*
- * \param ctx The SHA-1 context.
+ * \param ctx The SHA-1 context. This must be initialized and
+ * have a hash operation started.
* \param output The SHA-1 checksum result.
- *
+ * This must be a writable buffer of length \c 20 Bytes.
*/
MBEDTLS_DEPRECATED void mbedtls_sha1_finish( mbedtls_sha1_context *ctx,
unsigned char output[20] );
@@ -238,8 +255,9 @@
*
* \deprecated Superseded by mbedtls_internal_sha1_process() in 2.7.0.
*
- * \param ctx The SHA-1 context.
+ * \param ctx The SHA-1 context. This must be initialized.
* \param data The data block being processed.
+ * This must be a readable buffer of length \c 64 bytes.
*
*/
MBEDTLS_DEPRECATED void mbedtls_sha1_process( mbedtls_sha1_context *ctx,
@@ -262,10 +280,13 @@
* stronger message digests instead.
*
* \param input The buffer holding the input data.
- * \param ilen The length of the input data.
+ * This must be a readable buffer of length \p ilen Bytes.
+ * \param ilen The length of the input data \p input in Bytes.
* \param output The SHA-1 checksum result.
+ * This must be a writable buffer of length \c 20 Bytes.
*
* \return \c 0 on success.
+ * \return A negative error code on failure.
*
*/
int mbedtls_sha1_ret( const unsigned char *input,
@@ -294,8 +315,10 @@
* \deprecated Superseded by mbedtls_sha1_ret() in 2.7.0
*
* \param input The buffer holding the input data.
- * \param ilen The length of the input data.
- * \param output The SHA-1 checksum result.
+ * This must be a readable buffer of length \p ilen Bytes.
+ * \param ilen The length of the input data \p input in Bytes.
+ * \param output The SHA-1 checksum result. This must be a writable
+ * buffer of size \c 20 Bytes.
*
*/
MBEDTLS_DEPRECATED void mbedtls_sha1( const unsigned char *input,
@@ -305,6 +328,8 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief The SHA-1 checkup routine.
*
@@ -318,6 +343,8 @@
*/
int mbedtls_sha1_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/sha256.h b/include/mbedtls/sha256.h
index 47a31e8..d647398 100644
--- a/include/mbedtls/sha256.h
+++ b/include/mbedtls/sha256.h
@@ -38,6 +38,7 @@
/* MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED is deprecated and should not be used. */
#define MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED -0x0037 /**< SHA-256 hardware accelerator failed */
+#define MBEDTLS_ERR_SHA256_BAD_INPUT_DATA -0x0074 /**< SHA-256 input data was malformed. */
#ifdef __cplusplus
extern "C" {
@@ -71,22 +72,24 @@
/**
* \brief This function initializes a SHA-256 context.
*
- * \param ctx The SHA-256 context to initialize.
+ * \param ctx The SHA-256 context to initialize. This must not be \c NULL.
*/
void mbedtls_sha256_init( mbedtls_sha256_context *ctx );
/**
* \brief This function clears a SHA-256 context.
*
- * \param ctx The SHA-256 context to clear.
+ * \param ctx The SHA-256 context to clear. This may be \c NULL, in which
+ * case this function returns immediately. If it is not \c NULL,
+ * it must point to an initialized SHA-256 context.
*/
void mbedtls_sha256_free( mbedtls_sha256_context *ctx );
/**
* \brief This function clones the state of a SHA-256 context.
*
- * \param dst The destination context.
- * \param src The context to clone.
+ * \param dst The destination context. This must be initialized.
+ * \param src The context to clone. This must be initialized.
*/
void mbedtls_sha256_clone( mbedtls_sha256_context *dst,
const mbedtls_sha256_context *src );
@@ -95,11 +98,12 @@
* \brief This function starts a SHA-224 or SHA-256 checksum
* calculation.
*
- * \param ctx The context to initialize.
- * \param is224 Determines which function to use:
- * 0: Use SHA-256, or 1: Use SHA-224.
+ * \param ctx The context to use. This must be initialized.
+ * \param is224 This determines which function to use. This must be
+ * either \c 0 for SHA-256, or \c 1 for SHA-224.
*
* \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_sha256_starts_ret( mbedtls_sha256_context *ctx, int is224 );
@@ -107,11 +111,14 @@
* \brief This function feeds an input buffer into an ongoing
* SHA-256 checksum calculation.
*
- * \param ctx The SHA-256 context.
- * \param input The buffer holding the data.
- * \param ilen The length of the input data.
+ * \param ctx The SHA-256 context. This must be initialized
+ * and have a hash operation started.
+ * \param input The buffer holding the data. This must be a readable
+ * buffer of length \p ilen Bytes.
+ * \param ilen The length of the input data in Bytes.
*
* \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_sha256_update_ret( mbedtls_sha256_context *ctx,
const unsigned char *input,
@@ -121,10 +128,13 @@
* \brief This function finishes the SHA-256 operation, and writes
* the result to the output buffer.
*
- * \param ctx The SHA-256 context.
+ * \param ctx The SHA-256 context. This must be initialized
+ * and have a hash operation started.
* \param output The SHA-224 or SHA-256 checksum result.
+ * This must be a writable buffer of length \c 32 Bytes.
*
* \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_sha256_finish_ret( mbedtls_sha256_context *ctx,
unsigned char output[32] );
@@ -134,10 +144,12 @@
* the ongoing SHA-256 computation. This function is for
* internal use only.
*
- * \param ctx The SHA-256 context.
- * \param data The buffer holding one block of data.
+ * \param ctx The SHA-256 context. This must be initialized.
+ * \param data The buffer holding one block of data. This must
+ * be a readable buffer of length \c 64 Bytes.
*
* \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx,
const unsigned char data[64] );
@@ -152,12 +164,11 @@
* \brief This function starts a SHA-224 or SHA-256 checksum
* calculation.
*
- *
* \deprecated Superseded by mbedtls_sha256_starts_ret() in 2.7.0.
*
- * \param ctx The context to initialize.
- * \param is224 Determines which function to use:
- * 0: Use SHA-256, or 1: Use SHA-224.
+ * \param ctx The context to use. This must be initialized.
+ * \param is224 Determines which function to use. This must be
+ * either \c 0 for SHA-256, or \c 1 for SHA-224.
*/
MBEDTLS_DEPRECATED void mbedtls_sha256_starts( mbedtls_sha256_context *ctx,
int is224 );
@@ -168,9 +179,11 @@
*
* \deprecated Superseded by mbedtls_sha256_update_ret() in 2.7.0.
*
- * \param ctx The SHA-256 context to initialize.
- * \param input The buffer holding the data.
- * \param ilen The length of the input data.
+ * \param ctx The SHA-256 context to use. This must be
+ * initialized and have a hash operation started.
+ * \param input The buffer holding the data. This must be a readable
+ * buffer of length \p ilen Bytes.
+ * \param ilen The length of the input data in Bytes.
*/
MBEDTLS_DEPRECATED void mbedtls_sha256_update( mbedtls_sha256_context *ctx,
const unsigned char *input,
@@ -182,8 +195,10 @@
*
* \deprecated Superseded by mbedtls_sha256_finish_ret() in 2.7.0.
*
- * \param ctx The SHA-256 context.
- * \param output The SHA-224 or SHA-256 checksum result.
+ * \param ctx The SHA-256 context. This must be initialized and
+ * have a hash operation started.
+ * \param output The SHA-224 or SHA-256 checksum result. This must be
+ * a writable buffer of length \c 32 Bytes.
*/
MBEDTLS_DEPRECATED void mbedtls_sha256_finish( mbedtls_sha256_context *ctx,
unsigned char output[32] );
@@ -195,8 +210,9 @@
*
* \deprecated Superseded by mbedtls_internal_sha256_process() in 2.7.0.
*
- * \param ctx The SHA-256 context.
- * \param data The buffer holding one block of data.
+ * \param ctx The SHA-256 context. This must be initialized.
+ * \param data The buffer holding one block of data. This must be
+ * a readable buffer of size \c 64 Bytes.
*/
MBEDTLS_DEPRECATED void mbedtls_sha256_process( mbedtls_sha256_context *ctx,
const unsigned char data[64] );
@@ -214,11 +230,13 @@
* The SHA-256 result is calculated as
* output = SHA-256(input buffer).
*
- * \param input The buffer holding the input data.
- * \param ilen The length of the input data.
- * \param output The SHA-224 or SHA-256 checksum result.
- * \param is224 Determines which function to use:
- * 0: Use SHA-256, or 1: Use SHA-224.
+ * \param input The buffer holding the data. This must be a readable
+ * buffer of length \p ilen Bytes.
+ * \param ilen The length of the input data in Bytes.
+ * \param output The SHA-224 or SHA-256 checksum result. This must
+ * be a writable buffer of length \c 32 Bytes.
+ * \param is224 Determines which function to use. This must be
+ * either \c 0 for SHA-256, or \c 1 for SHA-224.
*/
int mbedtls_sha256_ret( const unsigned char *input,
size_t ilen,
@@ -244,11 +262,13 @@
*
* \deprecated Superseded by mbedtls_sha256_ret() in 2.7.0.
*
- * \param input The buffer holding the data.
- * \param ilen The length of the input data.
- * \param output The SHA-224 or SHA-256 checksum result.
- * \param is224 Determines which function to use:
- * 0: Use SHA-256, or 1: Use SHA-224.
+ * \param input The buffer holding the data. This must be a readable
+ * buffer of length \p ilen Bytes.
+ * \param ilen The length of the input data in Bytes.
+ * \param output The SHA-224 or SHA-256 checksum result. This must be
+ * a writable buffer of length \c 32 Bytes.
+ * \param is224 Determines which function to use. This must be either
+ * \c 0 for SHA-256, or \c 1 for SHA-224.
*/
MBEDTLS_DEPRECATED void mbedtls_sha256( const unsigned char *input,
size_t ilen,
@@ -258,6 +278,8 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief The SHA-224 and SHA-256 checkup routine.
*
@@ -266,6 +288,8 @@
*/
int mbedtls_sha256_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/sha512.h b/include/mbedtls/sha512.h
index 020f95d..c06ceed 100644
--- a/include/mbedtls/sha512.h
+++ b/include/mbedtls/sha512.h
@@ -37,6 +37,7 @@
/* MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED is deprecated and should not be used. */
#define MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED -0x0039 /**< SHA-512 hardware accelerator failed */
+#define MBEDTLS_ERR_SHA512_BAD_INPUT_DATA -0x0075 /**< SHA-512 input data was malformed. */
#ifdef __cplusplus
extern "C" {
@@ -70,22 +71,26 @@
/**
* \brief This function initializes a SHA-512 context.
*
- * \param ctx The SHA-512 context to initialize.
+ * \param ctx The SHA-512 context to initialize. This must
+ * not be \c NULL.
*/
void mbedtls_sha512_init( mbedtls_sha512_context *ctx );
/**
* \brief This function clears a SHA-512 context.
*
- * \param ctx The SHA-512 context to clear.
+ * \param ctx The SHA-512 context to clear. This may be \c NULL,
+ * in which case this function does nothing. If it
+ * is not \c NULL, it must point to an initialized
+ * SHA-512 context.
*/
void mbedtls_sha512_free( mbedtls_sha512_context *ctx );
/**
* \brief This function clones the state of a SHA-512 context.
*
- * \param dst The destination context.
- * \param src The context to clone.
+ * \param dst The destination context. This must be initialized.
+ * \param src The context to clone. This must be initialized.
*/
void mbedtls_sha512_clone( mbedtls_sha512_context *dst,
const mbedtls_sha512_context *src );
@@ -94,11 +99,12 @@
* \brief This function starts a SHA-384 or SHA-512 checksum
* calculation.
*
- * \param ctx The SHA-512 context to initialize.
- * \param is384 Determines which function to use:
- * 0: Use SHA-512, or 1: Use SHA-384.
+ * \param ctx The SHA-512 context to use. This must be initialized.
+ * \param is384 Determines which function to use. This must be
+ * either \c for SHA-512, or \c 1 for SHA-384.
*
* \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_sha512_starts_ret( mbedtls_sha512_context *ctx, int is384 );
@@ -106,11 +112,14 @@
* \brief This function feeds an input buffer into an ongoing
* SHA-512 checksum calculation.
*
- * \param ctx The SHA-512 context.
- * \param input The buffer holding the input data.
- * \param ilen The length of the input data.
+ * \param ctx The SHA-512 context. This must be initialized
+ * and have a hash operation started.
+ * \param input The buffer holding the input data. This must
+ * be a readable buffer of length \p ilen Bytes.
+ * \param ilen The length of the input data in Bytes.
*
* \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx,
const unsigned char *input,
@@ -121,10 +130,13 @@
* the result to the output buffer. This function is for
* internal use only.
*
- * \param ctx The SHA-512 context.
+ * \param ctx The SHA-512 context. This must be initialized
+ * and have a hash operation started.
* \param output The SHA-384 or SHA-512 checksum result.
+ * This must be a writable buffer of length \c 64 Bytes.
*
* \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,
unsigned char output[64] );
@@ -133,10 +145,12 @@
* \brief This function processes a single data block within
* the ongoing SHA-512 computation.
*
- * \param ctx The SHA-512 context.
- * \param data The buffer holding one block of data.
+ * \param ctx The SHA-512 context. This must be initialized.
+ * \param data The buffer holding one block of data. This
+ * must be a readable buffer of length \c 128 Bytes.
*
* \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
const unsigned char data[128] );
@@ -152,9 +166,9 @@
*
* \deprecated Superseded by mbedtls_sha512_starts_ret() in 2.7.0
*
- * \param ctx The SHA-512 context to initialize.
- * \param is384 Determines which function to use:
- * 0: Use SHA-512, or 1: Use SHA-384.
+ * \param ctx The SHA-512 context to use. This must be initialized.
+ * \param is384 Determines which function to use. This must be either
+ * \c 0 for SHA-512 or \c 1 for SHA-384.
*/
MBEDTLS_DEPRECATED void mbedtls_sha512_starts( mbedtls_sha512_context *ctx,
int is384 );
@@ -165,9 +179,11 @@
*
* \deprecated Superseded by mbedtls_sha512_update_ret() in 2.7.0.
*
- * \param ctx The SHA-512 context.
- * \param input The buffer holding the data.
- * \param ilen The length of the input data.
+ * \param ctx The SHA-512 context. This must be initialized
+ * and have a hash operation started.
+ * \param input The buffer holding the data. This must be a readable
+ * buffer of length \p ilen Bytes.
+ * \param ilen The length of the input data in Bytes.
*/
MBEDTLS_DEPRECATED void mbedtls_sha512_update( mbedtls_sha512_context *ctx,
const unsigned char *input,
@@ -179,8 +195,10 @@
*
* \deprecated Superseded by mbedtls_sha512_finish_ret() in 2.7.0.
*
- * \param ctx The SHA-512 context.
- * \param output The SHA-384 or SHA-512 checksum result.
+ * \param ctx The SHA-512 context. This must be initialized
+ * and have a hash operation started.
+ * \param output The SHA-384 or SHA-512 checksum result. This must
+ * be a writable buffer of size \c 64 Bytes.
*/
MBEDTLS_DEPRECATED void mbedtls_sha512_finish( mbedtls_sha512_context *ctx,
unsigned char output[64] );
@@ -192,8 +210,9 @@
*
* \deprecated Superseded by mbedtls_internal_sha512_process() in 2.7.0.
*
- * \param ctx The SHA-512 context.
- * \param data The buffer holding one block of data.
+ * \param ctx The SHA-512 context. This must be initialized.
+ * \param data The buffer holding one block of data. This must be
+ * a readable buffer of length \c 128 Bytes.
*/
MBEDTLS_DEPRECATED void mbedtls_sha512_process(
mbedtls_sha512_context *ctx,
@@ -212,13 +231,16 @@
* The SHA-512 result is calculated as
* output = SHA-512(input buffer).
*
- * \param input The buffer holding the input data.
- * \param ilen The length of the input data.
+ * \param input The buffer holding the input data. This must be
+ * a readable buffer of length \p ilen Bytes.
+ * \param ilen The length of the input data in Bytes.
* \param output The SHA-384 or SHA-512 checksum result.
- * \param is384 Determines which function to use:
- * 0: Use SHA-512, or 1: Use SHA-384.
+ * This must be a writable buffer of length \c 64 Bytes.
+ * \param is384 Determines which function to use. This must be either
+ * \c 0 for SHA-512, or \c 1 for SHA-384.
*
* \return \c 0 on success.
+ * \return A negative error code on failure.
*/
int mbedtls_sha512_ret( const unsigned char *input,
size_t ilen,
@@ -231,6 +253,7 @@
#else
#define MBEDTLS_DEPRECATED
#endif
+
/**
* \brief This function calculates the SHA-512 or SHA-384
* checksum of a buffer.
@@ -243,11 +266,13 @@
*
* \deprecated Superseded by mbedtls_sha512_ret() in 2.7.0
*
- * \param input The buffer holding the data.
- * \param ilen The length of the input data.
- * \param output The SHA-384 or SHA-512 checksum result.
- * \param is384 Determines which function to use:
- * 0: Use SHA-512, or 1: Use SHA-384.
+ * \param input The buffer holding the data. This must be a
+ * readable buffer of length \p ilen Bytes.
+ * \param ilen The length of the input data in Bytes.
+ * \param output The SHA-384 or SHA-512 checksum result. This must
+ * be a writable buffer of length \c 64 Bytes.
+ * \param is384 Determines which function to use. This must be either
+ * \c 0 for SHA-512, or \c 1 for SHA-384.
*/
MBEDTLS_DEPRECATED void mbedtls_sha512( const unsigned char *input,
size_t ilen,
@@ -256,6 +281,9 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief The SHA-384 or SHA-512 checkup routine.
*
@@ -263,6 +291,7 @@
* \return \c 1 on failure.
*/
int mbedtls_sha512_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus
}
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index f7c9d93..b793ac0 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -787,6 +787,25 @@
typedef void mbedtls_ssl_async_cancel_t( mbedtls_ssl_context *ssl );
#endif /* MBEDTLS_SSL_ASYNC_PRIVATE */
+#if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED) && \
+ !defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE)
+#define MBEDTLS_SSL_PEER_CERT_DIGEST_MAX_LEN 48
+#if defined(MBEDTLS_SHA256_C)
+#define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA256
+#define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN 32
+#elif defined(MBEDTLS_SHA512_C)
+#define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA384
+#define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN 48
+#elif defined(MBEDTLS_SHA1_C)
+#define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA1
+#define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN 20
+#else
+/* This is already checked in check_config.h, but be sure. */
+#error "Bad configuration - need SHA-1, SHA-256 or SHA-512 enabled to compute digest of peer CRT."
+#endif
+#endif /* MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED &&
+ !MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */
+
/*
* This structure is used for storing current session data.
*/
@@ -802,7 +821,15 @@
unsigned char master[48]; /*!< the master secret */
#if defined(MBEDTLS_X509_CRT_PARSE_C)
- mbedtls_x509_crt *peer_cert; /*!< peer X.509 cert chain */
+#if defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE)
+ mbedtls_x509_crt *peer_cert; /*!< peer X.509 cert chain */
+#else /* MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */
+ /*! The digest of the peer's end-CRT. This must be kept to detect CRT
+ * changes during renegotiation, mitigating the triple handshake attack. */
+ unsigned char *peer_cert_digest;
+ size_t peer_cert_digest_len;
+ mbedtls_md_type_t peer_cert_digest_type;
+#endif /* !MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */
#endif /* MBEDTLS_X509_CRT_PARSE_C */
uint32_t verify_result; /*!< verification result */
@@ -929,11 +956,11 @@
#if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
#if defined(MBEDTLS_USE_PSA_CRYPTO)
- psa_key_slot_t psk_opaque; /*!< PSA key slot holding opaque PSK.
- * This field should only be set via
- * mbedtls_ssl_conf_psk_opaque().
- * If either no PSK or a raw PSK have
- * been configured, this has value \c 0. */
+ psa_key_handle_t psk_opaque; /*!< PSA key slot holding opaque PSK.
+ * This field should only be set via
+ * mbedtls_ssl_conf_psk_opaque().
+ * If either no PSK or a raw PSK have
+ * been configured, this has value \c 0. */
#endif /* MBEDTLS_USE_PSA_CRYPTO */
unsigned char *psk; /*!< The raw pre-shared key. This field should
@@ -2055,7 +2082,7 @@
* provision more than one cert/key pair (eg one ECDSA, one
* RSA with SHA-256, one RSA with SHA-1). An adequate
* certificate will be selected according to the client's
- * advertised capabilities. In case mutliple certificates are
+ * advertised capabilities. In case multiple certificates are
* adequate, preference is given to the one set by the first
* call to this function, then second, etc.
*
@@ -2066,6 +2093,14 @@
* whether it matches those preferences - the server can then
* decide what it wants to do with it.
*
+ * \note The provided \p pk_key needs to match the public key in the
+ * first certificate in \p own_cert, or all handshakes using
+ * that certificate will fail. It is your responsibility
+ * to ensure that; this function will not perform any check.
+ * You may use mbedtls_pk_check_pair() in order to perform
+ * this check yourself, but be aware that this function can
+ * be computationally expensive on some key types.
+ *
* \param conf SSL configuration
* \param own_cert own public certificate chain
* \param pk_key own private key
@@ -2129,7 +2164,7 @@
* \param psk The identifier of the key slot holding the PSK.
* Until \p conf is destroyed or this function is successfully
* called again, the key slot \p psk must be populated with a
- * key of type #PSA_ALG_CATEGORY_KEY_DERIVATION whose policy
+ * key of type PSA_ALG_CATEGORY_KEY_DERIVATION whose policy
* allows its use for the key derivation algorithm applied
* in the handshake.
* \param psk_identity The pointer to the pre-shared key identity.
@@ -2144,7 +2179,7 @@
* \return An \c MBEDTLS_ERR_SSL_XXX error code on failure.
*/
int mbedtls_ssl_conf_psk_opaque( mbedtls_ssl_config *conf,
- psa_key_slot_t psk,
+ psa_key_handle_t psk,
const unsigned char *psk_identity,
size_t psk_identity_len );
#endif /* MBEDTLS_USE_PSA_CRYPTO */
@@ -2176,7 +2211,7 @@
* \param psk The identifier of the key slot holding the PSK.
* For the duration of the current handshake, the key slot
* must be populated with a key of type
- * #PSA_ALG_CATEGORY_KEY_DERIVATION whose policy allows its
+ * PSA_ALG_CATEGORY_KEY_DERIVATION whose policy allows its
* use for the key derivation algorithm
* applied in the handshake.
*
@@ -2184,7 +2219,7 @@
* \return An \c MBEDTLS_ERR_SSL_XXX error code on failure.
*/
int mbedtls_ssl_set_hs_psk_opaque( mbedtls_ssl_context *ssl,
- psa_key_slot_t psk );
+ psa_key_handle_t psk );
#endif /* MBEDTLS_USE_PSA_CRYPTO */
/**
@@ -2964,18 +2999,34 @@
#if defined(MBEDTLS_X509_CRT_PARSE_C)
/**
- * \brief Return the peer certificate from the current connection
+ * \brief Return the peer certificate from the current connection.
*
- * Note: Can be NULL in case no certificate was sent during
- * the handshake. Different calls for the same connection can
- * return the same or different pointers for the same
- * certificate and even a different certificate altogether.
- * The peer cert CAN change in a single connection if
- * renegotiation is performed.
+ * \param ssl The SSL context to use. This must be initialized and setup.
*
- * \param ssl SSL context
+ * \return The current peer certificate, if available.
+ * The returned certificate is owned by the SSL context and
+ * is valid only until the next call to the SSL API.
+ * \return \c NULL if no peer certificate is available. This might
+ * be because the chosen ciphersuite doesn't use CRTs
+ * (PSK-based ciphersuites, for example), or because
+ * #MBEDTLS_SSL_KEEP_PEER_CERTIFICATE has been disabled,
+ * allowing the stack to free the peer's CRT to save memory.
*
- * \return the current peer certificate
+ * \note For one-time inspection of the peer's certificate during
+ * the handshake, consider registering an X.509 CRT verification
+ * callback through mbedtls_ssl_conf_verify() instead of calling
+ * this function. Using mbedtls_ssl_conf_verify() also comes at
+ * the benefit of allowing you to influence the verification
+ * process, for example by masking expected and tolerated
+ * verification failures.
+ *
+ * \warning You must not use the pointer returned by this function
+ * after any further call to the SSL API, including
+ * mbedtls_ssl_read() and mbedtls_ssl_write(); this is
+ * because the pointer might change during renegotiation,
+ * which happens transparently to the user.
+ * If you want to use the certificate across API calls,
+ * you must make a copy.
*/
const mbedtls_x509_crt *mbedtls_ssl_get_peer_cert( const mbedtls_ssl_context *ssl );
#endif /* MBEDTLS_X509_CRT_PARSE_C */
@@ -3292,7 +3343,7 @@
* mbedtls_ssl_config_defaults() or mbedtls_ssl_config_free().
*
* \note You need to call mbedtls_ssl_config_defaults() unless you
- * manually set all of the relevent fields yourself.
+ * manually set all of the relevant fields yourself.
*
* \param conf SSL configuration context
*/
diff --git a/include/mbedtls/ssl_cache.h b/include/mbedtls/ssl_cache.h
index ec081e6..84254d3 100644
--- a/include/mbedtls/ssl_cache.h
+++ b/include/mbedtls/ssl_cache.h
@@ -24,6 +24,12 @@
#ifndef MBEDTLS_SSL_CACHE_H
#define MBEDTLS_SSL_CACHE_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "ssl.h"
#if defined(MBEDTLS_THREADING_C)
@@ -64,7 +70,8 @@
mbedtls_time_t timestamp; /*!< entry timestamp */
#endif
mbedtls_ssl_session session; /*!< entry session */
-#if defined(MBEDTLS_X509_CRT_PARSE_C)
+#if defined(MBEDTLS_X509_CRT_PARSE_C) && \
+ defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE)
mbedtls_x509_buf peer_cert; /*!< entry peer_cert */
#endif
mbedtls_ssl_cache_entry *next; /*!< chain pointer */
diff --git a/include/mbedtls/ssl_ciphersuites.h b/include/mbedtls/ssl_ciphersuites.h
index cda8b48..7126783 100644
--- a/include/mbedtls/ssl_ciphersuites.h
+++ b/include/mbedtls/ssl_ciphersuites.h
@@ -24,6 +24,12 @@
#ifndef MBEDTLS_SSL_CIPHERSUITES_H
#define MBEDTLS_SSL_CIPHERSUITES_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "pk.h"
#include "cipher.h"
#include "md.h"
@@ -480,6 +486,24 @@
}
}
+static inline int mbedtls_ssl_ciphersuite_uses_srv_cert( const mbedtls_ssl_ciphersuite_t *info )
+{
+ switch( info->key_exchange )
+ {
+ case MBEDTLS_KEY_EXCHANGE_RSA:
+ case MBEDTLS_KEY_EXCHANGE_RSA_PSK:
+ case MBEDTLS_KEY_EXCHANGE_DHE_RSA:
+ case MBEDTLS_KEY_EXCHANGE_ECDH_RSA:
+ case MBEDTLS_KEY_EXCHANGE_ECDHE_RSA:
+ case MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA:
+ case MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA:
+ return( 1 );
+
+ default:
+ return( 0 );
+ }
+}
+
#if defined(MBEDTLS_KEY_EXCHANGE__SOME__DHE_ENABLED)
static inline int mbedtls_ssl_ciphersuite_uses_dhe( const mbedtls_ssl_ciphersuite_t *info )
{
diff --git a/include/mbedtls/ssl_cookie.h b/include/mbedtls/ssl_cookie.h
index 6a0ad4f..e34760a 100644
--- a/include/mbedtls/ssl_cookie.h
+++ b/include/mbedtls/ssl_cookie.h
@@ -24,6 +24,12 @@
#ifndef MBEDTLS_SSL_COOKIE_H
#define MBEDTLS_SSL_COOKIE_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "ssl.h"
#if defined(MBEDTLS_THREADING_C)
diff --git a/include/mbedtls/ssl_internal.h b/include/mbedtls/ssl_internal.h
index 318d13f..5dde239 100644
--- a/include/mbedtls/ssl_internal.h
+++ b/include/mbedtls/ssl_internal.h
@@ -24,9 +24,19 @@
#ifndef MBEDTLS_SSL_INTERNAL_H
#define MBEDTLS_SSL_INTERNAL_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#include "ssl.h"
#include "cipher.h"
+#if defined(MBEDTLS_USE_PSA_CRYPTO)
+#include "psa/crypto.h"
+#endif
+
#if defined(MBEDTLS_MD5_C)
#include "md5.h"
#endif
@@ -47,6 +57,11 @@
#include "ecjpake.h"
#endif
+#if defined(MBEDTLS_USE_PSA_CRYPTO)
+#include "psa/crypto.h"
+#include "psa_util.h"
+#endif /* MBEDTLS_USE_PSA_CRYPTO */
+
#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
!defined(inline) && !defined(__cplusplus)
#define inline __inline
@@ -270,7 +285,15 @@
#endif
#if defined(MBEDTLS_ECDH_C)
mbedtls_ecdh_context ecdh_ctx; /*!< ECDH key exchange */
-#endif
+
+#if defined(MBEDTLS_USE_PSA_CRYPTO)
+ psa_ecc_curve_t ecdh_psa_curve;
+ psa_key_handle_t ecdh_psa_privkey;
+ unsigned char ecdh_psa_peerkey[MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH];
+ size_t ecdh_psa_peerkey_len;
+#endif /* MBEDTLS_USE_PSA_CRYPTO */
+#endif /* MBEDTLS_ECDH_C */
+
#if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
mbedtls_ecjpake_context ecjpake_ctx; /*!< EC J-PAKE key exchange */
#if defined(MBEDTLS_SSL_CLI_C)
@@ -284,7 +307,7 @@
#endif
#if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
#if defined(MBEDTLS_USE_PSA_CRYPTO)
- psa_key_slot_t psk_opaque; /*!< Opaque PSK from the callback */
+ psa_key_handle_t psk_opaque; /*!< Opaque PSK from the callback */
#endif /* MBEDTLS_USE_PSA_CRYPTO */
unsigned char *psk; /*!< PSK from the callback */
size_t psk_len; /*!< Length of PSK from callback */
@@ -308,8 +331,13 @@
ssl_ecrs_cke_ecdh_calc_secret, /*!< ClientKeyExchange: ECDH step 2 */
ssl_ecrs_crt_vrfy_sign, /*!< CertificateVerify: pk_sign() */
} ecrs_state; /*!< current (or last) operation */
+ mbedtls_x509_crt *ecrs_peer_cert; /*!< The peer's CRT chain. */
size_t ecrs_n; /*!< place for saving a length */
#endif
+#if defined(MBEDTLS_X509_CRT_PARSE_C) && \
+ !defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE)
+ mbedtls_pk_context peer_pubkey; /*!< The public key from the peer. */
+#endif /* MBEDTLS_X509_CRT_PARSE_C && !MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */
#if defined(MBEDTLS_SSL_PROTO_DTLS)
unsigned int out_msg_seq; /*!< Outgoing handshake sequence number */
unsigned int in_msg_seq; /*!< Incoming handshake sequence number */
@@ -370,11 +398,19 @@
#endif
#if defined(MBEDTLS_SSL_PROTO_TLS1_2)
#if defined(MBEDTLS_SHA256_C)
+#if defined(MBEDTLS_USE_PSA_CRYPTO)
+ psa_hash_operation_t fin_sha256_psa;
+#else
mbedtls_sha256_context fin_sha256;
#endif
+#endif
#if defined(MBEDTLS_SHA512_C)
+#if defined(MBEDTLS_USE_PSA_CRYPTO)
+ psa_hash_operation_t fin_sha384_psa;
+#else
mbedtls_sha512_context fin_sha512;
#endif
+#endif
#endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
void (*update_checksum)(mbedtls_ssl_context *, const unsigned char *, size_t);
@@ -735,6 +771,9 @@
void mbedtls_ssl_dtls_replay_update( mbedtls_ssl_context *ssl );
#endif
+int mbedtls_ssl_session_copy( mbedtls_ssl_session *dst,
+ const mbedtls_ssl_session *src );
+
/* constant-time buffer comparison */
static inline int mbedtls_ssl_safer_memcmp( const void *a, const void *b, size_t n )
{
@@ -765,6 +804,7 @@
#if defined(MBEDTLS_SSL_PROTO_TLS1) || defined(MBEDTLS_SSL_PROTO_TLS1_1) || \
defined(MBEDTLS_SSL_PROTO_TLS1_2)
+/* The hash buffer must have at least MBEDTLS_MD_MAX_SIZE bytes of length. */
int mbedtls_ssl_get_key_exchange_md_tls1_2( mbedtls_ssl_context *ssl,
unsigned char *hash, size_t *hashlen,
unsigned char *data, size_t data_len,
diff --git a/include/mbedtls/ssl_ticket.h b/include/mbedtls/ssl_ticket.h
index b2686df..774a007 100644
--- a/include/mbedtls/ssl_ticket.h
+++ b/include/mbedtls/ssl_ticket.h
@@ -24,6 +24,12 @@
#ifndef MBEDTLS_SSL_TICKET_H
#define MBEDTLS_SSL_TICKET_H
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
/*
* This implementation of the session ticket callbacks includes key
* management, rotating the keys periodically in order to preserve forward
@@ -111,14 +117,14 @@
/**
* \brief Implementation of the ticket write callback
*
- * \note See \c mbedlts_ssl_ticket_write_t for description
+ * \note See \c mbedtls_ssl_ticket_write_t for description
*/
mbedtls_ssl_ticket_write_t mbedtls_ssl_ticket_write;
/**
* \brief Implementation of the ticket parse callback
*
- * \note See \c mbedlts_ssl_ticket_parse_t for description
+ * \note See \c mbedtls_ssl_ticket_parse_t for description
*/
mbedtls_ssl_ticket_parse_t mbedtls_ssl_ticket_parse;
diff --git a/include/mbedtls/version.h b/include/mbedtls/version.h
index 492fde3..79b42b2 100644
--- a/include/mbedtls/version.h
+++ b/include/mbedtls/version.h
@@ -39,7 +39,7 @@
* Major, Minor, Patchlevel
*/
#define MBEDTLS_VERSION_MAJOR 2
-#define MBEDTLS_VERSION_MINOR 14
+#define MBEDTLS_VERSION_MINOR 17
#define MBEDTLS_VERSION_PATCH 0
/**
@@ -47,9 +47,9 @@
* MMNNPP00
* Major version | Minor version | Patch version
*/
-#define MBEDTLS_VERSION_NUMBER 0x020E0000
-#define MBEDTLS_VERSION_STRING "2.14.0"
-#define MBEDTLS_VERSION_STRING_FULL "mbed TLS 2.14.0"
+#define MBEDTLS_VERSION_NUMBER 0x02110000
+#define MBEDTLS_VERSION_STRING "2.17.0"
+#define MBEDTLS_VERSION_STRING_FULL "mbed TLS 2.17.0"
#if defined(MBEDTLS_VERSION_C)
diff --git a/include/mbedtls/x509.h b/include/mbedtls/x509.h
index d6db9c6..b63e864 100644
--- a/include/mbedtls/x509.h
+++ b/include/mbedtls/x509.h
@@ -77,7 +77,7 @@
#define MBEDTLS_ERR_X509_ALLOC_FAILED -0x2880 /**< Allocation of memory failed. */
#define MBEDTLS_ERR_X509_FILE_IO_ERROR -0x2900 /**< Read/write of file failed. */
#define MBEDTLS_ERR_X509_BUFFER_TOO_SMALL -0x2980 /**< Destination buffer is too small. */
-#define MBEDTLS_ERR_X509_FATAL_ERROR -0x3000 /**< A fatal error occured, eg the chain is too long or the vrfy callback failed. */
+#define MBEDTLS_ERR_X509_FATAL_ERROR -0x3000 /**< A fatal error occurred, eg the chain is too long or the vrfy callback failed. */
/* \} name */
/**
@@ -142,24 +142,26 @@
*
* Comments refer to the status for using certificates. Status can be
* different for writing certificates or reading CRLs or CSRs.
+ *
+ * Those are defined in oid.h as oid.c needs them in a data structure. Since
+ * these were previously defined here, let's have aliases for compatibility.
*/
-#define MBEDTLS_X509_EXT_AUTHORITY_KEY_IDENTIFIER (1 << 0)
-#define MBEDTLS_X509_EXT_SUBJECT_KEY_IDENTIFIER (1 << 1)
-#define MBEDTLS_X509_EXT_KEY_USAGE (1 << 2)
-#define MBEDTLS_X509_EXT_CERTIFICATE_POLICIES (1 << 3)
-#define MBEDTLS_X509_EXT_POLICY_MAPPINGS (1 << 4)
-#define MBEDTLS_X509_EXT_SUBJECT_ALT_NAME (1 << 5) /* Supported (DNS) */
-#define MBEDTLS_X509_EXT_ISSUER_ALT_NAME (1 << 6)
-#define MBEDTLS_X509_EXT_SUBJECT_DIRECTORY_ATTRS (1 << 7)
-#define MBEDTLS_X509_EXT_BASIC_CONSTRAINTS (1 << 8) /* Supported */
-#define MBEDTLS_X509_EXT_NAME_CONSTRAINTS (1 << 9)
-#define MBEDTLS_X509_EXT_POLICY_CONSTRAINTS (1 << 10)
-#define MBEDTLS_X509_EXT_EXTENDED_KEY_USAGE (1 << 11)
-#define MBEDTLS_X509_EXT_CRL_DISTRIBUTION_POINTS (1 << 12)
-#define MBEDTLS_X509_EXT_INIHIBIT_ANYPOLICY (1 << 13)
-#define MBEDTLS_X509_EXT_FRESHEST_CRL (1 << 14)
-
-#define MBEDTLS_X509_EXT_NS_CERT_TYPE (1 << 16)
+#define MBEDTLS_X509_EXT_AUTHORITY_KEY_IDENTIFIER MBEDTLS_OID_X509_EXT_AUTHORITY_KEY_IDENTIFIER
+#define MBEDTLS_X509_EXT_SUBJECT_KEY_IDENTIFIER MBEDTLS_OID_X509_EXT_SUBJECT_KEY_IDENTIFIER
+#define MBEDTLS_X509_EXT_KEY_USAGE MBEDTLS_OID_X509_EXT_KEY_USAGE
+#define MBEDTLS_X509_EXT_CERTIFICATE_POLICIES MBEDTLS_OID_X509_EXT_CERTIFICATE_POLICIES
+#define MBEDTLS_X509_EXT_POLICY_MAPPINGS MBEDTLS_OID_X509_EXT_POLICY_MAPPINGS
+#define MBEDTLS_X509_EXT_SUBJECT_ALT_NAME MBEDTLS_OID_X509_EXT_SUBJECT_ALT_NAME /* Supported (DNS) */
+#define MBEDTLS_X509_EXT_ISSUER_ALT_NAME MBEDTLS_OID_X509_EXT_ISSUER_ALT_NAME
+#define MBEDTLS_X509_EXT_SUBJECT_DIRECTORY_ATTRS MBEDTLS_OID_X509_EXT_SUBJECT_DIRECTORY_ATTRS
+#define MBEDTLS_X509_EXT_BASIC_CONSTRAINTS MBEDTLS_OID_X509_EXT_BASIC_CONSTRAINTS /* Supported */
+#define MBEDTLS_X509_EXT_NAME_CONSTRAINTS MBEDTLS_OID_X509_EXT_NAME_CONSTRAINTS
+#define MBEDTLS_X509_EXT_POLICY_CONSTRAINTS MBEDTLS_OID_X509_EXT_POLICY_CONSTRAINTS
+#define MBEDTLS_X509_EXT_EXTENDED_KEY_USAGE MBEDTLS_OID_X509_EXT_EXTENDED_KEY_USAGE
+#define MBEDTLS_X509_EXT_CRL_DISTRIBUTION_POINTS MBEDTLS_OID_X509_EXT_CRL_DISTRIBUTION_POINTS
+#define MBEDTLS_X509_EXT_INIHIBIT_ANYPOLICY MBEDTLS_OID_X509_EXT_INIHIBIT_ANYPOLICY
+#define MBEDTLS_X509_EXT_FRESHEST_CRL MBEDTLS_OID_X509_EXT_FRESHEST_CRL
+#define MBEDTLS_X509_EXT_NS_CERT_TYPE MBEDTLS_OID_X509_EXT_NS_CERT_TYPE
/*
* Storage format identifiers
@@ -250,7 +252,7 @@
*
* \param to mbedtls_x509_time to check
*
- * \return 1 if the given time is in the past or an error occured,
+ * \return 1 if the given time is in the past or an error occurred,
* 0 otherwise.
*/
int mbedtls_x509_time_is_past( const mbedtls_x509_time *to );
@@ -264,11 +266,13 @@
*
* \param from mbedtls_x509_time to check
*
- * \return 1 if the given time is in the future or an error occured,
+ * \return 1 if the given time is in the future or an error occurred,
* 0 otherwise.
*/
int mbedtls_x509_time_is_future( const mbedtls_x509_time *from );
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief Checkup routine
*
@@ -276,6 +280,8 @@
*/
int mbedtls_x509_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
/*
* Internal module functions. You probably do not want to use these unless you
* know you do.
diff --git a/include/mbedtls/x509_crl.h b/include/mbedtls/x509_crl.h
index 08a4283..fa838d6 100644
--- a/include/mbedtls/x509_crl.h
+++ b/include/mbedtls/x509_crl.h
@@ -111,7 +111,7 @@
/**
* \brief Parse one or more CRLs and append them to the chained list
*
- * \note Mutliple CRLs are accepted only if using PEM format
+ * \note Multiple CRLs are accepted only if using PEM format
*
* \param chain points to the start of the chain
* \param buf buffer holding the CRL data in PEM or DER format
@@ -126,7 +126,7 @@
/**
* \brief Load one or more CRLs and append them to the chained list
*
- * \note Mutliple CRLs are accepted only if using PEM format
+ * \note Multiple CRLs are accepted only if using PEM format
*
* \param chain points to the start of the chain
* \param path filename to read the CRLs from (in PEM or DER encoding)
diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h
index afeefca..b3f27be 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -52,6 +52,8 @@
*/
typedef struct mbedtls_x509_crt
{
+ int own_buffer; /**< Indicates if \c raw is owned
+ * by the structure or not. */
mbedtls_x509_buf raw; /**< The raw certificate data (DER). */
mbedtls_x509_buf tbs; /**< The raw certificate body (DER). The part that is To Be Signed. */
@@ -68,6 +70,7 @@
mbedtls_x509_time valid_from; /**< Start time of certificate validity. */
mbedtls_x509_time valid_to; /**< End time of certificate validity. */
+ mbedtls_x509_buf pk_raw;
mbedtls_pk_context pk; /**< Container for the public key context. */
mbedtls_x509_buf issuer_id; /**< Optional X.509 v2/v3 issuer unique identifier. */
@@ -220,31 +223,88 @@
/**
* \brief Parse a single DER formatted certificate and add it
- * to the chained list.
+ * to the end of the provided chained list.
*
- * \param chain points to the start of the chain
- * \param buf buffer holding the certificate DER data
- * \param buflen size of the buffer
+ * \param chain The pointer to the start of the CRT chain to attach to.
+ * When parsing the first CRT in a chain, this should point
+ * to an instance of ::mbedtls_x509_crt initialized through
+ * mbedtls_x509_crt_init().
+ * \param buf The buffer holding the DER encoded certificate.
+ * \param buflen The size in Bytes of \p buf.
*
- * \return 0 if successful, or a specific X509 or PEM error code
+ * \note This function makes an internal copy of the CRT buffer
+ * \p buf. In particular, \p buf may be destroyed or reused
+ * after this call returns. To avoid duplicating the CRT
+ * buffer (at the cost of stricter lifetime constraints),
+ * use mbedtls_x509_crt_parse_der_nocopy() instead.
+ *
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
*/
-int mbedtls_x509_crt_parse_der( mbedtls_x509_crt *chain, const unsigned char *buf,
- size_t buflen );
+int mbedtls_x509_crt_parse_der( mbedtls_x509_crt *chain,
+ const unsigned char *buf,
+ size_t buflen );
/**
- * \brief Parse one or more certificates and add them
- * to the chained list. Parses permissively. If some
- * certificates can be parsed, the result is the number
- * of failed certificates it encountered. If none complete
- * correctly, the first error is returned.
+ * \brief Parse a single DER formatted certificate and add it
+ * to the end of the provided chained list. This is a
+ * variant of mbedtls_x509_crt_parse_der() which takes
+ * temporary ownership of the CRT buffer until the CRT
+ * is destroyed.
*
- * \param chain points to the start of the chain
- * \param buf buffer holding the certificate data in PEM or DER format
- * \param buflen size of the buffer
- * (including the terminating null byte for PEM data)
+ * \param chain The pointer to the start of the CRT chain to attach to.
+ * When parsing the first CRT in a chain, this should point
+ * to an instance of ::mbedtls_x509_crt initialized through
+ * mbedtls_x509_crt_init().
+ * \param buf The address of the readable buffer holding the DER encoded
+ * certificate to use. On success, this buffer must be
+ * retained and not be changed for the liftetime of the
+ * CRT chain \p chain, that is, until \p chain is destroyed
+ * through a call to mbedtls_x509_crt_free().
+ * \param buflen The size in Bytes of \p buf.
*
- * \return 0 if all certificates parsed successfully, a positive number
- * if partly successful or a specific X509 or PEM error code
+ * \note This call is functionally equivalent to
+ * mbedtls_x509_crt_parse_der(), but it avoids creating a
+ * copy of the input buffer at the cost of stronger lifetime
+ * constraints. This is useful in constrained environments
+ * where duplication of the CRT cannot be tolerated.
+ *
+ * \return \c 0 if successful.
+ * \return A negative error code on failure.
+ */
+int mbedtls_x509_crt_parse_der_nocopy( mbedtls_x509_crt *chain,
+ const unsigned char *buf,
+ size_t buflen );
+
+/**
+ * \brief Parse one DER-encoded or one or more concatenated PEM-encoded
+ * certificates and add them to the chained list.
+ *
+ * For CRTs in PEM encoding, the function parses permissively:
+ * if at least one certificate can be parsed, the function
+ * returns the number of certificates for which parsing failed
+ * (hence \c 0 if all certificates were parsed successfully).
+ * If no certificate could be parsed, the function returns
+ * the first (negative) error encountered during parsing.
+ *
+ * PEM encoded certificates may be interleaved by other data
+ * such as human readable descriptions of their content, as
+ * long as the certificates are enclosed in the PEM specific
+ * '-----{BEGIN/END} CERTIFICATE-----' delimiters.
+ *
+ * \param chain The chain to which to add the parsed certificates.
+ * \param buf The buffer holding the certificate data in PEM or DER format.
+ * For certificates in PEM encoding, this may be a concatenation
+ * of multiple certificates; for DER encoding, the buffer must
+ * comprise exactly one certificate.
+ * \param buflen The size of \p buf, including the terminating \c NULL byte
+ * in case of PEM encoded data.
+ *
+ * \return \c 0 if all certificates were parsed successfully.
+ * \return The (positive) number of certificates that couldn't
+ * be parsed if parsing was partly successful (see above).
+ * \return A negative X509 or PEM error code otherwise.
+ *
*/
int mbedtls_x509_crt_parse( mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen );
diff --git a/include/mbedtls/x509_csr.h b/include/mbedtls/x509_csr.h
index 0c6ccad..a3c2804 100644
--- a/include/mbedtls/x509_csr.h
+++ b/include/mbedtls/x509_csr.h
@@ -205,6 +205,14 @@
* \param key_usage key usage flags to set
*
* \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
+ *
+ * \note The <code>decipherOnly</code> flag from the Key Usage
+ * extension is represented by bit 8 (i.e.
+ * <code>0x8000</code>), which cannot typically be represented
+ * in an unsigned char. Therefore, the flag
+ * <code>decipherOnly</code> (i.e.
+ * #MBEDTLS_X509_KU_DECIPHER_ONLY) cannot be set using this
+ * function.
*/
int mbedtls_x509write_csr_set_key_usage( mbedtls_x509write_csr *ctx, unsigned char key_usage );
diff --git a/include/mbedtls/xtea.h b/include/mbedtls/xtea.h
index 6430c13..b47f553 100644
--- a/include/mbedtls/xtea.h
+++ b/include/mbedtls/xtea.h
@@ -121,6 +121,8 @@
unsigned char *output);
#endif /* MBEDTLS_CIPHER_MODE_CBC */
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief Checkup routine
*
@@ -128,6 +130,8 @@
*/
int mbedtls_xtea_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index bdbbc1f..6a7bce8 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -193,7 +193,7 @@
* the policy has been saved to persistent storage. Implementations
* may defer saving the policy until the key material is created.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
* \retval #PSA_ERROR_NOT_SUPPORTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
@@ -285,7 +285,7 @@
* Success. The application can now use the value of `*handle`
* to access the newly allocated key slot.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p lifetime is invalid, for example #PSA_KEY_LIFETIME_VOLATILE.
* \retval #PSA_ERROR_INVALID_ARGUMENT
@@ -322,7 +322,7 @@
* to access the newly allocated key slot.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
* There is already a key with the identifier \p id in the storage
* area designated by \p lifetime.
* \retval #PSA_ERROR_INVALID_ARGUMENT
@@ -404,7 +404,7 @@
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The key slot is invalid,
* or the key data is not correctly formatted.
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
* There is already a key in the specified slot.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
@@ -476,7 +476,7 @@
*
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* The handle is to a key slot which does not contain key material yet.
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
@@ -655,7 +655,7 @@
*
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_NOT_SUPPORTED
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
@@ -723,7 +723,7 @@
*
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The key is neither a public key nor a key pair.
* \retval #PSA_ERROR_NOT_SUPPORTED
@@ -750,8 +750,9 @@
*
* Copy key material from one location to another.
*
- * This function is primarily useful to copy a key from one lifetime
- * to another. The target key retains its lifetime and location.
+ * This function is primarily useful to copy a key from one location
+ * to another, since it populates a key using the material from
+ * another key which may have a different lifetime.
*
* In an implementation where slots have different ownerships,
* this function may be used to share a key with a different party,
@@ -791,9 +792,9 @@
*
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
* \p target_handle already contains key material.
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \p source_handle does not contain key material.
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The policy constraints on the source, on the target and
@@ -956,6 +957,9 @@
* Success.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a hash algorithm.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (already set up and not
+ * subsequently completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
@@ -1291,7 +1295,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p handle is not compatible with \p alg.
@@ -1302,6 +1306,9 @@
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (already set up and not
+ * subsequently completed).
+ * \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.
@@ -1348,7 +1355,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \c key is not compatible with \c alg.
@@ -1359,6 +1366,9 @@
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (already set up and not
+ * subsequently completed).
+ * \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.
@@ -1677,7 +1687,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p handle is not compatible with \p alg.
@@ -1688,6 +1698,9 @@
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (already set up and not
+ * subsequently completed).
+ * \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.
@@ -1736,7 +1749,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p handle is not compatible with \p alg.
@@ -1747,6 +1760,9 @@
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (already set up and not
+ * subsequently completed).
+ * \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.
@@ -1964,7 +1980,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p handle is not compatible with \p alg.
@@ -2020,7 +2036,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_INVALID_SIGNATURE
* The ciphertext is not authentic.
* \retval #PSA_ERROR_NOT_PERMITTED
@@ -2861,7 +2877,7 @@
* \param output_length Number of bytes to output.
*
* \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_INSUFFICIENT_CAPACITY
+ * \retval #PSA_ERROR_INSUFFICIENT_DATA
* There were fewer than \p output_length bytes
* in the generator. Note that in this case, no
* output is written to the output buffer.
@@ -2968,7 +2984,7 @@
* Success.
* If the key is persistent, the key material and the key's metadata
* have been saved to persistent storage.
- * \retval #PSA_ERROR_INSUFFICIENT_CAPACITY
+ * \retval #PSA_ERROR_INSUFFICIENT_DATA
* There was not enough data to create the desired key.
* Note that in this case, no output is written to the output buffer.
* The generator's capacity is set to 0, thus subsequent calls to
@@ -2978,7 +2994,7 @@
* implementation in general or in this particular slot.
* \retval #PSA_ERROR_BAD_STATE
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
* There is already a key in the specified slot.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
@@ -3140,7 +3156,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \c step is not compatible with the generator's algorithm.
@@ -3201,7 +3217,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \c private_key is not compatible with \c alg,
@@ -3368,7 +3384,7 @@
* If the key is persistent, the key material and the key's metadata
* have been saved to persistent storage.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
* There is already a key in the specified slot.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
diff --git a/include/psa/crypto_accel_driver.h b/include/psa/crypto_accel_driver.h
index b752fed..4a540f0 100644
--- a/include/psa/crypto_accel_driver.h
+++ b/include/psa/crypto_accel_driver.h
@@ -38,12 +38,13 @@
extern "C" {
#endif
-/** \defgroup driver_digest Message Digests
+/** \defgroup driver_digest Hardware-Accelerated Message Digests
*
* Generation and authentication of Message Digests (aka hashes) must be done
* in parts using the following sequence:
* - `psa_drv_hash_setup_t`
* - `psa_drv_hash_update_t`
+ * - `psa_drv_hash_update_t`
* - ...
* - `psa_drv_hash_finish_t`
*
@@ -64,7 +65,7 @@
/** \brief The function prototype for the start operation of a hash (message
* digest) operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
* psa_drv_hash_<ALGO>_setup
@@ -81,7 +82,7 @@
/** \brief The function prototype for the update operation of a hash (message
* digest) operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
* psa_drv_hash_<ALGO>_update
@@ -99,10 +100,10 @@
const uint8_t *p_input,
size_t input_length);
-/** \brief The prototype for the finish operation of a hash (message digest)
- * operation
+/** \brief The function prototype for the finish operation of a hash (message
+ * digest) operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
* psa_drv_hash_<ALGO>_finish
@@ -130,7 +131,7 @@
/** \brief The function prototype for the abort operation of a hash (message
* digest) operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
* psa_drv_hash_<ALGO>_abort
@@ -144,39 +145,39 @@
/**@}*/
-/** \defgroup transparent_mac Transparent Message Authentication Code
+/** \defgroup accel_mac Hardware-Accelerated Message Authentication Code
* Generation and authentication of Message Authentication Codes (MACs) using
- * transparent keys can be done either as a single function call (via the
- * `psa_drv_mac_transparent_generate_t` or `psa_drv_mac_transparent_verify_t`
+ * cryptographic accelerators can be done either as a single function call (via the
+ * `psa_drv_accel_mac_generate_t` or `psa_drv_accel_mac_verify_t`
* functions), or in parts using the following sequence:
- * - `psa_drv_mac_transparent_setup_t`
- * - `psa_drv_mac_transparent_update_t`
- * - `psa_drv_mac_transparent_update_t`
+ * - `psa_drv_accel_mac_setup_t`
+ * - `psa_drv_accel_mac_update_t`
+ * - `psa_drv_accel_mac_update_t`
* - ...
- * - `psa_drv_mac_transparent_finish_t` or `psa_drv_mac_transparent_finish_verify_t`
+ * - `psa_drv_accel_mac_finish_t` or `psa_drv_accel_mac_finish_verify_t`
*
- * If a previously started Transparent MAC operation needs to be terminated, it
- * should be done so by the `psa_drv_mac_transparent_abort_t`. Failure to do so may
+ * If a previously started MAC operation needs to be terminated, it
+ * should be done so by the `psa_drv_accel_mac_abort_t`. Failure to do so may
* result in allocated resources not being freed or in other undefined
* behavior.
*
*/
/**@{*/
-/** \brief The hardware-specific transparent-key MAC context structure
+/** \brief The hardware-accelerator-specific MAC context structure
*
* The contents of this structure are implementation dependent and are
* therefore not described here.
*/
-typedef struct psa_drv_mac_transparent_context_s psa_drv_mac_transparent_context_t;
+typedef struct psa_drv_accel_mac_context_s psa_drv_accel_mac_context_t;
/** \brief The function prototype for the setup operation of a
- * transparent-key MAC operation
+ * hardware-accelerated MAC operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_setup
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_setup
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the underlying primitive, and `MAC_VARIANT`
* is the specific variant of a MAC operation (such as HMAC or CMAC)
@@ -190,17 +191,17 @@
* \retval PSA_SUCCESS
* Success.
*/
-typedef psa_status_t (*psa_drv_mac_transparent_setup_t)(psa_drv_mac_transparent_context_t *p_context,
- const uint8_t *p_key,
- size_t key_length);
+typedef psa_status_t (*psa_drv_accel_mac_setup_t)(psa_drv_accel_mac_context_t *p_context,
+ const uint8_t *p_key,
+ size_t key_length);
/** \brief The function prototype for the update operation of a
- * transparent-key MAC operation
+ * hardware-accelerated MAC operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_update
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_update
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT`
* is the specific variant of a MAC operation (such as HMAC or CMAC)
@@ -212,17 +213,17 @@
* to the MAC operation
* \param[in] input_length The size in bytes of the input message buffer
*/
-typedef psa_status_t (*psa_drv_mac_transparent_update_t)(psa_drv_mac_transparent_context_t *p_context,
- const uint8_t *p_input,
- size_t input_length);
+typedef psa_status_t (*psa_drv_accel_mac_update_t)(psa_drv_accel_mac_context_t *p_context,
+ const uint8_t *p_input,
+ size_t input_length);
/** \brief The function prototype for the finish operation of a
- * transparent-key MAC operation
+ * hardware-accelerated MAC operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_finish
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_finish
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
* the specific variant of a MAC operation (such as HMAC or CMAC)
@@ -237,17 +238,17 @@
* \retval PSA_SUCCESS
* Success.
*/
-typedef psa_status_t (*psa_drv_mac_transparent_finish_t)(psa_drv_mac_transparent_context_t *p_context,
- uint8_t *p_mac,
- size_t mac_length);
+typedef psa_status_t (*psa_drv_accel_mac_finish_t)(psa_drv_accel_mac_context_t *p_context,
+ uint8_t *p_mac,
+ size_t mac_length);
/** \brief The function prototype for the finish and verify operation of a
- * transparent-key MAC operation
+ * hardware-accelerated MAC operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_finish_verify
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_finish_verify
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
* the specific variant of a MAC operation (such as HMAC or CMAC)
@@ -263,17 +264,17 @@
* \retval PSA_SUCCESS
* The operation completed successfully and the comparison matched
*/
-typedef psa_status_t (*psa_drv_mac_transparent_finish_verify_t)(psa_drv_mac_transparent_context_t *p_context,
- const uint8_t *p_mac,
- size_t mac_length);
+typedef psa_status_t (*psa_drv_accel_mac_finish_verify_t)(psa_drv_accel_mac_context_t *p_context,
+ const uint8_t *p_mac,
+ size_t mac_length);
/** \brief The function prototype for the abort operation for a previously
- * started transparent-key MAC operation
+ * started hardware-accelerated MAC operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_abort
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_abort
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
* the specific variant of a MAC operation (such as HMAC or CMAC)
@@ -283,15 +284,15 @@
* aborted
*
*/
-typedef psa_status_t (*psa_drv_mac_transparent_abort_t)(psa_drv_mac_transparent_context_t *p_context);
+typedef psa_status_t (*psa_drv_accel_mac_abort_t)(psa_drv_accel_mac_context_t *p_context);
-/** \brief The function prototype for a one-shot operation of a transparent-key
- * MAC operation
+/** \brief The function prototype for the one-shot operation of a
+ * hardware-accelerated MAC operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
* the specific variant of a MAC operation (such as HMAC or CMAC)
@@ -306,21 +307,21 @@
* upon success
* \param[in] mac_length The length in bytes of the `p_mac` buffer
*/
-typedef psa_status_t (*psa_drv_mac_transparent_t)(const uint8_t *p_input,
- size_t input_length,
- const uint8_t *p_key,
- size_t key_length,
- psa_algorithm_t alg,
- uint8_t *p_mac,
- size_t mac_length);
+typedef psa_status_t (*psa_drv_accel_mac_t)(const uint8_t *p_input,
+ size_t input_length,
+ const uint8_t *p_key,
+ size_t key_length,
+ psa_algorithm_t alg,
+ uint8_t *p_mac,
+ size_t mac_length);
-/** \brief The function prototype for a one-shot operation of a transparent-key
- * MAC Verify operation
+/** \brief The function prototype for the one-shot hardware-accelerated MAC
+ * Verify operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_verify
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_verify
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
* the specific variant of a MAC operation (such as HMAC or CMAC)
@@ -337,51 +338,53 @@
* \retval PSA_SUCCESS
* The operation completed successfully and the comparison matched
*/
-typedef psa_status_t (*psa_drv_mac_transparent_verify_t)(const uint8_t *p_input,
- size_t input_length,
- const uint8_t *p_key,
- size_t key_length,
- psa_algorithm_t alg,
- const uint8_t *p_mac,
- size_t mac_length);
+typedef psa_status_t (*psa_drv_accel_mac_verify_t)(const uint8_t *p_input,
+ size_t input_length,
+ const uint8_t *p_key,
+ size_t key_length,
+ psa_algorithm_t alg,
+ const uint8_t *p_mac,
+ size_t mac_length);
/**@}*/
-/** \defgroup transparent_cipher Transparent Block Cipher
- * Encryption and Decryption using transparent keys in block modes other than
- * ECB must be done in multiple parts, using the following flow:
- * - `psa_drv_cipher_transparent_setup_t`
- * - `psa_drv_cipher_transparent_set_iv_t` (optional depending upon block mode)
- * - `psa_drv_cipher_transparent_update_t`
+/** \defgroup accel_cipher Hardware-Accelerated Block Ciphers
+ * Encryption and Decryption using hardware-acceleration in block modes other
+ * than ECB must be done in multiple parts, using the following flow:
+ * - `psa_drv_accel_ciphersetup_t`
+ * - `psa_drv_accel_cipher_set_iv_t` (optional depending upon block mode)
+ * - `psa_drv_accel_cipher_update_t`
+ * - `psa_drv_accel_cipher_update_t`
* - ...
- * - `psa_drv_cipher_transparent_finish_t`
-
- * If a previously started Transparent Cipher operation needs to be terminated,
- * it should be done so by the `psa_drv_cipher_transparent_abort_t`. Failure to do
- * so may result in allocated resources not being freed or in other undefined
- * behavior.
+ * - `psa_drv_accel_cipher_finish_t`
+ *
+ * If a previously started hardware-accelerated Cipher operation needs to be
+ * terminated, it should be done so by the `psa_drv_accel_cipher_abort_t`.
+ * Failure to do so may result in allocated resources not being freed or in
+ * other undefined behavior.
*/
/**@{*/
-/** \brief The hardware-specific transparent-key Cipher context structure
+/** \brief The hardware-accelerator-specific cipher context structure
*
* The contents of this structure are implementation dependent and are
* therefore not described here.
*/
-typedef struct psa_drv_cipher_transparent_context_s psa_drv_cipher_transparent_context_t;
+typedef struct psa_drv_accel_cipher_context_s psa_drv_accel_cipher_context_t;
-/** \brief The function prototype for the setup operation of transparent-key
- * block cipher operations.
- * Functions that implement the prototype should be named in the following
+/** \brief The function prototype for the setup operation of
+ * hardware-accelerated block cipher operations.
+ * Functions that implement this prototype should be named in the following
* conventions:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_setup_<CIPHER_NAME>_<MODE>
+ * psa_drv_accel_cipher_setup_<CIPHER_NAME>_<MODE>
* ~~~~~~~~~~~~~
* Where
* - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
* - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)
- * or for stream ciphers:
+ *
+ * For stream ciphers:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_setup_<CIPHER_NAME>
+ * psa_drv_accel_cipher_setup_<CIPHER_NAME>
* ~~~~~~~~~~~~~
* Where `CIPHER_NAME` is the name of a stream cipher (i.e. RC4)
*
@@ -395,17 +398,17 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_cipher_transparent_setup_t)(psa_drv_cipher_transparent_context_t *p_context,
- psa_encrypt_or_decrypt_t direction,
- const uint8_t *p_key_data,
- size_t key_data_size);
+typedef psa_status_t (*psa_drv_accel_cipher_setup_t)(psa_drv_accel_cipher_context_t *p_context,
+ psa_encrypt_or_decrypt_t direction,
+ const uint8_t *p_key_data,
+ size_t key_data_size);
/** \brief The function prototype for the set initialization vector operation
- * of transparent-key block cipher operations
- * Functions that implement the prototype should be named in the following
+ * of hardware-accelerated block cipher operations
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_set_iv_<CIPHER_NAME>_<MODE>
+ * psa_drv_accel_cipher_set_iv_<CIPHER_NAME>_<MODE>
* ~~~~~~~~~~~~~
* Where
* - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
@@ -418,17 +421,17 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_cipher_transparent_set_iv_t)(psa_drv_cipher_transparent_context_t *p_context,
- const uint8_t *p_iv,
- size_t iv_length);
+typedef psa_status_t (*psa_drv_accel_cipher_set_iv_t)(psa_drv_accel_cipher_context_t *p_context,
+ const uint8_t *p_iv,
+ size_t iv_length);
-/** \brief The function prototype for the update operation of transparent-key
- * block cipher operations.
+/** \brief The function prototype for the update operation of
+ * hardware-accelerated block cipher operations.
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_update_<CIPHER_NAME>_<MODE>
+ * psa_drv_accel_cipher_update_<CIPHER_NAME>_<MODE>
* ~~~~~~~~~~~~~
* Where
* - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
@@ -447,20 +450,20 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_cipher_transparent_update_t)(psa_drv_cipher_transparent_context_t *p_context,
- const uint8_t *p_input,
- size_t input_size,
- uint8_t *p_output,
- size_t output_size,
- size_t *p_output_length);
+typedef psa_status_t (*psa_drv_accel_cipher_update_t)(psa_drv_accel_cipher_context_t *p_context,
+ const uint8_t *p_input,
+ size_t input_size,
+ uint8_t *p_output,
+ size_t output_size,
+ size_t *p_output_length);
-/** \brief The function prototype for the finish operation of transparent-key
- * block cipher operations.
+/** \brief The function prototype for the finish operation of
+ * hardware-accelerated block cipher operations.
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_finish_<CIPHER_NAME>_<MODE>
+ * psa_drv_accel_cipher_finish_<CIPHER_NAME>_<MODE>
* ~~~~~~~~~~~~~
* Where
* - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
@@ -476,18 +479,18 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_cipher_transparent_finish_t)(psa_drv_cipher_transparent_context_t *p_context,
- uint8_t *p_output,
- size_t output_size,
- size_t *p_output_length);
+typedef psa_status_t (*psa_drv_accel_cipher_finish_t)(psa_drv_accel_cipher_context_t *p_context,
+ uint8_t *p_output,
+ size_t output_size,
+ size_t *p_output_length);
-/** \brief The function prototype for the abort operation of transparent-key
- * block cipher operations.
+/** \brief The function prototype for the abort operation of
+ * hardware-accelerated block cipher operations.
*
* Functions that implement the following prototype should be named in the
* following convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_abort_<CIPHER_NAME>_<MODE>
+ * psa_drv_accel_cipher_abort_<CIPHER_NAME>_<MODE>
* ~~~~~~~~~~~~~
* Where
* - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
@@ -498,27 +501,27 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_cipher_transparent_abort_t)(psa_drv_cipher_transparent_context_t *p_context);
+typedef psa_status_t (*psa_drv_accel_cipher_abort_t)(psa_drv_accel_cipher_context_t *p_context);
/**@}*/
-/** \defgroup aead_transparent AEAD Transparent
+/** \defgroup accel_aead Hardware-Accelerated Authenticated Encryption with Additional Data
*
- * Authenticated Encryption with Additional Data (AEAD) operations with
- * transparent keys must be done in one function call. While this creates a
- * burden for implementers as there must be sufficient space in memory for the
- * entire message, it prevents decrypted data from being made available before
- * the authentication operation is complete and the data is known to be
- * authentic.
+ * Hardware-accelerated Authenticated Encryption with Additional Data (AEAD)
+ * operations must be done in one function call. While this creates a burden
+ * for implementers as there must be sufficient space in memory for the entire
+ * message, it prevents decrypted data from being made available before the
+ * authentication operation is complete and the data is known to be authentic.
*/
/**@{*/
-/** Process an authenticated encryption operation using an opaque key.
+/** \brief The function prototype for the hardware-accelerated authenticated
+ * encryption operation.
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_aead_<ALGO>_encrypt
+ * psa_drv_accel_aead_<ALGO>_encrypt
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the AEAD algorithm
*
@@ -551,27 +554,28 @@
* the `ciphertext` buffer
*
* \retval #PSA_SUCCESS
-
- */
-typedef psa_status_t (*psa_drv_aead_transparent_encrypt_t)(const uint8_t *p_key,
- size_t key_length,
- psa_algorithm_t alg,
- const uint8_t *nonce,
- size_t nonce_length,
- const uint8_t *additional_data,
- size_t additional_data_length,
- const uint8_t *plaintext,
- size_t plaintext_length,
- uint8_t *ciphertext,
- size_t ciphertext_size,
- size_t *ciphertext_length);
-
-/** Process an authenticated decryption operation using an opaque key.
*
- * Functions that implement the prototype should be named in the following
+ */
+typedef psa_status_t (*psa_drv_accel_aead_encrypt_t)(const uint8_t *p_key,
+ size_t key_length,
+ psa_algorithm_t alg,
+ const uint8_t *nonce,
+ size_t nonce_length,
+ const uint8_t *additional_data,
+ size_t additional_data_length,
+ const uint8_t *plaintext,
+ size_t plaintext_length,
+ uint8_t *ciphertext,
+ size_t ciphertext_size,
+ size_t *ciphertext_length);
+
+/** \brief The function prototype for the hardware-accelerated authenticated
+ * decryption operation.
+ *
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_aead_<ALGO>_decrypt
+ * psa_drv_accel_aead_<ALGO>_decrypt
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the AEAD algorithm
* \param[in] p_key A pointer to the key material
@@ -604,41 +608,45 @@
* \retval #PSA_SUCCESS
* Success.
*/
-typedef psa_status_t (*psa_drv_aead_transparent_decrypt_t)(const uint8_t *p_key,
- size_t key_length,
- psa_algorithm_t alg,
- const uint8_t *nonce,
- size_t nonce_length,
- const uint8_t *additional_data,
- size_t additional_data_length,
- const uint8_t *ciphertext,
- size_t ciphertext_length,
- uint8_t *plaintext,
- size_t plaintext_size,
- size_t *plaintext_length);
+typedef psa_status_t (*psa_drv_accel_aead_decrypt_t)(const uint8_t *p_key,
+ size_t key_length,
+ psa_algorithm_t alg,
+ const uint8_t *nonce,
+ size_t nonce_length,
+ const uint8_t *additional_data,
+ size_t additional_data_length,
+ const uint8_t *ciphertext,
+ size_t ciphertext_length,
+ uint8_t *plaintext,
+ size_t plaintext_size,
+ size_t *plaintext_length);
/**@}*/
-/** \defgroup transparent_asymmetric Transparent Asymmetric Cryptography
+/** \defgroup accel_asymmetric Hardware-Accelerated Asymmetric Cryptography
*
* Since the amount of data that can (or should) be encrypted or signed using
- * asymmetric keys is limited by the key size, asymmetric key operations using
- * transparent keys must be done in single function calls.
+ * asymmetric keys is limited by the key size, hardware-accelerated asymmetric
+ * key operations must be done in single function calls.
*/
/**@{*/
/**
- * \brief A function that signs a hash or short message with a transparent
- * asymmetric private key
+ * \brief The function prototype for the hardware-accelerated asymmetric sign
+ * operation.
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_asymmetric_<ALGO>_sign
+ * psa_drv_accel_asymmetric_<ALGO>_sign
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the signing algorithm
*
+ * This function supports any asymmetric-key output from psa_export_key() as
+ * the buffer in \p p_key. Refer to the documentation of \ref
+ * psa_export_key() for the formats.
+ *
* \param[in] p_key A buffer containing the private key
* material
* \param[in] key_size The size in bytes of the `p_key` data
@@ -653,26 +661,32 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_asymmetric_transparent_sign_t)(const uint8_t *p_key,
- size_t key_size,
- psa_algorithm_t alg,
- const uint8_t *p_hash,
- size_t hash_length,
- uint8_t *p_signature,
- size_t signature_size,
- size_t *p_signature_length);
+typedef psa_status_t (*psa_drv_accel_asymmetric_sign_t)(const uint8_t *p_key,
+ size_t key_size,
+ psa_algorithm_t alg,
+ psa_key_type_t key_type,
+ const uint8_t *p_hash,
+ size_t hash_length,
+ uint8_t *p_signature,
+ size_t signature_size,
+ size_t *p_signature_length);
/**
- * \brief A function that verifies the signature a hash or short message using
- * a transparent asymmetric public key
+ * \brief The function prototype for the hardware-accelerated signature verify
+ * operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_asymmetric_<ALGO>_verify
+ * psa_drv_accel_asymmetric_<ALGO>_verify
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the signing algorithm
*
+ * This function supports any output from \ref psa_export_public_key() as the
+ * buffer in \p p_key. Refer to the documentation of \ref
+ * psa_export_public_key() for the format of public keys and to the
+ * documentation of \ref psa_export_key() for the format for other key types.
+ *
* \param[in] p_key A buffer containing the public key material
* \param[in] key_size The size in bytes of the `p_key` data
* \param[in] alg A signature algorithm that is compatible with
@@ -686,25 +700,31 @@
* \retval PSA_SUCCESS
* The signature is valid.
*/
-typedef psa_status_t (*psa_drv_asymmetric_transparent_verify_t)(const uint8_t *p_key,
- size_t key_size,
- psa_algorithm_t alg,
- const uint8_t *p_hash,
- size_t hash_length,
- const uint8_t *p_signature,
- size_t signature_length);
+typedef psa_status_t (*psa_drv_accel_asymmetric_verify_t)(const uint8_t *p_key,
+ size_t key_size,
+ psa_algorithm_t alg,
+ psa_key_type_t key_type,
+ const uint8_t *p_hash,
+ size_t hash_length,
+ const uint8_t *p_signature,
+ size_t signature_length);
/**
- * \brief A function that encrypts a short message with a transparent
- * asymmetric public key
+ * \brief The function prototype for the hardware-accelerated asymmetric
+ * encrypt operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_asymmetric_<ALGO>_encrypt
+ * psa_drv_accel_asymmetric_<ALGO>_encrypt
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the encryption algorithm
*
+ * This function supports any output from \ref psa_export_public_key() as the
+ * buffer in \p p_key. Refer to the documentation of \ref
+ * psa_export_public_key() for the format of public keys and to the
+ * documentation of \ref psa_export_key() for the format for other key types.
+ *
* \param[in] p_key A buffer containing the public key material
* \param[in] key_size The size in bytes of the `p_key` data
* \param[in] alg An asymmetric encryption algorithm that is
@@ -730,27 +750,33 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_asymmetric_transparent_encrypt_t)(const uint8_t *p_key,
- size_t key_size,
- psa_algorithm_t alg,
- const uint8_t *p_input,
- size_t input_length,
- const uint8_t *p_salt,
- size_t salt_length,
- uint8_t *p_output,
- size_t output_size,
- size_t *p_output_length);
+typedef psa_status_t (*psa_drv_accel_asymmetric_encrypt_t)(const uint8_t *p_key,
+ size_t key_size,
+ psa_algorithm_t alg,
+ psa_key_type_t key_type,
+ const uint8_t *p_input,
+ size_t input_length,
+ const uint8_t *p_salt,
+ size_t salt_length,
+ uint8_t *p_output,
+ size_t output_size,
+ size_t *p_output_length);
/**
- * \brief Decrypt a short message with a transparent asymmetric private key
+ * \brief The function prototype for the hardware=acce;erated asymmetric
+ * decrypt operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_asymmetric_<ALGO>_decrypt
+ * psa_drv_accel_asymmetric_<ALGO>_decrypt
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the encryption algorithm
*
+ * This function supports any asymmetric-key output from psa_export_key() as
+ * the buffer in \p p_key. Refer to the documentation of \ref
+ * psa_export_key() for the formats.
+ *
* \param[in] p_key A buffer containing the private key material
* \param[in] key_size The size in bytes of the `p_key` data
* \param[in] alg An asymmetric encryption algorithm that is
@@ -776,16 +802,17 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_asymmetric_transparent_decrypt_t)(const uint8_t *p_key,
- size_t key_size,
- psa_algorithm_t alg,
- const uint8_t *p_input,
- size_t input_length,
- const uint8_t *p_salt,
- size_t salt_length,
- uint8_t *p_output,
- size_t output_size,
- size_t *p_output_length);
+typedef psa_status_t (*psa_drv_accel_asymmetric_decrypt_t)(const uint8_t *p_key,
+ size_t key_size,
+ psa_algorithm_t alg,
+ psa_key_type_t key_type,
+ const uint8_t *p_input,
+ size_t input_length,
+ const uint8_t *p_salt,
+ size_t salt_length,
+ uint8_t *p_output,
+ size_t output_size,
+ size_t *p_output_length);
/**@}*/
diff --git a/include/psa/crypto_entropy_driver.h b/include/psa/crypto_entropy_driver.h
index f5e383e..f596b6b 100644
--- a/include/psa/crypto_entropy_driver.h
+++ b/include/psa/crypto_entropy_driver.h
@@ -40,10 +40,6 @@
*/
/**@{*/
-/** \brief A hardware-specific structure for a entropy providing hardware
- */
-typedef struct psa_drv_entropy_context_s psa_drv_entropy_context_t;
-
/** \brief Initialize an entropy driver
*
*
@@ -53,7 +49,7 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_entropy_init_t)(psa_drv_entropy_context_t *p_context);
+typedef psa_status_t (*psa_drv_entropy_init_t)(void *p_context);
/** \brief Get a specified number of bits from the entropy source
*
@@ -81,7 +77,7 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_entropy_get_bits_t)(psa_drv_entropy_context_t *p_context,
+typedef psa_status_t (*psa_drv_entropy_get_bits_t)(void *p_context,
uint8_t *p_buffer,
uint32_t buffer_size,
uint32_t *p_received_entropy_bits);
@@ -96,11 +92,12 @@
* If one of the functions is not implemented, it should be set to NULL.
*/
typedef struct {
+ /** The driver-specific size of the entropy context */
+ const size_t context_size;
/** Function that performs initialization for the entropy source */
- psa_drv_entropy_init_t *p_init;
- /** Function that performs the get_bits operation for the entropy source
- */
- psa_drv_entropy_get_bits_t *p_get_bits;
+ psa_drv_entropy_init_t p_init;
+ /** Function that performs the get_bits operation for the entropy source */
+ psa_drv_entropy_get_bits_t p_get_bits;
} psa_drv_entropy_t;
/**@}*/
diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index d14edd9..093355d 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -30,6 +30,8 @@
#ifndef PSA_CRYPTO_EXTRA_H
#define PSA_CRYPTO_EXTRA_H
+#include "mbedtls/platform_util.h"
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -37,6 +39,29 @@
/* UID for secure storage seed */
#define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52
+/*
+ * Deprecated PSA Crypto error code definitions
+ */
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define PSA_ERROR_UNKNOWN_ERROR \
+ MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_GENERIC_ERROR )
+#endif
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define PSA_ERROR_OCCUPIED_SLOT \
+ MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_ALREADY_EXISTS )
+#endif
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define PSA_ERROR_EMPTY_SLOT \
+ MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_DOES_NOT_EXIST )
+#endif
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define PSA_ERROR_INSUFFICIENT_CAPACITY \
+ MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_INSUFFICIENT_DATA )
+#endif
+
/**
* \brief Library deinitialization.
*
@@ -89,10 +114,9 @@
* This is an Mbed TLS extension.
*
* \note This function is only available on the following platforms:
- * * If the compile-time options MBEDTLS_ENTROPY_NV_SEED and
- * MBEDTLS_PSA_HAS_ITS_IO are both enabled. Note that you
- * must provide compatible implementations of mbedtls_nv_seed_read
- * and mbedtls_nv_seed_write.
+ * * 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.
@@ -111,7 +135,6 @@
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p seed_size is out of range.
* \retval #PSA_ERROR_STORAGE_FAILURE
- * \retval `PSA_ITS_ERROR_XXX`
* There was a failure reading or writing from storage.
* \retval #PSA_ERROR_NOT_PERMITTED
* The library has already been initialized. It is no longer
diff --git a/include/psa/crypto_platform.h b/include/psa/crypto_platform.h
index 50ca546..42cdad3 100644
--- a/include/psa/crypto_platform.h
+++ b/include/psa/crypto_platform.h
@@ -49,4 +49,53 @@
/* Integral type representing a key handle. */
typedef uint16_t psa_key_handle_t;
+/* This implementation distinguishes *application key identifiers*, which
+ * are the key identifiers specified by the application, from
+ * *key file identifiers*, which are the key identifiers that the library
+ * sees internally. The two types can be different if there is a remote
+ * call layer between the application and the library which supports
+ * multiple client applications that do not have access to each others'
+ * keys. The point of having different types is that the key file
+ * identifier may encode not only the key identifier specified by the
+ * application, but also the the identity of the application.
+ *
+ * Note that this is an internal concept of the library and the remote
+ * call layer. The application itself never sees anything other than
+ * #psa_app_key_id_t with its standard definition.
+ */
+
+/* The application key identifier is always what the application sees as
+ * #psa_key_id_t. */
+typedef uint32_t psa_app_key_id_t;
+
+#if defined(MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER)
+
+#if defined(PSA_CRYPTO_SECURE)
+/* Building for the PSA Crypto service on a PSA platform. */
+/* A key owner is a PSA partition identifier. */
+typedef int32_t psa_key_owner_id_t;
+#endif
+
+typedef struct
+{
+ uint32_t key_id;
+ psa_key_owner_id_t owner;
+} psa_key_file_id_t;
+#define PSA_KEY_FILE_GET_KEY_ID( file_id ) ( ( file_id ).key_id )
+
+/* Since crypto.h is used as part of the PSA Cryptography API specification,
+ * it must use standard types for things like the argument of psa_open_key().
+ * If it wasn't for that constraint, psa_open_key() would take a
+ * `psa_key_file_id_t` argument. As a workaround, make `psa_key_id_t` an
+ * alias for `psa_key_file_id_t` when building for a multi-client service. */
+typedef psa_key_file_id_t psa_key_id_t;
+
+#else /* !MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER */
+
+/* By default, a key file identifier is just the application key identifier. */
+typedef psa_app_key_id_t psa_key_file_id_t;
+#define PSA_KEY_FILE_GET_KEY_ID( id ) ( id )
+
+#endif /* !MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER */
+
#endif /* PSA_CRYPTO_PLATFORM_H */
diff --git a/include/psa/crypto_se_driver.h b/include/psa/crypto_se_driver.h
index 0578664..5fb7bc3 100644
--- a/include/psa/crypto_se_driver.h
+++ b/include/psa/crypto_se_driver.h
@@ -3,10 +3,10 @@
* \brief PSA external cryptoprocessor driver module
*
* This header declares types and function signatures for cryptography
- * drivers that access key material via opaque references. This is
- * meant for cryptoprocessors that have a separate key storage from the
+ * drivers that access key material via opaque references.
+ * This is meant for cryptoprocessors that have a separate key storage from the
* space in which the PSA Crypto implementation runs, typically secure
- * elements.
+ * elements (SEs).
*
* This file is part of the PSA Crypto Driver Model, containing functions for
* driver developers to implement to enable hardware to be called in a
@@ -43,27 +43,27 @@
/** An internal designation of a key slot between the core part of the
* PSA Crypto implementation and the driver. The meaning of this value
* is driver-dependent. */
-typedef uint32_t psa_key_slot_t;
+typedef uint32_t psa_key_slot_number_t; // Change this to psa_key_slot_t after psa_key_slot_t is removed from Mbed crypto
-/** \defgroup opaque_mac Opaque Message Authentication Code
+/** \defgroup se_mac Secure Element Message Authentication Codes
* Generation and authentication of Message Authentication Codes (MACs) using
- * opaque keys can be done either as a single function call (via the
- * `psa_drv_mac_opaque_generate_t` or `psa_drv_mac_opaque_verify_t` functions), or in
+ * a secure element can be done either as a single function call (via the
+ * `psa_drv_se_mac_generate_t` or `psa_drv_se_mac_verify_t` functions), or in
* parts using the following sequence:
- * - `psa_drv_mac_opaque_setup_t`
- * - `psa_drv_mac_opaque_update_t`
- * - `psa_drv_mac_opaque_update_t`
+ * - `psa_drv_se_mac_setup_t`
+ * - `psa_drv_se_mac_update_t`
+ * - `psa_drv_se_mac_update_t`
* - ...
- * - `psa_drv_mac_opaque_finish_t` or `psa_drv_mac_opaque_finish_verify_t`
+ * - `psa_drv_se_mac_finish_t` or `psa_drv_se_mac_finish_verify_t`
*
- * If a previously started Opaque MAC operation needs to be terminated, it
- * should be done so by the `psa_drv_mac_opaque_abort_t`. Failure to do so may
+ * If a previously started secure element MAC operation needs to be terminated,
+ * it should be done so by the `psa_drv_se_mac_abort_t`. Failure to do so may
* result in allocated resources not being freed or in other undefined
* behavior.
*/
/**@{*/
-/** \brief A function that starts a MAC operation for a PSA Crypto Driver
- * implementation using an opaque key
+/** \brief A function that starts a secure element MAC operation for a PSA
+ * Crypto Driver implementation
*
* \param[in,out] p_context A structure that will contain the
* hardware-specific MAC context
@@ -75,26 +75,26 @@
* \retval PSA_SUCCESS
* Success.
*/
-typedef psa_status_t (*psa_drv_mac_opaque_setup_t)(void *p_context,
- psa_key_slot_t key_slot,
- psa_algorithm_t algorithm);
+typedef psa_status_t (*psa_drv_se_mac_setup_t)(void *p_context,
+ psa_key_slot_number_t key_slot,
+ psa_algorithm_t algorithm);
-/** \brief A function that continues a previously started MAC operation using
- * an opaque key
+/** \brief A function that continues a previously started secure element MAC
+ * operation
*
* \param[in,out] p_context A hardware-specific structure for the
* previously-established MAC operation to be
- * continued
+ * updated
* \param[in] p_input A buffer containing the message to be appended
* to the MAC operation
* \param[in] input_length The size in bytes of the input message buffer
*/
-typedef psa_status_t (*psa_drv_mac_opaque_update_t)(void *p_context,
- const uint8_t *p_input,
- size_t input_length);
+typedef psa_status_t (*psa_drv_se_mac_update_t)(void *p_context,
+ const uint8_t *p_input,
+ size_t input_length);
-/** \brief a function that completes a previously started MAC operation by
- * returning the resulting MAC using an opaque key
+/** \brief a function that completes a previously started secure element MAC
+ * operation by returning the resulting MAC.
*
* \param[in,out] p_context A hardware-specific structure for the
* previously started MAC operation to be
@@ -109,13 +109,13 @@
* \retval PSA_SUCCESS
* Success.
*/
-typedef psa_status_t (*psa_drv_mac_opaque_finish_t)(void *p_context,
- uint8_t *p_mac,
- size_t mac_size,
- size_t *p_mac_length);
+typedef psa_status_t (*psa_drv_se_mac_finish_t)(void *p_context,
+ uint8_t *p_mac,
+ size_t mac_size,
+ size_t *p_mac_length);
-/** \brief A function that completes a previously started MAC operation by
- * comparing the resulting MAC against a known value using an opaque key
+/** \brief A function that completes a previously started secure element MAC
+ * operation by comparing the resulting MAC against a provided value
*
* \param[in,out] p_context A hardware-specific structure for the previously
* started MAC operation to be fiinished
@@ -130,19 +130,20 @@
* The operation completed successfully, but the calculated MAC did
* not match the provided MAC
*/
-typedef psa_status_t (*psa_drv_mac_opaque_finish_verify_t)(void *p_context,
- const uint8_t *p_mac,
- size_t mac_length);
+typedef psa_status_t (*psa_drv_se_mac_finish_verify_t)(void *p_context,
+ const uint8_t *p_mac,
+ size_t mac_length);
-/** \brief A function that aborts a previous started opaque-key MAC operation
-
+/** \brief A function that aborts a previous started secure element MAC
+ * operation
+ *
* \param[in,out] p_context A hardware-specific structure for the previously
* started MAC operation to be aborted
*/
-typedef psa_status_t (*psa_drv_mac_opaque_abort_t)(void *p_context);
+typedef psa_status_t (*psa_drv_se_mac_abort_t)(void *p_context);
-/** \brief A function that performs a MAC operation in one command and returns
- * the calculated MAC using an opaque key
+/** \brief A function that performs a secure element MAC operation in one
+ * command and returns the calculated MAC
*
* \param[in] p_input A buffer containing the message to be MACed
* \param[in] input_length The size in bytes of `p_input`
@@ -158,16 +159,16 @@
* \retval PSA_SUCCESS
* Success.
*/
-typedef psa_status_t (*psa_drv_mac_opaque_generate_t)(const uint8_t *p_input,
- size_t input_length,
- psa_key_slot_t key_slot,
- psa_algorithm_t alg,
- uint8_t *p_mac,
- size_t mac_size,
- size_t *p_mac_length);
+typedef psa_status_t (*psa_drv_se_mac_generate_t)(const uint8_t *p_input,
+ size_t input_length,
+ psa_key_slot_number_t key_slot,
+ psa_algorithm_t alg,
+ uint8_t *p_mac,
+ size_t mac_size,
+ size_t *p_mac_length);
-/** \brief A function that performs an MAC operation in one command and
- * compare the resulting MAC against a known value using an opaque key
+/** \brief A function that performs a secure element MAC operation in one
+ * command and compares the resulting MAC against a provided value
*
* \param[in] p_input A buffer containing the message to be MACed
* \param[in] input_length The size in bytes of `input`
@@ -185,21 +186,21 @@
* The operation completed successfully, but the calculated MAC did
* not match the provided MAC
*/
-typedef psa_status_t (*psa_drv_mac_opaque_verify_t)(const uint8_t *p_input,
- size_t input_length,
- psa_key_slot_t key_slot,
- psa_algorithm_t alg,
- const uint8_t *p_mac,
- size_t mac_length);
+typedef psa_status_t (*psa_drv_se_mac_verify_t)(const uint8_t *p_input,
+ size_t input_length,
+ psa_key_slot_number_t key_slot,
+ psa_algorithm_t alg,
+ const uint8_t *p_mac,
+ size_t mac_length);
/** \brief A struct containing all of the function pointers needed to
- * implement MAC operations using opaque keys.
+ * perform secure element MAC operations
*
* PSA Crypto API implementations should populate the table as appropriate
* upon startup.
*
* If one of the functions is not implemented (such as
- * `psa_drv_mac_opaque_generate_t`), it should be set to NULL.
+ * `psa_drv_se_mac_generate_t`), it should be set to NULL.
*
* Driver implementers should ensure that they implement all of the functions
* that make sense for their hardware, and that they provide a full solution
@@ -208,57 +209,59 @@
*
*/
typedef struct {
- /**The size in bytes of the hardware-specific Opaque-MAC Context structure
+ /**The size in bytes of the hardware-specific secure element MAC context
+ * structure
*/
- size_t context_size;
- /** Function that performs the setup operation
+ size_t context_size;
+ /** Function that performs a MAC setup operation
*/
- psa_drv_mac_opaque_setup_t *p_setup;
- /** Function that performs the update operation
+ psa_drv_se_mac_setup_t p_setup;
+ /** Function that performs a MAC update operation
*/
- psa_drv_mac_opaque_update_t *p_update;
- /** Function that completes the operation
+ psa_drv_se_mac_update_t p_update;
+ /** Function that completes a MAC operation
*/
- psa_drv_mac_opaque_finish_t *p_finish;
- /** Function that completed a MAC operation with a verify check
+ psa_drv_se_mac_finish_t p_finish;
+ /** Function that completes a MAC operation with a verify check
*/
- psa_drv_mac_opaque_finish_verify_t *p_finish_verify;
- /** Function that aborts a previoustly started operation
+ psa_drv_se_mac_finish_verify_t p_finish_verify;
+ /** Function that aborts a previoustly started MAC operation
*/
- psa_drv_mac_opaque_abort_t *p_abort;
- /** Function that performs the MAC operation in one call
+ psa_drv_se_mac_abort_t p_abort;
+ /** Function that performs a MAC operation in one call
*/
- psa_drv_mac_opaque_generate_t *p_mac;
- /** Function that performs the MAC and verify operation in one call
+ psa_drv_se_mac_generate_t p_mac;
+ /** Function that performs a MAC and verify operation in one call
*/
- psa_drv_mac_opaque_verify_t *p_mac_verify;
-} psa_drv_mac_opaque_t;
+ psa_drv_se_mac_verify_t p_mac_verify;
+} psa_drv_se_mac_t;
/**@}*/
-/** \defgroup opaque_cipher Opaque Symmetric Ciphers
+/** \defgroup se_cipher Secure Element Symmetric Ciphers
*
- * Encryption and Decryption using opaque keys in block modes other than ECB
- * must be done in multiple parts, using the following flow:
- * - `psa_drv_cipher_opaque_setup_t`
- * - `psa_drv_cipher_opaque_set_iv_t` (optional depending upon block mode)
- * - `psa_drv_cipher_opaque_update_t`
+ * Encryption and Decryption using secure element keys in block modes other
+ * than ECB must be done in multiple parts, using the following flow:
+ * - `psa_drv_se_cipher_setup_t`
+ * - `psa_drv_se_cipher_set_iv_t` (optional depending upon block mode)
+ * - `psa_drv_se_cipher_update_t`
+ * - `psa_drv_se_cipher_update_t`
* - ...
- * - `psa_drv_cipher_opaque_finish_t`
-
- * If a previously started Opaque Cipher operation needs to be terminated, it
- * should be done so by the `psa_drv_cipher_opaque_abort_t`. Failure to do so may
- * result in allocated resources not being freed or in other undefined
- * behavior.
+ * - `psa_drv_se_cipher_finish_t`
+ *
+ * If a previously started secure element Cipher operation needs to be
+ * terminated, it should be done so by the `psa_drv_se_cipher_abort_t`. Failure
+ * to do so may result in allocated resources not being freed or in other
+ * undefined behavior.
*
* In situations where a PSA Cryptographic API implementation is using a block
* mode not-supported by the underlying hardware or driver, it can construct
- * the block mode itself, while calling the `psa_drv_cipher_opaque_ecb_t` function
- * pointer for the cipher operations.
+ * the block mode itself, while calling the `psa_drv_se_cipher_ecb_t` function
+ * for the cipher operations.
*/
/**@{*/
-/** \brief A function pointer that provides the cipher setup function for
- * opaque-key operations
+/** \brief A function that provides the cipher setup function for a
+ * secure element driver
*
* \param[in,out] p_context A structure that will contain the
* hardware-specific cipher context.
@@ -272,16 +275,16 @@
* \retval PSA_SUCCESS
* \retval PSA_ERROR_NOT_SUPPORTED
*/
-typedef psa_status_t (*psa_drv_cipher_opaque_setup_t)(void *p_context,
- psa_key_slot_t key_slot,
- psa_algorithm_t algorithm,
- psa_encrypt_or_decrypt_t direction);
+typedef psa_status_t (*psa_drv_se_cipher_setup_t)(void *p_context,
+ psa_key_slot_number_t key_slot,
+ psa_algorithm_t algorithm,
+ psa_encrypt_or_decrypt_t direction);
-/** \brief A function pointer that sets the initialization vector (if
- * necessary) for an opaque cipher operation
+/** \brief A function that sets the initialization vector (if
+ * necessary) for an secure element cipher operation
*
- * Rationale: The `psa_cipher_*` function in the PSA Cryptographic API has two
- * IV functions: one to set the IV, and one to generate it internally. The
+ * Rationale: The `psa_se_cipher_*` operation in the PSA Cryptographic API has
+ * two IV functions: one to set the IV, and one to generate it internally. The
* generate function is not necessary for the drivers to implement as the PSA
* Crypto implementation can do the generation using its RNG features.
*
@@ -292,11 +295,11 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_cipher_opaque_set_iv_t)(void *p_context,
- const uint8_t *p_iv,
- size_t iv_length);
+typedef psa_status_t (*psa_drv_se_cipher_set_iv_t)(void *p_context,
+ const uint8_t *p_iv,
+ size_t iv_length);
-/** \brief A function that continues a previously started opaque-key cipher
+/** \brief A function that continues a previously started secure element cipher
* operation
*
* \param[in,out] p_context A hardware-specific structure for the
@@ -314,14 +317,14 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_cipher_opaque_update_t)(void *p_context,
- const uint8_t *p_input,
- size_t input_size,
- uint8_t *p_output,
- size_t output_size,
- size_t *p_output_length);
+typedef psa_status_t (*psa_drv_se_cipher_update_t)(void *p_context,
+ const uint8_t *p_input,
+ size_t input_size,
+ uint8_t *p_output,
+ size_t output_size,
+ size_t *p_output_length);
-/** \brief A function that completes a previously started opaque-key cipher
+/** \brief A function that completes a previously started secure element cipher
* operation
*
* \param[in,out] p_context A hardware-specific structure for the
@@ -335,21 +338,21 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_cipher_opaque_finish_t)(void *p_context,
- uint8_t *p_output,
- size_t output_size,
- size_t *p_output_length);
+typedef psa_status_t (*psa_drv_se_cipher_finish_t)(void *p_context,
+ uint8_t *p_output,
+ size_t output_size,
+ size_t *p_output_length);
-/** \brief A function that aborts a previously started opaque-key cipher
+/** \brief A function that aborts a previously started secure element cipher
* operation
*
* \param[in,out] p_context A hardware-specific structure for the
* previously started cipher operation
*/
-typedef psa_status_t (*psa_drv_cipher_opaque_abort_t)(void *p_context);
+typedef psa_status_t (*psa_drv_se_cipher_abort_t)(void *p_context);
-/** \brief A function that performs the ECB block mode for opaque-key cipher
- * operations
+/** \brief A function that performs the ECB block mode for secure element
+ * cipher operations
*
* Note: this function should only be used with implementations that do not
* provide a needed higher-level operation.
@@ -370,58 +373,59 @@
* \retval PSA_SUCCESS
* \retval PSA_ERROR_NOT_SUPPORTED
*/
-typedef psa_status_t (*psa_drv_cipher_opaque_ecb_t)(psa_key_slot_t key_slot,
- psa_algorithm_t algorithm,
- psa_encrypt_or_decrypt_t direction,
- const uint8_t *p_input,
- size_t input_size,
- uint8_t *p_output,
- size_t output_size);
+typedef psa_status_t (*psa_drv_se_cipher_ecb_t)(psa_key_slot_number_t key_slot,
+ psa_algorithm_t algorithm,
+ psa_encrypt_or_decrypt_t direction,
+ const uint8_t *p_input,
+ size_t input_size,
+ uint8_t *p_output,
+ size_t output_size);
/**
* \brief A struct containing all of the function pointers needed to implement
- * cipher operations using opaque keys.
+ * cipher operations using secure elements.
*
* PSA Crypto API implementations should populate instances of the table as
- * appropriate upon startup.
+ * appropriate upon startup or at build time.
*
* If one of the functions is not implemented (such as
- * `psa_drv_cipher_opaque_ecb_t`), it should be set to NULL.
+ * `psa_drv_se_cipher_ecb_t`), it should be set to NULL.
*/
typedef struct {
- /** The size in bytes of the hardware-specific Opaque Cipher context
- * structure
+ /** The size in bytes of the hardware-specific secure element cipher
+ * context structure
*/
- size_t size;
- /** Function that performs the setup operation */
- psa_drv_cipher_opaque_setup_t *p_setup;
- /** Function that sets the IV (if necessary) */
- psa_drv_cipher_opaque_set_iv_t *p_set_iv;
- /** Function that performs the update operation */
- psa_drv_cipher_opaque_update_t *p_update;
- /** Function that completes the operation */
- psa_drv_cipher_opaque_finish_t *p_finish;
- /** Function that aborts the operation */
- psa_drv_cipher_opaque_abort_t *p_abort;
- /** Function that performs ECB mode for the cipher
+ size_t context_size;
+ /** Function that performs a cipher setup operation */
+ psa_drv_se_cipher_setup_t p_setup;
+ /** Function that sets a cipher IV (if necessary) */
+ psa_drv_se_cipher_set_iv_t p_set_iv;
+ /** Function that performs a cipher update operation */
+ psa_drv_se_cipher_update_t p_update;
+ /** Function that completes a cipher operation */
+ psa_drv_se_cipher_finish_t p_finish;
+ /** Function that aborts a cipher operation */
+ psa_drv_se_cipher_abort_t p_abort;
+ /** Function that performs ECB mode for a cipher operation
* (Danger: ECB mode should not be used directly by clients of the PSA
* Crypto Client API)
*/
- psa_drv_cipher_opaque_ecb_t *p_ecb;
-} psa_drv_cipher_opaque_t;
+ psa_drv_se_cipher_ecb_t p_ecb;
+} psa_drv_se_cipher_t;
/**@}*/
-/** \defgroup opaque_asymmetric Opaque Asymmetric Cryptography
+/** \defgroup se_asymmetric Secure Element Asymmetric Cryptography
*
* Since the amount of data that can (or should) be encrypted or signed using
* asymmetric keys is limited by the key size, asymmetric key operations using
- * opaque keys must be done in single function calls.
+ * keys in a secure element must be done in single function calls.
*/
/**@{*/
/**
- * \brief A function that signs a hash or short message with a private key
+ * \brief A function that signs a hash or short message with a private key in
+ * a secure element
*
* \param[in] key_slot Key slot of an asymmetric key pair
* \param[in] alg A signature algorithm that is compatible
@@ -435,17 +439,17 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_asymmetric_opaque_sign_t)(psa_key_slot_t key_slot,
- psa_algorithm_t alg,
- const uint8_t *p_hash,
- size_t hash_length,
- uint8_t *p_signature,
- size_t signature_size,
- size_t *p_signature_length);
+typedef psa_status_t (*psa_drv_se_asymmetric_sign_t)(psa_key_slot_number_t key_slot,
+ psa_algorithm_t alg,
+ const uint8_t *p_hash,
+ size_t hash_length,
+ uint8_t *p_signature,
+ size_t signature_size,
+ size_t *p_signature_length);
/**
* \brief A function that verifies the signature a hash or short message using
- * an asymmetric public key
+ * an asymmetric public key in a secure element
*
* \param[in] key_slot Key slot of a public key or an asymmetric key
* pair
@@ -459,16 +463,16 @@
* \retval PSA_SUCCESS
* The signature is valid.
*/
-typedef psa_status_t (*psa_drv_asymmetric_opaque_verify_t)(psa_key_slot_t key_slot,
- psa_algorithm_t alg,
- const uint8_t *p_hash,
- size_t hash_length,
- const uint8_t *p_signature,
- size_t signature_length);
+typedef psa_status_t (*psa_drv_se_asymmetric_verify_t)(psa_key_slot_number_t key_slot,
+ psa_algorithm_t alg,
+ const uint8_t *p_hash,
+ size_t hash_length,
+ const uint8_t *p_signature,
+ size_t signature_length);
/**
* \brief A function that encrypts a short message with an asymmetric public
- * key
+ * key in a secure element
*
* \param[in] key_slot Key slot of a public key or an asymmetric key
* pair
@@ -495,18 +499,19 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_asymmetric_opaque_encrypt_t)(psa_key_slot_t key_slot,
- psa_algorithm_t alg,
- const uint8_t *p_input,
- size_t input_length,
- const uint8_t *p_salt,
- size_t salt_length,
- uint8_t *p_output,
- size_t output_size,
- size_t *p_output_length);
+typedef psa_status_t (*psa_drv_se_asymmetric_encrypt_t)(psa_key_slot_number_t key_slot,
+ psa_algorithm_t alg,
+ const uint8_t *p_input,
+ size_t input_length,
+ const uint8_t *p_salt,
+ size_t salt_length,
+ uint8_t *p_output,
+ size_t output_size,
+ size_t *p_output_length);
/**
- * \brief Decrypt a short message with an asymmetric private key.
+ * \brief A function that decrypts a short message with an asymmetric private
+ * key in a secure element.
*
* \param[in] key_slot Key slot of an asymmetric key pair
* \param[in] alg An asymmetric encryption algorithm that is
@@ -532,48 +537,49 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_asymmetric_opaque_decrypt_t)(psa_key_slot_t key_slot,
- psa_algorithm_t alg,
- const uint8_t *p_input,
- size_t input_length,
- const uint8_t *p_salt,
- size_t salt_length,
- uint8_t *p_output,
- size_t output_size,
- size_t *p_output_length);
+typedef psa_status_t (*psa_drv_se_asymmetric_decrypt_t)(psa_key_slot_number_t key_slot,
+ psa_algorithm_t alg,
+ const uint8_t *p_input,
+ size_t input_length,
+ const uint8_t *p_salt,
+ size_t salt_length,
+ uint8_t *p_output,
+ size_t output_size,
+ size_t *p_output_length);
/**
* \brief A struct containing all of the function pointers needed to implement
- * asymmetric cryptographic operations using opaque keys.
+ * asymmetric cryptographic operations using secure elements.
*
* PSA Crypto API implementations should populate instances of the table as
- * appropriate upon startup.
+ * appropriate upon startup or at build time.
*
* If one of the functions is not implemented, it should be set to NULL.
*/
typedef struct {
- /** Function that performs the asymmetric sign operation */
- psa_drv_asymmetric_opaque_sign_t *p_sign;
- /** Function that performs the asymmetric verify operation */
- psa_drv_asymmetric_opaque_verify_t *p_verify;
- /** Function that performs the asymmetric encrypt operation */
- psa_drv_asymmetric_opaque_encrypt_t *p_encrypt;
- /** Function that performs the asymmetric decrypt operation */
- psa_drv_asymmetric_opaque_decrypt_t *p_decrypt;
-} psa_drv_asymmetric_opaque_t;
+ /** Function that performs an asymmetric sign operation */
+ psa_drv_se_asymmetric_sign_t p_sign;
+ /** Function that performs an asymmetric verify operation */
+ psa_drv_se_asymmetric_verify_t p_verify;
+ /** Function that performs an asymmetric encrypt operation */
+ psa_drv_se_asymmetric_encrypt_t p_encrypt;
+ /** Function that performs an asymmetric decrypt operation */
+ psa_drv_se_asymmetric_decrypt_t p_decrypt;
+} psa_drv_se_asymmetric_t;
/**@}*/
-/** \defgroup aead_opaque AEAD Opaque
- * Authenticated Encryption with Additional Data (AEAD) operations with opaque
- * keys must be done in one function call. While this creates a burden for
+/** \defgroup se_aead Secure Element Authenticated Encryption with Additional Data
+ * Authenticated Encryption with Additional Data (AEAD) operations with secure
+ * elements must be done in one function call. While this creates a burden for
* implementers as there must be sufficient space in memory for the entire
* message, it prevents decrypted data from being made available before the
* authentication operation is complete and the data is known to be authentic.
*/
/**@{*/
-/** \brief Process an authenticated encryption operation using an opaque key
+/** \brief A function that performs a secure element authenticated encryption
+ * operation
*
* \param[in] key_slot Slot containing the key to use.
* \param[in] algorithm The AEAD algorithm to compute
@@ -602,19 +608,19 @@
* \retval #PSA_SUCCESS
* Success.
*/
-typedef psa_status_t (*psa_drv_aead_opaque_encrypt_t)(psa_key_slot_t key_slot,
- psa_algorithm_t algorithm,
- const uint8_t *p_nonce,
- size_t nonce_length,
- const uint8_t *p_additional_data,
- size_t additional_data_length,
- const uint8_t *p_plaintext,
- size_t plaintext_length,
- uint8_t *p_ciphertext,
- size_t ciphertext_size,
- size_t *p_ciphertext_length);
+typedef psa_status_t (*psa_drv_se_aead_encrypt_t)(psa_key_slot_number_t key_slot,
+ psa_algorithm_t algorithm,
+ const uint8_t *p_nonce,
+ size_t nonce_length,
+ const uint8_t *p_additional_data,
+ size_t additional_data_length,
+ const uint8_t *p_plaintext,
+ size_t plaintext_length,
+ uint8_t *p_ciphertext,
+ size_t ciphertext_size,
+ size_t *p_ciphertext_length);
-/** Process an authenticated decryption operation using an opaque key
+/** A function that peforms a secure element authenticated decryption operation
*
* \param[in] key_slot Slot containing the key to use
* \param[in] algorithm The AEAD algorithm to compute
@@ -642,21 +648,21 @@
* \retval #PSA_SUCCESS
* Success.
*/
-typedef psa_status_t (*psa_drv_aead_opaque_decrypt_t)(psa_key_slot_t key_slot,
- psa_algorithm_t algorithm,
- const uint8_t *p_nonce,
- size_t nonce_length,
- const uint8_t *p_additional_data,
- size_t additional_data_length,
- const uint8_t *p_ciphertext,
- size_t ciphertext_length,
- uint8_t *p_plaintext,
- size_t plaintext_size,
- size_t *p_plaintext_length);
+typedef psa_status_t (*psa_drv_se_aead_decrypt_t)(psa_key_slot_number_t key_slot,
+ psa_algorithm_t algorithm,
+ const uint8_t *p_nonce,
+ size_t nonce_length,
+ const uint8_t *p_additional_data,
+ size_t additional_data_length,
+ const uint8_t *p_ciphertext,
+ size_t ciphertext_length,
+ uint8_t *p_plaintext,
+ size_t plaintext_size,
+ size_t *p_plaintext_length);
/**
* \brief A struct containing all of the function pointers needed to implement
- * Authenticated Encryption with Additional Data operations using opaque keys
+ * secure element Authenticated Encryption with Additional Data operations
*
* PSA Crypto API implementations should populate instances of the table as
* appropriate upon startup.
@@ -665,13 +671,13 @@
*/
typedef struct {
/** Function that performs the AEAD encrypt operation */
- psa_drv_aead_opaque_encrypt_t *p_encrypt;
+ psa_drv_se_aead_encrypt_t p_encrypt;
/** Function that performs the AEAD decrypt operation */
- psa_drv_aead_opaque_decrypt_t *p_decrypt;
-} psa_drv_aead_opaque_t;
+ psa_drv_se_aead_decrypt_t p_decrypt;
+} psa_drv_se_aead_t;
/**@}*/
-/** \defgroup driver_key_management Key Management
+/** \defgroup se_key_management Secure Element Key Management
* Currently, key management is limited to importing keys in the clear,
* destroying keys, and exporting keys in the clear.
* Whether a key may be exported is determined by the key policies in place
@@ -679,7 +685,7 @@
*/
/**@{*/
-/** \brief Import a key in binary format
+/** \brief A function that imports a key into a secure element in binary format
*
* This function can support any output from psa_export_key(). Refer to the
* documentation of psa_export_key() for the format for each key type.
@@ -687,6 +693,7 @@
* \param[in] key_slot Slot where the key will be stored
* This must be a valid slot for a key of the chosen
* type. It must be unoccupied.
+ * \param[in] lifetime The required lifetime of the key storage
* \param[in] type Key type (a \c PSA_KEY_TYPE_XXX value)
* \param[in] algorithm Key algorithm (a \c PSA_ALG_XXX value)
* \param[in] usage The allowed uses of the key
@@ -696,33 +703,33 @@
* \retval #PSA_SUCCESS
* Success.
*/
-typedef psa_status_t (*psa_drv_opaque_import_key_t)(psa_key_slot_t key_slot,
- psa_key_type_t type,
- psa_algorithm_t algorithm,
- psa_key_usage_t usage,
- const uint8_t *p_data,
- size_t data_length);
+typedef psa_status_t (*psa_drv_se_import_key_t)(psa_key_slot_number_t key_slot,
+ psa_key_lifetime_t lifetime,
+ psa_key_type_t type,
+ psa_algorithm_t algorithm,
+ psa_key_usage_t usage,
+ const uint8_t *p_data,
+ size_t data_length);
/**
- * \brief Destroy a key and restore the slot to its default state
+ * \brief A function that destroys a secure element key and restore the slot to
+ * its default state
*
- * This function destroys the content of the key slot from both volatile
- * memory and, if applicable, non-volatile storage. Implementations shall
- * make a best effort to ensure that any previous content of the slot is
- * unrecoverable.
+ * This function destroys the content of the key from a secure element.
+ * Implementations shall make a best effort to ensure that any previous content
+ * of the slot is unrecoverable.
*
- * This function also erases any metadata such as policies. It returns the
- * specified slot to its default state.
+ * This function returns the specified slot to its default state.
*
* \param[in] key_slot The key slot to erase.
*
* \retval #PSA_SUCCESS
* The slot's content, if any, has been erased.
*/
-typedef psa_status_t (*psa_drv_destroy_key_t)(psa_key_slot_t key);
+typedef psa_status_t (*psa_drv_se_destroy_key_t)(psa_key_slot_number_t key);
/**
- * \brief Export a key in binary format
+ * \brief A function that exports a secure element key in binary format
*
* The output of this function can be passed to psa_import_key() to
* create an equivalent object.
@@ -732,19 +739,9 @@
* identical: the implementation may choose a different representation
* of the same key if the format permits it.
*
- * For standard key types, the output format is as follows:
- *
- * - For symmetric keys (including MAC keys), the format is the
- * raw bytes of the key.
- * - For DES, the key data consists of 8 bytes. The parity bits must be
- * correct.
- * - For Triple-DES, the format is the concatenation of the
- * two or three DES keys.
- * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEYPAIR), the format
- * is the non-encrypted DER representation defined by PKCS\#1 (RFC 8017)
- * as RSAPrivateKey.
- * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the format
- * is the DER representation defined by RFC 5280 as SubjectPublicKeyInfo.
+ * This function should generate output in the same format that
+ * `psa_export_key()` does. Refer to the
+ * documentation of `psa_export_key()` for the format for each key type.
*
* \param[in] key Slot whose content is to be exported. This must
* be an occupied key slot.
@@ -754,67 +751,79 @@
* that make up the key data.
*
* \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_NOT_SUPPORTED
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
*/
-typedef psa_status_t (*psa_drv_export_key_t)(psa_key_slot_t key,
- uint8_t *p_data,
- size_t data_size,
- size_t *p_data_length);
+typedef psa_status_t (*psa_drv_se_export_key_t)(psa_key_slot_number_t key,
+ uint8_t *p_data,
+ size_t data_size,
+ size_t *p_data_length);
/**
- * \brief Export a public key or the public part of a key pair in binary format
+ * \brief A function that generates a symmetric or asymmetric key on a secure
+ * element
*
- * The output of this function can be passed to psa_import_key() to
- * create an object that is equivalent to the public key.
+ * If \p type is asymmetric (`#PSA_KEY_TYPE_IS_ASYMMETRIC(\p type) == 1`),
+ * the public component of the generated key will be placed in `p_pubkey_out`.
+ * The format of the public key information will match the format specified for
+ * the psa_export_key() function for the key type.
*
- * For standard key types, the output format is as follows:
- *
- * - For RSA keys (#PSA_KEY_TYPE_RSA_KEYPAIR or #PSA_KEY_TYPE_RSA_PUBLIC_KEY),
- * the format is the DER representation of the public key defined by RFC 5280
- * as SubjectPublicKeyInfo.
- *
- * \param[in] key_slot Slot whose content is to be exported. This must
- * be an occupied key slot.
- * \param[out] p_data Buffer where the key data is to be written.
- * \param[in] data_size Size of the `data` buffer in bytes.
- * \param[out] p_data_length On success, the number of bytes
- * that make up the key data.
- *
- * \retval #PSA_SUCCESS
+ * \param[in] key_slot Slot where the generated key will be placed
+ * \param[in] type The type of the key to be generated
+ * \param[in] usage The prescribed usage of the generated key
+ * Note: Not all Secure Elements support the same
+ * restrictions that PSA Crypto does (and vice versa).
+ * Driver developers should endeavor to match the
+ * usages as close as possible.
+ * \param[in] bits The size in bits of the key to be generated.
+ * \param[in] extra Extra parameters for key generation. The
+ * interpretation of this parameter should match the
+ * interpretation in the `extra` parameter is the
+ * `psa_generate_key` function
+ * \param[in] extra_size The size in bytes of the \p extra buffer
+ * \param[out] p_pubkey_out The buffer where the public key information will
+ * be placed
+ * \param[in] pubkey_out_size The size in bytes of the `p_pubkey_out` buffer
+ * \param[out] p_pubkey_length Upon successful completion, will contain the
+ * size of the data placed in `p_pubkey_out`.
*/
-typedef psa_status_t (*psa_drv_export_public_key_t)(psa_key_slot_t key,
- uint8_t *p_data,
- size_t data_size,
- size_t *p_data_length);
+typedef psa_status_t (*psa_drv_se_generate_key_t)(psa_key_slot_number_t key_slot,
+ psa_key_type_t type,
+ psa_key_usage_t usage,
+ size_t bits,
+ const void *extra,
+ size_t extra_size,
+ uint8_t *p_pubkey_out,
+ size_t pubkey_out_size,
+ size_t *p_pubkey_length);
/**
- * \brief A struct containing all of the function pointers needed to for key
- * management using opaque keys
+ * \brief A struct containing all of the function pointers needed to for secure
+ * element key management
*
* PSA Crypto API implementations should populate instances of the table as
- * appropriate upon startup.
+ * appropriate upon startup or at build time.
*
* If one of the functions is not implemented, it should be set to NULL.
*/
typedef struct {
- /** Function that performs the key import operation */
- psa_drv_opaque_import_key_t *p_import;
- /** Function that performs the key destroy operation */
- psa_drv_destroy_key_t *p_destroy;
- /** Function that performs the key export operation */
- psa_drv_export_key_t *p_export;
- /** Function that perforsm the public key export operation */
- psa_drv_export_public_key_t *p_export_public;
-} psa_drv_key_management_t;
+ /** Function that performs a key import operation */
+ psa_drv_se_import_key_t p_import;
+ /** Function that performs a generation */
+ psa_drv_se_generate_key_t p_generate;
+ /** Function that performs a key destroy operation */
+ psa_drv_se_destroy_key_t p_destroy;
+ /** Function that performs a key export operation */
+ psa_drv_se_export_key_t p_export;
+} psa_drv_se_key_management_t;
/**@}*/
-/** \defgroup driver_derivation Key Derivation and Agreement
+/** \defgroup driver_derivation Secure Element Key Derivation and Agreement
* Key derivation is the process of generating new key material using an
* existing key and additional parameters, iterating through a basic
* cryptographic function, such as a hash.
@@ -825,53 +834,46 @@
* for both of the flows.
*
* There are two different final functions for the flows,
- * `psa_drv_key_derivation_derive` and `psa_drv_key_derivation_export`.
- * `psa_drv_key_derivation_derive` is used when the key material should be placed
- * in a slot on the hardware and not exposed to the caller.
- * `psa_drv_key_derivation_export` is used when the key material should be returned
- * to the PSA Cryptographic API implementation.
+ * `psa_drv_se_key_derivation_derive` and `psa_drv_se_key_derivation_export`.
+ * `psa_drv_se_key_derivation_derive` is used when the key material should be
+ * placed in a slot on the hardware and not exposed to the caller.
+ * `psa_drv_se_key_derivation_export` is used when the key material should be
+ * returned to the PSA Cryptographic API implementation.
*
* Different key derivation algorithms require a different number of inputs.
* Instead of having an API that takes as input variable length arrays, which
* can be problemmatic to manage on embedded platforms, the inputs are passed
- * to the driver via a function, `psa_drv_key_derivation_collateral`, that is
- * called multiple times with different `collateral_id`s. Thus, for a key
+ * to the driver via a function, `psa_drv_se_key_derivation_collateral`, that
+ * is called multiple times with different `collateral_id`s. Thus, for a key
* derivation algorithm that required 3 paramter inputs, the flow would look
* something like:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_key_derivation_setup(kdf_algorithm, source_key, dest_key_size_bytes);
- * psa_drv_key_derivation_collateral(kdf_algorithm_collateral_id_0,
- * p_collateral_0,
- * collateral_0_size);
- * psa_drv_key_derivation_collateral(kdf_algorithm_collateral_id_1,
- * p_collateral_1,
- * collateral_1_size);
- * psa_drv_key_derivation_collateral(kdf_algorithm_collateral_id_2,
- * p_collateral_2,
- * collateral_2_size);
- * psa_drv_key_derivation_derive();
+ * psa_drv_se_key_derivation_setup(kdf_algorithm, source_key, dest_key_size_bytes);
+ * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_0,
+ * p_collateral_0,
+ * collateral_0_size);
+ * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_1,
+ * p_collateral_1,
+ * collateral_1_size);
+ * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_2,
+ * p_collateral_2,
+ * collateral_2_size);
+ * psa_drv_se_key_derivation_derive();
* ~~~~~~~~~~~~~
*
* key agreement example:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_key_derivation_setup(alg, source_key. dest_key_size_bytes);
- * psa_drv_key_derivation_collateral(DHE_PUBKEY, p_pubkey, pubkey_size);
- * psa_drv_key_derivation_export(p_session_key,
- * session_key_size,
- * &session_key_length);
+ * psa_drv_se_key_derivation_setup(alg, source_key. dest_key_size_bytes);
+ * psa_drv_se_key_derivation_collateral(DHE_PUBKEY, p_pubkey, pubkey_size);
+ * psa_drv_se_key_derivation_export(p_session_key,
+ * session_key_size,
+ * &session_key_length);
* ~~~~~~~~~~~~~
*/
/**@{*/
-/** \brief The hardware-specific key derivation context structure
- *
- * The contents of this structure are implementation dependent and are
- * therefore not described here
- */
-typedef struct psa_drv_key_derivation_context_s psa_drv_key_derivation_context_t;
-
-/** \brief Set up a key derivation operation by specifying the algorithm and
- * the source key sot
+/** \brief A function that Sets up a secure element key derivation operation by
+ * specifying the algorithm and the source key sot
*
* \param[in,out] p_context A hardware-specific structure containing any
* context information for the implementation
@@ -881,12 +883,12 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_key_derivation_setup_t)(psa_drv_key_derivation_context_t *p_context,
- psa_algorithm_t kdf_alg,
- psa_key_slot_t source_key);
+typedef psa_status_t (*psa_drv_se_key_derivation_setup_t)(void *p_context,
+ psa_algorithm_t kdf_alg,
+ psa_key_slot_number_t source_key);
-/** \brief Provide collateral (parameters) needed for a key derivation or key
- * agreement operation
+/** \brief A function that provides collateral (parameters) needed for a secure
+ * element key derivation or key agreement operation
*
* Since many key derivation algorithms require multiple parameters, it is
* expeced that this function may be called multiple times for the same
@@ -900,13 +902,14 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_key_derivation_collateral_t)(psa_drv_key_derivation_context_t *p_context,
- uint32_t collateral_id,
- const uint8_t *p_collateral,
- size_t collateral_size);
+typedef psa_status_t (*psa_drv_se_key_derivation_collateral_t)(void *p_context,
+ uint32_t collateral_id,
+ const uint8_t *p_collateral,
+ size_t collateral_size);
-/** \brief Perform the final key derivation step and place the generated key
- * material in a slot
+/** \brief A function that performs the final secure element key derivation
+ * step and place the generated key material in a slot
+ *
* \param[in,out] p_context A hardware-specific structure containing any
* context information for the implementation
* \param[in] dest_key The slot where the generated key material
@@ -914,11 +917,11 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_key_derivation_derive_t)(psa_drv_key_derivation_context_t *p_context,
- psa_key_slot_t dest_key);
+typedef psa_status_t (*psa_drv_se_key_derivation_derive_t)(void *p_context,
+ psa_key_slot_number_t dest_key);
-/** \brief Perform the final step of a key agreement and place the generated
- * key material in a buffer
+/** \brief A function that performs the final step of a secure element key
+ * agreement and place the generated key material in a buffer
*
* \param[out] p_output Buffer in which to place the generated key
* material
@@ -928,13 +931,14 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_key_derivation_export_t)(uint8_t *p_output,
- size_t output_size,
- size_t *p_output_length);
+typedef psa_status_t (*psa_drv_se_key_derivation_export_t)(void *p_context,
+ uint8_t *p_output,
+ size_t output_size,
+ size_t *p_output_length);
/**
- * \brief A struct containing all of the function pointers needed to for key
- * derivation and agreement
+ * \brief A struct containing all of the function pointers needed to for secure
+ * element key derivation and agreement
*
* PSA Crypto API implementations should populate instances of the table as
* appropriate upon startup.
@@ -942,16 +946,18 @@
* If one of the functions is not implemented, it should be set to NULL.
*/
typedef struct {
- /** Function that performs the key derivation setup */
- psa_drv_key_derivation_setup_t *p_setup;
- /** Function that sets the key derivation collateral */
- psa_drv_key_derivation_collateral_t *p_collateral;
- /** Function that performs the final key derivation step */
- psa_drv_key_derivation_derive_t *p_derive;
- /** Function that perforsm the final key derivation or agreement and
+ /** The driver-specific size of the key derivation context */
+ size_t context_size;
+ /** Function that performs a key derivation setup */
+ psa_drv_se_key_derivation_setup_t p_setup;
+ /** Function that sets key derivation collateral */
+ psa_drv_se_key_derivation_collateral_t p_collateral;
+ /** Function that performs a final key derivation step */
+ psa_drv_se_key_derivation_derive_t p_derive;
+ /** Function that perforsm a final key derivation or agreement and
* exports the key */
- psa_drv_key_derivation_export_t *p_export;
-} psa_drv_key_derivation_t;
+ psa_drv_se_key_derivation_export_t p_export;
+} psa_drv_se_key_derivation_t;
/**@}*/
diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h
index e1ac630..3c879e8 100644
--- a/include/psa/crypto_sizes.h
+++ b/include/psa/crypto_sizes.h
@@ -313,9 +313,9 @@
(plaintext_length) - PSA_AEAD_TAG_LENGTH(alg) : \
0)
-#define PSA_RSA_MINIMUM_PADDING_SIZE(alg) \
- (PSA_ALG_IS_RSA_OAEP(alg) ? \
- 2 * PSA_HASH_FINAL_SIZE(PSA_ALG_RSA_OAEP_GET_HASH(alg)) + 1 : \
+#define PSA_RSA_MINIMUM_PADDING_SIZE(alg) \
+ (PSA_ALG_IS_RSA_OAEP(alg) ? \
+ 2 * PSA_HASH_SIZE(PSA_ALG_RSA_OAEP_GET_HASH(alg)) + 1 : \
11 /*PKCS#1v1.5*/)
/**
@@ -438,25 +438,16 @@
/* Maximum size of the export encoding of an RSA public key.
* Assumes that the public exponent is less than 2^32.
*
- * SubjectPublicKeyInfo ::= SEQUENCE {
- * algorithm AlgorithmIdentifier,
- * subjectPublicKey BIT STRING } -- contains RSAPublicKey
- * AlgorithmIdentifier ::= SEQUENCE {
- * algorithm OBJECT IDENTIFIER,
- * parameters NULL }
* RSAPublicKey ::= SEQUENCE {
* modulus INTEGER, -- n
* publicExponent INTEGER } -- e
*
- * - 3 * 4 bytes of SEQUENCE overhead;
- * - 1 + 1 + 9 bytes of algorithm (RSA OID);
- * - 2 bytes of NULL;
- * - 4 bytes of BIT STRING overhead;
+ * - 4 bytes of SEQUENCE overhead;
* - n : INTEGER;
* - 7 bytes for the public exponent.
*/
#define PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) \
- (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) + 36)
+ (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) + 11)
/* Maximum size of the export encoding of an RSA key pair.
* Assumes thatthe public exponent is less than 2^32 and that the size
@@ -523,26 +514,16 @@
/* Maximum size of the export encoding of an ECC public key.
*
- * SubjectPublicKeyInfo ::= SEQUENCE {
- * algorithm AlgorithmIdentifier,
- * subjectPublicKey BIT STRING } -- contains ECPoint
- * AlgorithmIdentifier ::= SEQUENCE {
- * algorithm OBJECT IDENTIFIER,
- * parameters OBJECT IDENTIFIER } -- namedCurve
- * ECPoint ::= ...
- * -- first 8 bits: 0x04;
- * -- then x_P as a `ceiling(m/8)`-byte string, big endian;
- * -- then y_P as a `ceiling(m/8)`-byte string, big endian;
- * -- where `m` is the bit size associated with the curve.
+ * The representation of an ECC public key is:
+ * - The byte 0x04;
+ * - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
+ * - `y_P` as a `ceiling(m/8)`-byte string, big-endian;
+ * - where m is the bit size associated with the curve.
*
- * - 2 * 4 bytes of SEQUENCE overhead;
- * - 1 + 1 + 7 bytes of algorithm (id-ecPublicKey OID);
- * - 1 + 1 + 12 bytes of namedCurve OID;
- * - 4 bytes of BIT STRING overhead;
- * - 1 byte + 2 * point size in ECPoint.
+ * - 1 byte + 2 * point size.
*/
#define PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) \
- (2 * PSA_BITS_TO_BYTES(key_bits) + 36)
+ (2 * PSA_BITS_TO_BYTES(key_bits) + 1)
/* Maximum size of the export encoding of an ECC key pair.
*
diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h
index 637e07c..7054de7 100644
--- a/include/psa/crypto_types.h
+++ b/include/psa/crypto_types.h
@@ -47,8 +47,13 @@
* This is either #PSA_SUCCESS (which is zero), indicating success,
* or a nonzero value indicating that an error occurred. Errors are
* encoded as one of the \c PSA_ERROR_xxx values defined here.
+ * If #PSA_SUCCESS is already defined, it means that #psa_status_t
+ * is also defined in an external header, so prevent its multiple
+ * definition.
*/
+#ifndef PSA_SUCCESS
typedef int32_t psa_status_t;
+#endif
/**@}*/
@@ -85,7 +90,14 @@
/** Encoding of identifiers of persistent keys.
*/
+/* Implementation-specific quirk: The Mbed Crypto library can be built as
+ * part of a multi-client service that exposes the PSA Crypto API in each
+ * client and encodes the client identity in the key id argument of functions
+ * such as psa_open_key(). In this build configuration, we define
+ * psa_key_id_t in crypto_platform.h instead of here. */
+#if !defined(MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER)
typedef uint32_t psa_key_id_t;
+#endif
/**@}*/
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index f6ce04e..f9ac00a 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -40,25 +40,17 @@
* @{
*/
-#if !defined(PSA_SUCCESS)
-/* If PSA_SUCCESS is defined, assume that PSA crypto is being used
- * together with PSA IPC, which also defines the identifier
- * PSA_SUCCESS. We must not define PSA_SUCCESS ourselves in that case;
- * the other error code names don't clash. This is a temporary hack
- * until we unify error reporting in PSA IPC and PSA crypto.
- *
- * Note that psa_defs.h must be included before this header!
- */
+/* PSA error codes */
+
/** The action was completed successfully. */
#define PSA_SUCCESS ((psa_status_t)0)
-#endif /* !defined(PSA_SUCCESS) */
/** An error occurred that does not correspond to any defined
* failure cause.
*
* Implementations may use this error code if none of the other standard
* error codes are applicable. */
-#define PSA_ERROR_UNKNOWN_ERROR ((psa_status_t)1)
+#define PSA_ERROR_GENERIC_ERROR ((psa_status_t)-132)
/** The requested operation or a parameter is not supported
* by this implementation.
@@ -67,7 +59,7 @@
* parameter such as a key type, algorithm, etc. is not recognized.
* If a combination of parameters is recognized and identified as
* not valid, return #PSA_ERROR_INVALID_ARGUMENT instead. */
-#define PSA_ERROR_NOT_SUPPORTED ((psa_status_t)2)
+#define PSA_ERROR_NOT_SUPPORTED ((psa_status_t)-134)
/** The requested action is denied by a policy.
*
@@ -80,7 +72,7 @@
* not valid or not supported, it is unspecified whether the function
* returns #PSA_ERROR_NOT_PERMITTED, #PSA_ERROR_NOT_SUPPORTED or
* #PSA_ERROR_INVALID_ARGUMENT. */
-#define PSA_ERROR_NOT_PERMITTED ((psa_status_t)3)
+#define PSA_ERROR_NOT_PERMITTED ((psa_status_t)-133)
/** An output buffer is too small.
*
@@ -92,23 +84,19 @@
* buffer would succeed. However implementations may return this
* error if a function has invalid or unsupported parameters in addition
* to the parameters that determine the necessary output buffer size. */
-#define PSA_ERROR_BUFFER_TOO_SMALL ((psa_status_t)4)
+#define PSA_ERROR_BUFFER_TOO_SMALL ((psa_status_t)-138)
-/** A slot is occupied, but must be empty to carry out the
- * requested action.
+/** Asking for an item that already exists
*
- * If a handle is invalid, it does not designate an occupied slot.
- * The error for an invalid handle is #PSA_ERROR_INVALID_HANDLE.
- */
-#define PSA_ERROR_OCCUPIED_SLOT ((psa_status_t)5)
+ * Implementations should return this error, when attempting
+ * to write an item (like a key) that already exists. */
+#define PSA_ERROR_ALREADY_EXISTS ((psa_status_t)-139)
-/** A slot is empty, but must be occupied to carry out the
- * requested action.
+/** Asking for an item that doesn't exist
*
- * If a handle is invalid, it does not designate an empty slot.
- * The error for an invalid handle is #PSA_ERROR_INVALID_HANDLE.
- */
-#define PSA_ERROR_EMPTY_SLOT ((psa_status_t)6)
+ * Implementations should return this error, if a requested item (like
+ * a key) does not exist. */
+#define PSA_ERROR_DOES_NOT_EXIST ((psa_status_t)-140)
/** The requested action cannot be performed in the current state.
*
@@ -118,9 +106,9 @@
*
* Implementations shall not return this error code to indicate
* that a key slot is occupied when it needs to be free or vice versa,
- * but shall return #PSA_ERROR_OCCUPIED_SLOT or #PSA_ERROR_EMPTY_SLOT
+ * but shall return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST
* as applicable. */
-#define PSA_ERROR_BAD_STATE ((psa_status_t)7)
+#define PSA_ERROR_BAD_STATE ((psa_status_t)-137)
/** The parameters passed to the function are invalid.
*
@@ -129,20 +117,20 @@
*
* Implementations shall not return this error code to indicate
* that a key slot is occupied when it needs to be free or vice versa,
- * but shall return #PSA_ERROR_OCCUPIED_SLOT or #PSA_ERROR_EMPTY_SLOT
+ * but shall return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST
* as applicable.
*
* Implementation shall not return this error code to indicate that a
* key handle is invalid, but shall return #PSA_ERROR_INVALID_HANDLE
* instead.
*/
-#define PSA_ERROR_INVALID_ARGUMENT ((psa_status_t)8)
+#define PSA_ERROR_INVALID_ARGUMENT ((psa_status_t)-135)
/** There is not enough runtime memory.
*
* If the action is carried out across multiple security realms, this
* error can refer to available memory in any of the security realms. */
-#define PSA_ERROR_INSUFFICIENT_MEMORY ((psa_status_t)9)
+#define PSA_ERROR_INSUFFICIENT_MEMORY ((psa_status_t)-141)
/** There is not enough persistent storage.
*
@@ -151,7 +139,7 @@
* many functions that do not otherwise access storage may return this
* error code if the implementation requires a mandatory log entry for
* the requested action and the log storage space is full. */
-#define PSA_ERROR_INSUFFICIENT_STORAGE ((psa_status_t)10)
+#define PSA_ERROR_INSUFFICIENT_STORAGE ((psa_status_t)-142)
/** There was a communication failure inside the implementation.
*
@@ -168,7 +156,7 @@
* cryptoprocessor but there was a breakdown of communication before
* the cryptoprocessor could report the status to the application.
*/
-#define PSA_ERROR_COMMUNICATION_FAILURE ((psa_status_t)11)
+#define PSA_ERROR_COMMUNICATION_FAILURE ((psa_status_t)-145)
/** There was a storage failure that may have led to data loss.
*
@@ -193,13 +181,13 @@
* permanent storage corruption. However application writers should
* keep in mind that transient errors while reading the storage may be
* reported using this error code. */
-#define PSA_ERROR_STORAGE_FAILURE ((psa_status_t)12)
+#define PSA_ERROR_STORAGE_FAILURE ((psa_status_t)-146)
/** A hardware failure was detected.
*
* A hardware failure may be transient or permanent depending on the
* cause. */
-#define PSA_ERROR_HARDWARE_FAILURE ((psa_status_t)13)
+#define PSA_ERROR_HARDWARE_FAILURE ((psa_status_t)-147)
/** A tampering attempt was detected.
*
@@ -230,7 +218,7 @@
* This error indicates an attack against the application. Implementations
* shall not return this error code as a consequence of the behavior of
* the application itself. */
-#define PSA_ERROR_TAMPERING_DETECTED ((psa_status_t)14)
+#define PSA_ERROR_TAMPERING_DETECTED ((psa_status_t)-151)
/** There is not enough entropy to generate random data needed
* for the requested action.
@@ -249,7 +237,7 @@
* secure pseudorandom generator (PRNG). However implementations may return
* this error at any time if a policy requires the PRNG to be reseeded
* during normal operation. */
-#define PSA_ERROR_INSUFFICIENT_ENTROPY ((psa_status_t)15)
+#define PSA_ERROR_INSUFFICIENT_ENTROPY ((psa_status_t)-148)
/** The signature, MAC or hash is incorrect.
*
@@ -259,7 +247,7 @@
*
* If the value to verify has an invalid size, implementations may return
* either #PSA_ERROR_INVALID_ARGUMENT or #PSA_ERROR_INVALID_SIGNATURE. */
-#define PSA_ERROR_INVALID_SIGNATURE ((psa_status_t)16)
+#define PSA_ERROR_INVALID_SIGNATURE ((psa_status_t)-149)
/** The decrypted padding is incorrect.
*
@@ -275,17 +263,15 @@
* as close as possible to indistinguishable to an external observer.
* In particular, the timing of a decryption operation should not
* depend on the validity of the padding. */
-#define PSA_ERROR_INVALID_PADDING ((psa_status_t)17)
+#define PSA_ERROR_INVALID_PADDING ((psa_status_t)-150)
-/** The generator has insufficient capacity left.
- *
- * Once a function returns this error, attempts to read from the
- * generator will always return this error. */
-#define PSA_ERROR_INSUFFICIENT_CAPACITY ((psa_status_t)18)
+/** Return this error when there's insufficient data when attempting
+ * to read from a resource. */
+#define PSA_ERROR_INSUFFICIENT_DATA ((psa_status_t)-143)
/** The key handle is not valid.
*/
-#define PSA_ERROR_INVALID_HANDLE ((psa_status_t)19)
+#define PSA_ERROR_INVALID_HANDLE ((psa_status_t)-136)
/**@}*/
@@ -663,15 +649,18 @@
/** SHA3-512 */
#define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x01000013)
-/** Allow any hash algorithm.
+/** In a hash-and-sign algorithm policy, allow any hash algorithm.
*
- * This value may only be used to form the algorithm usage field of a policy
- * for a signature algorithm that is parametrized by a hash. That is,
- * suppose that `PSA_xxx_SIGNATURE` is one of the following macros:
+ * This value may be used to form the algorithm usage field of a policy
+ * for a signature algorithm that is parametrized by a hash. The key
+ * may then be used to perform operations using the same signature
+ * algorithm parametrized with any supported hash.
+ *
+ * That is, suppose that `PSA_xxx_SIGNATURE` is one of the following macros:
* - #PSA_ALG_RSA_PKCS1V15_SIGN, #PSA_ALG_RSA_PSS,
* - #PSA_ALG_DSA, #PSA_ALG_DETERMINISTIC_DSA,
* - #PSA_ALG_ECDSA, #PSA_ALG_DETERMINISTIC_ECDSA.
- * Then you may create a key as follows:
+ * Then you may create and use a key as follows:
* - Set the key usage field using #PSA_ALG_ANY_HASH, for example:
* ```
* psa_key_policy_set_usage(&policy,
@@ -758,7 +747,7 @@
* algorithm is considered identical to the untruncated algorithm
* for policy comparison purposes.
*
- * \param alg A MAC algorithm identifier (value of type
+ * \param mac_alg A MAC algorithm identifier (value of type
* #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
* is true). This may be a truncated or untruncated
* MAC algorithm.
@@ -774,14 +763,14 @@
* MAC algorithm or if \p mac_length is too small or
* too large for the specified MAC algorithm.
*/
-#define PSA_ALG_TRUNCATED_MAC(alg, mac_length) \
- (((alg) & ~PSA_ALG_MAC_TRUNCATION_MASK) | \
+#define PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length) \
+ (((mac_alg) & ~PSA_ALG_MAC_TRUNCATION_MASK) | \
((mac_length) << PSA_MAC_TRUNCATION_OFFSET & PSA_ALG_MAC_TRUNCATION_MASK))
/** Macro to build the base MAC algorithm corresponding to a truncated
* MAC algorithm.
*
- * \param alg A MAC algorithm identifier (value of type
+ * \param mac_alg A MAC algorithm identifier (value of type
* #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
* is true). This may be a truncated or untruncated
* MAC algorithm.
@@ -790,12 +779,12 @@
* \return Unspecified if \p alg is not a supported
* MAC algorithm.
*/
-#define PSA_ALG_FULL_LENGTH_MAC(alg) \
- ((alg) & ~PSA_ALG_MAC_TRUNCATION_MASK)
+#define PSA_ALG_FULL_LENGTH_MAC(mac_alg) \
+ ((mac_alg) & ~PSA_ALG_MAC_TRUNCATION_MASK)
/** Length to which a MAC algorithm is truncated.
*
- * \param alg A MAC algorithm identifier (value of type
+ * \param mac_alg A MAC algorithm identifier (value of type
* #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
* is true).
*
@@ -804,8 +793,8 @@
* \return Unspecified if \p alg is not a supported
* MAC algorithm.
*/
-#define PSA_MAC_TRUNCATED_LENGTH(alg) \
- (((alg) & PSA_ALG_MAC_TRUNCATION_MASK) >> PSA_MAC_TRUNCATION_OFFSET)
+#define PSA_MAC_TRUNCATED_LENGTH(mac_alg) \
+ (((mac_alg) & PSA_ALG_MAC_TRUNCATION_MASK) >> PSA_MAC_TRUNCATION_OFFSET)
#define PSA_ALG_CIPHER_MAC_BASE ((psa_algorithm_t)0x02c00000)
#define PSA_ALG_CBC_MAC ((psa_algorithm_t)0x02c00001)
@@ -907,7 +896,7 @@
* Depending on the algorithm, the tag length may affect the calculation
* of the ciphertext.
*
- * \param alg A AEAD algorithm identifier (value of type
+ * \param aead_alg An AEAD algorithm identifier (value of type
* #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p alg)
* is true).
* \param tag_length Desired length of the authentication tag in bytes.
@@ -918,26 +907,26 @@
* AEAD algorithm or if \p tag_length is not valid
* for the specified AEAD algorithm.
*/
-#define PSA_ALG_AEAD_WITH_TAG_LENGTH(alg, tag_length) \
- (((alg) & ~PSA_ALG_AEAD_TAG_LENGTH_MASK) | \
+#define PSA_ALG_AEAD_WITH_TAG_LENGTH(aead_alg, tag_length) \
+ (((aead_alg) & ~PSA_ALG_AEAD_TAG_LENGTH_MASK) | \
((tag_length) << PSA_AEAD_TAG_LENGTH_OFFSET & \
PSA_ALG_AEAD_TAG_LENGTH_MASK))
/** Calculate the corresponding AEAD algorithm with the default tag length.
*
- * \param alg An AEAD algorithm (\c PSA_ALG_XXX value such that
- * #PSA_ALG_IS_AEAD(\p alg) is true).
+ * \param aead_alg An AEAD algorithm (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_AEAD(\p alg) is true).
*
- * \return The corresponding AEAD algorithm with the default tag length
- * for that algorithm.
+ * \return The corresponding AEAD algorithm with the default
+ * tag length for that algorithm.
*/
-#define PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH(alg) \
+#define PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH(aead_alg) \
( \
- PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(alg, PSA_ALG_CCM) \
- PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(alg, PSA_ALG_GCM) \
+ PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(aead_alg, PSA_ALG_CCM) \
+ PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(aead_alg, PSA_ALG_GCM) \
0)
-#define PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(alg, ref) \
- PSA_ALG_AEAD_WITH_TAG_LENGTH(alg, 0) == \
+#define PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(aead_alg, ref) \
+ PSA_ALG_AEAD_WITH_TAG_LENGTH(aead_alg, 0) == \
PSA_ALG_AEAD_WITH_TAG_LENGTH(ref, 0) ? \
ref :