Merge development commit 8e76332 into development-psa
Additional changes to temporarily enable running tests:
ssl_srv.c and test_suite_ecdh use mbedtls_ecp_group_load instead of
mbedtls_ecdh_setup
test_suite_ctr_drbg uses mbedtls_ctr_drbg_update instead of
mbedtls_ctr_drbg_update_ret
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/asn1write.h b/include/mbedtls/asn1write.h
index 76c1780..360540a 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) \
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..a54c18e 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,512 @@
* 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 Export X into unsigned binary data, big endian.
- * Always fills the whole buffer, which will start with zeros
- * if the number is smaller.
+ * \brief Export an MPI into unsigned big endian binary data
+ * of fixed size.
*
- * \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 Perform a left-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_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 +816,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 +855,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 +891,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 +921,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 +952,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..ac1e3f9 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) \
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 0a6f4bf..ab35e20 100644
--- a/include/mbedtls/check_config.h
+++ b/include/mbedtls/check_config.h
@@ -114,6 +114,7 @@
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"
#endif
@@ -137,6 +138,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"
diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h
index d6ecac6..e07ed44 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,13 +674,15 @@
#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 Bytes.
*
* \return \c 0 on success.
* \return A specific error code on failure.
@@ -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.
@@ -795,20 +834,27 @@
/**
* \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
@@ -829,20 +875,27 @@
* 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
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 9751d26..f8684ac 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -256,6 +256,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 */
/**
@@ -414,11 +456,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.
*
@@ -3033,6 +3075,36 @@
//#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 */
@@ -3041,31 +3113,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.
@@ -3075,11 +3181,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..2909f5f 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,6 +344,7 @@
*/
int mbedtls_dhm_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus
}
#endif
@@ -353,15 +392,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..4479a1d 100644
--- a/include/mbedtls/ecdh.h
+++ b/include/mbedtls/ecdh.h
@@ -34,8 +34,26 @@
#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"
+/*
+ * Use a backward compatible ECDH context.
+ *
+ * This flag is always enabled for now and future versions might add a
+ * configuration option that conditionally undefines this flag.
+ * The configuration option in question may have a different name.
+ *
+ * Features undefining this flag, must have a warning in their description in
+ * config.h stating that the feature breaks backward compatibility.
+ */
+#define MBEDTLS_ECDH_LEGACY_CONTEXT
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -49,6 +67,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 +109,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 +122,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 +155,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 +187,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 +216,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 +279,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 +315,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 +361,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 +393,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 +428,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..2401778 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"
/*
@@ -159,6 +165,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 +195,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 +322,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.
@@ -493,24 +503,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 +542,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 +555,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 +593,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 +606,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,15 +621,21 @@
* \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.
+ * \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 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,
@@ -615,108 +649,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.
- *
*/
-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 +814,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 +845,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 +863,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 +879,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 +914,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 +935,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 +960,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 +1024,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,34 +1056,42 @@
* 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 checks that the keypair objects
@@ -963,16 +1099,19 @@
* 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..7eae32b 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)
@@ -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/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 4f1b06f..f1ce746 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -202,13 +202,19 @@
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
*
+ * \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
* key slot and you still need to call psa_destroy_key()
@@ -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,
@@ -280,7 +293,8 @@
/**
* \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
*/
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_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/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..906c427 100644
--- a/include/mbedtls/rsa.h
+++ b/include/mbedtls/rsa.h
@@ -158,15 +158,16 @@
* making signatures, but can be overriden for verifying them.
* If set to #MBEDTLS_MD_NONE, it is always overriden.
*
- * \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,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, 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. This must not be \c NULL.
+ * \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 +620,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 +629,22 @@
* 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. This must not be \c NULL.
+ * \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 +672,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 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. This must not be \c NULL.
+ * \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 +716,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 +725,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 +765,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 +774,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 +816,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 +825,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 +883,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 +922,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 +931,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 +969,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 +995,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 +1033,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 +1046,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 +1083,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 +1092,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 +1132,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 +1149,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 +1194,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 +1235,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 +1246,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 +1262,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 3e38f15..64b6380 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -2066,6 +2066,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
diff --git a/include/mbedtls/ssl_cache.h b/include/mbedtls/ssl_cache.h
index ec081e6..52ba094 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)
diff --git a/include/mbedtls/ssl_ciphersuites.h b/include/mbedtls/ssl_ciphersuites.h
index cda8b48..71053e5 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"
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 fced2cb..2794ca9 100644
--- a/include/mbedtls/ssl_internal.h
+++ b/include/mbedtls/ssl_internal.h
@@ -24,6 +24,12 @@
#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"
diff --git a/include/mbedtls/ssl_ticket.h b/include/mbedtls/ssl_ticket.h
index b2686df..a84e781 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
diff --git a/include/mbedtls/version.h b/include/mbedtls/version.h
index 69e1db9..56e7398 100644
--- a/include/mbedtls/version.h
+++ b/include/mbedtls/version.h
@@ -39,17 +39,17 @@
* Major, Minor, Patchlevel
*/
#define MBEDTLS_VERSION_MAJOR 2
-#define MBEDTLS_VERSION_MINOR 15
-#define MBEDTLS_VERSION_PATCH 1
+#define MBEDTLS_VERSION_MINOR 16
+#define MBEDTLS_VERSION_PATCH 0
/**
* The single version number has the following structure:
* MMNNPP00
* Major version | Minor version | Patch version
*/
-#define MBEDTLS_VERSION_NUMBER 0x020F0100
-#define MBEDTLS_VERSION_STRING "2.15.1"
-#define MBEDTLS_VERSION_STRING_FULL "mbed TLS 2.15.1"
+#define MBEDTLS_VERSION_NUMBER 0x02100000
+#define MBEDTLS_VERSION_STRING "2.16.0"
+#define MBEDTLS_VERSION_STRING_FULL "mbed TLS 2.16.0"
#if defined(MBEDTLS_VERSION_C)
diff --git a/include/mbedtls/x509.h b/include/mbedtls/x509.h
index d6db9c6..9ae825c 100644
--- a/include/mbedtls/x509.h
+++ b/include/mbedtls/x509.h
@@ -269,6 +269,8 @@
*/
int mbedtls_x509_time_is_future( const mbedtls_x509_time *from );
+#if defined(MBEDTLS_SELF_TEST)
+
/**
* \brief Checkup routine
*
@@ -276,6 +278,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_crt.h b/include/mbedtls/x509_crt.h
index afeefca..3dd5922 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -232,19 +232,34 @@
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 one DER-encoded or one or more concatenated PEM-encoded
+ * certificates and add them to the chained list.
*
- * \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)
+ * 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.
*
- * \return 0 if all certificates parsed successfully, a positive number
- * if partly successful or a specific X509 or PEM error code
+ * 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/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