Merge remote-tracking branch 'upstream-restricted/pr/421' into development-proposed
diff --git a/ChangeLog b/ChangeLog
index fe588a4..7b50534 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -2,30 +2,7 @@
= mbed TLS x.x.x branch released xxxx-xx-xx
-Security
- * Fix a bug in the X.509 module potentially leading to a buffer overread
- during CRT verification or to invalid or omitted checks for certificate
- validity. The former can be triggered remotely, while the latter requires
- a non DER-compliant certificate correctly signed by a trusted CA, or a
- trusted CA with a non DER-compliant certificate. Found by luocm on GitHub.
- Fixes #825.
-
-Features
- * Add option MBEDTLS_AES_FEWER_TABLES to dynamically compute 3/4 of the AES tables
- during runtime, thereby reducing the RAM/ROM footprint by ~6kb. Suggested
- and contributed by jkivilin in #394.
- * Add initial support for Curve448 (RFC 7748). Only mbedtls_ecp_mul() and
- ECDH primitive functions (mbedtls_ecdh_gen_public(),
- mbedtls_ecdh_compute_shared()) are supported for now. Contributed by
- Nicholas Wilson (#348).
-
API Changes
- * Add function mbedtls_net_poll to public API allowing to wait for a
- network context to become ready for reading or writing.
- * Add function mbedtls_ssl_check_pending to public API allowing to check
- if more data is pending to be processed in the internal message buffers.
- This function is necessary to determine when it is safe to idle on the
- underlying transport in case event-driven IO is used.
* Extend the platform module with a util component that contains
functionality shared by multiple Mbed TLS modules. At this stage
platform_util.h (and its associated platform_util.c) only contain
@@ -36,8 +13,49 @@
Therefore, mbedtls_platform_zeroize() is moved to the platform module to
facilitate testing and maintenance.
+= mbed TLS 2.9.0 branch released 2018-04-30
+
+Security
+ * Fix an issue in the X.509 module which could lead to a buffer overread
+ during certificate validation. Additionally, the issue could also lead to
+ unnecessary callback checks being made or to some validation checks to be
+ omitted. The overread could be triggered remotely, while the other issues
+ would require a non DER-compliant certificate to be correctly signed by a
+ trusted CA, or a trusted CA with a non DER-compliant certificate. Found by
+ luocm. Fixes #825.
+ * Fix the buffer length assertion in the ssl_parse_certificate_request()
+ function which led to an arbitrary overread of the message buffer. The
+ overreads could be caused by receiving a malformed message at the point
+ where an optional signature algorithms list is expected when the signature
+ algorithms section is too short. In builds with debug output, the overread
+ data is output with the debug data.
+ * Fix a client-side bug in the validation of the server's ciphersuite choice
+ which could potentially lead to the client accepting a ciphersuite it didn't
+ offer or a ciphersuite that cannot be used with the TLS or DTLS version
+ chosen by the server. This could lead to corruption of internal data
+ structures for some configurations.
+
+Features
+ * Add an option, MBEDTLS_AES_FEWER_TABLES, to dynamically compute smaller AES
+ tables during runtime, thereby reducing the RAM/ROM footprint by ~6KiB.
+ Suggested and contributed by jkivilin in pull request #394.
+ * Add initial support for Curve448 (RFC 7748). Only mbedtls_ecp_mul() and
+ ECDH primitive functions (mbedtls_ecdh_gen_public(),
+ mbedtls_ecdh_compute_shared()) are supported for now. Contributed by
+ Nicholas Wilson in pull request #348.
+
+API Changes
+ * Extend the public API with the function of mbedtls_net_poll() to allow user
+ applications to wait for a network context to become ready before reading
+ or writing.
+ * Add function mbedtls_ssl_check_pending() to the public API to allow
+ a check for whether more more data is pending to be processed in the
+ internal message buffers.
+ This function is necessary to determine when it is safe to idle on the
+ underlying transport in case event-driven IO is used.
+
Bugfix
- * Fix spurious uninitialized variable warning in cmac.c. Fix independently
+ * Fix a spurious uninitialized variable warning in cmac.c. Fix independently
contributed by Brian J Murray and David Brown.
* Add missing dependencies in test suites that led to build failures
in configurations that omit certain hashes or public-key algorithms.
@@ -45,15 +63,16 @@
* Fix C89 incompatibility in benchmark.c. Contributed by Brendan Shanks.
#1353
* Add missing dependencies for MBEDTLS_HAVE_TIME_DATE and
- MBEDTLS_VERSION_FEATURES in test suites. Contributed by Deomid Ryabkov.
- Fixes #1299, #1475.
- * Fix dynamic library building process with Makefile on Mac OS X. Fixed by
- mnacamura.
+ MBEDTLS_VERSION_FEATURES in some test suites. Contributed by
+ Deomid Ryabkov. Fixes #1299, #1475.
+ * Fix the Makefile build process for building shared libraries on Mac OS X.
+ Fixed by mnacamura.
* Fix parsing of PKCS#8 encoded Elliptic Curve keys. Previously Mbed TLS was
- unable to parse keys with only the optional parameters field of the
- ECPrivateKey structure. Found by jethrogb, fixed in #1379.
- * Return plaintext data sooner on unpadded CBC decryption, as stated in
- the mbedtls_cipher_update() documentation. Contributed by Andy Leiserson.
+ unable to parse keys which had only the optional parameters field of the
+ ECPrivateKey structure. Found by Jethro Beekman, fixed in #1379.
+ * Return the plaintext data more quickly on unpadded CBC decryption, as
+ stated in the mbedtls_cipher_update() documentation. Contributed by
+ Andy Leiserson.
* Fix overriding and ignoring return values when parsing and writing to
a file in pk_sign program. Found by kevlut in #1142.
* Restrict usage of error code MBEDTLS_ERR_SSL_WANT_READ to situations
@@ -61,24 +80,32 @@
to make progress. Previously, this error code was also occasionally
returned when unexpected messages were being discarded, ignoring that
further messages could potentially already be pending to be processed
- in the internal buffers; these cases lead to deadlocks in case
- event-driven I/O was used.
- Found and reported by Hubert Mis in #772.
+ in the internal buffers; these cases led to deadlocks when event-driven
+ I/O was used. Found and reported by Hubert Mis in #772.
+ * Fix buffer length assertions in the ssl_parse_certificate_request()
+ function which leads to a potential one byte overread of the message
+ buffer.
+ * Fix invalid buffer sizes passed to zlib during record compression and
+ decompression.
+ * Fix the soversion of libmbedcrypto to match the soversion of the
+ maintained 2.7 branch. The soversion was increased in Mbed TLS
+ version 2.7.1 to reflect breaking changes in that release, but the
+ increment was missed in 2.8.0 and later releases outside of the 2.7 branch.
Changes
* Remove some redundant code in bignum.c. Contributed by Alexey Skalozub.
- * Support cmake build where Mbed TLS is a subproject. Fix
- contributed independently by Matthieu Volat and Arne Schwabe.
+ * Support cmake builds where Mbed TLS is a subproject. Fix contributed
+ independently by Matthieu Volat and Arne Schwabe.
* Improve testing in configurations that omit certain hashes or
public-key algorithms. Includes contributions by Gert van Dijk.
* Improve negative testing of X.509 parsing.
* Do not define global mutexes around readdir() and gmtime() in
configurations where the feature is disabled. Found and fixed by Gergely
Budai.
- * Harden mbedtls_ssl_config_free() against misuse, so that it doesn't
- leak memory in case the user doesn't use mbedtls_ssl_conf_psk() and
- instead incorrectly manipulates conf->psk and/or conf->psk_identity
- directly. Found and fix submitted by junyeonLEE in #1220.
+ * Harden the function mbedtls_ssl_config_free() against misuse, so that it
+ doesn't leak memory if the user doesn't use mbedtls_ssl_conf_psk() and
+ instead incorrectly manipulates the configuration structure directly.
+ Found and fix submitted by junyeonLEE in #1220.
* Provide an empty implementation of mbedtls_pkcs5_pbes2() when
MBEDTLS_ASN1_PARSE_C is not enabled. This allows the use of PBKDF2
without PBES2. Fixed by Marcos Del Sol Vives.
@@ -89,7 +116,7 @@
Krylov.
* Improve the documentation of mbedtls_ssl_write(). Suggested by
Paul Sokolovsky in #1356.
- * Add an option in the makefile to support ar utilities where the operation
+ * Add an option in the Makefile to support ar utilities where the operation
letter must not be prefixed by '-', such as LLVM. Found and fixed by
Alex Hixon.
* Allow configuring the shared library extension by setting the DLEXT
@@ -102,6 +129,14 @@
* Improve robustness of mbedtls_ssl_derive_keys against the use of
HMAC functions with non-HMAC ciphersuites. Independently contributed
by Jiayuan Chen in #1377. Fixes #1437.
+ * Improve security of RSA key generation by including criteria from
+ FIPS 186-4. Contributed by Jethro Beekman. #1380
+ * Declare functions in header files even when an alternative implementation
+ of the corresponding module is activated by defining the corresponding
+ MBEDTLS_XXX_ALT macro. This means that alternative implementations do
+ not need to copy the declarations, and ensures that they will have the
+ same API.
+ * Add platform setup and teardown calls in test suites.
= mbed TLS 2.8.0 branch released 2018-03-16
@@ -299,7 +334,7 @@
* Fix ssl_parse_record_header() to silently discard invalid DTLS records
as recommended in RFC 6347 Section 4.1.2.7.
* Fix memory leak in mbedtls_ssl_set_hostname() when called multiple times.
- Found by projectgus and jethrogb, #836.
+ Found by projectgus and Jethro Beekman, #836.
* Fix usage help in ssl_server2 example. Found and fixed by Bei Lin.
* Parse signature algorithm extension when renegotiating. Previously,
renegotiated handshakes would only accept signatures using SHA-1
@@ -493,8 +528,7 @@
Previous behaviour was to keep processing data even after the alert has
been sent.
* Accept empty trusted CA chain in authentication mode
- MBEDTLS_SSL_VERIFY_OPTIONAL.
- Found by jethrogb. #864
+ MBEDTLS_SSL_VERIFY_OPTIONAL. Found by Jethro Beekman. #864
* Fix implementation of mbedtls_ssl_parse_certificate() to not annihilate
fatal errors in authentication mode MBEDTLS_SSL_VERIFY_OPTIONAL and to
reflect bad EC curves within verification result.
diff --git a/doxygen/input/doc_mainpage.h b/doxygen/input/doc_mainpage.h
index 7952cbc..e27c221 100644
--- a/doxygen/input/doc_mainpage.h
+++ b/doxygen/input/doc_mainpage.h
@@ -24,7 +24,7 @@
*/
/**
- * @mainpage mbed TLS v2.8.0 source code documentation
+ * @mainpage mbed TLS v2.9.0 source code documentation
*
* This documentation describes the internal structure of mbed TLS. It was
* automatically generated from specially formatted comment blocks in
diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile
index 3592af2..510fa85 100644
--- a/doxygen/mbedtls.doxyfile
+++ b/doxygen/mbedtls.doxyfile
@@ -28,7 +28,7 @@
# identify the project. Note that if you do not use Doxywizard you need
# to put quotes around the project name if it contains spaces.
-PROJECT_NAME = "mbed TLS v2.8.0"
+PROJECT_NAME = "mbed TLS v2.9.0"
# The PROJECT_NUMBER tag can be used to enter a project or revision number.
# This could be handy for archiving the generated documentation or
@@ -702,7 +702,7 @@
# directories that are symbolic links (a Unix file system feature) are excluded
# from the input.
-EXCLUDE_SYMLINKS = NO
+EXCLUDE_SYMLINKS = YES
# If the value of the INPUT tag contains directories, you can use the
# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h
index 46016dc..e0fc238 100644
--- a/include/mbedtls/aes.h
+++ b/include/mbedtls/aes.h
@@ -1,7 +1,9 @@
/**
* \file aes.h
*
- * \brief The Advanced Encryption Standard (AES) specifies a FIPS-approved
+ * \brief This file contains AES definitions and functions.
+ *
+ * The Advanced Encryption Standard (AES) specifies a FIPS-approved
* cryptographic algorithm that can be used to protect electronic
* data.
*
@@ -12,6 +14,7 @@
* techniques -- Encryption algorithms -- Part 2: Asymmetric
* ciphers</em>.
*/
+
/* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
* SPDX-License-Identifier: Apache-2.0
*
@@ -59,14 +62,14 @@
#define inline __inline
#endif
-#if !defined(MBEDTLS_AES_ALT)
-// Regular implementation
-//
-
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_AES_ALT)
+// Regular implementation
+//
+
/**
* \brief The AES context-type definition.
*/
@@ -85,6 +88,10 @@
}
mbedtls_aes_context;
+#else /* MBEDTLS_AES_ALT */
+#include "aes_alt.h"
+#endif /* MBEDTLS_AES_ALT */
+
/**
* \brief This function initializes the specified AES context.
*
@@ -112,8 +119,8 @@
* <li>192 bits</li>
* <li>256 bits</li></ul>
*
- * \return \c 0 on success or #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH
- * on failure.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
*/
int mbedtls_aes_setkey_enc( mbedtls_aes_context *ctx, const unsigned char *key,
unsigned int keybits );
@@ -128,7 +135,8 @@
* <li>192 bits</li>
* <li>256 bits</li></ul>
*
- * \return \c 0 on success, or #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
*/
int mbedtls_aes_setkey_dec( mbedtls_aes_context *ctx, const unsigned char *key,
unsigned int keybits );
@@ -192,7 +200,8 @@
* \param input The buffer holding the input data.
* \param output The buffer holding the output data.
*
- * \return \c 0 on success, or #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
* on failure.
*/
int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx,
@@ -313,7 +322,7 @@
* \param input The buffer holding the input data.
* \param output The buffer holding the output data.
*
- * \return \c 0 on success.
+ * \return \c 0 on success.
*/
int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx,
size_t length,
@@ -391,22 +400,11 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_AES_ALT */
-#include "aes_alt.h"
-#endif /* MBEDTLS_AES_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
/**
* \brief Checkup routine.
*
- * \return \c 0 on success, or \c 1 on failure.
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_aes_self_test( int verbose );
diff --git a/include/mbedtls/arc4.h b/include/mbedtls/arc4.h
index f9d93f8..f11fc5b 100644
--- a/include/mbedtls/arc4.h
+++ b/include/mbedtls/arc4.h
@@ -38,14 +38,14 @@
#define MBEDTLS_ERR_ARC4_HW_ACCEL_FAILED -0x0019 /**< ARC4 hardware accelerator failed. */
-#if !defined(MBEDTLS_ARC4_ALT)
-// Regular implementation
-//
-
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_ARC4_ALT)
+// Regular implementation
+//
+
/**
* \brief ARC4 context structure
*
@@ -61,6 +61,10 @@
}
mbedtls_arc4_context;
+#else /* MBEDTLS_ARC4_ALT */
+#include "arc4_alt.h"
+#endif /* MBEDTLS_ARC4_ALT */
+
/**
* \brief Initialize ARC4 context
*
@@ -118,18 +122,6 @@
int mbedtls_arc4_crypt( mbedtls_arc4_context *ctx, size_t length, const unsigned char *input,
unsigned char *output );
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_ARC4_ALT */
-#include "arc4_alt.h"
-#endif /* MBEDTLS_ARC4_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
/**
* \brief Checkup routine
*
diff --git a/include/mbedtls/blowfish.h b/include/mbedtls/blowfish.h
index c0ef5a0..22479be 100644
--- a/include/mbedtls/blowfish.h
+++ b/include/mbedtls/blowfish.h
@@ -44,14 +44,14 @@
#define MBEDTLS_ERR_BLOWFISH_HW_ACCEL_FAILED -0x0017 /**< Blowfish hardware accelerator failed. */
#define MBEDTLS_ERR_BLOWFISH_INVALID_INPUT_LENGTH -0x0018 /**< Invalid data input length. */
-#if !defined(MBEDTLS_BLOWFISH_ALT)
-// Regular implementation
-//
-
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_BLOWFISH_ALT)
+// Regular implementation
+//
+
/**
* \brief Blowfish context structure
*/
@@ -62,6 +62,10 @@
}
mbedtls_blowfish_context;
+#else /* MBEDTLS_BLOWFISH_ALT */
+#include "blowfish_alt.h"
+#endif /* MBEDTLS_BLOWFISH_ALT */
+
/**
* \brief Initialize Blowfish context
*
@@ -198,8 +202,4 @@
}
#endif
-#else /* MBEDTLS_BLOWFISH_ALT */
-#include "blowfish_alt.h"
-#endif /* MBEDTLS_BLOWFISH_ALT */
-
#endif /* blowfish.h */
diff --git a/include/mbedtls/camellia.h b/include/mbedtls/camellia.h
index cf07629..f0466bf 100644
--- a/include/mbedtls/camellia.h
+++ b/include/mbedtls/camellia.h
@@ -40,14 +40,14 @@
#define MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH -0x0026 /**< Invalid data input length. */
#define MBEDTLS_ERR_CAMELLIA_HW_ACCEL_FAILED -0x0027 /**< Camellia hardware accelerator failed. */
-#if !defined(MBEDTLS_CAMELLIA_ALT)
-// Regular implementation
-//
-
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_CAMELLIA_ALT)
+// Regular implementation
+//
+
/**
* \brief CAMELLIA context structure
*/
@@ -58,6 +58,10 @@
}
mbedtls_camellia_context;
+#else /* MBEDTLS_CAMELLIA_ALT */
+#include "camellia_alt.h"
+#endif /* MBEDTLS_CAMELLIA_ALT */
+
/**
* \brief Initialize CAMELLIA context
*
@@ -211,18 +215,6 @@
unsigned char *output );
#endif /* MBEDTLS_CIPHER_MODE_CTR */
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_CAMELLIA_ALT */
-#include "camellia_alt.h"
-#endif /* MBEDTLS_CAMELLIA_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
/**
* \brief Checkup routine
*
diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h
index 630b7fd..8585ce5 100644
--- a/include/mbedtls/ccm.h
+++ b/include/mbedtls/ccm.h
@@ -1,8 +1,11 @@
/**
* \file ccm.h
*
- * \brief CCM combines Counter mode encryption with CBC-MAC authentication
- * for 128-bit block ciphers.
+ * \brief This file provides an API for the CCM authenticated encryption
+ * mode for block ciphers.
+ *
+ * CCM combines Counter mode encryption with CBC-MAC authentication
+ * for 128-bit block ciphers.
*
* Input to CCM includes the following elements:
* <ul><li>Payload - data that is both authenticated and encrypted.</li>
@@ -40,14 +43,15 @@
#define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F /**< Authenticated decryption failed. */
#define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */
-#if !defined(MBEDTLS_CCM_ALT)
-// Regular implementation
-//
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_CCM_ALT)
+// Regular implementation
+//
+
/**
* \brief The CCM context-type definition. The CCM context is passed
* to the APIs called.
@@ -57,6 +61,10 @@
}
mbedtls_ccm_context;
+#else /* MBEDTLS_CCM_ALT */
+#include "ccm_alt.h"
+#endif /* MBEDTLS_CCM_ALT */
+
/**
* \brief This function initializes the specified CCM context,
* to make references valid, and prepare the context
@@ -75,7 +83,8 @@
* \param key The encryption key.
* \param keybits The key size in bits. This must be acceptable by the cipher.
*
- * \return \c 0 on success, or a cipher-specific error code.
+ * \return \c 0 on success.
+ * \return A CCM or cipher-specific error code on failure.
*/
int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx,
mbedtls_cipher_id_t cipher,
@@ -93,6 +102,13 @@
/**
* \brief This function encrypts a buffer using CCM.
*
+ *
+ * \note The tag is written to a separate buffer. To concatenate
+ * the \p tag with the \p output, as done in <em>RFC-3610:
+ * Counter with CBC-MAC (CCM)</em>, use
+ * \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 length The length of the input data in Bytes.
* \param iv Initialization vector (nonce).
@@ -107,13 +123,8 @@
* \param tag_len The length of the tag to generate in Bytes:
* 4, 6, 8, 10, 12, 14 or 16.
*
- * \note The tag is written to a separate buffer. To concatenate
- * the \p tag with the \p output, as done in <em>RFC-3610:
- * Counter with CBC-MAC (CCM)</em>, use
- * \p tag = \p output + \p length, and make sure that the
- * output buffer is at least \p length + \p tag_len wide.
- *
* \return \c 0 on success.
+ * \return A CCM or cipher-specific error code on failure.
*/
int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
const unsigned char *iv, size_t iv_len,
@@ -139,8 +150,9 @@
* \param tag_len The length of the tag in Bytes.
* 4, 6, 8, 10, 12, 14 or 16.
*
- * \return 0 if successful and authenticated, or
- * #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
+ * \return \c 0 on success. This indicates that the message is authentic.
+ * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
+ * \return A cipher-specific error code on calculation failure.
*/
int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
const unsigned char *iv, size_t iv_len,
@@ -148,23 +160,13 @@
const unsigned char *input, unsigned char *output,
const unsigned char *tag, size_t tag_len );
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_CCM_ALT */
-#include "ccm_alt.h"
-#endif /* MBEDTLS_CCM_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
#if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C)
/**
* \brief The CCM checkup routine.
*
- * \return \c 0 on success, or \c 1 on failure.
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_ccm_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */
diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h
index d1f4efe..3ee2ab7 100644
--- a/include/mbedtls/cipher.h
+++ b/include/mbedtls/cipher.h
@@ -1,7 +1,9 @@
/**
* \file cipher.h
*
- * \brief The generic cipher wrapper.
+ * \brief This file contains an abstraction interface for use with the cipher
+ * primitives provided by the library. It provides a common interface to all of
+ * the available cipher operations.
*
* \author Adriaan de Jong <dejong@fox-it.com>
*/
@@ -69,93 +71,93 @@
#endif
/**
- * \brief An enumeration of supported ciphers.
+ * \brief Supported cipher types.
*
- * \warning ARC4 and DES are considered weak ciphers and their use
- * constitutes a security risk. We recommend considering stronger
+ * \warning RC4 and DES are considered weak ciphers and their use
+ * constitutes a security risk. Arm recommends considering stronger
* ciphers instead.
*/
typedef enum {
- MBEDTLS_CIPHER_ID_NONE = 0,
- MBEDTLS_CIPHER_ID_NULL,
- MBEDTLS_CIPHER_ID_AES,
- MBEDTLS_CIPHER_ID_DES,
- MBEDTLS_CIPHER_ID_3DES,
- MBEDTLS_CIPHER_ID_CAMELLIA,
- MBEDTLS_CIPHER_ID_BLOWFISH,
- MBEDTLS_CIPHER_ID_ARC4,
+ MBEDTLS_CIPHER_ID_NONE = 0, /**< Placeholder to mark the end of cipher ID lists. */
+ MBEDTLS_CIPHER_ID_NULL, /**< The identity cipher, treated as a stream cipher. */
+ MBEDTLS_CIPHER_ID_AES, /**< The AES cipher. */
+ MBEDTLS_CIPHER_ID_DES, /**< The DES cipher. */
+ MBEDTLS_CIPHER_ID_3DES, /**< The Triple DES cipher. */
+ MBEDTLS_CIPHER_ID_CAMELLIA, /**< The Camellia cipher. */
+ MBEDTLS_CIPHER_ID_BLOWFISH, /**< The Blowfish cipher. */
+ MBEDTLS_CIPHER_ID_ARC4, /**< The RC4 cipher. */
} mbedtls_cipher_id_t;
/**
- * \brief An enumeration of supported (cipher, mode) pairs.
+ * \brief Supported {cipher type, cipher mode} pairs.
*
- * \warning ARC4 and DES are considered weak ciphers and their use
- * constitutes a security risk. We recommend considering stronger
+ * \warning RC4 and DES are considered weak ciphers and their use
+ * constitutes a security risk. Arm recommends considering stronger
* ciphers instead.
*/
typedef enum {
- MBEDTLS_CIPHER_NONE = 0,
- MBEDTLS_CIPHER_NULL,
- MBEDTLS_CIPHER_AES_128_ECB,
- MBEDTLS_CIPHER_AES_192_ECB,
- MBEDTLS_CIPHER_AES_256_ECB,
- MBEDTLS_CIPHER_AES_128_CBC,
- MBEDTLS_CIPHER_AES_192_CBC,
- MBEDTLS_CIPHER_AES_256_CBC,
- MBEDTLS_CIPHER_AES_128_CFB128,
- MBEDTLS_CIPHER_AES_192_CFB128,
- MBEDTLS_CIPHER_AES_256_CFB128,
- MBEDTLS_CIPHER_AES_128_CTR,
- MBEDTLS_CIPHER_AES_192_CTR,
- MBEDTLS_CIPHER_AES_256_CTR,
- MBEDTLS_CIPHER_AES_128_GCM,
- MBEDTLS_CIPHER_AES_192_GCM,
- MBEDTLS_CIPHER_AES_256_GCM,
- MBEDTLS_CIPHER_CAMELLIA_128_ECB,
- MBEDTLS_CIPHER_CAMELLIA_192_ECB,
- MBEDTLS_CIPHER_CAMELLIA_256_ECB,
- MBEDTLS_CIPHER_CAMELLIA_128_CBC,
- MBEDTLS_CIPHER_CAMELLIA_192_CBC,
- MBEDTLS_CIPHER_CAMELLIA_256_CBC,
- MBEDTLS_CIPHER_CAMELLIA_128_CFB128,
- MBEDTLS_CIPHER_CAMELLIA_192_CFB128,
- MBEDTLS_CIPHER_CAMELLIA_256_CFB128,
- MBEDTLS_CIPHER_CAMELLIA_128_CTR,
- MBEDTLS_CIPHER_CAMELLIA_192_CTR,
- MBEDTLS_CIPHER_CAMELLIA_256_CTR,
- MBEDTLS_CIPHER_CAMELLIA_128_GCM,
- MBEDTLS_CIPHER_CAMELLIA_192_GCM,
- MBEDTLS_CIPHER_CAMELLIA_256_GCM,
- MBEDTLS_CIPHER_DES_ECB,
- MBEDTLS_CIPHER_DES_CBC,
- MBEDTLS_CIPHER_DES_EDE_ECB,
- MBEDTLS_CIPHER_DES_EDE_CBC,
- MBEDTLS_CIPHER_DES_EDE3_ECB,
- MBEDTLS_CIPHER_DES_EDE3_CBC,
- MBEDTLS_CIPHER_BLOWFISH_ECB,
- MBEDTLS_CIPHER_BLOWFISH_CBC,
- MBEDTLS_CIPHER_BLOWFISH_CFB64,
- MBEDTLS_CIPHER_BLOWFISH_CTR,
- MBEDTLS_CIPHER_ARC4_128,
- MBEDTLS_CIPHER_AES_128_CCM,
- MBEDTLS_CIPHER_AES_192_CCM,
- MBEDTLS_CIPHER_AES_256_CCM,
- MBEDTLS_CIPHER_CAMELLIA_128_CCM,
- MBEDTLS_CIPHER_CAMELLIA_192_CCM,
- MBEDTLS_CIPHER_CAMELLIA_256_CCM,
+ MBEDTLS_CIPHER_NONE = 0, /**< Placeholder to mark the end of cipher-pair lists. */
+ MBEDTLS_CIPHER_NULL, /**< The identity stream cipher. */
+ MBEDTLS_CIPHER_AES_128_ECB, /**< AES cipher with 128-bit ECB mode. */
+ MBEDTLS_CIPHER_AES_192_ECB, /**< AES cipher with 192-bit ECB mode. */
+ MBEDTLS_CIPHER_AES_256_ECB, /**< AES cipher with 256-bit ECB mode. */
+ MBEDTLS_CIPHER_AES_128_CBC, /**< AES cipher with 128-bit CBC mode. */
+ MBEDTLS_CIPHER_AES_192_CBC, /**< AES cipher with 192-bit CBC mode. */
+ MBEDTLS_CIPHER_AES_256_CBC, /**< AES cipher with 256-bit CBC mode. */
+ MBEDTLS_CIPHER_AES_128_CFB128, /**< AES cipher with 128-bit CFB128 mode. */
+ MBEDTLS_CIPHER_AES_192_CFB128, /**< AES cipher with 192-bit CFB128 mode. */
+ MBEDTLS_CIPHER_AES_256_CFB128, /**< AES cipher with 256-bit CFB128 mode. */
+ MBEDTLS_CIPHER_AES_128_CTR, /**< AES cipher with 128-bit CTR mode. */
+ MBEDTLS_CIPHER_AES_192_CTR, /**< AES cipher with 192-bit CTR mode. */
+ MBEDTLS_CIPHER_AES_256_CTR, /**< AES cipher with 256-bit CTR mode. */
+ MBEDTLS_CIPHER_AES_128_GCM, /**< AES cipher with 128-bit GCM mode. */
+ MBEDTLS_CIPHER_AES_192_GCM, /**< AES cipher with 192-bit GCM mode. */
+ MBEDTLS_CIPHER_AES_256_GCM, /**< AES cipher with 256-bit GCM mode. */
+ MBEDTLS_CIPHER_CAMELLIA_128_ECB, /**< Camellia cipher with 128-bit ECB mode. */
+ MBEDTLS_CIPHER_CAMELLIA_192_ECB, /**< Camellia cipher with 192-bit ECB mode. */
+ MBEDTLS_CIPHER_CAMELLIA_256_ECB, /**< Camellia cipher with 256-bit ECB mode. */
+ MBEDTLS_CIPHER_CAMELLIA_128_CBC, /**< Camellia cipher with 128-bit CBC mode. */
+ MBEDTLS_CIPHER_CAMELLIA_192_CBC, /**< Camellia cipher with 192-bit CBC mode. */
+ MBEDTLS_CIPHER_CAMELLIA_256_CBC, /**< Camellia cipher with 256-bit CBC mode. */
+ MBEDTLS_CIPHER_CAMELLIA_128_CFB128, /**< Camellia cipher with 128-bit CFB128 mode. */
+ MBEDTLS_CIPHER_CAMELLIA_192_CFB128, /**< Camellia cipher with 192-bit CFB128 mode. */
+ MBEDTLS_CIPHER_CAMELLIA_256_CFB128, /**< Camellia cipher with 256-bit CFB128 mode. */
+ MBEDTLS_CIPHER_CAMELLIA_128_CTR, /**< Camellia cipher with 128-bit CTR mode. */
+ MBEDTLS_CIPHER_CAMELLIA_192_CTR, /**< Camellia cipher with 192-bit CTR mode. */
+ MBEDTLS_CIPHER_CAMELLIA_256_CTR, /**< Camellia cipher with 256-bit CTR mode. */
+ MBEDTLS_CIPHER_CAMELLIA_128_GCM, /**< Camellia cipher with 128-bit GCM mode. */
+ MBEDTLS_CIPHER_CAMELLIA_192_GCM, /**< Camellia cipher with 192-bit GCM mode. */
+ MBEDTLS_CIPHER_CAMELLIA_256_GCM, /**< Camellia cipher with 256-bit GCM mode. */
+ MBEDTLS_CIPHER_DES_ECB, /**< DES cipher with ECB mode. */
+ MBEDTLS_CIPHER_DES_CBC, /**< DES cipher with CBC mode. */
+ MBEDTLS_CIPHER_DES_EDE_ECB, /**< DES cipher with EDE ECB mode. */
+ MBEDTLS_CIPHER_DES_EDE_CBC, /**< DES cipher with EDE CBC mode. */
+ MBEDTLS_CIPHER_DES_EDE3_ECB, /**< DES cipher with EDE3 ECB mode. */
+ MBEDTLS_CIPHER_DES_EDE3_CBC, /**< DES cipher with EDE3 CBC mode. */
+ MBEDTLS_CIPHER_BLOWFISH_ECB, /**< Blowfish cipher with ECB mode. */
+ MBEDTLS_CIPHER_BLOWFISH_CBC, /**< Blowfish cipher with CBC mode. */
+ MBEDTLS_CIPHER_BLOWFISH_CFB64, /**< Blowfish cipher with CFB64 mode. */
+ MBEDTLS_CIPHER_BLOWFISH_CTR, /**< Blowfish cipher with CTR mode. */
+ MBEDTLS_CIPHER_ARC4_128, /**< RC4 cipher with 128-bit mode. */
+ MBEDTLS_CIPHER_AES_128_CCM, /**< AES cipher with 128-bit CCM mode. */
+ MBEDTLS_CIPHER_AES_192_CCM, /**< AES cipher with 192-bit CCM mode. */
+ MBEDTLS_CIPHER_AES_256_CCM, /**< AES cipher with 256-bit CCM mode. */
+ MBEDTLS_CIPHER_CAMELLIA_128_CCM, /**< Camellia cipher with 128-bit CCM mode. */
+ MBEDTLS_CIPHER_CAMELLIA_192_CCM, /**< Camellia cipher with 192-bit CCM mode. */
+ MBEDTLS_CIPHER_CAMELLIA_256_CCM, /**< Camellia cipher with 256-bit CCM mode. */
} mbedtls_cipher_type_t;
/** Supported cipher modes. */
typedef enum {
- MBEDTLS_MODE_NONE = 0,
- MBEDTLS_MODE_ECB,
- MBEDTLS_MODE_CBC,
- MBEDTLS_MODE_CFB,
- MBEDTLS_MODE_OFB, /* Unused! */
- MBEDTLS_MODE_CTR,
- MBEDTLS_MODE_GCM,
- MBEDTLS_MODE_STREAM,
- MBEDTLS_MODE_CCM,
+ MBEDTLS_MODE_NONE = 0, /**< None. */
+ MBEDTLS_MODE_ECB, /**< The ECB cipher mode. */
+ MBEDTLS_MODE_CBC, /**< The CBC cipher mode. */
+ MBEDTLS_MODE_CFB, /**< The CFB cipher mode. */
+ MBEDTLS_MODE_OFB, /**< The OFB cipher mode - unsupported. */
+ MBEDTLS_MODE_CTR, /**< The CTR cipher mode. */
+ MBEDTLS_MODE_GCM, /**< The GCM cipher mode. */
+ MBEDTLS_MODE_STREAM, /**< The stream cipher mode. */
+ MBEDTLS_MODE_CCM, /**< The CCM cipher mode. */
} mbedtls_cipher_mode_t;
/** Supported cipher padding types. */
@@ -163,8 +165,8 @@
MBEDTLS_PADDING_PKCS7 = 0, /**< PKCS7 padding (default). */
MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding. */
MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding. */
- MBEDTLS_PADDING_ZEROS, /**< zero padding (not reversible). */
- MBEDTLS_PADDING_NONE, /**< never pad (full blocks only). */
+ MBEDTLS_PADDING_ZEROS, /**< Zero padding (not reversible). */
+ MBEDTLS_PADDING_NONE, /**< Never pad (full blocks only). */
} mbedtls_cipher_padding_t;
/** Type of operation. */
@@ -228,7 +230,10 @@
*/
unsigned int iv_size;
- /** Flags to set. For example, if the cipher supports variable IV sizes or variable key sizes. */
+ /** Bitflag comprised of MBEDTLS_CIPHER_VARIABLE_IV_LEN and
+ * MBEDTLS_CIPHER_VARIABLE_KEY_LEN indicating whether the
+ * cipher supports variable IV or variable key sizes, respectively.
+ */
int flags;
/** The block size, in Bytes. */
@@ -299,7 +304,8 @@
* \param cipher_name Name of the cipher to search for.
*
* \return The cipher information structure associated with the
- * given \p cipher_name, or NULL if not found.
+ * given \p cipher_name.
+ * \return NULL if the associated cipher information is not found.
*/
const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name );
@@ -310,7 +316,8 @@
* \param cipher_type Type of the cipher to search for.
*
* \return The cipher information structure associated with the
- * given \p cipher_type, or NULL if not found.
+ * given \p cipher_type.
+ * \return 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 );
@@ -325,7 +332,8 @@
* \param mode The cipher mode. For example, #MBEDTLS_MODE_CBC.
*
* \return The cipher information structure associated with the
- * given \p cipher_id, or NULL if not found.
+ * given \p cipher_id.
+ * \return 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,
@@ -352,10 +360,11 @@
* \param ctx The context to initialize. May not be NULL.
* \param cipher_info The cipher to use.
*
- * \return \c 0 on success,
- * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure,
- * #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
- * cipher-specific context failed.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ * parameter-verification failure.
+ * \return #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
+ * cipher-specific context fails.
*
* \internal Currently, the function also clears the structure.
* In future versions, the caller will be required to call
@@ -368,8 +377,8 @@
*
* \param ctx The context of the cipher. Must be initialized.
*
- * \return The size of the blocks of the cipher, or zero if \p ctx
- * has not been initialized.
+ * \return The size of the blocks of the cipher.
+ * \return 0 if \p ctx has not been initialized.
*/
static inline unsigned int mbedtls_cipher_get_block_size( const mbedtls_cipher_context_t *ctx )
{
@@ -385,8 +394,8 @@
*
* \param ctx The context of the cipher. Must be initialized.
*
- * \return The mode of operation, or #MBEDTLS_MODE_NONE if
- * \p ctx has not been initialized.
+ * \return The mode of operation.
+ * \return #MBEDTLS_MODE_NONE if \p ctx has not been initialized.
*/
static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtls_cipher_context_t *ctx )
{
@@ -402,9 +411,9 @@
*
* \param ctx The context of the cipher. Must be initialized.
*
- * \return <ul><li>If no IV has been set: the recommended IV size.
- * 0 for ciphers not using IV or nonce.</li>
- * <li>If IV has already been set: the actual size.</li></ul>
+ * \return The recommended IV size if no IV has been set.
+ * \return \c 0 for ciphers not using an IV or a nonce.
+ * \return The actual size if an IV has been set.
*/
static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ctx )
{
@@ -422,8 +431,8 @@
*
* \param ctx The context of the cipher. Must be initialized.
*
- * \return The type of the cipher, or #MBEDTLS_CIPHER_NONE if
- * \p ctx has not been initialized.
+ * \return The type of the cipher.
+ * \return #MBEDTLS_CIPHER_NONE if \p ctx has not been initialized.
*/
static inline mbedtls_cipher_type_t mbedtls_cipher_get_type( const mbedtls_cipher_context_t *ctx )
{
@@ -439,8 +448,8 @@
*
* \param ctx The context of the cipher. Must be initialized.
*
- * \return The name of the cipher, or NULL if \p ctx has not
- * been not initialized.
+ * \return The name of the cipher.
+ * \return NULL if \p ctx has not been not initialized.
*/
static inline const char *mbedtls_cipher_get_name( const mbedtls_cipher_context_t *ctx )
{
@@ -455,8 +464,8 @@
*
* \param ctx The context of the cipher. Must be initialized.
*
- * \return The key length of the cipher in bits, or
- * #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been
+ * \return The key length of the cipher in bits.
+ * \return #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been
* initialized.
*/
static inline int mbedtls_cipher_get_key_bitlen( const mbedtls_cipher_context_t *ctx )
@@ -472,9 +481,8 @@
*
* \param ctx The context of the cipher. Must be initialized.
*
- * \return The type of operation: #MBEDTLS_ENCRYPT or
- * #MBEDTLS_DECRYPT, or #MBEDTLS_OPERATION_NONE if \p ctx
- * has not been initialized.
+ * \return The type of operation: #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT.
+ * \return #MBEDTLS_OPERATION_NONE if \p ctx has not been initialized.
*/
static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_cipher_context_t *ctx )
{
@@ -495,9 +503,10 @@
* \param operation The operation that the key will be used for:
* #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT.
*
- * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
- * parameter verification fails, or a cipher-specific
- * error code.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ * parameter-verification failure.
+ * \return A cipher-specific error code on failure.
*/
int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *key,
int key_bitlen, const mbedtls_operation_t operation );
@@ -512,9 +521,10 @@
* \param ctx The generic cipher context.
* \param mode The padding mode.
*
- * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
- * if the selected padding mode is not supported, or
- * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
+ * if the selected padding mode is not supported.
+ * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
* does not support padding.
*/
int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx, mbedtls_cipher_padding_t mode );
@@ -524,15 +534,17 @@
* \brief This function sets the initialization vector (IV)
* or nonce.
*
+ * \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 iv_len The IV length for ciphers with variable-size IV.
* This parameter is discarded by ciphers with fixed-size IV.
*
- * \returns \c 0 on success, or #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
- *
- * \note Some ciphers do not use IVs nor nonce. For these
- * ciphers, this function has no effect.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ * parameter-verification failure.
*/
int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx,
const unsigned char *iv, size_t iv_len );
@@ -542,8 +554,9 @@
*
* \param ctx The generic cipher context.
*
- * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
- * if parameter verification fails.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ * parameter-verification failure.
*/
int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx );
@@ -557,7 +570,8 @@
* \param ad The additional data to use.
* \param ad_len the Length of \p ad.
*
- * \return \c 0 on success, or a specific error code on failure.
+ * \return \c 0 on success.
+ * \return A specific error code on failure.
*/
int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx,
const unsigned char *ad, size_t ad_len );
@@ -573,6 +587,11 @@
* Exception: For MBEDTLS_MODE_ECB, expects a single block
* in size. For example, 16 Bytes for AES.
*
+ * \note If the underlying cipher is used in GCM mode, all calls
+ * to this function, except for the last one before
+ * 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 ilen The length of the input data.
@@ -582,16 +601,12 @@
* \param olen The length of the output data, to be updated with the
* actual number of Bytes written.
*
- * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
- * parameter verification fails,
- * #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an
- * unsupported mode for a cipher, or a cipher-specific
- * error code.
- *
- * \note If the underlying cipher is GCM, all calls to this
- * function, except the last one before
- * mbedtls_cipher_finish(). Must have \p ilen as a
- * multiple of the block_size.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ * parameter-verification failure.
+ * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an
+ * unsupported mode for a cipher.
+ * \return A cipher-specific error code on failure.
*/
int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *input,
size_t ilen, unsigned char *output, size_t *olen );
@@ -606,13 +621,14 @@
* \param output The buffer to write data to. Needs block_size available.
* \param olen The length of the data written to the \p output buffer.
*
- * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
- * parameter verification fails,
- * #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
- * expected a full block but was not provided one,
- * #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
- * while decrypting, or a cipher-specific error code
- * on failure for any other reason.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ * parameter-verification failure.
+ * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption
+ * expecting a full block but not receiving one.
+ * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
+ * while decrypting.
+ * \return A cipher-specific error code on failure.
*/
int mbedtls_cipher_finish( mbedtls_cipher_context_t *ctx,
unsigned char *output, size_t *olen );
@@ -627,7 +643,8 @@
* \param tag The buffer to write the tag to.
* \param tag_len The length of the tag to write.
*
- * \return \c 0 on success, or a specific error code on failure.
+ * \return \c 0 on success.
+ * \return A specific error code on failure.
*/
int mbedtls_cipher_write_tag( mbedtls_cipher_context_t *ctx,
unsigned char *tag, size_t tag_len );
@@ -641,7 +658,8 @@
* \param tag The buffer holding the tag.
* \param tag_len The length of the tag to check.
*
- * \return \c 0 on success, or a specific error code on failure.
+ * \return \c 0 on success.
+ * \return A specific error code on failure.
*/
int mbedtls_cipher_check_tag( mbedtls_cipher_context_t *ctx,
const unsigned char *tag, size_t tag_len );
@@ -667,13 +685,14 @@
* \note Some ciphers do not use IVs nor nonce. For these
* ciphers, use \p iv = NULL and \p iv_len = 0.
*
- * \returns \c 0 on success, or
- * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
- * #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
- * expected a full block but was not provided one, or
- * #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
- * while decrypting, or a cipher-specific error code on
- * failure for any other reason.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ * parameter-verification failure.
+ * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption
+ * expecting a full block but not receiving one.
+ * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
+ * while decrypting.
+ * \return A cipher-specific error code on failure.
*/
int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx,
const unsigned char *iv, size_t iv_len,
@@ -699,9 +718,10 @@
* \param tag The buffer for the authentication tag.
* \param tag_len The desired length of the authentication tag.
*
- * \returns \c 0 on success, or
- * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
- * a cipher-specific error code.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ * parameter-verification failure.
+ * \return A cipher-specific error code on failure.
*/
int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx,
const unsigned char *iv, size_t iv_len,
@@ -713,6 +733,10 @@
/**
* \brief The generic autenticated decryption (AEAD) function.
*
+ * \note If the data is not authentic, then the output buffer
+ * is zeroed out to prevent the unauthentic plaintext being
+ * used, making this interface safer.
+ *
* \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.
@@ -728,14 +752,11 @@
* \param tag The buffer holding the authentication tag.
* \param tag_len The length of the authentication tag.
*
- * \returns \c 0 on success, or
- * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
- * #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic,
- * or a cipher-specific error code on failure for any other reason.
- *
- * \note If the data is not authentic, then the output buffer
- * is zeroed out to prevent the unauthentic plaintext being
- * used, making this interface safer.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ * parameter-verification failure.
+ * \return #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic.
+ * \return A cipher-specific error code on failure.
*/
int mbedtls_cipher_auth_decrypt( mbedtls_cipher_context_t *ctx,
const unsigned char *iv, size_t iv_len,
diff --git a/include/mbedtls/cmac.h b/include/mbedtls/cmac.h
index 628c9da..913c05f 100644
--- a/include/mbedtls/cmac.h
+++ b/include/mbedtls/cmac.h
@@ -1,8 +1,10 @@
/**
* \file cmac.h
*
- * \brief The Cipher-based Message Authentication Code (CMAC) Mode for
- * Authentication.
+ * \brief This file contains CMAC definitions and functions.
+ *
+ * The Cipher-based Message Authentication Code (CMAC) Mode for
+ * Authentication is defined in <em>RFC-4493: The AES-CMAC Algorithm</em>.
*/
/*
* Copyright (C) 2015-2018, Arm Limited (or its affiliates), All Rights Reserved
@@ -38,9 +40,9 @@
#define MBEDTLS_DES3_BLOCK_SIZE 8
#if defined(MBEDTLS_AES_C)
-#define MBEDTLS_CIPHER_BLKSIZE_MAX 16 /* The longest block used by CMAC is that of AES. */
+#define MBEDTLS_CIPHER_BLKSIZE_MAX 16 /**< The longest block used by CMAC is that of AES. */
#else
-#define MBEDTLS_CIPHER_BLKSIZE_MAX 8 /* The longest block used by CMAC is that of 3DES. */
+#define MBEDTLS_CIPHER_BLKSIZE_MAX 8 /**< The longest block used by CMAC is that of 3DES. */
#endif
#if !defined(MBEDTLS_CMAC_ALT)
@@ -61,22 +63,25 @@
size_t unprocessed_len;
};
+#else /* !MBEDTLS_CMAC_ALT */
+#include "cmac_alt.h"
+#endif /* !MBEDTLS_CMAC_ALT */
+
/**
* \brief This function sets the CMAC key, and prepares to authenticate
* the input data.
* Must be called with an initialized cipher context.
*
* \param ctx The cipher context used for the CMAC operation, initialized
- * as one of the following types:<ul>
- * <li>MBEDTLS_CIPHER_AES_128_ECB</li>
- * <li>MBEDTLS_CIPHER_AES_192_ECB</li>
- * <li>MBEDTLS_CIPHER_AES_256_ECB</li>
- * <li>MBEDTLS_CIPHER_DES_EDE3_ECB</li></ul>
+ * as one of the following types: MBEDTLS_CIPHER_AES_128_ECB,
+ * MBEDTLS_CIPHER_AES_192_ECB, MBEDTLS_CIPHER_AES_256_ECB,
+ * or MBEDTLS_CIPHER_DES_EDE3_ECB.
* \param key The CMAC key.
* \param keybits The length of the CMAC key in bits.
* Must be supported by the cipher.
*
- * \return \c 0 on success, or a cipher-specific error code.
+ * \return \c 0 on success.
+ * \return A cipher-specific error code on failure.
*/
int mbedtls_cipher_cmac_starts( mbedtls_cipher_context_t *ctx,
const unsigned char *key, size_t keybits );
@@ -93,8 +98,9 @@
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
*
- * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
- * if parameter verification fails.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * if parameter verification fails.
*/
int mbedtls_cipher_cmac_update( mbedtls_cipher_context_t *ctx,
const unsigned char *input, size_t ilen );
@@ -110,7 +116,8 @@
* \param ctx The cipher context used for the CMAC operation.
* \param output The output buffer for the CMAC checksum result.
*
- * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA
* if parameter verification fails.
*/
int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx,
@@ -126,7 +133,8 @@
*
* \param ctx The cipher context used for the CMAC operation.
*
- * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA
* if parameter verification fails.
*/
int mbedtls_cipher_cmac_reset( mbedtls_cipher_context_t *ctx );
@@ -149,7 +157,8 @@
* \param ilen The length of the input data.
* \param output The buffer for the generic CMAC result.
*
- * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA
* if parameter verification fails.
*/
int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info,
@@ -180,23 +189,12 @@
unsigned char output[16] );
#endif /* MBEDTLS_AES_C */
-#ifdef __cplusplus
-}
-#endif
-
-#else /* !MBEDTLS_CMAC_ALT */
-#include "cmac_alt.h"
-#endif /* !MBEDTLS_CMAC_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
#if defined(MBEDTLS_SELF_TEST) && ( defined(MBEDTLS_AES_C) || defined(MBEDTLS_DES_C) )
/**
* \brief The CMAC checkup routine.
*
- * \return \c 0 on success, or \c 1 on failure.
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_cmac_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST && ( MBEDTLS_AES_C || MBEDTLS_DES_C ) */
diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h
index 121575a..dcbc047 100644
--- a/include/mbedtls/ctr_drbg.h
+++ b/include/mbedtls/ctr_drbg.h
@@ -1,10 +1,15 @@
/**
* \file ctr_drbg.h
*
- * \brief CTR_DRBG is based on AES-256, as defined in <em>NIST SP 800-90A:
- * Recommendation for Random Number Generation Using Deterministic
- * Random Bit Generators</em>.
+ * \brief This file contains CTR_DRBG definitions and functions.
*
+ * CTR_DRBG is a standardized way of building a PRNG from a block-cipher
+ * in counter mode operation, as defined in <em>NIST SP 800-90A:
+ * Recommendation for Random Number Generation Using Deterministic Random
+ * Bit Generators</em>.
+ *
+ * The Mbed TLS implementation of CTR_DRBG uses AES-256 as the underlying
+ * block cipher.
*/
/*
* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
@@ -156,8 +161,8 @@
identifiers. Can be NULL.
* \param len The length of the personalization data.
*
- * \return \c 0 on success, or
- * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
*/
int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
int (*f_entropy)(void *, unsigned char *, size_t),
@@ -216,22 +221,24 @@
* \param additional Additional data to add to the state. Can be NULL.
* \param len The length of the additional data.
*
- * \return \c 0 on success, or
- * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
*/
int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
const unsigned char *additional, size_t len );
/**
- * \brief This function updates the state of the CTR_DRBG context.
+ * \brief This function updates the state of the CTR_DRBG context.
*
- * \param ctx The CTR_DRBG context.
- * \param additional The data to update the state with.
- * \param add_len Length of \p additional data.
+ * \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.
*
- * \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.
+ *
*/
void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx,
const unsigned char *additional, size_t add_len );
@@ -249,8 +256,8 @@
* \param additional Additional data to update. Can be NULL.
* \param add_len The length of the additional data.
*
- * \return \c 0 on success, or
- * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
* #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
*/
int mbedtls_ctr_drbg_random_with_add( void *p_rng,
@@ -267,8 +274,8 @@
* \param output The buffer to fill.
* \param output_len The length of the buffer.
*
- * \return \c 0 on success, or
- * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
* #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
*/
int mbedtls_ctr_drbg_random( void *p_rng,
@@ -281,9 +288,9 @@
* \param ctx The CTR_DRBG context.
* \param path The name of the file.
*
- * \return \c 0 on success,
- * #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or
- * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
+ * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
* failure.
*/
int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
@@ -295,9 +302,9 @@
* \param ctx The CTR_DRBG context.
* \param path The name of the file.
*
- * \return \c 0 on success,
- * #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error,
- * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
+ * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
* #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG on failure.
*/
int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
@@ -306,7 +313,8 @@
/**
* \brief The CTR_DRBG checkup routine.
*
- * \return \c 0 on success, or \c 1 on failure.
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_ctr_drbg_self_test( int verbose );
diff --git a/include/mbedtls/des.h b/include/mbedtls/des.h
index 5a1a636..6eb7d03 100644
--- a/include/mbedtls/des.h
+++ b/include/mbedtls/des.h
@@ -46,14 +46,14 @@
#define MBEDTLS_DES_KEY_SIZE 8
-#if !defined(MBEDTLS_DES_ALT)
-// Regular implementation
-//
-
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_DES_ALT)
+// Regular implementation
+//
+
/**
* \brief DES context structure
*
@@ -76,6 +76,10 @@
}
mbedtls_des3_context;
+#else /* MBEDTLS_DES_ALT */
+#include "des_alt.h"
+#endif /* MBEDTLS_DES_ALT */
+
/**
* \brief Initialize DES context
*
@@ -331,17 +335,6 @@
*/
void mbedtls_des_setkey( uint32_t SK[32],
const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_DES_ALT */
-#include "des_alt.h"
-#endif /* MBEDTLS_DES_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
/**
* \brief Checkup routine
diff --git a/include/mbedtls/dhm.h b/include/mbedtls/dhm.h
index 00fafd8..f848e22 100644
--- a/include/mbedtls/dhm.h
+++ b/include/mbedtls/dhm.h
@@ -1,7 +1,13 @@
/**
* \file dhm.h
*
- * \brief Diffie-Hellman-Merkle key exchange.
+ * \brief This file contains Diffie-Hellman-Merkle (DHM) key exchange
+ * definitions and functions.
+ *
+ * Diffie-Hellman-Merkle (DHM) key exchange is defined in
+ * <em>RFC-2631: Diffie-Hellman Key Agreement Method</em> and
+ * <em>Public-Key Cryptography Standards (PKCS) #3: Diffie
+ * Hellman Key Agreement Standard</em>.
*
* <em>RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for
* Internet Key Exchange (IKE)</em> defines a number of standardized
@@ -65,7 +71,6 @@
#include MBEDTLS_CONFIG_FILE
#endif
#include "bignum.h"
-#if !defined(MBEDTLS_DHM_ALT)
/*
* DHM Error codes
@@ -86,6 +91,8 @@
extern "C" {
#endif
+#if !defined(MBEDTLS_DHM_ALT)
+
/**
* \brief The DHM context structure.
*/
@@ -105,6 +112,10 @@
}
mbedtls_dhm_context;
+#else /* MBEDTLS_DHM_ALT */
+#include "dhm_alt.h"
+#endif /* MBEDTLS_DHM_ALT */
+
/**
* \brief This function initializes the DHM context.
*
@@ -125,8 +136,8 @@
* failures.
* \param end The end of the input buffer.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
- * on failure.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
*/
int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx,
unsigned char **p,
@@ -136,13 +147,6 @@
* \brief This function sets up and writes the ServerKeyExchange
* parameters.
*
- * \param ctx The DHM context.
- * \param x_size The private value 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 parameter.
- *
* \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.
@@ -155,8 +159,15 @@
* mbedtls_dhm_set_group() below in conjunction with
* mbedtls_mpi_read_binary() and mbedtls_mpi_read_string().
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
- * on failure.
+ * \param ctx The DHM context.
+ * \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.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
*/
int mbedtls_dhm_make_params( mbedtls_dhm_context *ctx, int x_size,
unsigned char *output, size_t *olen,
@@ -164,54 +175,54 @@
void *p_rng );
/**
- * \brief Set prime modulus and generator
+ * \brief This function sets the prime modulus and generator.
+ *
+ * \note This function can be used to set \p P, \p G
+ * in preparation for mbedtls_dhm_make_params().
*
* \param ctx The DHM context.
- * \param P The MPI holding DHM prime modulus.
- * \param G The MPI holding DHM generator.
+ * \param P The MPI holding the DHM prime modulus.
+ * \param G The MPI holding the DHM generator.
*
- * \note This function can be used to set P, G
- * in preparation for \c mbedtls_dhm_make_params.
- *
- * \return \c 0 if successful, or an \c MBEDTLS_ERR_DHM_XXX error code
- * on failure.
+ * \return \c 0 if successful.
+ * \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
*/
int mbedtls_dhm_set_group( mbedtls_dhm_context *ctx,
const mbedtls_mpi *P,
const mbedtls_mpi *G );
/**
- * \brief This function imports the public value G^Y of the peer.
+ * \brief This function imports the public value of the peer, G^Y.
*
* \param ctx The DHM context.
- * \param input The input buffer.
+ * \param input The input buffer containing the G^Y value of the peer.
* \param ilen The size of the input buffer.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
- * on failure.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
*/
int mbedtls_dhm_read_public( mbedtls_dhm_context *ctx,
const unsigned char *input, size_t ilen );
/**
- * \brief This function creates its own private value \c X and
+ * \brief This function creates its own private key, \c X, and
* exports \c G^X.
*
+ * \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
+ * with zero-bytes at the beginning.
+ *
* \param ctx The DHM context.
- * \param x_size The private value size in Bytes.
+ * \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).
+ * equal to ctx->len (the size of \c P).
* \param f_rng The RNG function.
- * \param p_rng The RNG parameter.
+ * \param p_rng The RNG context.
*
- * \note The destination buffer will always be fully written
- * so as to contain a big-endian presentation of G^X mod P.
- * If it is larger than ctx->len, it will accordingly be
- * padded with zero-bytes in the beginning.
- *
- * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
- * on failure.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
*/
int mbedtls_dhm_make_public( mbedtls_dhm_context *ctx, int x_size,
unsigned char *output, size_t olen,
@@ -222,22 +233,22 @@
* \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.
+ *
* \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 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 parameter.
+ * \param p_rng The RNG context.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
- * on failure.
- *
- * \note If non-NULL, \p f_rng is used to blind the input as
- * a countermeasure against timing attacks. Blinding is used
- * only if our secret value \p X is re-used and omitted
- * otherwise. Therefore, we recommend always passing a
- * non-NULL \p f_rng argument.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
*/
int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx,
unsigned char *output, size_t output_size, size_t *olen,
@@ -245,7 +256,7 @@
void *p_rng );
/**
- * \brief This function frees and clears the components of a DHM key.
+ * \brief This function frees and clears the components of a DHM context.
*
* \param ctx The DHM context to free and clear.
*/
@@ -261,8 +272,9 @@
* \param dhminlen The size of the buffer, including the terminating null
* Byte for PEM data.
*
- * \return \c 0 on success, or a specific DHM or PEM error code
- * on failure.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX error code
+ * error code on failure.
*/
int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin,
size_t dhminlen );
@@ -275,29 +287,19 @@
* \param dhm The DHM context to load the parameters to.
* \param path The filename to read the DHM parameters from.
*
- * \return \c 0 on success, or a specific DHM or PEM error code
- * on failure.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX error code
+ * 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 */
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_DHM_ALT */
-#include "dhm_alt.h"
-#endif /* MBEDTLS_DHM_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
/**
* \brief The DMH checkup routine.
*
- * \return \c 0 on success, or \c 1 on failure.
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_dhm_self_test( int verbose );
diff --git a/include/mbedtls/ecdh.h b/include/mbedtls/ecdh.h
index 99cfde0..922f029 100644
--- a/include/mbedtls/ecdh.h
+++ b/include/mbedtls/ecdh.h
@@ -1,10 +1,11 @@
/**
* \file ecdh.h
*
- * \brief The Elliptic Curve Diffie-Hellman (ECDH) protocol APIs.
- *
- * ECDH is an anonymous key agreement protocol allowing two parties to
- * establish a shared secret over an insecure channel. Each party must have an
+ * \brief This file contains ECDH definitions and functions.
+ *
+ * The Elliptic Curve Diffie-Hellman (ECDH) protocol is an anonymous
+ * key agreement protocol allowing two parties to establish a shared
+ * secret over an insecure channel. Each party must have an
* elliptic-curve public–private key pair.
*
* For more information, see <em>NIST SP 800-56A Rev. 2: Recommendation for
@@ -40,14 +41,12 @@
#endif
/**
- * Defines the source of the imported EC key:
- * <ul><li>Our key.</li>
- * <li>The key of the peer.</li></ul>
+ * Defines the source of the imported EC key.
*/
typedef enum
{
- MBEDTLS_ECDH_OURS,
- MBEDTLS_ECDH_THEIRS,
+ MBEDTLS_ECDH_OURS, /**< Our key. */
+ MBEDTLS_ECDH_THEIRS, /**< The key of the peer. */
} mbedtls_ecdh_side;
/**
@@ -75,16 +74,18 @@
* implemented during the ECDH key exchange. The second core
* computation is performed by mbedtls_ecdh_compute_shared().
*
+ * \see ecp.h
+ *
* \param grp The ECP group.
* \param d The destination MPI (private key).
* \param Q The destination point (public key).
* \param f_rng The RNG function.
- * \param p_rng The RNG parameter.
+ * \param p_rng The RNG context.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or
* \c MBEDTLS_MPI_XXX error code on failure.
*
- * \see ecp.h
*/
int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -97,21 +98,22 @@
* implemented during the ECDH key exchange. The first core
* computation is performed by mbedtls_ecdh_gen_public().
*
+ * \see ecp.h
+ *
+ * \note If \p f_rng is not NULL, it is used to implement
+ * countermeasures against side-channel attacks.
+ * For more information, see mbedtls_ecp_mul().
+ *
* \param grp The ECP group.
* \param z The destination MPI (shared secret).
* \param Q The public key from another party.
* \param d Our secret exponent (private key).
* \param f_rng The RNG function.
- * \param p_rng The RNG parameter.
+ * \param p_rng The RNG context.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or
* \c MBEDTLS_MPI_XXX error code on failure.
- *
- * \see ecp.h
- *
- * \note If \p f_rng is not NULL, it is used to implement
- * countermeasures against potential elaborate timing
- * attacks. For more information, see mbedtls_ecp_mul().
*/
int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
@@ -139,21 +141,21 @@
* 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().
+ *
+ * \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 parameter.
+ * \param p_rng The RNG context.
*
- * \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().
- *
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- * on failure.
- *
- * \see ecp.h
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
*/
int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
unsigned char *buf, size_t blen,
@@ -167,14 +169,15 @@
* This is the first function used by a TLS client for ECDHE
* ciphersuites.
*
+ * \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.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- * on failure.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
*
- * \see ecp.h
*/
int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
const unsigned char **buf, const unsigned char *end );
@@ -186,16 +189,16 @@
* ServerKeyEchange for static ECDH, and imports ECDH
* parameters from the EC key information of a certificate.
*
+ * \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:
- * <ul><li>1: Our key.</li>
- <li>0: The key of the peer.</li></ul>
+ * \param side Defines the source of the key: 1: Our key, or
+ * 0: The key of the peer.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- * on failure.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
*
- * \see ecp.h
*/
int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
mbedtls_ecdh_side side );
@@ -207,17 +210,17 @@
* 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 parameter.
+ * \param p_rng The RNG context.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- * on failure.
- *
- * \see ecp.h
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
*/
int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
unsigned char *buf, size_t blen,
@@ -231,14 +234,14 @@
* This is the second function used by a TLS server for ECDH(E)
* ciphersuites.
*
+ * \see ecp.h
+ *
* \param ctx The ECDH context.
* \param buf The start of the input buffer.
* \param blen The length of the input buffer.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- * on failure.
- *
- * \see ecp.h
+ * \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 );
@@ -249,21 +252,21 @@
* This is the last function used by both TLS client
* and servers.
*
+ * \note If \p f_rng is not NULL, it is used to implement
+ * countermeasures against side-channel attacks.
+ * 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 parameter.
+ * \param p_rng The RNG context.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- * on failure.
- *
- * \see ecp.h
- *
- * \note If \p f_rng is not NULL, it is used to implement
- * countermeasures against potential elaborate timing
- * attacks. For more information, see mbedtls_ecp_mul().
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
*/
int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
unsigned char *buf, size_t blen,
diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h
index ff6efbc..ce1a03d 100644
--- a/include/mbedtls/ecdsa.h
+++ b/include/mbedtls/ecdsa.h
@@ -1,9 +1,10 @@
/**
* \file ecdsa.h
*
- * \brief The Elliptic Curve Digital Signature Algorithm (ECDSA).
+ * \brief This file contains ECDSA definitions and functions.
*
- * ECDSA is defined in <em>Standards for Efficient Cryptography Group (SECG):
+ * The Elliptic Curve Digital Signature Algorithm (ECDSA) is defined in
+ * <em>Standards for Efficient Cryptography Group (SECG):
* SEC1 Elliptic Curve Cryptography</em>.
* The use of ECDSA for TLS is defined in <em>RFC-4492: Elliptic Curve
* Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)</em>.
@@ -69,6 +70,14 @@
*
* \note The deterministic version 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
+ * as defined in <em>Standards for Efficient Cryptography Group
+ * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ * 4.1.3, step 5.
+ *
+ * \see ecp.h
+ *
* \param grp The ECP group.
* \param r The first output integer.
* \param s The second output integer.
@@ -76,18 +85,11 @@
* \param buf The message hash.
* \param blen The length of \p buf.
* \param f_rng The RNG function.
- * \param p_rng The RNG parameter.
+ * \param p_rng The RNG context.
*
- * \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
- * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
- * 4.1.3, step 5.
- *
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX
* or \c MBEDTLS_MPI_XXX error code on failure.
- *
- * \see ecp.h
*/
int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
@@ -97,10 +99,19 @@
/**
* \brief This function computes the ECDSA signature of a
* previously-hashed message, deterministic version.
+ *
* For more information, see <em>RFC-6979: Deterministic
* Usage of the Digital Signature Algorithm (DSA) and Elliptic
* Curve Digital Signature Algorithm (ECDSA)</em>.
*
+ * \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
+ * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ * 4.1.3, step 5.
+ *
+ * \see ecp.h
+ *
* \param grp The ECP group.
* \param r The first output integer.
* \param s The second output integer.
@@ -109,17 +120,9 @@
* \param blen The length of \p buf.
* \param md_alg The MD algorithm used to hash the message.
*
- * \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
- * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
- * 4.1.3, step 5.
- *
- * \return \c 0 on success,
- * or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
* error code on failure.
- *
- * \see ecp.h
*/
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,
@@ -130,6 +133,14 @@
* \brief This function verifies the ECDSA signature of a
* previously-hashed message.
*
+ * \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
+ * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ * 4.1.4, step 3.
+ *
+ * \see ecp.h
+ *
* \param grp The ECP group.
* \param buf The message hash.
* \param blen The length of \p buf.
@@ -137,18 +148,11 @@
* \param r The first integer of the signature.
* \param s The second integer of the signature.
*
- * \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
- * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
- * 4.1.4, step 3.
- *
- * \return \c 0 on success,
- * #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
- * or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature
+ * is invalid.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
* error code on failure for any other reason.
- *
- * \see ecp.h
*/
int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
const unsigned char *buf, size_t blen,
@@ -169,15 +173,6 @@
* of the Digital Signature Algorithm (DSA) and Elliptic
* Curve Digital Signature Algorithm (ECDSA)</em>.
*
- * \param ctx The ECDSA context.
- * \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 parameter.
- *
* \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
@@ -189,11 +184,20 @@
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.3, step 5.
*
- * \return \c 0 on success,
- * or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
- * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
- *
* \see ecp.h
+ *
+ * \param ctx The ECDSA context.
+ * \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.
+ *
+ * \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,
const unsigned char *hash, size_t hlen,
@@ -209,26 +213,17 @@
#define MBEDTLS_DEPRECATED
#endif
/**
- * \brief This function computes an ECDSA signature and writes it to a buffer,
- * serialized as defined in <em>RFC-4492: Elliptic Curve Cryptography
- * (ECC) Cipher Suites for Transport Layer Security (TLS)</em>.
+ * \brief This function computes an ECDSA signature and writes
+ * it to a buffer, serialized as defined in <em>RFC-4492:
+ * Elliptic Curve Cryptography (ECC) Cipher Suites for
+ * Transport Layer Security (TLS)</em>.
*
- * The deterministic version is defined in <em>RFC-6979:
- * Deterministic Usage of the Digital Signature Algorithm (DSA) and
- * Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
+ * The deterministic version is defined in <em>RFC-6979:
+ * Deterministic Usage of the Digital Signature Algorithm (DSA)
+ * and Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
*
* \warning It is not thread-safe to use the same context in
* multiple threads.
-
- *
- * \deprecated Superseded by mbedtls_ecdsa_write_signature() in 2.0.0
- *
- * \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.
*
* \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
@@ -241,11 +236,21 @@
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.3, step 5.
*
- * \return \c 0 on success,
- * or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
- * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
- *
* \see ecp.h
+ *
+ * \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.
+ *
+ * \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_det( mbedtls_ecdsa_context *ctx,
const unsigned char *hash, size_t hlen,
@@ -258,26 +263,26 @@
/**
* \brief This function reads and verifies an ECDSA signature.
*
- * \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.
- *
* \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
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.4, step 3.
*
- * \return \c 0 on success,
- * #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
- * #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid
- * signature in sig but its length is less than \p siglen,
- * or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
- * error code on failure for any other reason.
- *
* \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.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
+ * \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid
+ * signature in \p sig, but its length is less than \p siglen.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
+ * error code on failure for any other reason.
*/
int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
const unsigned char *hash, size_t hlen,
@@ -286,16 +291,16 @@
/**
* \brief This function generates an ECDSA keypair on the given curve.
*
+ * \see ecp.h
+ *
* \param ctx The ECDSA context to store the keypair in.
* \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 parameter.
+ * \param p_rng The RNG context.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on
- * failure.
- *
- * \see ecp.h
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX code on failure.
*/
int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
@@ -303,13 +308,13 @@
/**
* \brief This function sets 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.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on
- * failure.
- *
- * \see ecp.h
+ * \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 );
diff --git a/include/mbedtls/ecjpake.h b/include/mbedtls/ecjpake.h
index d86e820..cc2b316 100644
--- a/include/mbedtls/ecjpake.h
+++ b/include/mbedtls/ecjpake.h
@@ -44,8 +44,6 @@
#include "ecp.h"
#include "md.h"
-#if !defined(MBEDTLS_ECJPAKE_ALT)
-
#ifdef __cplusplus
extern "C" {
#endif
@@ -58,6 +56,7 @@
MBEDTLS_ECJPAKE_SERVER, /**< Server */
} mbedtls_ecjpake_role;
+#if !defined(MBEDTLS_ECJPAKE_ALT)
/**
* EC J-PAKE context structure.
*
@@ -88,6 +87,10 @@
mbedtls_mpi s; /**< Pre-shared secret (passphrase) */
} mbedtls_ecjpake_context;
+#else /* MBEDTLS_ECJPAKE_ALT */
+#include "ecjpake_alt.h"
+#endif /* MBEDTLS_ECJPAKE_ALT */
+
/**
* \brief Initialize a context
* (just makes it ready for setup() or free()).
@@ -225,20 +228,10 @@
*/
void mbedtls_ecjpake_free( mbedtls_ecjpake_context *ctx );
-#ifdef __cplusplus
-}
-#endif
-#else /* MBEDTLS_ECJPAKE_ALT */
-#include "ecjpake_alt.h"
-#endif /* MBEDTLS_ECJPAKE_ALT */
#if defined(MBEDTLS_SELF_TEST)
-#ifdef __cplusplus
-extern "C" {
-#endif
-
/**
* \brief Checkup routine
*
@@ -246,10 +239,11 @@
*/
int mbedtls_ecjpake_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif
-#endif /* MBEDTLS_SELF_TEST */
#endif /* ecjpake.h */
diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h
index e024da8..3a40798 100644
--- a/include/mbedtls/ecp.h
+++ b/include/mbedtls/ecp.h
@@ -1,10 +1,21 @@
/**
* \file ecp.h
*
- * \brief Elliptic curves over GF(p)
+ * \brief This file provides an API for Elliptic Curves over GF(P) (ECP).
+ *
+ * The use of ECP in cryptography and TLS is defined in
+ * <em>Standards for Efficient Cryptography Group (SECG): SEC1
+ * Elliptic Curve Cryptography</em> and
+ * <em>RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites
+ * for Transport Layer Security (TLS)</em>.
+ *
+ * <em>RFC-2409: The Internet Key Exchange (IKE)</em> defines ECP
+ * group types.
+ *
*/
+
/*
- * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -19,8 +30,9 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*
- * This file is part of mbed TLS (https://tls.mbed.org)
+ * This file is part of Mbed TLS (https://tls.mbed.org)
*/
+
#ifndef MBEDTLS_ECP_H
#define MBEDTLS_ECP_H
@@ -31,13 +43,81 @@
*/
#define MBEDTLS_ERR_ECP_BAD_INPUT_DATA -0x4F80 /**< Bad input parameters to function. */
#define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL -0x4F00 /**< The buffer is too small to write to. */
-#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< Requested curve not available. */
+#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< The requested feature is not available, for example, the requested curve is not supported. */
#define MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00 /**< The signature is not valid. */
#define MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80 /**< Memory allocation failed. */
-#define MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00 /**< Generation of random value, such as (ephemeral) key, failed. */
+#define MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00 /**< Generation of random value, such as ephemeral key, failed. */
#define MBEDTLS_ERR_ECP_INVALID_KEY -0x4C80 /**< Invalid private or public key. */
#define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH -0x4C00 /**< The buffer contains a valid signature followed by more data. */
-#define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED -0x4B80 /**< ECP hardware accelerator failed. */
+#define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED -0x4B80 /**< The ECP hardware accelerator failed. */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Domain-parameter identifiers: curve, subgroup, and generator.
+ *
+ * \note Only curves over prime fields are supported.
+ *
+ * \warning This library does not support validation of arbitrary domain
+ * parameters. Therefore, only standardized domain parameters from trusted
+ * sources should be used. See mbedtls_ecp_group_load().
+ */
+typedef enum
+{
+ MBEDTLS_ECP_DP_NONE = 0, /*!< Curve not defined. */
+ MBEDTLS_ECP_DP_SECP192R1, /*!< Domain parameters for the 192-bit curve defined by FIPS 186-4 and SEC1. */
+ MBEDTLS_ECP_DP_SECP224R1, /*!< Domain parameters for the 224-bit curve defined by FIPS 186-4 and SEC1. */
+ MBEDTLS_ECP_DP_SECP256R1, /*!< Domain parameters for the 256-bit curve defined by FIPS 186-4 and SEC1. */
+ MBEDTLS_ECP_DP_SECP384R1, /*!< Domain parameters for the 384-bit curve defined by FIPS 186-4 and SEC1. */
+ MBEDTLS_ECP_DP_SECP521R1, /*!< Domain parameters for the 521-bit curve defined by FIPS 186-4 and SEC1. */
+ MBEDTLS_ECP_DP_BP256R1, /*!< Domain parameters for 256-bit Brainpool curve. */
+ MBEDTLS_ECP_DP_BP384R1, /*!< Domain parameters for 384-bit Brainpool curve. */
+ MBEDTLS_ECP_DP_BP512R1, /*!< Domain parameters for 512-bit Brainpool curve. */
+ MBEDTLS_ECP_DP_CURVE25519, /*!< Domain parameters for Curve25519. */
+ MBEDTLS_ECP_DP_SECP192K1, /*!< Domain parameters for 192-bit "Koblitz" curve. */
+ MBEDTLS_ECP_DP_SECP224K1, /*!< Domain parameters for 224-bit "Koblitz" curve. */
+ MBEDTLS_ECP_DP_SECP256K1, /*!< Domain parameters for 256-bit "Koblitz" curve. */
+ MBEDTLS_ECP_DP_CURVE448, /*!< Domain parameters for Curve448. */
+} mbedtls_ecp_group_id;
+
+/**
+ * The number of supported curves, plus one for #MBEDTLS_ECP_DP_NONE.
+ *
+ * \note Montgomery curves are currently excluded.
+ */
+#define MBEDTLS_ECP_DP_MAX 12
+
+/**
+ * Curve information, for use by other modules.
+ */
+typedef struct
+{
+ mbedtls_ecp_group_id grp_id; /*!< An internal identifier. */
+ uint16_t tls_id; /*!< The TLS NamedCurve identifier. */
+ uint16_t bit_size; /*!< The curve size in bits. */
+ const char *name; /*!< A human-friendly name. */
+} mbedtls_ecp_curve_info;
+
+/**
+ * \brief The ECP point structure, in Jacobian coordinates.
+ *
+ * \note All functions expect and return points satisfying
+ * the following condition: <code>Z == 0</code> or
+ * <code>Z == 1</code>. Other values of \p Z are
+ * used only by internal functions.
+ * The point is zero, or "at infinity", if <code>Z == 0</code>.
+ * Otherwise, \p X and \p Y are its standard (affine)
+ * coordinates.
+ */
+typedef struct
+{
+ mbedtls_mpi X; /*!< The X coordinate of the ECP point. */
+ mbedtls_mpi Y; /*!< The Y coordinate of the ECP point. */
+ mbedtls_mpi Z; /*!< The Z coordinate of the ECP point. */
+}
+mbedtls_ecp_point;
#if !defined(MBEDTLS_ECP_ALT)
/*
@@ -48,144 +128,72 @@
* one.)
*/
-#ifdef __cplusplus
-extern "C" {
-#endif
-
/**
- * Domain parameters (curve, subgroup and generator) identifiers.
+ * \brief The ECP group structure.
*
- * Only curves over prime fields are supported.
+ * We consider two types of curve equations:
+ * <ul><li>Short Weierstrass: <code>y^2 = x^3 + A x + B mod P</code>
+ * (SEC1 + RFC-4492)</li>
+ * <li>Montgomery: <code>y^2 = x^3 + A x^2 + x mod P</code> (Curve25519,
+ * Curve448)</li></ul>
+ * In both cases, the generator (\p G) for a prime-order subgroup is fixed.
*
- * \warning This library does not support validation of arbitrary domain
- * parameters. Therefore, only well-known domain parameters from trusted
- * sources should be used. See mbedtls_ecp_group_load().
- */
-typedef enum
-{
- MBEDTLS_ECP_DP_NONE = 0,
- MBEDTLS_ECP_DP_SECP192R1, /*!< 192-bits NIST curve */
- MBEDTLS_ECP_DP_SECP224R1, /*!< 224-bits NIST curve */
- MBEDTLS_ECP_DP_SECP256R1, /*!< 256-bits NIST curve */
- MBEDTLS_ECP_DP_SECP384R1, /*!< 384-bits NIST curve */
- MBEDTLS_ECP_DP_SECP521R1, /*!< 521-bits NIST curve */
- MBEDTLS_ECP_DP_BP256R1, /*!< 256-bits Brainpool curve */
- MBEDTLS_ECP_DP_BP384R1, /*!< 384-bits Brainpool curve */
- MBEDTLS_ECP_DP_BP512R1, /*!< 512-bits Brainpool curve */
- MBEDTLS_ECP_DP_CURVE25519, /*!< Curve25519 */
- MBEDTLS_ECP_DP_CURVE448, /*!< Curve448 */
- MBEDTLS_ECP_DP_SECP192K1, /*!< 192-bits "Koblitz" curve */
- MBEDTLS_ECP_DP_SECP224K1, /*!< 224-bits "Koblitz" curve */
- MBEDTLS_ECP_DP_SECP256K1, /*!< 256-bits "Koblitz" curve */
-} mbedtls_ecp_group_id;
-
-/**
- * Number of supported curves (plus one for NONE).
+ * For Short Weierstrass, this subgroup is the whole curve, and its
+ * cardinality is denoted by \p N. Our code requires that \p N is an
+ * odd prime as mbedtls_ecp_mul() requires an odd number, and
+ * mbedtls_ecdsa_sign() requires that it is prime for blinding purposes.
*
- * (Montgomery curves excluded for now.)
- */
-#define MBEDTLS_ECP_DP_MAX 12
-
-/**
- * Curve information for use by other modules
+ * For Montgomery curves, we do not store \p A, but <code>(A + 2) / 4</code>,
+ * which is the quantity used in the formulas. Additionally, \p nbits is
+ * not the size of \p N but the required size for private keys.
+ *
+ * If \p modp is NULL, reduction modulo \p P is done using a generic algorithm.
+ * Otherwise, \p modp must point to a function that takes an \p mbedtls_mpi in the
+ * range of <code>0..2^(2*pbits)-1</code>, and transforms it in-place to an integer
+ * which is congruent mod \p P to the given MPI, and is close enough to \p pbits
+ * in size, so that it may be efficiently brought in the 0..P-1 range by a few
+ * additions or subtractions. Therefore, it is only an approximative modular
+ * reduction. It must return 0 on success and non-zero on failure.
+ *
*/
typedef struct
{
- mbedtls_ecp_group_id grp_id; /*!< Internal identifier */
- uint16_t tls_id; /*!< TLS NamedCurve identifier */
- uint16_t bit_size; /*!< Curve size in bits */
- const char *name; /*!< Human-friendly name */
-} mbedtls_ecp_curve_info;
-
-/**
- * \brief ECP point structure (jacobian coordinates)
- *
- * \note All functions expect and return points satisfying
- * the following condition: Z == 0 or Z == 1. (Other
- * values of Z are used by internal functions only.)
- * The point is zero, or "at infinity", if Z == 0.
- * Otherwise, X and Y are its standard (affine) coordinates.
- */
-typedef struct
-{
- mbedtls_mpi X; /*!< the point's X coordinate */
- mbedtls_mpi Y; /*!< the point's Y coordinate */
- mbedtls_mpi Z; /*!< the point's Z coordinate */
-}
-mbedtls_ecp_point;
-
-/**
- * \brief ECP group structure
- *
- * We consider two types of curves equations:
- * 1. Short Weierstrass y^2 = x^3 + A x + B mod P (SEC1 + RFC 4492)
- * 2. Montgomery, y^2 = x^3 + A x^2 + x mod P (Curve25519 + draft)
- * In both cases, a generator G for a prime-order subgroup is fixed. In the
- * short weierstrass, this subgroup is actually the whole curve, and its
- * cardinal is denoted by N.
- *
- * In the case of Short Weierstrass curves, our code requires that N is an odd
- * prime. (Use odd in mbedtls_ecp_mul() and prime in mbedtls_ecdsa_sign() for blinding.)
- *
- * In the case of Montgomery curves, we don't store A but (A + 2) / 4 which is
- * the quantity actually used in the formulas. Also, nbits is not the size of N
- * but the required size for private keys.
- *
- * If modp is NULL, reduction modulo P is done using a generic algorithm.
- * Otherwise, it must point to a function that takes an mbedtls_mpi in the range
- * 0..2^(2*pbits)-1 and transforms it in-place in an integer of little more
- * than pbits, so that the integer may be efficiently brought in the 0..P-1
- * range by a few additions or substractions. It must return 0 on success and
- * non-zero on failure.
- */
-typedef struct
-{
- mbedtls_ecp_group_id id; /*!< internal group identifier */
- mbedtls_mpi P; /*!< prime modulus of the base field */
- mbedtls_mpi A; /*!< 1. A in the equation, or 2. (A + 2) / 4 */
- mbedtls_mpi B; /*!< 1. B in the equation, or 2. unused */
- mbedtls_ecp_point G; /*!< generator of the (sub)group used */
- mbedtls_mpi N; /*!< the order of G */
- size_t pbits; /*!< number of bits in P */
- size_t nbits; /*!< number of bits in 1. P, or 2. private keys */
- unsigned int h; /*!< internal: 1 if the constants are static */
- int (*modp)(mbedtls_mpi *); /*!< function for fast reduction mod P */
- int (*t_pre)(mbedtls_ecp_point *, void *); /*!< unused */
- int (*t_post)(mbedtls_ecp_point *, void *); /*!< unused */
- void *t_data; /*!< unused */
- mbedtls_ecp_point *T; /*!< pre-computed points for ecp_mul_comb() */
- size_t T_size; /*!< number for pre-computed points */
+ mbedtls_ecp_group_id id; /*!< An internal group identifier. */
+ mbedtls_mpi P; /*!< The prime modulus of the base field. */
+ mbedtls_mpi A; /*!< For Short Weierstrass: \p A in the equation. For
+ Montgomery curves: <code>(A + 2) / 4</code>. */
+ mbedtls_mpi B; /*!< For Short Weierstrass: \p B in the equation.
+ For Montgomery curves: unused. */
+ mbedtls_ecp_point G; /*!< The generator of the subgroup used. */
+ mbedtls_mpi N; /*!< The order of \p G. */
+ size_t pbits; /*!< The number of bits in \p P.*/
+ size_t nbits; /*!< For Short Weierstrass: The number of bits in \p P.
+ For Montgomery curves: the number of bits in the
+ private keys. */
+ unsigned int h; /*!< \internal 1 if the constants are static. */
+ int (*modp)(mbedtls_mpi *); /*!< The function for fast pseudo-reduction
+ mod \p P (see above).*/
+ int (*t_pre)(mbedtls_ecp_point *, void *); /*!< Unused. */
+ int (*t_post)(mbedtls_ecp_point *, void *); /*!< Unused. */
+ void *t_data; /*!< Unused. */
+ mbedtls_ecp_point *T; /*!< Pre-computed points for ecp_mul_comb(). */
+ size_t T_size; /*!< The number of pre-computed points. */
}
mbedtls_ecp_group;
/**
- * \brief ECP key pair structure
- *
- * A generic key pair that could be used for ECDSA, fixed ECDH, etc.
- *
- * \note Members purposefully in the same order as struc mbedtls_ecdsa_context.
- */
-typedef struct
-{
- mbedtls_ecp_group grp; /*!< Elliptic curve and base point */
- mbedtls_mpi d; /*!< our secret value */
- mbedtls_ecp_point Q; /*!< our public value */
-}
-mbedtls_ecp_keypair;
-
-/**
* \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 on the compiler command line.
+ * Either change them in config.h, or define them using the compiler command line.
* \{
*/
#if !defined(MBEDTLS_ECP_MAX_BITS)
/**
- * Maximum size of the groups (that is, of N and P)
+ * The maximum size of the groups, that is, of \c N and \c P.
*/
-#define MBEDTLS_ECP_MAX_BITS 521 /**< Maximum bit size of groups */
+#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 )
@@ -208,11 +216,10 @@
* 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 /**< Maximum window size used */
+#define MBEDTLS_ECP_WINDOW_SIZE 6 /**< The maximum window size used. */
#endif /* MBEDTLS_ECP_WINDOW_SIZE */
#if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM)
@@ -227,33 +234,55 @@
*
* Change this value to 0 to reduce peak memory usage.
*/
-#define MBEDTLS_ECP_FIXED_POINT_OPTIM 1 /**< Enable fixed-point speed-up */
+#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.
+ *
+ * \note Members are deliberately in the same order as in the
+ * ::mbedtls_ecdsa_context structure.
+ */
+typedef struct
+{
+ mbedtls_ecp_group grp; /*!< Elliptic curve and base point */
+ mbedtls_mpi d; /*!< our secret value */
+ mbedtls_ecp_point Q; /*!< our public value */
+}
+mbedtls_ecp_keypair;
+
/*
* Point formats, from RFC 4492's enum ECPointFormat
*/
-#define MBEDTLS_ECP_PF_UNCOMPRESSED 0 /**< Uncompressed point format */
-#define MBEDTLS_ECP_PF_COMPRESSED 1 /**< Compressed point format */
+#define MBEDTLS_ECP_PF_UNCOMPRESSED 0 /**< Uncompressed point format. */
+#define MBEDTLS_ECP_PF_COMPRESSED 1 /**< Compressed point format. */
/*
* Some other constants from RFC 4492
*/
-#define MBEDTLS_ECP_TLS_NAMED_CURVE 3 /**< ECCurveType's named_curve */
+#define MBEDTLS_ECP_TLS_NAMED_CURVE 3 /**< The named_curve of ECCurveType. */
/**
- * \brief Get the list of supported curves in order of preferrence
- * (full information)
+ * \brief This function retrieves the information defined in
+ * mbedtls_ecp_curve_info() for all supported curves in order
+ * of preference.
*
- * \return A statically allocated array, the last entry is 0.
+ * \return A statically allocated array. The last entry is 0.
*/
const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void );
/**
- * \brief Get the list of supported curves in order of preferrence
- * (grp_id only)
+ * \brief This function retrieves the list of internal group
+ * identifiers of all supported curves in the order of
+ * preference.
*
* \return A statically allocated array,
* terminated with MBEDTLS_ECP_DP_NONE.
@@ -261,357 +290,400 @@
const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list( void );
/**
- * \brief Get curve information from an internal group identifier
+ * \brief This function retrieves curve information from an internal
+ * group identifier.
*
- * \param grp_id A MBEDTLS_ECP_DP_XXX value
+ * \param grp_id An \c MBEDTLS_ECP_DP_XXX value.
*
- * \return The associated curve information or NULL
+ * \return The associated curve information on success.
+ * \return NULL on failure.
*/
const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_group_id grp_id );
/**
- * \brief Get curve information from a TLS NamedCurve value
+ * \brief This function retrieves curve information from a TLS
+ * NamedCurve value.
*
- * \param tls_id A MBEDTLS_ECP_DP_XXX value
+ * \param tls_id An \c MBEDTLS_ECP_DP_XXX value.
*
- * \return The associated curve information or NULL
+ * \return The associated curve information on success.
+ * \return NULL on failure.
*/
const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_id );
/**
- * \brief Get curve information from a human-readable name
+ * \brief This function retrieves curve information from a
+ * human-readable name.
*
- * \param name The name
+ * \param name The human-readable name.
*
- * \return The associated curve information or NULL
+ * \return The associated curve information on success.
+ * \return NULL on failure.
*/
const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name( const char *name );
/**
- * \brief Initialize a point (as zero)
+ * \brief This function initializes a point as zero.
+ *
+ * \param pt The point to initialize.
*/
void mbedtls_ecp_point_init( mbedtls_ecp_point *pt );
/**
- * \brief Initialize a group (to something meaningless)
+ * \brief This function initializes an ECP group context
+ * without loading any domain parameters.
+ *
+ * \note After this function is called, domain parameters
+ * for various ECP groups can be loaded through the
+ * mbedtls_ecp_load() or mbedtls_ecp_tls_read_group()
+ * functions.
*/
void mbedtls_ecp_group_init( mbedtls_ecp_group *grp );
/**
- * \brief Initialize a key pair (as an invalid one)
+ * \brief This function initializes a key pair as an invalid one.
+ *
+ * \param key The key pair to initialize.
*/
void mbedtls_ecp_keypair_init( mbedtls_ecp_keypair *key );
/**
- * \brief Free the components of a point
+ * \brief This function frees the components of a point.
+ *
+ * \param pt The point to free.
*/
void mbedtls_ecp_point_free( mbedtls_ecp_point *pt );
/**
- * \brief Free the components of an ECP group
+ * \brief This function frees the components of an ECP group.
+ * \param grp The group to free.
*/
void mbedtls_ecp_group_free( mbedtls_ecp_group *grp );
/**
- * \brief Free the components of a key pair
+ * \brief This function frees the components of a key pair.
+ * \param key The key pair to free.
*/
void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key );
/**
- * \brief Copy the contents of point Q into P
+ * \brief This function copies the contents of point \p Q into
+ * point \p P.
*
- * \param P Destination point
- * \param Q Source point
+ * \param P The destination point.
+ * \param Q The source point.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
*/
int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q );
/**
- * \brief Copy the contents of a group object
+ * \brief This function copies the contents of group \p src into
+ * group \p dst.
*
- * \param dst Destination group
- * \param src Source group
+ * \param dst The destination group.
+ * \param src The source group.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
*/
int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src );
/**
- * \brief Set a point to zero
+ * \brief This function sets a point to zero.
*
- * \param pt Destination point
+ * \param pt The point to set.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
*/
int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt );
/**
- * \brief Tell if a point is zero
+ * \brief This function checks if a point is zero.
*
- * \param pt Point to test
+ * \param pt The point to test.
*
- * \return 1 if point is zero, 0 otherwise
+ * \return \c 1 if the point is zero.
+ * \return \c 0 if the point is non-zero.
*/
int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt );
/**
- * \brief Compare two points
+ * \brief This function compares two points.
*
- * \note This assumes the points are normalized. Otherwise,
+ * \note This assumes that the points are normalized. Otherwise,
* they may compare as "not equal" even if they are.
*
- * \param P First point to compare
- * \param Q Second point to compare
+ * \param P The first point to compare.
+ * \param Q The second point to compare.
*
- * \return 0 if the points are equal,
- * MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise
+ * \return \c 0 if the points are equal.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal.
*/
int mbedtls_ecp_point_cmp( const mbedtls_ecp_point *P,
const mbedtls_ecp_point *Q );
/**
- * \brief Import a non-zero point from two ASCII strings
+ * \brief This function imports a non-zero point from two ASCII
+ * strings.
*
- * \param P Destination point
- * \param radix Input numeric base
- * \param x First affine coordinate as a null-terminated string
- * \param y Second affine coordinate as a null-terminated string
+ * \param P The destination point.
+ * \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.
*
- * \return 0 if successful, or a MBEDTLS_ERR_MPI_XXX error code
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_MPI_XXX error code on failure.
*/
int mbedtls_ecp_point_read_string( mbedtls_ecp_point *P, int radix,
const char *x, const char *y );
/**
- * \brief Export a point into unsigned binary data
+ * \brief This function exports a point into unsigned binary data.
*
- * \param grp Group to which the point should belong
- * \param P Point to export
- * \param format Point format, should be a MBEDTLS_ECP_PF_XXX macro
- * \param olen Length of the actual output
- * \param buf Output buffer
- * \param buflen Length of the output buffer
+ * \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.
*
- * \return 0 if successful,
- * or MBEDTLS_ERR_ECP_BAD_INPUT_DATA
- * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA
+ * or #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
*/
int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *P,
int format, size_t *olen,
unsigned char *buf, size_t buflen );
/**
- * \brief Import a point from unsigned binary data
+ * \brief This function imports a point from unsigned binary data.
*
- * \param grp Group to which the point should belong
- * \param P Point to import
- * \param buf Input buffer
- * \param ilen Actual length of input
+ * \note This function does not check that the point actually
+ * belongs to the given group, see mbedtls_ecp_check_pubkey()
+ * for that.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- * MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
+ * \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.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if 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.
*
- * \note This function does NOT check that the point actually
- * belongs to the given group, see mbedtls_ecp_check_pubkey() for
- * that.
*/
int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_point *P,
const unsigned char *buf, size_t ilen );
/**
- * \brief Import a point from a TLS ECPoint record
+ * \brief This function imports a point from a TLS ECPoint record.
*
- * \param grp ECP group used
- * \param pt Destination point
- * \param buf $(Start of input buffer)
- * \param len Buffer length
+ * \note On function return, \p buf is updated to point to immediately
+ * after the ECPoint record.
*
- * \note buf is updated to point right after the ECPoint on exit
+ * \param grp The ECP group used.
+ * \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 0 if successful,
- * MBEDTLS_ERR_MPI_XXX if initialization failed
- * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid
+ * \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.
*/
int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point *pt,
const unsigned char **buf, size_t len );
/**
- * \brief Export a point as a TLS ECPoint record
+ * \brief This function exports a point as a TLS ECPoint record.
*
- * \param grp ECP group used
- * \param pt Point to export
- * \param format Export format
- * \param olen length of data written
- * \param buf Buffer to write to
- * \param blen Buffer length
+ * \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.
*
- * \return 0 if successful,
- * or MBEDTLS_ERR_ECP_BAD_INPUT_DATA
- * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA or
+ * #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on 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 );
/**
- * \brief Set a group using well-known domain parameters
+ * \brief This function sets a group using standardized domain parameters.
*
- * \param grp Destination group
- * \param id Index in the list of well-known 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.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_XXX if initialization failed
- * MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups
+ * \param grp The destination group.
+ * \param id The identifier of the domain parameter set to load.
*
- * \note Index should be a value of RFC 4492's enum NamedCurve,
- * usually in the form of a MBEDTLS_ECP_DP_XXX macro.
+ * \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.
+
*/
int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id );
/**
- * \brief Set a group from a TLS ECParameters record
+ * \brief This function sets a group from a TLS ECParameters record.
*
- * \param grp Destination group
- * \param buf &(Start of input buffer)
- * \param len Buffer length
+ * \note \p buf is updated to point right after the ECParameters record
+ * on exit.
*
- * \note buf is updated to point right after ECParameters on exit
+ * \param grp The destination group.
+ * \param buf The address of the pointer to the start of the input buffer.
+ * \param len The length of the buffer.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_XXX if initialization failed
- * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid
+ * \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.
*/
int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp, const unsigned char **buf, size_t len );
/**
- * \brief Write the TLS ECParameters record for a group
+ * \brief This function writes the TLS ECParameters record for a group.
*
- * \param grp ECP group used
- * \param olen Number of bytes actually written
- * \param buf Buffer to write to
- * \param blen Buffer length
+ * \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.
*
- * \return 0 if successful,
- * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
*/
int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen,
unsigned char *buf, size_t blen );
/**
- * \brief Multiplication by an integer: R = m * P
- * (Not thread-safe to use same group in multiple threads)
+ * \brief This function performs multiplication of a point by
+ * an integer: \p R = \p m * \p P.
*
- * \note In order to prevent timing attacks, this function
- * executes the exact same sequence of (base field)
- * operations for any valid m. It avoids any if-branch or
- * array index depending on the value of m.
+ * It is not thread-safe to use same group in multiple threads.
*
- * \note If f_rng is not NULL, it is used to randomize intermediate
- * results in order to prevent potential timing attacks
- * targeting these results. It is recommended to always
- * provide a non-NULL f_rng (the overhead is negligible).
+ * \note To prevent timing attacks, this function
+ * executes the exact same sequence of base-field
+ * operations for any valid \p m. It avoids any if-branch or
+ * array index depending on the value of \p m.
*
- * \param grp ECP group
- * \param R Destination point
- * \param m Integer by which to multiply
- * \param P Point to multiply
- * \param f_rng RNG function (see notes)
- * \param p_rng RNG parameter
+ * \note If \p f_rng is not NULL, it is used to randomize
+ * intermediate results to prevent potential timing attacks
+ * targeting these results. We recommend always providing
+ * a non-NULL \p f_rng. The overhead is negligible.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_ECP_INVALID_KEY if m is not a valid privkey
- * or P is not a valid pubkey,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \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.
+ *
+ * \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.
*/
int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
const mbedtls_mpi *m, const mbedtls_ecp_point *P,
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
/**
- * \brief Multiplication and addition of two points by integers:
- * R = m * P + n * Q
- * (Not thread-safe to use same group in multiple threads)
+ * \brief This function performs multiplication and addition of two
+ * points by integers: \p R = \p m * \p P + \p n * \p Q
*
- * \note In contrast to mbedtls_ecp_mul(), this function does not guarantee
- * a constant execution flow and timing.
+ * It is not thread-safe to use same group in multiple threads.
*
- * \param grp ECP group
- * \param R Destination point
- * \param m Integer by which to multiply P
- * \param P Point to multiply by m
- * \param n Integer by which to multiply Q
- * \param Q Point to be multiplied by n
+ * \note In contrast to mbedtls_ecp_mul(), this function does not
+ * guarantee a constant execution flow and timing.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_ECP_INVALID_KEY if m or n is not a valid privkey
- * or P or Q is not a valid pubkey,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \param grp The ECP group.
+ * \param R The destination point.
+ * \param m The integer by which to multiply \p P.
+ * \param P The point to multiply by \p m.
+ * \param n The integer by which to multiply \p Q.
+ * \param Q The point to be multiplied by \p n.
+ *
+ * \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.
*/
int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
const mbedtls_mpi *m, const mbedtls_ecp_point *P,
const mbedtls_mpi *n, const mbedtls_ecp_point *Q );
/**
- * \brief Check that a point is a valid public key on this curve
+ * \brief This function checks that a point is a valid public key
+ * on this curve.
*
- * \param grp Curve/group the point should belong to
- * \param pt Point to check
+ * It only checks that the point is non-zero, has
+ * valid coordinates and lies on the curve. It does not verify
+ * that it is indeed a multiple of \p G. This additional
+ * check is computationally more expensive, is not required
+ * by standards, and should not be necessary if the group
+ * used has a small cofactor. In particular, it is useless for
+ * the NIST groups which all have a cofactor of 1.
*
- * \return 0 if point is a valid public key,
- * MBEDTLS_ERR_ECP_INVALID_KEY otherwise.
+ * \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.
*
- * \note This function only checks the point is non-zero, has valid
- * coordinates and lies on the curve, but not that it is
- * indeed a multiple of G. This is additional check is more
- * expensive, isn't required by standards, and shouldn't be
- * necessary if the group used has a small cofactor. In
- * particular, it is useless for the NIST groups which all
- * have a cofactor of 1.
+ * \param grp The curve the point should lie on.
+ * \param pt The point to check.
*
- * \note Uses bare components rather than an mbedtls_ecp_keypair structure
- * in order to ease use with other structures such as
- * mbedtls_ecdh_context of mbedtls_ecdsa_context.
+ * \return \c 0 if the point is a valid public key.
+ * \return #MBEDTLS_ERR_ECP_INVALID_KEY on failure.
*/
int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt );
/**
- * \brief Check that an 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.
*
- * \param grp Group used
- * \param d Integer to check
+ * \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.
*
- * \return 0 if point is a valid private key,
- * MBEDTLS_ERR_ECP_INVALID_KEY otherwise.
+ * \param grp The group used.
+ * \param d The integer to check.
*
- * \note Uses bare components rather than an mbedtls_ecp_keypair structure
- * in order to ease use with other structures such as
- * mbedtls_ecdh_context of mbedtls_ecdsa_context.
+ * \return \c 0 if the point is a valid private key.
+ * \return #MBEDTLS_ERR_ECP_INVALID_KEY on failure.
*/
int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d );
/**
- * \brief Generate a keypair with configurable base point
+ * \brief This function generates a keypair with a configurable base
+ * point.
*
- * \param grp ECP group
- * \param G Chosen base point
- * \param d Destination MPI (secret part)
- * \param Q Destination point (public part)
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \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.
*
- * \return 0 if successful,
- * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \param grp The ECP group.
+ * \param G The chosen base point.
+ * \param d The destination MPI (secret part).
+ * \param Q The destination point (public part).
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG context.
*
- * \note Uses bare components rather than an mbedtls_ecp_keypair structure
- * in order to ease use with other structures such as
- * mbedtls_ecdh_context of mbedtls_ecdsa_context.
+ * \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,
@@ -620,57 +692,66 @@
void *p_rng );
/**
- * \brief Generate a keypair
+ * \brief This function generates an ECP keypair.
*
- * \param grp ECP group
- * \param d Destination MPI (secret part)
- * \param Q Destination point (public part)
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \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.
*
- * \return 0 if successful,
- * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \param grp The ECP group.
+ * \param d The destination MPI (secret part).
+ * \param Q The destination point (public part).
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG context.
*
- * \note Uses bare components rather than an mbedtls_ecp_keypair structure
- * in order to ease use with other structures such as
- * mbedtls_ecdh_context of mbedtls_ecdsa_context.
+ * \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 );
/**
- * \brief Generate a keypair
+ * \brief This function generates an ECP key.
*
- * \param grp_id ECP group identifier
- * \param key Destination keypair
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \param grp_id The ECP group identifier.
+ * \param key The destination key.
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG context.
*
- * \return 0 if successful,
- * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \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 );
/**
- * \brief Check a public-private key pair
+ * \brief This function checks that the keypair objects
+ * \p pub and \p prv have the same group and the
+ * same public point, and that the private key in
+ * \p prv is consistent with the public key.
*
- * \param pub Keypair structure holding a public key
- * \param prv Keypair structure holding a private (plus public) key
+ * \param pub The keypair structure holding the public key.
+ * If it contains a private key, that part is ignored.
+ * \param prv The keypair structure holding the full keypair.
*
- * \return 0 if successful (keys are valid and match), or
- * MBEDTLS_ERR_ECP_BAD_INPUT_DATA, or
- * a MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX code.
+ * \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 );
#if defined(MBEDTLS_SELF_TEST)
/**
- * \brief Checkup routine
+ * \brief The ECP checkup routine.
*
- * \return 0 if successful, or 1 if a test failed
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_ecp_self_test( int verbose );
@@ -680,8 +761,4 @@
}
#endif
-#else /* MBEDTLS_ECP_ALT */
-#include "ecp_alt.h"
-#endif /* MBEDTLS_ECP_ALT */
-
#endif /* ecp.h */
diff --git a/include/mbedtls/gcm.h b/include/mbedtls/gcm.h
index 1e5a507..3c22033 100644
--- a/include/mbedtls/gcm.h
+++ b/include/mbedtls/gcm.h
@@ -1,9 +1,11 @@
/**
* \file gcm.h
*
- * \brief Galois/Counter Mode (GCM) for 128-bit block ciphers, as defined
- * in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
- * (GCM), Natl. Inst. Stand. Technol.</em>
+ * \brief This file contains GCM definitions and functions.
+ *
+ * The Galois/Counter Mode (GCM) for 128-bit block ciphers is defined
+ * in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
+ * (GCM), Natl. Inst. Stand. Technol.</em>
*
* For more information on GCM, see <em>NIST SP 800-38D: Recommendation for
* Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</em>.
@@ -42,12 +44,12 @@
#define MBEDTLS_ERR_GCM_HW_ACCEL_FAILED -0x0013 /**< GCM hardware accelerator failed. */
#define MBEDTLS_ERR_GCM_BAD_INPUT -0x0014 /**< Bad input parameters to function. */
-#if !defined(MBEDTLS_GCM_ALT)
-
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_GCM_ALT)
+
/**
* \brief The GCM context structure.
*/
@@ -66,6 +68,10 @@
}
mbedtls_gcm_context;
+#else /* !MBEDTLS_GCM_ALT */
+#include "gcm_alt.h"
+#endif /* !MBEDTLS_GCM_ALT */
+
/**
* \brief This function initializes the specified GCM context,
* to make references valid, and prepares the context
@@ -91,7 +97,8 @@
* <li>192 bits</li>
* <li>256 bits</li></ul>
*
- * \return \c 0 on success, or a cipher specific error code.
+ * \return \c 0 on success.
+ * \return A cipher-specific error code on failure.
*/
int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
mbedtls_cipher_id_t cipher,
@@ -101,15 +108,16 @@
/**
* \brief This function performs GCM encryption or decryption of a buffer.
*
- * \note For encryption, the output buffer can be the same as the input buffer.
- * For decryption, the output buffer cannot be the same as input buffer.
- * If the buffers overlap, the output buffer must trail at least 8 Bytes
- * behind the input buffer.
+ * \note For encryption, the output buffer can be the same as the
+ * input buffer. For decryption, the output buffer cannot be
+ * the same as input buffer. If the buffers overlap, the output
+ * buffer must trail at least 8 Bytes behind the input buffer.
*
* \param ctx The GCM context to use for encryption or decryption.
* \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or
* #MBEDTLS_GCM_DECRYPT.
- * \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 length The length of the input data. This must be a multiple of
+ * 16 except in the last call before mbedtls_gcm_finish().
* \param iv The initialization vector.
* \param iv_len The length of the IV.
* \param add The buffer holding the additional data.
@@ -137,12 +145,13 @@
* \brief This function performs a GCM authenticated decryption of a
* buffer.
*
- * \note For decryption, the output buffer cannot be the same as input buffer.
- * If the buffers overlap, the output buffer must trail at least 8 Bytes
- * behind the input buffer.
+ * \note For decryption, the output buffer cannot be the same as
+ * 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 length The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
+ * \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 iv The initialization vector.
* \param iv_len The length of the IV.
* \param add The buffer holding the additional data.
@@ -152,8 +161,8 @@
* \param input The buffer holding the input data.
* \param output The buffer for holding the output data.
*
- * \return 0 if successful and authenticated, or
- * #MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match.
+ * \return 0 if successful and authenticated.
+ * \return #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match.
*/
int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
size_t length,
@@ -175,10 +184,12 @@
* #MBEDTLS_GCM_DECRYPT.
* \param iv The initialization vector.
* \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 NULL
+ * if \p add_len is 0.
+ * \param add_len The length of the additional data. If 0,
+ * \p add is NULL.
*
- * \return \c 0 on success.
+ * \return \c 0 on success.
*/
int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
int mode,
@@ -195,16 +206,18 @@
* Bytes. Only the last call before calling
* mbedtls_gcm_finish() can be less than 16 Bytes.
*
- * \note For decryption, the output buffer cannot be the same as input buffer.
- * If the buffers overlap, the output buffer must trail at least 8 Bytes
- * behind the input buffer.
+ * \note For decryption, the output buffer cannot be the same as
+ * 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 length The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
+ * \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.
*
- * \return \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
*/
int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
size_t length,
@@ -222,7 +235,8 @@
* \param tag The buffer for holding the tag.
* \param tag_len The length of the tag to generate. Must be at least four.
*
- * \return \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
*/
int mbedtls_gcm_finish( mbedtls_gcm_context *ctx,
unsigned char *tag,
@@ -236,22 +250,11 @@
*/
void mbedtls_gcm_free( mbedtls_gcm_context *ctx );
-#ifdef __cplusplus
-}
-#endif
-
-#else /* !MBEDTLS_GCM_ALT */
-#include "gcm_alt.h"
-#endif /* !MBEDTLS_GCM_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
/**
* \brief The GCM checkup routine.
*
- * \return \c 0 on success, or \c 1 on failure.
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_gcm_self_test( int verbose );
diff --git a/include/mbedtls/md.h b/include/mbedtls/md.h
index 06538c3..6b6f5c5 100644
--- a/include/mbedtls/md.h
+++ b/include/mbedtls/md.h
@@ -1,7 +1,7 @@
/**
* \file md.h
*
- * \brief The generic message-digest wrapper.
+ * \brief This file contains the generic message-digest wrapper.
*
* \author Adriaan de Jong <dejong@fox-it.com>
*/
@@ -46,7 +46,7 @@
#endif
/**
- * \brief Enumeration of supported message digests
+ * \brief Supported message digests.
*
* \warning MD2, MD4, MD5 and SHA-1 are considered weak message digests and
* their use constitutes a security risk. We recommend considering
@@ -54,16 +54,16 @@
*
*/
typedef enum {
- MBEDTLS_MD_NONE=0,
- MBEDTLS_MD_MD2,
- MBEDTLS_MD_MD4,
- MBEDTLS_MD_MD5,
- MBEDTLS_MD_SHA1,
- MBEDTLS_MD_SHA224,
- MBEDTLS_MD_SHA256,
- MBEDTLS_MD_SHA384,
- MBEDTLS_MD_SHA512,
- MBEDTLS_MD_RIPEMD160,
+ MBEDTLS_MD_NONE=0, /**< None. */
+ MBEDTLS_MD_MD2, /**< The MD2 message digest. */
+ MBEDTLS_MD_MD4, /**< The MD4 message digest. */
+ MBEDTLS_MD_MD5, /**< The MD5 message digest. */
+ MBEDTLS_MD_SHA1, /**< The SHA-1 message digest. */
+ MBEDTLS_MD_SHA224, /**< The SHA-224 message digest. */
+ MBEDTLS_MD_SHA256, /**< The SHA-256 message digest. */
+ MBEDTLS_MD_SHA384, /**< The SHA-384 message digest. */
+ MBEDTLS_MD_SHA512, /**< The SHA-512 message digest. */
+ MBEDTLS_MD_RIPEMD160, /**< The RIPEMD-160 message digest. */
} mbedtls_md_type_t;
#if defined(MBEDTLS_SHA512_C)
@@ -108,8 +108,8 @@
*
* \param md_name The name of the digest to search for.
*
- * \return The message-digest information associated with \p md_name,
- * or NULL if not found.
+ * \return The message-digest information associated with \p md_name.
+ * \return NULL if the associated message-digest information is not found.
*/
const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name );
@@ -119,8 +119,8 @@
*
* \param md_type The type of digest to search for.
*
- * \return The message-digest information associated with \p md_type,
- * or NULL if not found.
+ * \return The message-digest information associated with \p md_type.
+ * \return NULL if the associated message-digest information is not found.
*/
const mbedtls_md_info_t *mbedtls_md_info_from_type( mbedtls_md_type_t md_type );
@@ -168,9 +168,10 @@
* \param md_info The information structure of the message-digest algorithm
* to use.
*
- * \returns \c 0 on success,
- * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure,
- * #MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
+ * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.
*/
int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info ) MBEDTLS_DEPRECATED;
#undef MBEDTLS_DEPRECATED
@@ -187,12 +188,13 @@
* \param ctx The context to set up.
* \param md_info The information structure of the message-digest algorithm
* to use.
- * \param hmac <ul><li>0: HMAC is not used. Saves some memory.</li>
- * <li>non-zero: HMAC is used with this context.</li></ul>
+ * \param hmac Defines if HMAC is used. 0: HMAC is not used (saves some memory),
+ * or non-zero: HMAC is used with this context.
*
- * \returns \c 0 on success,
- * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, or
- * #MBEDTLS_ERR_MD_ALLOC_FAILED on memory allocation failure.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
+ * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.
*/
int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac );
@@ -212,8 +214,8 @@
* \param dst The destination context.
* \param src The context to be cloned.
*
- * \return \c 0 on success,
- * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.
*/
int mbedtls_md_clone( mbedtls_md_context_t *dst,
const mbedtls_md_context_t *src );
@@ -260,8 +262,9 @@
*
* \param ctx The generic message-digest context.
*
- * \returns \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- * parameter verification fails.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
int mbedtls_md_starts( mbedtls_md_context_t *ctx );
@@ -277,8 +280,9 @@
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
*
- * \returns \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- * parameter verification fails.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen );
@@ -296,8 +300,9 @@
* \param ctx The generic message-digest context.
* \param output The buffer for the generic message-digest checksum result.
*
- * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- * parameter verification fails.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output );
@@ -315,8 +320,9 @@
* \param ilen The length of the input data.
* \param output The generic message-digest checksum result.
*
- * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- * parameter verification fails.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,
unsigned char *output );
@@ -334,9 +340,10 @@
* \param path The input file name.
* \param output The generic message-digest checksum result.
*
- * \return \c 0 on success,
- * #MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed, or
- * #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_FILE_IO_ERROR on an I/O error accessing
+ * the file pointed by \p path.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL.
*/
int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path,
unsigned char *output );
@@ -356,8 +363,9 @@
* \param key The HMAC secret key.
* \param keylen The length of the HMAC key in Bytes.
*
- * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- * parameter verification fails.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key,
size_t keylen );
@@ -377,8 +385,9 @@
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
*
- * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- * parameter verification fails.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input,
size_t ilen );
@@ -397,8 +406,9 @@
* context.
* \param output The generic HMAC checksum result.
*
- * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- * parameter verification fails.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output);
@@ -413,8 +423,9 @@
* \param ctx The message digest context containing an embedded HMAC
* context.
*
- * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- * parameter verification fails.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx );
@@ -436,8 +447,9 @@
* \param ilen The length of the input data.
* \param output The generic HMAC result.
*
- * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- * parameter verification fails.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
int mbedtls_md_hmac( const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen,
const unsigned char *input, size_t ilen,
diff --git a/include/mbedtls/md2.h b/include/mbedtls/md2.h
index 0fd8b5a..08e75b2 100644
--- a/include/mbedtls/md2.h
+++ b/include/mbedtls/md2.h
@@ -39,14 +39,14 @@
#define MBEDTLS_ERR_MD2_HW_ACCEL_FAILED -0x002B /**< MD2 hardware accelerator failed */
-#if !defined(MBEDTLS_MD2_ALT)
-// Regular implementation
-//
-
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_MD2_ALT)
+// Regular implementation
+//
+
/**
* \brief MD2 context structure
*
@@ -64,6 +64,10 @@
}
mbedtls_md2_context;
+#else /* MBEDTLS_MD2_ALT */
+#include "md2_alt.h"
+#endif /* MBEDTLS_MD2_ALT */
+
/**
* \brief Initialize MD2 context
*
@@ -235,18 +239,6 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_MD2_ALT */
-#include "md2_alt.h"
-#endif /* MBEDTLS_MD2_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
/**
* \brief Output = MD2( input buffer )
*
diff --git a/include/mbedtls/md4.h b/include/mbedtls/md4.h
index 23fa95e..8ee4e5c 100644
--- a/include/mbedtls/md4.h
+++ b/include/mbedtls/md4.h
@@ -40,14 +40,14 @@
#define MBEDTLS_ERR_MD4_HW_ACCEL_FAILED -0x002D /**< MD4 hardware accelerator failed */
-#if !defined(MBEDTLS_MD4_ALT)
-// Regular implementation
-//
-
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_MD4_ALT)
+// Regular implementation
+//
+
/**
* \brief MD4 context structure
*
@@ -64,6 +64,10 @@
}
mbedtls_md4_context;
+#else /* MBEDTLS_MD4_ALT */
+#include "md4_alt.h"
+#endif /* MBEDTLS_MD4_ALT */
+
/**
* \brief Initialize MD4 context
*
@@ -238,18 +242,6 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_MD4_ALT */
-#include "md4_alt.h"
-#endif /* MBEDTLS_MD4_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
/**
* \brief Output = MD4( input buffer )
*
diff --git a/include/mbedtls/md5.h b/include/mbedtls/md5.h
index 06ea4c5..43ead4b 100644
--- a/include/mbedtls/md5.h
+++ b/include/mbedtls/md5.h
@@ -39,14 +39,14 @@
#define MBEDTLS_ERR_MD5_HW_ACCEL_FAILED -0x002F /**< MD5 hardware accelerator failed */
-#if !defined(MBEDTLS_MD5_ALT)
-// Regular implementation
-//
-
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_MD5_ALT)
+// Regular implementation
+//
+
/**
* \brief MD5 context structure
*
@@ -63,6 +63,10 @@
}
mbedtls_md5_context;
+#else /* MBEDTLS_MD5_ALT */
+#include "md5_alt.h"
+#endif /* MBEDTLS_MD5_ALT */
+
/**
* \brief Initialize MD5 context
*
@@ -238,18 +242,6 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_MD5_ALT */
-#include "md5_alt.h"
-#endif /* MBEDTLS_MD5_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
/**
* \brief Output = MD5( input buffer )
*
diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h
index ed10775..a53229b 100644
--- a/include/mbedtls/platform.h
+++ b/include/mbedtls/platform.h
@@ -1,7 +1,16 @@
/**
* \file platform.h
*
- * \brief The Mbed TLS platform abstraction layer.
+ * \brief This file contains the definitions and functions of the
+ * Mbed TLS platform abstraction layer.
+ *
+ * The platform abstraction layer removes the need for the library
+ * to directly link to standard C library functions or operating
+ * system services, making the library easier to port and embed.
+ * Application developers and users of the library can provide their own
+ * implementations of these functions, or implementations specific to
+ * their platform, which can be statically linked to the library or
+ * dynamically configured at runtime.
*/
/*
* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
@@ -102,7 +111,7 @@
/* \} name SECTION: Module settings */
/*
- * The function pointers for calloc and free
+ * The function pointers for calloc and free.
*/
#if defined(MBEDTLS_PLATFORM_MEMORY)
#if defined(MBEDTLS_PLATFORM_FREE_MACRO) && \
@@ -116,7 +125,8 @@
extern void (*mbedtls_free)( void *ptr );
/**
- * \brief This function allows configuring custom memory-management functions.
+ * \brief This function dynamically sets the memory-management
+ * functions used by the library, during runtime.
*
* \param calloc_func The \c calloc function implementation.
* \param free_func The \c free function implementation.
@@ -140,7 +150,9 @@
extern int (*mbedtls_fprintf)( FILE *stream, const char *format, ... );
/**
- * \brief This function allows configuring a custom \p fprintf function pointer.
+ * \brief This function dynamically configures the fprintf
+ * function that is called when the
+ * mbedtls_fprintf() function is invoked by the library.
*
* \param fprintf_func The \c fprintf function implementation.
*
@@ -163,8 +175,9 @@
extern int (*mbedtls_printf)( const char *format, ... );
/**
- * \brief This function allows configuring a custom \c printf function
- * pointer.
+ * \brief This function dynamically configures the snprintf
+ * function that is called when the mbedtls_snprintf()
+ * function is invoked by the library.
*
* \param printf_func The \c printf function implementation.
*
@@ -197,12 +210,12 @@
extern int (*mbedtls_snprintf)( char * s, size_t n, const char * format, ... );
/**
- * \brief This function allows configuring a custom \c snprintf function
- * pointer.
+ * \brief This function allows configuring a custom
+ * \c snprintf function pointer.
*
* \param snprintf_func The \c snprintf function implementation.
*
- * \return \c 0 on success.
+ * \return \c 0 on success.
*/
int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n,
const char * format, ... ) );
@@ -210,7 +223,7 @@
#if defined(MBEDTLS_PLATFORM_SNPRINTF_MACRO)
#define mbedtls_snprintf MBEDTLS_PLATFORM_SNPRINTF_MACRO
#else
-#define mbedtls_snprintf snprintf
+#define mbedtls_snprintf MBEDTLS_PLATFORM_STD_SNPRINTF
#endif /* MBEDTLS_PLATFORM_SNPRINTF_MACRO */
#endif /* MBEDTLS_PLATFORM_SNPRINTF_ALT */
@@ -221,12 +234,13 @@
extern void (*mbedtls_exit)( int status );
/**
- * \brief This function allows configuring a custom \c exit function
- * pointer.
+ * \brief This function dynamically configures the exit
+ * function that is called when the mbedtls_exit()
+ * function is invoked by the library.
*
* \param exit_func The \c exit function implementation.
*
- * \return \c 0 on success.
+ * \return \c 0 on success.
*/
int mbedtls_platform_set_exit( void (*exit_func)( int status ) );
#else
@@ -302,7 +316,7 @@
* setup or teardown operations.
*/
typedef struct {
- char dummy; /**< Placeholder member, as empty structs are not portable. */
+ char dummy; /**< A placeholder member, as empty structs are not portable. */
}
mbedtls_platform_context;
@@ -311,33 +325,34 @@
#endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */
/**
- * \brief This function performs any platform initialization operations.
+ * \brief This function performs any platform-specific initialization
+ * operations.
*
- * \param ctx The Mbed TLS context.
+ * \note This function should be called before any other library functions.
+ *
+ * Its implementation is platform-specific, and unless
+ * platform-specific code is provided, it does nothing.
+ *
+ * \note The usage and necessity of this function is dependent on the platform.
+ *
+ * \param ctx The platform context.
*
* \return \c 0 on success.
- *
- * \note This function is intended to allow platform-specific initialization,
- * and should be called before any other library functions. Its
- * implementation is platform-specific, and unless
- * platform-specific code is provided, it does nothing.
- *
- * Its use and whether it is necessary to call it is dependent on the
- * platform.
*/
int mbedtls_platform_setup( mbedtls_platform_context *ctx );
/**
* \brief This function performs any platform teardown operations.
*
- * \param ctx The Mbed TLS context.
- *
* \note This function should be called after every other Mbed TLS module
* has been correctly freed using the appropriate free function.
+ *
* Its implementation is platform-specific, and unless
* platform-specific code is provided, it does nothing.
*
- * Its use and whether it is necessary to call it is dependent on the
- * platform.
+ * \note The usage and necessity of this function is dependent on the platform.
+ *
+ * \param ctx The platform context.
+ *
*/
void mbedtls_platform_teardown( mbedtls_platform_context *ctx );
diff --git a/include/mbedtls/ripemd160.h b/include/mbedtls/ripemd160.h
index 3a8b50a..a0dac0c 100644
--- a/include/mbedtls/ripemd160.h
+++ b/include/mbedtls/ripemd160.h
@@ -35,14 +35,14 @@
#define MBEDTLS_ERR_RIPEMD160_HW_ACCEL_FAILED -0x0031 /**< RIPEMD160 hardware accelerator failed */
-#if !defined(MBEDTLS_RIPEMD160_ALT)
-// Regular implementation
-//
-
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_RIPEMD160_ALT)
+// Regular implementation
+//
+
/**
* \brief RIPEMD-160 context structure
*/
@@ -54,6 +54,10 @@
}
mbedtls_ripemd160_context;
+#else /* MBEDTLS_RIPEMD160_ALT */
+#include "ripemd160.h"
+#endif /* MBEDTLS_RIPEMD160_ALT */
+
/**
* \brief Initialize RIPEMD-160 context
*
@@ -178,18 +182,6 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_RIPEMD160_ALT */
-#include "ripemd160_alt.h"
-#endif /* MBEDTLS_RIPEMD160_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
/**
* \brief Output = RIPEMD-160( input buffer )
*
diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h
index 5548f3c..df6e3e5 100644
--- a/include/mbedtls/rsa.h
+++ b/include/mbedtls/rsa.h
@@ -1,11 +1,12 @@
/**
* \file rsa.h
*
- * \brief The RSA public-key cryptosystem.
+ * \brief This file provides an API for the RSA public-key cryptosystem.
*
- * For more information, see <em>Public-Key Cryptography Standards (PKCS)
- * #1 v1.5: RSA Encryption</em> and <em>Public-Key Cryptography Standards
- * (PKCS) #1 v2.1: RSA Cryptography Specifications</em>.
+ * The RSA public-key cryptosystem is defined in <em>Public-Key
+ * Cryptography Standards (PKCS) #1 v1.5: RSA Encryption</em>
+ * and <em>Public-Key Cryptography Standards (PKCS) #1 v2.1:
+ * RSA Cryptography Specifications</em>.
*
*/
/*
@@ -63,8 +64,8 @@
#define MBEDTLS_RSA_PUBLIC 0 /**< Request private key operation. */
#define MBEDTLS_RSA_PRIVATE 1 /**< Request public key operation. */
-#define MBEDTLS_RSA_PKCS_V15 0 /**< Use PKCS-1 v1.5 encoding. */
-#define MBEDTLS_RSA_PKCS_V21 1 /**< Use PKCS-1 v2.1 encoding. */
+#define MBEDTLS_RSA_PKCS_V15 0 /**< Use PKCS#1 v1.5 encoding. */
+#define MBEDTLS_RSA_PKCS_V21 1 /**< Use PKCS#1 v2.1 encoding. */
#define MBEDTLS_RSA_SIGN 1 /**< Identifier for RSA signature operations. */
#define MBEDTLS_RSA_CRYPT 2 /**< Identifier for RSA encryption and decryption operations. */
@@ -76,14 +77,14 @@
* eg for alternative (PKCS#11) RSA implemenations in the PK layers.
*/
-#if !defined(MBEDTLS_RSA_ALT)
-// Regular implementation
-//
-
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_RSA_ALT)
+// Regular implementation
+//
+
/**
* \brief The RSA context structure.
*
@@ -96,24 +97,24 @@
int ver; /*!< Always 0.*/
size_t len; /*!< The size of \p N in Bytes. */
- mbedtls_mpi N; /*!< The public modulus. */
- mbedtls_mpi E; /*!< The public exponent. */
+ mbedtls_mpi N; /*!< The public modulus. */
+ mbedtls_mpi E; /*!< The public exponent. */
- mbedtls_mpi D; /*!< The private exponent. */
- mbedtls_mpi P; /*!< The first prime factor. */
- mbedtls_mpi Q; /*!< The second prime factor. */
+ mbedtls_mpi D; /*!< The private exponent. */
+ mbedtls_mpi P; /*!< The first prime factor. */
+ mbedtls_mpi Q; /*!< The second prime factor. */
- mbedtls_mpi DP; /*!< \p D % (P - 1) */
- mbedtls_mpi DQ; /*!< \p D % (Q - 1) */
- mbedtls_mpi QP; /*!< 1 / (Q % P) */
+ mbedtls_mpi DP; /*!< <code>D % (P - 1)</code>. */
+ mbedtls_mpi DQ; /*!< <code>D % (Q - 1)</code>. */
+ mbedtls_mpi QP; /*!< <code>1 / (Q % P)</code>. */
- mbedtls_mpi RN; /*!< cached R^2 mod \p N */
+ mbedtls_mpi RN; /*!< cached <code>R^2 mod N</code>. */
- mbedtls_mpi RP; /*!< cached R^2 mod \p P */
- mbedtls_mpi RQ; /*!< cached R^2 mod \p Q */
+ mbedtls_mpi RP; /*!< cached <code>R^2 mod P</code>. */
+ mbedtls_mpi RQ; /*!< cached <code>R^2 mod Q</code>. */
- mbedtls_mpi Vi; /*!< The cached blinding value. */
- mbedtls_mpi Vf; /*!< The cached un-blinding value. */
+ mbedtls_mpi Vi; /*!< The cached blinding value. */
+ mbedtls_mpi Vf; /*!< The cached un-blinding value. */
int padding; /*!< Selects padding mode:
#MBEDTLS_RSA_PKCS_V15 for 1.5 padding and
@@ -128,18 +129,16 @@
}
mbedtls_rsa_context;
+#else /* MBEDTLS_RSA_ALT */
+#include "rsa_alt.h"
+#endif /* MBEDTLS_RSA_ALT */
+
/**
* \brief This function initializes an RSA context.
*
* \note Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP
* encryption scheme and the RSASSA-PSS signature scheme.
*
- * \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.
- *
* \note The \p hash_id parameter is ignored when using
* #MBEDTLS_RSA_PKCS_V15 padding.
*
@@ -153,6 +152,12 @@
* encryption. For PSS signatures, it is always used for
* making signatures, but can be overriden for verifying them.
* If set to #MBEDTLS_MD_NONE, it is always overriden.
+ *
+ * \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.
*/
void mbedtls_rsa_init( mbedtls_rsa_context *ctx,
int padding,
@@ -162,13 +167,6 @@
* \brief This function imports a set of core parameters into an
* RSA context.
*
- * \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.
- *
* \note This function can be called multiple times for successive
* imports, if the parameters are not simultaneously present.
*
@@ -184,7 +182,15 @@
* \note The imported parameters are copied and need not be preserved
* for the lifetime of the RSA context being set up.
*
- * \return \c 0 on success, or a non-zero error code on failure.
+ * \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.
+ *
+ * \return \c 0 on success.
+ * \return A non-zero error code on failure.
*/
int mbedtls_rsa_import( mbedtls_rsa_context *ctx,
const mbedtls_mpi *N,
@@ -195,6 +201,21 @@
* \brief This function imports core RSA parameters, in raw big-endian
* binary format, into an RSA context.
*
+ * \note This function can be called multiple times for successive
+ * imports, if the parameters are not simultaneously present.
+ *
+ * Any sequence of calls to this function should be followed
+ * by a call to mbedtls_rsa_complete(), which checks and
+ * completes the provided information to a ready-for-use
+ * public or private RSA key.
+ *
+ * \note See mbedtls_rsa_complete() for more information on which
+ * parameters are necessary to set up a private or public
+ * RSA key.
+ *
+ * \note The imported parameters are copied and need not be preserved
+ * 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.
@@ -207,22 +228,8 @@
* \param E The public exponent, or NULL.
* \param E_len The Byte length of \p E, ignored if \p E == NULL.
*
- * \note This function can be called multiple times for successive
- * imports, if the parameters are not simultaneously present.
- *
- * Any sequence of calls to this function should be followed
- * by a call to mbedtls_rsa_complete(), which checks and
- * completes the provided information to a ready-for-use
- * public or private RSA key.
- *
- * \note See mbedtls_rsa_complete() for more information on which
- * parameters are necessary to set up a private or public
- * RSA key.
- *
- * \note The imported parameters are copied and need not be preserved
- * for the lifetime of the RSA context being set up.
- *
- * \return \c 0 on success, or a non-zero error code on failure.
+ * \return \c 0 on success.
+ * \return A non-zero error code on failure.
*/
int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx,
unsigned char const *N, size_t N_len,
@@ -250,17 +257,18 @@
* the RSA context can be used for RSA operations without
* the risk of failure or crash.
*
- * \param ctx The initialized RSA context holding imported parameters.
- *
- * \return \c 0 on success, or #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the
- * attempted derivations failed.
- *
* \warning This function need not perform consistency checks
* for the imported parameters. In particular, parameters that
* are not needed by the implementation might be silently
* discarded and left unchecked. To check the consistency
* of the key material, see mbedtls_rsa_check_privkey().
*
+ * \param ctx The initialized RSA context holding imported parameters.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted derivations
+ * failed.
+ *
*/
int mbedtls_rsa_complete( mbedtls_rsa_context *ctx );
@@ -292,11 +300,11 @@
* \param D The MPI to hold the private exponent, or NULL.
* \param E The MPI to hold the public exponent, or NULL.
*
- * \return \c 0 on success,
- * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
* requested parameters cannot be done due to missing
- * functionality or because of security policies,
- * or a non-zero return code on any other failure.
+ * functionality or because of security policies.
+ * \return A non-zero return code on any other failure.
*
*/
int mbedtls_rsa_export( const mbedtls_rsa_context *ctx,
@@ -324,6 +332,9 @@
* If the function fails due to an unsupported operation,
* the RSA context stays intact and remains usable.
*
+ * \note The length parameters are ignored if the corresponding
+ * buffer pointers are NULL.
+ *
* \param ctx The initialized RSA context.
* \param N The Byte array to store the RSA modulus, or NULL.
* \param N_len The size of the buffer for the modulus.
@@ -331,21 +342,18 @@
* NULL.
* \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.
+ * NULL.
* \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_len The size of the buffer for the private exponent.
* \param E The Byte array to hold the public exponent, or NULL.
* \param E_len The size of the buffer for the public exponent.
*
- * \note The length fields are ignored if the corresponding
- * buffer pointers are NULL.
- *
- * \return \c 0 on success,
- * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
* requested parameters cannot be done due to missing
- * functionality or because of security policies,
- * or a non-zero return code on any other failure.
+ * functionality or because of security policies.
+ * \return A non-zero return code on any other failure.
*/
int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx,
unsigned char *N, size_t N_len,
@@ -357,16 +365,17 @@
/**
* \brief This function exports CRT parameters of a private RSA key.
*
+ * \note Alternative RSA implementations not using CRT-parameters
+ * internally can implement this function based on
+ * 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.
*
- * \return \c 0 on success, non-zero error code otherwise.
- *
- * \note Alternative RSA implementations not using CRT-parameters
- * internally can implement this function based on
- * mbedtls_rsa_deduce_opt().
+ * \return \c 0 on success.
+ * \return A non-zero error code on failure.
*
*/
int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx,
@@ -397,17 +406,17 @@
/**
* \brief This function generates an RSA keypair.
*
- * \param ctx The RSA context used to hold the key.
- * \param f_rng The RNG function.
- * \param p_rng The RNG parameter.
- * \param nbits The size of the public key in bits.
- * \param exponent The public exponent. For example, 65537.
- *
* \note mbedtls_rsa_init() must be called before this function,
* to set up the RSA context.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- on failure.
+ * \param ctx The RSA context used to hold the key.
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG context.
+ * \param nbits The size of the public key in bits.
+ * \param exponent The public exponent. For example, 65537.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -424,8 +433,8 @@
*
* \param ctx The RSA context to check.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- * on failure.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*
*/
int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
@@ -434,11 +443,6 @@
* \brief This function checks if a context contains an RSA private key
* and perform basic consistency checks.
*
- * \param ctx The RSA context to check.
- *
- * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code on
- * failure.
- *
* \note The consistency checks performed by this function not only
* ensure that mbedtls_rsa_private() can be called successfully
* on the given context, but that the various parameters are
@@ -465,6 +469,11 @@
* user to ensure the trustworthiness of the source of his RSA
* parameters, which goes beyond what is effectively checkable
* by the library.</li></ul>
+ *
+ * \param ctx The RSA context to check.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx );
@@ -476,8 +485,8 @@
* \param pub The RSA context holding the public key.
* \param prv The RSA context holding the private key.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- * on failure.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub,
const mbedtls_rsa_context *prv );
@@ -485,13 +494,6 @@
/**
* \brief This function performs an RSA public key operation.
*
- * \param ctx The RSA context.
- * \param input The input buffer.
- * \param output The output buffer.
- *
- * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- * on failure.
- *
* \note This function does not handle message padding.
*
* \note Make sure to set \p input[0] = 0 or ensure that
@@ -499,6 +501,13 @@
*
* \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.
*/
int mbedtls_rsa_public( mbedtls_rsa_context *ctx,
const unsigned char *input,
@@ -507,15 +516,6 @@
/**
* \brief This function performs an RSA private key operation.
*
- * \param ctx The RSA context.
- * \param f_rng The RNG function. Needed for blinding.
- * \param p_rng The RNG parameter.
- * \param input The input buffer.
- * \param output The output buffer.
- *
- * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- * on failure.
- *
* \note The input and output buffers must be large
* enough. For example, 128 Bytes if RSA-1024 is used.
*
@@ -530,6 +530,15 @@
* 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.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
+ *
*/
int mbedtls_rsa_private( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -544,15 +553,8 @@
* It is the generic wrapper for performing a PKCS#1 encryption
* operation using the \p mode from the context.
*
- *
- * \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 parameter.
- * \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.
+ * \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
@@ -563,11 +565,17 @@
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- * on failure.
+ * \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.
*
- * \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.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -580,14 +588,8 @@
* \brief This function performs a PKCS#1 v1.5 encryption operation
* (RSAES-PKCS1-v1_5-ENCRYPT).
*
- * \param ctx The RSA context.
- * \param f_rng The RNG function. Needed for padding and
- * #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG parameter.
- * \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.
+ * \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
@@ -598,11 +600,17 @@
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- * on failure.
+ * \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.
*
- * \note The output buffer must be as large as the size
- * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -615,10 +623,22 @@
* \brief This function performs a PKCS#1 v2.1 OAEP encryption
* operation (RSAES-OAEP-ENCRYPT).
*
+ * \note The output buffer must be as large as the size
+ * of 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
+ * implicitly set to #MBEDTLS_RSA_PUBLIC.
+ *
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
* \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 parameter.
+ * \param p_rng The RNG context.
* \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
* \param label The buffer holding the custom label to use.
* \param label_len The length of the label.
@@ -626,20 +646,8 @@
* \param input The buffer holding the data to encrypt.
* \param output The buffer used to hold the ciphertext.
*
- * \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
- * implicitly set to #MBEDTLS_RSA_PUBLIC.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
- * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
- * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- * on failure.
- *
- * \note The output buffer must be as large as the size
- * of ctx->N. For example, 128 Bytes if RSA-1024 is used.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -657,14 +665,15 @@
* It is the generic wrapper for performing a PKCS#1 decryption
* operation using the \p mode from the context.
*
- * \param ctx The RSA context.
- * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG parameter.
- * \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.
+ * \note The output buffer length \c output_max_len should be
+ * as large as the size \p ctx->len of \p ctx->N (for example,
+ * 128 Bytes if RSA-1024 is used) to be able to hold an
+ * arbitrary decrypted message. If it is not large enough to
+ * 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
@@ -675,18 +684,17 @@
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- * on failure.
+ * \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.
*
- * \note The output buffer length \c output_max_len should be
- * as large as the size \p ctx->len of \p ctx->N (for example,
- * 128 Bytes if RSA-1024 is used) to be able to hold an
- * arbitrary decrypted message. If it is not large enough to
- * 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.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -700,14 +708,15 @@
* \brief This function performs a PKCS#1 v1.5 decryption
* operation (RSAES-PKCS1-v1_5-DECRYPT).
*
- * \param ctx The RSA context.
- * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG parameter.
- * \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.
+ * \note The output buffer length \c output_max_len should be
+ * as large as the size \p ctx->len of \p ctx->N, for example,
+ * 128 Bytes if RSA-1024 is used, to be able to hold an
+ * arbitrary decrypted message. If it is not large enough to
+ * 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
@@ -718,18 +727,18 @@
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- * on failure.
+ * \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.
*
- * \note The output buffer length \c output_max_len should be
- * as large as the size \p ctx->len of \p ctx->N, for example,
- * 128 Bytes if RSA-1024 is used, to be able to hold an
- * arbitrary decrypted message. If it is not large enough to
- * hold the decryption of the particular ciphertext provided,
- * the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*
- * \note The input buffer must be as large as the size
- * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*/
int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -740,42 +749,42 @@
size_t output_max_len );
/**
- * \brief This function performs a PKCS#1 v2.1 OAEP decryption
- * operation (RSAES-OAEP-DECRYPT).
+ * \brief This function performs a PKCS#1 v2.1 OAEP decryption
+ * operation (RSAES-OAEP-DECRYPT).
+ *
+ * \note The output buffer length \c output_max_len should be
+ * as large as the size \p ctx->len of \p ctx->N, for
+ * example, 128 Bytes if RSA-1024 is used, to be able to
+ * hold an arbitrary decrypted message. If it is not
+ * large enough to 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
+ * implicitly set to #MBEDTLS_RSA_PRIVATE.
+ *
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
* \param ctx The RSA context.
* \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG parameter.
+ * \param p_rng The RNG context.
* \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
* \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.
+ * \param output_max_len The maximum length of the output buffer.
*
- * \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
- * implicitly set to #MBEDTLS_RSA_PRIVATE.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
- * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
- * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- * on failure.
- *
- * \note The output buffer length \c output_max_len should be
- * as large as the size \p ctx->len of \p ctx->N, for
- * example, 128 Bytes if RSA-1024 is used, to be able to
- * hold an arbitrary decrypted message. If it is not
- * large enough to 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.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -794,16 +803,12 @@
* It is the generic wrapper for performing a PKCS#1
* signature using the \p mode from the context.
*
- * \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 parameter.
- * \param mode #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 sig The buffer to hold the ciphertext.
+ * \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_sign() for details on
+ * \p md_alg and \p hash_id.
*
* \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
@@ -814,15 +819,19 @@
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return \c 0 if the signing operation was successful,
- * or an \c MBEDTLS_ERR_RSA_XXX error code on failure.
+ * \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 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.
*
- * \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_sign() for details on
- * \p md_alg and \p hash_id.
+ * \return \c 0 if the signing operation was successful.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -837,15 +846,8 @@
* \brief This function performs a PKCS#1 v1.5 signature
* operation (RSASSA-PKCS1-v1_5-SIGN).
*
- * \param ctx The RSA context.
- * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG parameter.
- * \param mode #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 sig The buffer to hold the ciphertext.
+ * \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
@@ -856,12 +858,18 @@
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return \c 0 if the signing operation was successful,
- * or an \c MBEDTLS_ERR_RSA_XXX error code
- * on failure.
+ * \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 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.
*
- * \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.
+ * \return \c 0 if the signing operation was successful.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -876,16 +884,15 @@
* \brief This function performs a PKCS#1 v2.1 PSS signature
* operation (RSASSA-PSS-SIGN).
*
- * \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 parameter.
- * \param mode #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 sig The buffer to hold the ciphertext.
+ * \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
+ * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
+ * Specifications</em> it is advised to keep both hashes the
+ * same.
*
* \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
@@ -896,19 +903,19 @@
* mode being set to #MBEDTLS_RSA_PUBLIC and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return \c 0 if the signing operation was successful,
- * or an \c MBEDTLS_ERR_RSA_XXX error code
- * on failure.
+ * \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 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.
*
- * \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
- * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
- * Specifications</em> it is advised to keep both hashes the
- * same.
+ * \return \c 0 if the signing operation was successful.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -926,15 +933,12 @@
* This is the generic wrapper for performing a PKCS#1
* verification using the mode from the context.
*
- * \param ctx The RSA public key context.
- * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG parameter.
- * \param mode #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 sig The buffer holding the ciphertext.
+ * \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.
*
* \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
@@ -945,16 +949,18 @@
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return \c 0 if the verify operation was successful,
- * or an \c MBEDTLS_ERR_RSA_XXX error code
- * on failure.
+ * \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 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.
*
- * \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.
+ * \return \c 0 if the verify operation was successful.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -969,15 +975,8 @@
* \brief This function performs a PKCS#1 v1.5 verification
* operation (RSASSA-PKCS1-v1_5-VERIFY).
*
- * \param ctx The RSA public key context.
- * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG parameter.
- * \param mode #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 sig The buffer holding the ciphertext.
+ * \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
@@ -988,12 +987,18 @@
* mode being set to #MBEDTLS_RSA_PRIVATE and might instead
* return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return \c 0 if the verify operation was successful,
- * or an \c MBEDTLS_ERR_RSA_XXX error code
- * on failure.
+ * \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 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.
*
- * \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.
+ * \return \c 0 if the verify operation was successful.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -1011,29 +1016,6 @@
* The hash function for the MGF mask generating function
* is that specified in the RSA context.
*
- * \param ctx The RSA public key context.
- * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG parameter.
- * \param mode #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 sig The buffer holding the ciphertext.
- *
- * \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
- * implicitly set to #MBEDTLS_RSA_PUBLIC.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
- * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
- * \return \c 0 if the verify operation was successful,
- * or an \c MBEDTLS_ERR_RSA_XXX error code
- * on failure.
- *
* \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.
*
@@ -1044,6 +1026,28 @@
* Specifications</em> it is advised to keep both hashes the
* same. If \p hash_id in the RSA context is unset,
* the \p md_alg from the function call 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
+ * implicitly set to #MBEDTLS_RSA_PUBLIC.
+ *
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
+ * \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 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.
+ *
+ * \return \c 0 if the verify operation was successful.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -1061,27 +1065,27 @@
* The hash function for the MGF mask generating function
* is that specified in \p mgf1_hash_id.
*
- * \param ctx The RSA public key context.
- * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng The RNG parameter.
- * \param mode #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.
- *
- * \return \c 0 if the verify operation was successful,
- * or an \c MBEDTLS_ERR_RSA_XXX error code
- * on failure.
- *
* \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 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 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.
+ *
+ * \return \c 0 if the verify operation was successful.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -1100,8 +1104,8 @@
* \param dst The destination context.
* \param src The source context.
*
- * \return \c 0 on success,
- * #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure.
*/
int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src );
@@ -1112,22 +1116,11 @@
*/
void mbedtls_rsa_free( mbedtls_rsa_context *ctx );
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_RSA_ALT */
-#include "rsa_alt.h"
-#endif /* MBEDTLS_RSA_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
/**
* \brief The RSA checkup routine.
*
- * \return \c 0 on success, or \c 1 on failure.
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_rsa_self_test( int verbose );
diff --git a/include/mbedtls/sha1.h b/include/mbedtls/sha1.h
index 05540cd..8f805fb 100644
--- a/include/mbedtls/sha1.h
+++ b/include/mbedtls/sha1.h
@@ -1,7 +1,10 @@
/**
* \file sha1.h
*
- * \brief The SHA-1 cryptographic hash function.
+ * \brief This file contains SHA-1 definitions and functions.
+ *
+ * The Secure Hash Algorithm 1 (SHA-1) cryptographic hash function is defined in
+ * <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
*
* \warning SHA-1 is considered a weak message digest and its use constitutes
* a security risk. We recommend considering stronger message
@@ -39,14 +42,14 @@
#define MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED -0x0035 /**< SHA-1 hardware accelerator failed */
-#if !defined(MBEDTLS_SHA1_ALT)
-// Regular implementation
-//
-
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_SHA1_ALT)
+// Regular implementation
+//
+
/**
* \brief The SHA-1 context structure.
*
@@ -63,40 +66,44 @@
}
mbedtls_sha1_context;
+#else /* MBEDTLS_SHA1_ALT */
+#include "sha1_alt.h"
+#endif /* MBEDTLS_SHA1_ALT */
+
/**
* \brief This function initializes a SHA-1 context.
*
- * \param ctx The SHA-1 context to initialize.
- *
* \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
+ * \param ctx The SHA-1 context to initialize.
+ *
*/
void mbedtls_sha1_init( mbedtls_sha1_context *ctx );
/**
* \brief This function clears a SHA-1 context.
*
- * \param ctx The SHA-1 context to clear.
- *
* \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
+ * \param ctx The SHA-1 context to clear.
+ *
*/
void mbedtls_sha1_free( mbedtls_sha1_context *ctx );
/**
* \brief This function clones the state of a SHA-1 context.
*
- * \param dst The destination context.
- * \param src The context to clone.
- *
* \warning SHA-1 is considered a weak message digest and its use
* 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.
+ *
*/
void mbedtls_sha1_clone( mbedtls_sha1_context *dst,
const mbedtls_sha1_context *src );
@@ -104,14 +111,14 @@
/**
* \brief This function starts a SHA-1 checksum calculation.
*
- * \param ctx The context to initialize.
- *
- * \return \c 0 if successful
- *
* \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
+ * \param ctx The SHA-1 context to initialize.
+ *
+ * \return \c 0 on success.
+ *
*/
int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx );
@@ -119,16 +126,15 @@
* \brief This function feeds an input buffer into an ongoing SHA-1
* checksum calculation.
*
- * \param ctx The SHA-1 context.
- * \param input The buffer holding the input data.
- * \param ilen The length of the input data.
- *
- * \return \c 0 if successful
- *
* \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
+ * \param ctx The SHA-1 context.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ *
+ * \return \c 0 on success.
*/
int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx,
const unsigned char *input,
@@ -138,31 +144,30 @@
* \brief This function finishes the SHA-1 operation, and writes
* the result to the output buffer.
*
- * \param ctx The SHA-1 context.
- * \param output The SHA-1 checksum result.
- *
- * \return \c 0 if successful
- *
* \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
+ * \param ctx The SHA-1 context.
+ * \param output The SHA-1 checksum result.
+ *
+ * \return \c 0 on success.
*/
int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx,
unsigned char output[20] );
/**
- * \brief SHA-1 process data block (internal use only)
- *
- * \param ctx SHA-1 context
- * \param data The data block being processed.
- *
- * \return \c 0 if successful
+ * \brief SHA-1 process data block (internal use only).
*
* \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
+ * \param ctx The SHA-1 context.
+ * \param data The data block being processed.
+ *
+ * \return \c 0 on success.
+ *
*/
int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx,
const unsigned char data[64] );
@@ -174,65 +179,67 @@
#define MBEDTLS_DEPRECATED
#endif
/**
- * \brief SHA-1 context setup
- *
- * \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0
- *
- * \param ctx The SHA-1 context to be initialized.
+ * \brief This function starts a SHA-1 checksum calculation.
*
* \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
+ * \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0.
+ *
+ * \param ctx The SHA-1 context to initialize.
+ *
*/
MBEDTLS_DEPRECATED void mbedtls_sha1_starts( mbedtls_sha1_context *ctx );
/**
- * \brief SHA-1 process buffer
- *
- * \deprecated Superseded by mbedtls_sha1_update_ret() in 2.7.0
- *
- * \param ctx The SHA-1 context.
- * \param input The buffer holding the input data.
- * \param ilen The length of the input data.
+ * \brief This function feeds an input buffer into an ongoing SHA-1
+ * checksum calculation.
*
* \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
+ * \deprecated Superseded by mbedtls_sha1_update_ret() in 2.7.0.
+ *
+ * \param ctx The SHA-1 context.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ *
*/
MBEDTLS_DEPRECATED void mbedtls_sha1_update( mbedtls_sha1_context *ctx,
const unsigned char *input,
size_t ilen );
/**
- * \brief SHA-1 final digest
- *
- * \deprecated Superseded by mbedtls_sha1_finish_ret() in 2.7.0
- *
- * \param ctx The SHA-1 context.
- * \param output The SHA-1 checksum result.
+ * \brief This function finishes the SHA-1 operation, and writes
+ * the result to the output buffer.
*
* \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
+ * \deprecated Superseded by mbedtls_sha1_finish_ret() in 2.7.0.
+ *
+ * \param ctx The SHA-1 context.
+ * \param output The SHA-1 checksum result.
+ *
*/
MBEDTLS_DEPRECATED void mbedtls_sha1_finish( mbedtls_sha1_context *ctx,
unsigned char output[20] );
/**
- * \brief SHA-1 process data block (internal use only)
- *
- * \deprecated Superseded by mbedtls_internal_sha1_process() in 2.7.0
- *
- * \param ctx The SHA-1 context.
- * \param data The data block being processed.
+ * \brief SHA-1 process data block (internal use only).
*
* \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
+ * \deprecated Superseded by mbedtls_internal_sha1_process() in 2.7.0.
+ *
+ * \param ctx The SHA-1 context.
+ * \param data The data block being processed.
+ *
*/
MBEDTLS_DEPRECATED void mbedtls_sha1_process( mbedtls_sha1_context *ctx,
const unsigned char data[64] );
@@ -240,18 +247,6 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_SHA1_ALT */
-#include "sha1_alt.h"
-#endif /* MBEDTLS_SHA1_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
/**
* \brief This function calculates the SHA-1 checksum of a buffer.
*
@@ -261,15 +256,15 @@
* The SHA-1 result is calculated as
* output = SHA-1(input buffer).
*
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
* \param output The SHA-1 checksum result.
*
- * \return \c 0 if successful
- *
- * \warning SHA-1 is considered a weak message digest and its use
- * constitutes a security risk. We recommend considering
- * stronger message digests instead.
+ * \return \c 0 on success.
*
*/
int mbedtls_sha1_ret( const unsigned char *input,
@@ -283,7 +278,17 @@
#define MBEDTLS_DEPRECATED
#endif
/**
- * \brief Output = SHA-1( input buffer )
+ * \brief This function calculates the SHA-1 checksum of a buffer.
+ *
+ * The function allocates the context, performs the
+ * calculation, and frees the context.
+ *
+ * The SHA-1 result is calculated as
+ * output = SHA-1(input buffer).
+ *
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
*
* \deprecated Superseded by mbedtls_sha1_ret() in 2.7.0
*
@@ -291,10 +296,6 @@
* \param ilen The length of the input data.
* \param output The SHA-1 checksum result.
*
- * \warning SHA-1 is considered a weak message digest and its use
- * constitutes a security risk. We recommend considering
- * stronger message digests instead.
- *
*/
MBEDTLS_DEPRECATED void mbedtls_sha1( const unsigned char *input,
size_t ilen,
@@ -306,12 +307,13 @@
/**
* \brief The SHA-1 checkup routine.
*
- * \return \c 0 on success, or \c 1 on failure.
- *
* \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
+ *
*/
int mbedtls_sha1_self_test( int verbose );
diff --git a/include/mbedtls/sha256.h b/include/mbedtls/sha256.h
index ffb16c2..adf31a8 100644
--- a/include/mbedtls/sha256.h
+++ b/include/mbedtls/sha256.h
@@ -1,7 +1,10 @@
/**
* \file sha256.h
*
- * \brief The SHA-224 and SHA-256 cryptographic hash function.
+ * \brief This file contains SHA-224 and SHA-256 definitions and functions.
+ *
+ * The Secure Hash Algorithms 224 and 256 (SHA-224 and SHA-256) cryptographic
+ * hash functions are defined in <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
*/
/*
* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
@@ -35,14 +38,14 @@
#define MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED -0x0037 /**< SHA-256 hardware accelerator failed */
-#if !defined(MBEDTLS_SHA256_ALT)
-// Regular implementation
-//
-
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_SHA256_ALT)
+// Regular implementation
+//
+
/**
* \brief The SHA-256 context structure.
*
@@ -55,12 +58,15 @@
uint32_t total[2]; /*!< The number of Bytes processed. */
uint32_t state[8]; /*!< The intermediate digest state. */
unsigned char buffer[64]; /*!< The data block being processed. */
- int is224; /*!< Determines which function to use.
- <ul><li>0: Use SHA-256.</li>
- <li>1: Use SHA-224.</li></ul> */
+ int is224; /*!< Determines which function to use:
+ 0: Use SHA-256, or 1: Use SHA-224. */
}
mbedtls_sha256_context;
+#else /* MBEDTLS_SHA256_ALT */
+#include "sha256_alt.h"
+#endif /* MBEDTLS_SHA256_ALT */
+
/**
* \brief This function initializes a SHA-256 context.
*
@@ -89,9 +95,8 @@
* calculation.
*
* \param ctx The context to initialize.
- * \param is224 Determines which function to use.
- * <ul><li>0: Use SHA-256.</li>
- * <li>1: Use SHA-224.</li></ul>
+ * \param is224 Determines which function to use:
+ * 0: Use SHA-256, or 1: Use SHA-224.
*
* \return \c 0 on success.
*/
@@ -101,9 +106,9 @@
* \brief This function feeds an input buffer into an ongoing
* SHA-256 checksum calculation.
*
- * \param ctx SHA-256 context
- * \param input buffer holding the data
- * \param ilen length of the input data
+ * \param ctx The SHA-256 context.
+ * \param input The buffer holding the data.
+ * \param ilen The length of the input data.
*
* \return \c 0 on success.
*/
@@ -143,14 +148,15 @@
#define MBEDTLS_DEPRECATED
#endif
/**
- * \brief This function starts a SHA-256 checksum calculation.
+ * \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 SHA-256 context to initialize.
- * \param is224 Determines which function to use.
- * <ul><li>0: Use SHA-256.</li>
- * <li>1: Use SHA-224.</li></ul>
+ * \param ctx The context to initialize.
+ * \param is224 Determines which function to use:
+ * 0: Use SHA-256, or 1: Use SHA-224.
*/
MBEDTLS_DEPRECATED void mbedtls_sha256_starts( mbedtls_sha256_context *ctx,
int is224 );
@@ -176,7 +182,7 @@
* \deprecated Superseded by mbedtls_sha256_finish_ret() in 2.7.0.
*
* \param ctx The SHA-256 context.
- * \param output The SHA-224or SHA-256 checksum result.
+ * \param output The SHA-224 or SHA-256 checksum result.
*/
MBEDTLS_DEPRECATED void mbedtls_sha256_finish( mbedtls_sha256_context *ctx,
unsigned char output[32] );
@@ -196,17 +202,6 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_SHA256_ALT */
-#include "sha256_alt.h"
-#endif /* MBEDTLS_SHA256_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
/**
* \brief This function calculates the SHA-224 or SHA-256
@@ -221,9 +216,8 @@
* \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.
- * <ul><li>0: Use SHA-256.</li>
- * <li>1: Use SHA-224.</li></ul>
+ * \param is224 Determines which function to use:
+ * 0: Use SHA-256, or 1: Use SHA-224.
*/
int mbedtls_sha256_ret( const unsigned char *input,
size_t ilen,
@@ -252,9 +246,8 @@
* \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.
- * <ul><li>0: Use SHA-256.</li>
- * <li>1: Use SHA-224.</li></ul>
+ * \param is224 Determines which function to use:
+ * 0: Use SHA-256, or 1: Use SHA-224.
*/
MBEDTLS_DEPRECATED void mbedtls_sha256( const unsigned char *input,
size_t ilen,
@@ -267,7 +260,8 @@
/**
* \brief The SHA-224 and SHA-256 checkup routine.
*
- * \return \c 0 on success, or \c 1 on failure.
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_sha256_self_test( int verbose );
diff --git a/include/mbedtls/sha512.h b/include/mbedtls/sha512.h
index 8404a2d..5bb83f4 100644
--- a/include/mbedtls/sha512.h
+++ b/include/mbedtls/sha512.h
@@ -1,7 +1,9 @@
/**
* \file sha512.h
+ * \brief This file contains SHA-384 and SHA-512 definitions and functions.
*
- * \brief The SHA-384 and SHA-512 cryptographic hash function.
+ * The Secure Hash Algorithms 384 and 512 (SHA-384 and SHA-512) cryptographic
+ * hash functions are defined in <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
*/
/*
* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
@@ -35,14 +37,14 @@
#define MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED -0x0039 /**< SHA-512 hardware accelerator failed */
-#if !defined(MBEDTLS_SHA512_ALT)
-// Regular implementation
-//
-
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_SHA512_ALT)
+// Regular implementation
+//
+
/**
* \brief The SHA-512 context structure.
*
@@ -55,12 +57,15 @@
uint64_t total[2]; /*!< The number of Bytes processed. */
uint64_t state[8]; /*!< The intermediate digest state. */
unsigned char buffer[128]; /*!< The data block being processed. */
- int is384; /*!< Determines which function to use.
- * <ul><li>0: Use SHA-512.</li>
- * <li>1: Use SHA-384.</li></ul> */
+ int is384; /*!< Determines which function to use:
+ 0: Use SHA-512, or 1: Use SHA-384. */
}
mbedtls_sha512_context;
+#else /* MBEDTLS_SHA512_ALT */
+#include "sha512_alt.h"
+#endif /* MBEDTLS_SHA512_ALT */
+
/**
* \brief This function initializes a SHA-512 context.
*
@@ -89,9 +94,8 @@
* calculation.
*
* \param ctx The SHA-512 context to initialize.
- * \param is384 Determines which function to use.
- * <ul><li>0: Use SHA-512.</li>
- * <li>1: Use SHA-384.</li></ul>
+ * \param is384 Determines which function to use:
+ * 0: Use SHA-512, or 1: Use SHA-384.
*
* \return \c 0 on success.
*/
@@ -148,9 +152,8 @@
* \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.
- * <ul><li>0: Use SHA-512.</li>
- * <li>1: Use SHA-384.</li></ul>
+ * \param is384 Determines which function to use:
+ * 0: Use SHA-512, or 1: Use SHA-384.
*/
MBEDTLS_DEPRECATED void mbedtls_sha512_starts( mbedtls_sha512_context *ctx,
int is384 );
@@ -159,7 +162,7 @@
* \brief This function feeds an input buffer into an ongoing
* SHA-512 checksum calculation.
*
- * \deprecated Superseded by mbedtls_sha512_update_ret() in 2.7.0
+ * \deprecated Superseded by mbedtls_sha512_update_ret() in 2.7.0.
*
* \param ctx The SHA-512 context.
* \param input The buffer holding the data.
@@ -173,7 +176,7 @@
* \brief This function finishes the SHA-512 operation, and writes
* the result to the output buffer.
*
- * \deprecated Superseded by mbedtls_sha512_finish_ret() in 2.7.0
+ * \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.
@@ -186,7 +189,7 @@
* the ongoing SHA-512 computation. This function is for
* internal use only.
*
- * \deprecated Superseded by mbedtls_internal_sha512_process() in 2.7.0
+ * \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.
@@ -198,18 +201,6 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_SHA512_ALT */
-#include "sha512_alt.h"
-#endif /* MBEDTLS_SHA512_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
/**
* \brief This function calculates the SHA-512 or SHA-384
* checksum of a buffer.
@@ -223,9 +214,8 @@
* \param input The buffer holding the input 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.
- * <ul><li>0: Use SHA-512.</li>
- * <li>1: Use SHA-384.</li></ul>
+ * \param is384 Determines which function to use:
+ * 0: Use SHA-512, or 1: Use SHA-384.
*
* \return \c 0 on success.
*/
@@ -255,9 +245,8 @@
* \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.
- * <ul><li>0: Use SHA-512.</li>
- * <li>1: Use SHA-384.</li></ul>
+ * \param is384 Determines which function to use:
+ * 0: Use SHA-512, or 1: Use SHA-384.
*/
MBEDTLS_DEPRECATED void mbedtls_sha512( const unsigned char *input,
size_t ilen,
@@ -269,7 +258,8 @@
/**
* \brief The SHA-384 or SHA-512 checkup routine.
*
- * \return \c 0 on success, or \c 1 on failure.
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_sha512_self_test( int verbose );
diff --git a/include/mbedtls/timing.h b/include/mbedtls/timing.h
index 2c497bf..bbcb906 100644
--- a/include/mbedtls/timing.h
+++ b/include/mbedtls/timing.h
@@ -30,16 +30,16 @@
#include MBEDTLS_CONFIG_FILE
#endif
-#if !defined(MBEDTLS_TIMING_ALT)
-// Regular implementation
-//
-
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_TIMING_ALT)
+// Regular implementation
+//
+
/**
* \brief timer structure
*/
@@ -58,6 +58,10 @@
uint32_t fin_ms;
} mbedtls_timing_delay_context;
+#else /* MBEDTLS_TIMING_ALT */
+#include "timing_alt.h"
+#endif /* MBEDTLS_TIMING_ALT */
+
extern volatile int mbedtls_timing_alarmed;
/**
@@ -133,18 +137,6 @@
*/
int mbedtls_timing_get_delay( void *data );
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_TIMING_ALT */
-#include "timing_alt.h"
-#endif /* MBEDTLS_TIMING_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
#if defined(MBEDTLS_SELF_TEST)
/**
* \brief Checkup routine
diff --git a/include/mbedtls/version.h b/include/mbedtls/version.h
index c3ee649..aa52ce2 100644
--- a/include/mbedtls/version.h
+++ b/include/mbedtls/version.h
@@ -39,7 +39,7 @@
* Major, Minor, Patchlevel
*/
#define MBEDTLS_VERSION_MAJOR 2
-#define MBEDTLS_VERSION_MINOR 8
+#define MBEDTLS_VERSION_MINOR 9
#define MBEDTLS_VERSION_PATCH 0
/**
@@ -47,9 +47,9 @@
* MMNNPP00
* Major version | Minor version | Patch version
*/
-#define MBEDTLS_VERSION_NUMBER 0x02080000
-#define MBEDTLS_VERSION_STRING "2.8.0"
-#define MBEDTLS_VERSION_STRING_FULL "mbed TLS 2.8.0"
+#define MBEDTLS_VERSION_NUMBER 0x02090000
+#define MBEDTLS_VERSION_STRING "2.9.0"
+#define MBEDTLS_VERSION_STRING_FULL "mbed TLS 2.9.0"
#if defined(MBEDTLS_VERSION_C)
diff --git a/include/mbedtls/xtea.h b/include/mbedtls/xtea.h
index 34ccee3..8df708a 100644
--- a/include/mbedtls/xtea.h
+++ b/include/mbedtls/xtea.h
@@ -39,14 +39,14 @@
#define MBEDTLS_ERR_XTEA_INVALID_INPUT_LENGTH -0x0028 /**< The data input has an invalid length. */
#define MBEDTLS_ERR_XTEA_HW_ACCEL_FAILED -0x0029 /**< XTEA hardware accelerator failed. */
-#if !defined(MBEDTLS_XTEA_ALT)
-// Regular implementation
-//
-
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_XTEA_ALT)
+// Regular implementation
+//
+
/**
* \brief XTEA context structure
*/
@@ -56,6 +56,10 @@
}
mbedtls_xtea_context;
+#else /* MBEDTLS_XTEA_ALT */
+#include "xtea_alt.h"
+#endif /* MBEDTLS_XTEA_ALT */
+
/**
* \brief Initialize XTEA context
*
@@ -115,18 +119,6 @@
unsigned char *output);
#endif /* MBEDTLS_CIPHER_MODE_CBC */
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_XTEA_ALT */
-#include "xtea_alt.h"
-#endif /* MBEDTLS_XTEA_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
/**
* \brief Checkup routine
*
diff --git a/library/CMakeLists.txt b/library/CMakeLists.txt
index e525731..6177ca2 100644
--- a/library/CMakeLists.txt
+++ b/library/CMakeLists.txt
@@ -142,15 +142,15 @@
if(USE_SHARED_MBEDTLS_LIBRARY)
add_library(mbedcrypto SHARED ${src_crypto})
- set_target_properties(mbedcrypto PROPERTIES VERSION 2.8.0 SOVERSION 1)
+ set_target_properties(mbedcrypto PROPERTIES VERSION 2.9.0 SOVERSION 2)
target_link_libraries(mbedcrypto ${libs})
add_library(mbedx509 SHARED ${src_x509})
- set_target_properties(mbedx509 PROPERTIES VERSION 2.8.0 SOVERSION 0)
+ set_target_properties(mbedx509 PROPERTIES VERSION 2.9.0 SOVERSION 0)
target_link_libraries(mbedx509 ${libs} mbedcrypto)
add_library(mbedtls SHARED ${src_tls})
- set_target_properties(mbedtls PROPERTIES VERSION 2.8.0 SOVERSION 10)
+ set_target_properties(mbedtls PROPERTIES VERSION 2.9.0 SOVERSION 10)
target_link_libraries(mbedtls ${libs} mbedx509)
install(TARGETS mbedtls mbedx509 mbedcrypto
diff --git a/library/Makefile b/library/Makefile
index c6ec153..b155c72 100644
--- a/library/Makefile
+++ b/library/Makefile
@@ -33,7 +33,7 @@
SOEXT_TLS=so.10
SOEXT_X509=so.0
-SOEXT_CRYPTO=so.1
+SOEXT_CRYPTO=so.2
# Set DLEXT=dylib to compile as a shared library for Mac OS X
DLEXT ?= so
diff --git a/library/bignum.c b/library/bignum.c
index 02d93ed..423e375 100644
--- a/library/bignum.c
+++ b/library/bignum.c
@@ -2191,12 +2191,23 @@
/*
* Prime number generation
+ *
+ * If dh_flag is 0 and nbits is at least 1024, then the procedure
+ * follows the RSA probably-prime generation method of FIPS 186-4.
+ * NB. FIPS 186-4 only allows the specific bit lengths of 1024 and 1536.
*/
int mbedtls_mpi_gen_prime( mbedtls_mpi *X, size_t nbits, int dh_flag,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng )
{
- int ret;
+#ifdef MBEDTLS_HAVE_INT64
+// ceil(2^63.5)
+#define CEIL_MAXUINT_DIV_SQRT2 0xb504f333f9de6485ULL
+#else
+// ceil(2^31.5)
+#define CEIL_MAXUINT_DIV_SQRT2 0xb504f334U
+#endif
+ int ret = MBEDTLS_ERR_MPI_NOT_ACCEPTABLE;
size_t k, n;
mbedtls_mpi_uint r;
mbedtls_mpi Y;
@@ -2208,69 +2219,66 @@
n = BITS_TO_LIMBS( nbits );
- MBEDTLS_MPI_CHK( mbedtls_mpi_fill_random( X, n * ciL, f_rng, p_rng ) );
-
- k = mbedtls_mpi_bitlen( X );
- if( k > nbits ) MBEDTLS_MPI_CHK( mbedtls_mpi_shift_r( X, k - nbits + 1 ) );
-
- mbedtls_mpi_set_bit( X, nbits-1, 1 );
-
- X->p[0] |= 1;
-
- if( dh_flag == 0 )
+ while( 1 )
{
- while( ( ret = mbedtls_mpi_is_prime( X, f_rng, p_rng ) ) != 0 )
+ MBEDTLS_MPI_CHK( mbedtls_mpi_fill_random( X, n * ciL, f_rng, p_rng ) );
+ /* make sure generated number is at least (nbits-1)+0.5 bits (FIPS 186-4 §B.3.3 steps 4.4, 5.5) */
+ if( X->p[n-1] < CEIL_MAXUINT_DIV_SQRT2 ) continue;
+
+ k = n * biL;
+ if( k > nbits ) MBEDTLS_MPI_CHK( mbedtls_mpi_shift_r( X, k - nbits ) );
+ X->p[0] |= 1;
+
+ if( dh_flag == 0 )
{
+ ret = mbedtls_mpi_is_prime( X, f_rng, p_rng );
+
if( ret != MBEDTLS_ERR_MPI_NOT_ACCEPTABLE )
goto cleanup;
-
- MBEDTLS_MPI_CHK( mbedtls_mpi_add_int( X, X, 2 ) );
}
- }
- else
- {
- /*
- * An necessary condition for Y and X = 2Y + 1 to be prime
- * is X = 2 mod 3 (which is equivalent to Y = 2 mod 3).
- * Make sure it is satisfied, while keeping X = 3 mod 4
- */
-
- X->p[0] |= 2;
-
- MBEDTLS_MPI_CHK( mbedtls_mpi_mod_int( &r, X, 3 ) );
- if( r == 0 )
- MBEDTLS_MPI_CHK( mbedtls_mpi_add_int( X, X, 8 ) );
- else if( r == 1 )
- MBEDTLS_MPI_CHK( mbedtls_mpi_add_int( X, X, 4 ) );
-
- /* Set Y = (X-1) / 2, which is X / 2 because X is odd */
- MBEDTLS_MPI_CHK( mbedtls_mpi_copy( &Y, X ) );
- MBEDTLS_MPI_CHK( mbedtls_mpi_shift_r( &Y, 1 ) );
-
- while( 1 )
+ else
{
/*
- * First, check small factors for X and Y
- * before doing Miller-Rabin on any of them
+ * An necessary condition for Y and X = 2Y + 1 to be prime
+ * is X = 2 mod 3 (which is equivalent to Y = 2 mod 3).
+ * Make sure it is satisfied, while keeping X = 3 mod 4
*/
- if( ( ret = mpi_check_small_factors( X ) ) == 0 &&
- ( ret = mpi_check_small_factors( &Y ) ) == 0 &&
- ( ret = mpi_miller_rabin( X, f_rng, p_rng ) ) == 0 &&
- ( ret = mpi_miller_rabin( &Y, f_rng, p_rng ) ) == 0 )
+
+ X->p[0] |= 2;
+
+ MBEDTLS_MPI_CHK( mbedtls_mpi_mod_int( &r, X, 3 ) );
+ if( r == 0 )
+ MBEDTLS_MPI_CHK( mbedtls_mpi_add_int( X, X, 8 ) );
+ else if( r == 1 )
+ MBEDTLS_MPI_CHK( mbedtls_mpi_add_int( X, X, 4 ) );
+
+ /* Set Y = (X-1) / 2, which is X / 2 because X is odd */
+ MBEDTLS_MPI_CHK( mbedtls_mpi_copy( &Y, X ) );
+ MBEDTLS_MPI_CHK( mbedtls_mpi_shift_r( &Y, 1 ) );
+
+ while( 1 )
{
- break;
+ /*
+ * First, check small factors for X and Y
+ * before doing Miller-Rabin on any of them
+ */
+ if( ( ret = mpi_check_small_factors( X ) ) == 0 &&
+ ( ret = mpi_check_small_factors( &Y ) ) == 0 &&
+ ( ret = mpi_miller_rabin( X, f_rng, p_rng ) ) == 0 &&
+ ( ret = mpi_miller_rabin( &Y, f_rng, p_rng ) ) == 0 )
+ goto cleanup;
+
+ if( ret != MBEDTLS_ERR_MPI_NOT_ACCEPTABLE )
+ goto cleanup;
+
+ /*
+ * Next candidates. We want to preserve Y = (X-1) / 2 and
+ * Y = 1 mod 2 and Y = 2 mod 3 (eq X = 3 mod 4 and X = 2 mod 3)
+ * so up Y by 6 and X by 12.
+ */
+ MBEDTLS_MPI_CHK( mbedtls_mpi_add_int( X, X, 12 ) );
+ MBEDTLS_MPI_CHK( mbedtls_mpi_add_int( &Y, &Y, 6 ) );
}
-
- if( ret != MBEDTLS_ERR_MPI_NOT_ACCEPTABLE )
- goto cleanup;
-
- /*
- * Next candidates. We want to preserve Y = (X-1) / 2 and
- * Y = 1 mod 2 and Y = 2 mod 3 (eq X = 3 mod 4 and X = 2 mod 3)
- * so up Y by 6 and X by 12.
- */
- MBEDTLS_MPI_CHK( mbedtls_mpi_add_int( X, X, 12 ) );
- MBEDTLS_MPI_CHK( mbedtls_mpi_add_int( &Y, &Y, 6 ) );
}
}
diff --git a/library/error.c b/library/error.c
index 96ab203..222d85b 100644
--- a/library/error.c
+++ b/library/error.c
@@ -256,19 +256,19 @@
if( use_ret == -(MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL) )
mbedtls_snprintf( buf, buflen, "ECP - The buffer is too small to write to" );
if( use_ret == -(MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE) )
- mbedtls_snprintf( buf, buflen, "ECP - Requested curve not available" );
+ mbedtls_snprintf( buf, buflen, "ECP - The requested feature is not available, for example, the requested curve is not supported" );
if( use_ret == -(MBEDTLS_ERR_ECP_VERIFY_FAILED) )
mbedtls_snprintf( buf, buflen, "ECP - The signature is not valid" );
if( use_ret == -(MBEDTLS_ERR_ECP_ALLOC_FAILED) )
mbedtls_snprintf( buf, buflen, "ECP - Memory allocation failed" );
if( use_ret == -(MBEDTLS_ERR_ECP_RANDOM_FAILED) )
- mbedtls_snprintf( buf, buflen, "ECP - Generation of random value, such as (ephemeral) key, failed" );
+ mbedtls_snprintf( buf, buflen, "ECP - Generation of random value, such as ephemeral key, failed" );
if( use_ret == -(MBEDTLS_ERR_ECP_INVALID_KEY) )
mbedtls_snprintf( buf, buflen, "ECP - Invalid private or public key" );
if( use_ret == -(MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH) )
mbedtls_snprintf( buf, buflen, "ECP - The buffer contains a valid signature followed by more data" );
if( use_ret == -(MBEDTLS_ERR_ECP_HW_ACCEL_FAILED) )
- mbedtls_snprintf( buf, buflen, "ECP - ECP hardware accelerator failed" );
+ mbedtls_snprintf( buf, buflen, "ECP - The ECP hardware accelerator failed" );
#endif /* MBEDTLS_ECP_C */
#if defined(MBEDTLS_MD_C)
diff --git a/library/rsa.c b/library/rsa.c
index 0055223..88c1cf1 100644
--- a/library/rsa.c
+++ b/library/rsa.c
@@ -491,6 +491,9 @@
/*
* Generate an RSA keypair
+ *
+ * This generation method follows the RSA key pair generation procedure of
+ * FIPS 186-4 if 2^16 < exponent < 2^256 and nbits = 2048 or nbits = 3072.
*/
int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -498,7 +501,7 @@
unsigned int nbits, int exponent )
{
int ret;
- mbedtls_mpi H, G;
+ mbedtls_mpi H, G, L;
if( f_rng == NULL || nbits < 128 || exponent < 3 )
return( MBEDTLS_ERR_RSA_BAD_INPUT_DATA );
@@ -508,10 +511,13 @@
mbedtls_mpi_init( &H );
mbedtls_mpi_init( &G );
+ mbedtls_mpi_init( &L );
/*
* find primes P and Q with Q < P so that:
- * GCD( E, (P-1)*(Q-1) ) == 1
+ * 1. |P-Q| > 2^( nbits / 2 - 100 )
+ * 2. GCD( E, (P-1)*(Q-1) ) == 1
+ * 3. E^-1 mod LCM(P-1, Q-1) > 2^( nbits / 2 )
*/
MBEDTLS_MPI_CHK( mbedtls_mpi_lset( &ctx->E, exponent ) );
@@ -523,40 +529,51 @@
MBEDTLS_MPI_CHK( mbedtls_mpi_gen_prime( &ctx->Q, nbits >> 1, 0,
f_rng, p_rng ) );
- if( mbedtls_mpi_cmp_mpi( &ctx->P, &ctx->Q ) == 0 )
+ /* make sure the difference between p and q is not too small (FIPS 186-4 §B.3.3 step 5.4) */
+ MBEDTLS_MPI_CHK( mbedtls_mpi_sub_mpi( &H, &ctx->P, &ctx->Q ) );
+ if( mbedtls_mpi_bitlen( &H ) <= ( ( nbits >= 200 ) ? ( ( nbits >> 1 ) - 99 ) : 0 ) )
continue;
- MBEDTLS_MPI_CHK( mbedtls_mpi_mul_mpi( &ctx->N, &ctx->P, &ctx->Q ) );
- if( mbedtls_mpi_bitlen( &ctx->N ) != nbits )
- continue;
-
- if( mbedtls_mpi_cmp_mpi( &ctx->P, &ctx->Q ) < 0 )
+ /* not required by any standards, but some users rely on the fact that P > Q */
+ if( H.s < 0 )
mbedtls_mpi_swap( &ctx->P, &ctx->Q );
/* Temporarily replace P,Q by P-1, Q-1 */
MBEDTLS_MPI_CHK( mbedtls_mpi_sub_int( &ctx->P, &ctx->P, 1 ) );
MBEDTLS_MPI_CHK( mbedtls_mpi_sub_int( &ctx->Q, &ctx->Q, 1 ) );
MBEDTLS_MPI_CHK( mbedtls_mpi_mul_mpi( &H, &ctx->P, &ctx->Q ) );
+
+ /* check GCD( E, (P-1)*(Q-1) ) == 1 (FIPS 186-4 §B.3.1 criterion 2(a)) */
MBEDTLS_MPI_CHK( mbedtls_mpi_gcd( &G, &ctx->E, &H ) );
+ if( mbedtls_mpi_cmp_int( &G, 1 ) != 0 )
+ continue;
+
+ /* compute smallest possible D = E^-1 mod LCM(P-1, Q-1) (FIPS 186-4 §B.3.1 criterion 3(b)) */
+ MBEDTLS_MPI_CHK( mbedtls_mpi_gcd( &G, &ctx->P, &ctx->Q ) );
+ MBEDTLS_MPI_CHK( mbedtls_mpi_div_mpi( &L, NULL, &H, &G ) );
+ MBEDTLS_MPI_CHK( mbedtls_mpi_inv_mod( &ctx->D, &ctx->E, &L ) );
+
+ if( mbedtls_mpi_bitlen( &ctx->D ) <= ( ( nbits + 1 ) / 2 ) ) // (FIPS 186-4 §B.3.1 criterion 3(a))
+ continue;
+
+ break;
}
- while( mbedtls_mpi_cmp_int( &G, 1 ) != 0 );
+ while( 1 );
/* Restore P,Q */
MBEDTLS_MPI_CHK( mbedtls_mpi_add_int( &ctx->P, &ctx->P, 1 ) );
MBEDTLS_MPI_CHK( mbedtls_mpi_add_int( &ctx->Q, &ctx->Q, 1 ) );
+ MBEDTLS_MPI_CHK( mbedtls_mpi_mul_mpi( &ctx->N, &ctx->P, &ctx->Q ) );
+
ctx->len = mbedtls_mpi_size( &ctx->N );
+#if !defined(MBEDTLS_RSA_NO_CRT)
/*
- * D = E^-1 mod ((P-1)*(Q-1))
* DP = D mod (P - 1)
* DQ = D mod (Q - 1)
* QP = Q^-1 mod P
*/
-
- MBEDTLS_MPI_CHK( mbedtls_mpi_inv_mod( &ctx->D, &ctx->E, &H ) );
-
-#if !defined(MBEDTLS_RSA_NO_CRT)
MBEDTLS_MPI_CHK( mbedtls_rsa_deduce_crt( &ctx->P, &ctx->Q, &ctx->D,
&ctx->DP, &ctx->DQ, &ctx->QP ) );
#endif /* MBEDTLS_RSA_NO_CRT */
@@ -568,6 +585,7 @@
mbedtls_mpi_free( &H );
mbedtls_mpi_free( &G );
+ mbedtls_mpi_free( &L );
if( ret != 0 )
{
diff --git a/library/ssl_cli.c b/library/ssl_cli.c
index f5fecb7..b3dc4db 100644
--- a/library/ssl_cli.c
+++ b/library/ssl_cli.c
@@ -714,6 +714,49 @@
return( 0 );
}
+/**
+ * \brief Validate cipher suite against config in SSL context.
+ *
+ * \param suite_info cipher suite to validate
+ * \param ssl SSL context
+ * \param min_minor_ver Minimal minor version to accept a cipher suite
+ * \param max_minor_ver Maximal minor version to accept a cipher suite
+ *
+ * \return 0 if valid, else 1
+ */
+static int ssl_validate_ciphersuite( const mbedtls_ssl_ciphersuite_t * suite_info,
+ const mbedtls_ssl_context * ssl,
+ int min_minor_ver, int max_minor_ver )
+{
+ (void) ssl;
+ if( suite_info == NULL )
+ return( 1 );
+
+ if( suite_info->min_minor_ver > max_minor_ver ||
+ suite_info->max_minor_ver < min_minor_ver )
+ return( 1 );
+
+#if defined(MBEDTLS_SSL_PROTO_DTLS)
+ if( ssl->conf->transport == MBEDTLS_SSL_TRANSPORT_DATAGRAM &&
+ ( suite_info->flags & MBEDTLS_CIPHERSUITE_NODTLS ) )
+ return( 1 );
+#endif
+
+#if defined(MBEDTLS_ARC4_C)
+ if( ssl->conf->arc4_disabled == MBEDTLS_SSL_ARC4_DISABLED &&
+ suite_info->cipher == MBEDTLS_CIPHER_ARC4_128 )
+ return( 1 );
+#endif
+
+#if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
+ if( suite_info->key_exchange == MBEDTLS_KEY_EXCHANGE_ECJPAKE &&
+ mbedtls_ecjpake_check( &ssl->handshake->ecjpake_ctx ) != 0 )
+ return( 1 );
+#endif
+
+ return( 0 );
+}
+
static int ssl_write_client_hello( mbedtls_ssl_context *ssl )
{
int ret;
@@ -866,31 +909,11 @@
{
ciphersuite_info = mbedtls_ssl_ciphersuite_from_id( ciphersuites[i] );
- if( ciphersuite_info == NULL )
+ if( ssl_validate_ciphersuite( ciphersuite_info, ssl,
+ ssl->conf->min_minor_ver,
+ ssl->conf->max_minor_ver ) != 0 )
continue;
- if( ciphersuite_info->min_minor_ver > ssl->conf->max_minor_ver ||
- ciphersuite_info->max_minor_ver < ssl->conf->min_minor_ver )
- continue;
-
-#if defined(MBEDTLS_SSL_PROTO_DTLS)
- if( ssl->conf->transport == MBEDTLS_SSL_TRANSPORT_DATAGRAM &&
- ( ciphersuite_info->flags & MBEDTLS_CIPHERSUITE_NODTLS ) )
- continue;
-#endif
-
-#if defined(MBEDTLS_ARC4_C)
- if( ssl->conf->arc4_disabled == MBEDTLS_SSL_ARC4_DISABLED &&
- ciphersuite_info->cipher == MBEDTLS_CIPHER_ARC4_128 )
- continue;
-#endif
-
-#if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
- if( ciphersuite_info->key_exchange == MBEDTLS_KEY_EXCHANGE_ECJPAKE &&
- mbedtls_ecjpake_check( &ssl->handshake->ecjpake_ctx ) != 0 )
- continue;
-#endif
-
MBEDTLS_SSL_DEBUG_MSG( 3, ( "client hello, add ciphersuite: %04x",
ciphersuites[i] ) );
@@ -1687,22 +1710,9 @@
MBEDTLS_SSL_DEBUG_MSG( 3, ( "server hello, chosen ciphersuite: %04x", i ) );
MBEDTLS_SSL_DEBUG_MSG( 3, ( "server hello, compress alg.: %d", buf[37 + n] ) );
- suite_info = mbedtls_ssl_ciphersuite_from_id( ssl->session_negotiate->ciphersuite );
- if( suite_info == NULL
-#if defined(MBEDTLS_ARC4_C)
- || ( ssl->conf->arc4_disabled &&
- suite_info->cipher == MBEDTLS_CIPHER_ARC4_128 )
-#endif
- )
- {
- MBEDTLS_SSL_DEBUG_MSG( 1, ( "bad server hello message" ) );
- mbedtls_ssl_send_alert_message( ssl, MBEDTLS_SSL_ALERT_LEVEL_FATAL,
- MBEDTLS_SSL_ALERT_MSG_ILLEGAL_PARAMETER );
- return( MBEDTLS_ERR_SSL_BAD_HS_SERVER_HELLO );
- }
-
- MBEDTLS_SSL_DEBUG_MSG( 3, ( "server hello, chosen ciphersuite: %s", suite_info->name ) );
-
+ /*
+ * Perform cipher suite validation in same way as in ssl_write_client_hello.
+ */
i = 0;
while( 1 )
{
@@ -1721,6 +1731,17 @@
}
}
+ suite_info = mbedtls_ssl_ciphersuite_from_id( ssl->session_negotiate->ciphersuite );
+ if( ssl_validate_ciphersuite( suite_info, ssl, ssl->minor_ver, ssl->minor_ver ) != 0 )
+ {
+ MBEDTLS_SSL_DEBUG_MSG( 1, ( "bad server hello message" ) );
+ mbedtls_ssl_send_alert_message( ssl, MBEDTLS_SSL_ALERT_LEVEL_FATAL,
+ MBEDTLS_SSL_ALERT_MSG_ILLEGAL_PARAMETER );
+ return( MBEDTLS_ERR_SSL_BAD_HS_SERVER_HELLO );
+ }
+
+ MBEDTLS_SSL_DEBUG_MSG( 3, ( "server hello, chosen ciphersuite: %s", suite_info->name ) );
+
if( comp != MBEDTLS_SSL_COMPRESS_NULL
#if defined(MBEDTLS_ZLIB_SUPPORT)
&& comp != MBEDTLS_SSL_COMPRESS_DEFLATE
@@ -2670,10 +2691,27 @@
buf = ssl->in_msg;
/* certificate_types */
+ if( ssl->in_hslen <= mbedtls_ssl_hs_hdr_len( ssl ) )
+ {
+ MBEDTLS_SSL_DEBUG_MSG( 1, ( "bad certificate request message" ) );
+ mbedtls_ssl_send_alert_message( ssl, MBEDTLS_SSL_ALERT_LEVEL_FATAL,
+ MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR );
+ return( MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST );
+ }
cert_type_len = buf[mbedtls_ssl_hs_hdr_len( ssl )];
n = cert_type_len;
- if( ssl->in_hslen < mbedtls_ssl_hs_hdr_len( ssl ) + 2 + n )
+ /*
+ * In the subsequent code there are two paths that read from buf:
+ * * the length of the signature algorithms field (if minor version of
+ * SSL is 3),
+ * * distinguished name length otherwise.
+ * Both reach at most the index:
+ * ...hdr_len + 2 + n,
+ * therefore the buffer length at this point must be greater than that
+ * regardless of the actual code path.
+ */
+ if( ssl->in_hslen <= mbedtls_ssl_hs_hdr_len( ssl ) + 2 + n )
{
MBEDTLS_SSL_DEBUG_MSG( 1, ( "bad certificate request message" ) );
mbedtls_ssl_send_alert_message( ssl, MBEDTLS_SSL_ALERT_LEVEL_FATAL,
@@ -2688,9 +2726,32 @@
size_t sig_alg_len = ( ( buf[mbedtls_ssl_hs_hdr_len( ssl ) + 1 + n] << 8 )
| ( buf[mbedtls_ssl_hs_hdr_len( ssl ) + 2 + n] ) );
#if defined(MBEDTLS_DEBUG_C)
- unsigned char* sig_alg = buf + mbedtls_ssl_hs_hdr_len( ssl ) + 3 + n;
+ unsigned char* sig_alg;
size_t i;
+#endif
+ /*
+ * The furthest access in buf is in the loop few lines below:
+ * sig_alg[i + 1],
+ * where:
+ * sig_alg = buf + ...hdr_len + 3 + n,
+ * max(i) = sig_alg_len - 1.
+ * Therefore the furthest access is:
+ * buf[...hdr_len + 3 + n + sig_alg_len - 1 + 1],
+ * which reduces to:
+ * buf[...hdr_len + 3 + n + sig_alg_len],
+ * which is one less than we need the buf to be.
+ */
+ if( ssl->in_hslen <= mbedtls_ssl_hs_hdr_len( ssl ) + 3 + n + sig_alg_len )
+ {
+ MBEDTLS_SSL_DEBUG_MSG( 1, ( "bad certificate request message" ) );
+ mbedtls_ssl_send_alert_message( ssl, MBEDTLS_SSL_ALERT_LEVEL_FATAL,
+ MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR );
+ return( MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST );
+ }
+
+#if defined(MBEDTLS_DEBUG_C)
+ sig_alg = buf + mbedtls_ssl_hs_hdr_len( ssl ) + 3 + n;
for( i = 0; i < sig_alg_len; i += 2 )
{
MBEDTLS_SSL_DEBUG_MSG( 3, ( "Supported Signature Algorithm found: %d"
@@ -2699,14 +2760,6 @@
#endif
n += 2 + sig_alg_len;
-
- if( ssl->in_hslen < mbedtls_ssl_hs_hdr_len( ssl ) + 2 + n )
- {
- MBEDTLS_SSL_DEBUG_MSG( 1, ( "bad certificate request message" ) );
- mbedtls_ssl_send_alert_message( ssl, MBEDTLS_SSL_ALERT_LEVEL_FATAL,
- MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR );
- return( MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST );
- }
}
#endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
diff --git a/library/ssl_tls.c b/library/ssl_tls.c
index f249800..cf1b694 100644
--- a/library/ssl_tls.c
+++ b/library/ssl_tls.c
@@ -2106,6 +2106,7 @@
{
int ret;
unsigned char *msg_post = ssl->out_msg;
+ ptrdiff_t bytes_written = ssl->out_msg - ssl->out_buf;
size_t len_pre = ssl->out_msglen;
unsigned char *msg_pre = ssl->compress_buf;
@@ -2125,7 +2126,7 @@
ssl->transform_out->ctx_deflate.next_in = msg_pre;
ssl->transform_out->ctx_deflate.avail_in = len_pre;
ssl->transform_out->ctx_deflate.next_out = msg_post;
- ssl->transform_out->ctx_deflate.avail_out = MBEDTLS_SSL_BUFFER_LEN;
+ ssl->transform_out->ctx_deflate.avail_out = MBEDTLS_SSL_BUFFER_LEN - bytes_written;
ret = deflate( &ssl->transform_out->ctx_deflate, Z_SYNC_FLUSH );
if( ret != Z_OK )
@@ -2135,7 +2136,7 @@
}
ssl->out_msglen = MBEDTLS_SSL_BUFFER_LEN -
- ssl->transform_out->ctx_deflate.avail_out;
+ ssl->transform_out->ctx_deflate.avail_out - bytes_written;
MBEDTLS_SSL_DEBUG_MSG( 3, ( "after compression: msglen = %d, ",
ssl->out_msglen ) );
@@ -2152,6 +2153,7 @@
{
int ret;
unsigned char *msg_post = ssl->in_msg;
+ ptrdiff_t header_bytes = ssl->in_msg - ssl->in_buf;
size_t len_pre = ssl->in_msglen;
unsigned char *msg_pre = ssl->compress_buf;
@@ -2171,7 +2173,8 @@
ssl->transform_in->ctx_inflate.next_in = msg_pre;
ssl->transform_in->ctx_inflate.avail_in = len_pre;
ssl->transform_in->ctx_inflate.next_out = msg_post;
- ssl->transform_in->ctx_inflate.avail_out = MBEDTLS_SSL_MAX_CONTENT_LEN;
+ ssl->transform_in->ctx_inflate.avail_out = MBEDTLS_SSL_BUFFER_LEN -
+ header_bytes;
ret = inflate( &ssl->transform_in->ctx_inflate, Z_SYNC_FLUSH );
if( ret != Z_OK )
@@ -2180,8 +2183,8 @@
return( MBEDTLS_ERR_SSL_COMPRESSION_FAILED );
}
- ssl->in_msglen = MBEDTLS_SSL_MAX_CONTENT_LEN -
- ssl->transform_in->ctx_inflate.avail_out;
+ ssl->in_msglen = MBEDTLS_SSL_BUFFER_LEN -
+ ssl->transform_in->ctx_inflate.avail_out - header_bytes;
MBEDTLS_SSL_DEBUG_MSG( 3, ( "after decompression: msglen = %d, ",
ssl->in_msglen ) );
diff --git a/scripts/output_env.sh b/scripts/output_env.sh
index 1afaac3..e9ad8c5 100755
--- a/scripts/output_env.sh
+++ b/scripts/output_env.sh
@@ -47,13 +47,15 @@
print_version "uname" "-a" ""
echo
-: ${ARMC5_CC:=armcc}
-print_version "$ARMC5_CC" "--vsn" "armcc not found!" "head -n 2"
-echo
+if [ "${RUN_ARMCC:-1}" -ne 0 ]; then
+ : "${ARMC5_CC:=armcc}"
+ print_version "$ARMC5_CC" "--vsn" "armcc not found!" "head -n 2"
+ echo
-: ${ARMC6_CC:=armclang}
-print_version "$ARMC6_CC" "--vsn" "armclang not found!" "head -n 2"
-echo
+ : "${ARMC6_CC:=armclang}"
+ print_version "$ARMC6_CC" "--vsn" "armclang not found!" "head -n 2"
+ echo
+fi
print_version "arm-none-eabi-gcc" "--version" "gcc-arm not found!" "head -n 1"
echo
diff --git a/tests/scripts/all.sh b/tests/scripts/all.sh
index de0bbcc..e6c7549 100755
--- a/tests/scripts/all.sh
+++ b/tests/scripts/all.sh
@@ -94,7 +94,6 @@
MEMORY=0
FORCE=0
KEEP_GOING=0
-RELEASE=0
RUN_ARMCC=1
YOTTA=1
@@ -126,8 +125,12 @@
-m|--memory Additional optional memory tests.
--armcc Run ARM Compiler builds (on by default).
--no-armcc Skip ARM Compiler builds.
+ --no-force Refuse to overwrite modified files (default).
+ --no-keep-going Stop at the first error (default).
+ --no-memory No additional memory tests (default).
--no-yotta Skip yotta module build.
--out-of-source-dir=<path> Directory used for CMake out-of-source build tests.
+ --random-seed Use a random seed value for randomized tests (default).
-r|--release-test Run this script in release mode. This fixes the seed value to 1.
-s|--seed Integer seed value to use for this test run.
--yotta Build yotta module (on by default).
@@ -214,74 +217,29 @@
while [ $# -gt 0 ]; do
case "$1" in
- --armcc)
- RUN_ARMCC=1
- ;;
- --armc5-bin-dir)
- shift
- ARMC5_BIN_DIR="$1"
- ;;
- --armc6-bin-dir)
- shift
- ARMC6_BIN_DIR="$1"
- ;;
- --force|-f)
- FORCE=1
- ;;
- --gnutls-cli)
- shift
- GNUTLS_CLI="$1"
- ;;
- --gnutls-legacy-cli)
- shift
- GNUTLS_LEGACY_CLI="$1"
- ;;
- --gnutls-legacy-serv)
- shift
- GNUTLS_LEGACY_SERV="$1"
- ;;
- --gnutls-serv)
- shift
- GNUTLS_SERV="$1"
- ;;
- --help|-h)
- usage
- exit
- ;;
- --keep-going|-k)
- KEEP_GOING=1
- ;;
- --memory|-m)
- MEMORY=1
- ;;
- --no-armcc)
- RUN_ARMCC=0
- ;;
- --no-yotta)
- YOTTA=0
- ;;
- --openssl)
- shift
- OPENSSL="$1"
- ;;
- --openssl-legacy)
- shift
- OPENSSL_LEGACY="$1"
- ;;
- --out-of-source-dir)
- shift
- OUT_OF_SOURCE_DIR="$1"
- ;;
- --release-test|-r)
- RELEASE=1
- ;;
- --seed|-s)
- shift
- SEED="$1"
- ;;
- --yotta)
- YOTTA=1
- ;;
+ --armcc) RUN_ARMCC=1;;
+ --armc5-bin-dir) shift; ARMC5_BIN_DIR="$1";;
+ --armc6-bin-dir) shift; ARMC6_BIN_DIR="$1";;
+ --force|-f) FORCE=1;;
+ --gnutls-cli) shift; GNUTLS_CLI="$1";;
+ --gnutls-legacy-cli) shift; GNUTLS_LEGACY_CLI="$1";;
+ --gnutls-legacy-serv) shift; GNUTLS_LEGACY_SERV="$1";;
+ --gnutls-serv) shift; GNUTLS_SERV="$1";;
+ --help|-h) usage; exit;;
+ --keep-going|-k) KEEP_GOING=1;;
+ --memory|-m) MEMORY=1;;
+ --no-armcc) RUN_ARMCC=0;;
+ --no-force) FORCE=0;;
+ --no-keep-going) KEEP_GOING=0;;
+ --no-memory) MEMORY=0;;
+ --no-yotta) YOTTA=0;;
+ --openssl) shift; OPENSSL="$1";;
+ --openssl-legacy) shift; OPENSSL_LEGACY="$1";;
+ --out-of-source-dir) shift; OUT_OF_SOURCE_DIR="$1";;
+ --random-seed) unset SEED;;
+ --release-test|-r) SEED=1;;
+ --seed|-s) shift; SEED="$1";;
+ --yotta) YOTTA=1;;
*)
echo >&2 "Unknown option: $1"
echo >&2 "Run $0 --help for usage."
@@ -386,11 +344,6 @@
fi
}
-if [ $RELEASE -eq 1 ]; then
- # Fix the seed value to 1 to ensure that the tests are deterministic.
- SEED=1
-fi
-
msg "info: $0 configuration"
echo "MEMORY: $MEMORY"
echo "FORCE: $FORCE"
@@ -416,7 +369,9 @@
export GNUTLS_SERV="$GNUTLS_SERV"
# Avoid passing --seed flag in every call to ssl-opt.sh
-[ ! -z ${SEED+set} ] && export SEED
+if [ -n "${SEED-}" ]; then
+ export SEED
+fi
# Make sure the tools we need are available.
check_tools "$OPENSSL" "$OPENSSL_LEGACY" "$GNUTLS_CLI" "$GNUTLS_SERV" \
@@ -447,7 +402,7 @@
OPENSSL="$OPENSSL" OPENSSL_LEGACY="$OPENSSL_LEGACY" GNUTLS_CLI="$GNUTLS_CLI" \
GNUTLS_SERV="$GNUTLS_SERV" GNUTLS_LEGACY_CLI="$GNUTLS_LEGACY_CLI" \
GNUTLS_LEGACY_SERV="$GNUTLS_LEGACY_SERV" ARMC5_CC="$ARMC5_CC" \
- ARMC6_CC="$ARMC6_CC" scripts/output_env.sh
+ ARMC6_CC="$ARMC6_CC" RUN_ARMCC="$RUN_ARMCC" scripts/output_env.sh
msg "test: recursion.pl" # < 1s
tests/scripts/recursion.pl library/*.c
diff --git a/tests/suites/helpers.function b/tests/suites/helpers.function
index eef41c7..f82694a 100644
--- a/tests/suites/helpers.function
+++ b/tests/suites/helpers.function
@@ -109,6 +109,9 @@
}
test_info;
+#if defined(MBEDTLS_PLATFORM_C)
+mbedtls_platform_context platform_ctx;
+#endif
/*----------------------------------------------------------------------------*/
/* Helper flags for complex dependencies */
@@ -127,6 +130,21 @@
/*----------------------------------------------------------------------------*/
/* Helper Functions */
+static int platform_setup()
+{
+ int ret = 0;
+#if defined(MBEDTLS_PLATFORM_C)
+ ret = mbedtls_platform_setup( &platform_ctx );
+#endif /* MBEDTLS_PLATFORM_C */
+ return( ret );
+}
+
+static void platform_teardown()
+{
+#if defined(MBEDTLS_PLATFORM_C)
+ mbedtls_platform_teardown( &platform_ctx );
+#endif /* MBEDTLS_PLATFORM_C */
+}
#if defined(__unix__) || (defined(__APPLE__) && defined(__MACH__))
static int redirect_output( FILE** out_stream, const char* path )
diff --git a/tests/suites/main_test.function b/tests/suites/main_test.function
index 042085f..1390f9f 100644
--- a/tests/suites/main_test.function
+++ b/tests/suites/main_test.function
@@ -281,6 +281,18 @@
#if defined(MBEDTLS_MEMORY_BUFFER_ALLOC_C) && \
!defined(TEST_SUITE_MEMORY_BUFFER_ALLOC)
unsigned char alloc_buf[1000000];
+#endif
+ /* Platform setup should be called in the beginning */
+ ret = platform_setup();
+ if( ret != 0 )
+ {
+ mbedtls_fprintf( stderr,
+ "FATAL: Failed to initialize platform - error %d\n",
+ ret );
+ return( -1 );
+ }
+#if defined(MBEDTLS_MEMORY_BUFFER_ALLOC_C) && \
+ !defined(TEST_SUITE_MEMORY_BUFFER_ALLOC)
mbedtls_memory_buffer_alloc_init( alloc_buf, sizeof(alloc_buf) );
#endif
@@ -293,6 +305,7 @@
if( pointer != NULL )
{
mbedtls_fprintf( stderr, "all-bits-zero is not a NULL pointer\n" );
+ platform_teardown();
return( 1 );
}
@@ -302,7 +315,8 @@
if( run_test_snprintf() != 0 )
{
mbedtls_fprintf( stderr, "the snprintf implementation is broken\n" );
- return( 0 );
+ platform_teardown();
+ return( 1 );
}
while( arg_index < argc)
@@ -318,6 +332,7 @@
strcmp(next_arg, "-h" ) == 0 )
{
mbedtls_fprintf( stdout, USAGE );
+ platform_teardown();
mbedtls_exit( EXIT_SUCCESS );
}
else
@@ -357,6 +372,7 @@
{
mbedtls_fprintf( stderr, "Failed to open test file: %s\n",
test_filename );
+ platform_teardown();
return( 1 );
}
@@ -366,6 +382,7 @@
{
mbedtls_fprintf( stderr,
"FATAL: Dep count larger than zero at start of loop\n" );
+ platform_teardown();
mbedtls_exit( MBEDTLS_EXIT_FAILURE );
}
unmet_dep_count = 0;
@@ -402,6 +419,7 @@
if( unmet_dependencies[ unmet_dep_count ] == NULL )
{
mbedtls_fprintf( stderr, "FATAL: Out of memory\n" );
+ platform_teardown();
mbedtls_exit( MBEDTLS_EXIT_FAILURE );
}
unmet_dep_count++;
@@ -427,6 +445,7 @@
stdout_fd = redirect_output( &stdout, "/dev/null" );
if( stdout_fd == -1 )
{
+ platform_teardown();
/* Redirection has failed with no stdout so exit */
exit( 1 );
}
@@ -439,6 +458,7 @@
if( !option_verbose && restore_output( &stdout, stdout_fd ) )
{
/* Redirection has failed with no stdout so exit */
+ platform_teardown();
exit( 1 );
}
#endif /* __unix__ || __APPLE__ __MACH__ */
@@ -490,6 +510,7 @@
{
mbedtls_fprintf( stderr, "FAILED: FATAL PARSE ERROR\n" );
fclose( file );
+ platform_teardown();
mbedtls_exit( 2 );
}
else
@@ -501,6 +522,7 @@
{
mbedtls_fprintf( stderr, "Should be empty %d\n",
(int) strlen( buf ) );
+ platform_teardown();
return( 1 );
}
}
@@ -533,5 +555,6 @@
close_output( stdout );
#endif /* __unix__ || __APPLE__ __MACH__ */
+ platform_teardown();
return( total_errors != 0 );
}
diff --git a/tests/suites/test_suite_mpi.data b/tests/suites/test_suite_mpi.data
index 17cf350..2a2cfce 100644
--- a/tests/suites/test_suite_mpi.data
+++ b/tests/suites/test_suite_mpi.data
@@ -688,6 +688,18 @@
depends_on:MBEDTLS_GENPRIME
mbedtls_mpi_gen_prime:3:0:0
+Test mbedtls_mpi_gen_prime (corner case limb size -1 bits)
+depends_on:MBEDTLS_GENPRIME
+mbedtls_mpi_gen_prime:63:0:0
+
+Test mbedtls_mpi_gen_prime (corner case limb size)
+depends_on:MBEDTLS_GENPRIME
+mbedtls_mpi_gen_prime:64:0:0
+
+Test mbedtls_mpi_gen_prime (corner case limb size +1 bits)
+depends_on:MBEDTLS_GENPRIME
+mbedtls_mpi_gen_prime:65:0:0
+
Test mbedtls_mpi_gen_prime (Larger)
depends_on:MBEDTLS_GENPRIME
mbedtls_mpi_gen_prime:128:0:0
diff --git a/tests/suites/test_suite_version.data b/tests/suites/test_suite_version.data
index 79cc751..0aca470 100644
--- a/tests/suites/test_suite_version.data
+++ b/tests/suites/test_suite_version.data
@@ -1,8 +1,8 @@
Check compiletime library version
-check_compiletime_version:"2.8.0"
+check_compiletime_version:"2.9.0"
Check runtime library version
-check_runtime_version:"2.8.0"
+check_runtime_version:"2.9.0"
Check for MBEDTLS_VERSION_C
check_feature:"MBEDTLS_VERSION_C":0
