Commit 863dfb59 authored by Nathaniel Wesley Filardo's avatar Nathaniel Wesley Filardo Committed by Marcel Stör
Browse files

SSL rampage (#2938)

* Remove stale putative MD2 support

This hasn't worked in a while, presumably since one of our upstream
merges.  Don't bother making it work, since MD2 is generally considered
insecure.

* Land mbedtls 2.16.3-77-gf02988e57

* TLS: remove some dead code from espconn_mbedtls

There was some... frankly kind of scary buffer and data shuffling if
ESP8266_PLATFORM was defined.  Since we don't, in fact, define that
preprocessor symbol, just drop the code lest anyone (possibly future-me)
be scared.

* TLS: espconn_mbedtls: run through astyle

No functional changes

* TLS: espconn_mbedtls: put the file_params on the stack

There's no need to malloc a structure that's used only locally.

* TLS: Further minor tidying of mbedtls glue

What an absolute shitshow this is.  mbedtls should absolutely not
be mentioned inside sys/socket.h and app/mbedtls/app/lwIPSocket.c is not
so much glue as it as a complete copy of a random subset of lwIP; it
should go, but we aren't there yet.

Get rid of the mysterious "mbedlts_record" struct, which housed merely a
length of bytes sent solely for gating the "record sent" callback.

Remove spurious __attribute__((weak)) from symbols not otherwise
defined and rename them to emphasize that they are not actually part of
mbedtls proper.

* TLS: Rampage esp mbedtls glue and delete unused code

This at least makes the shitshow smaller

* TLS: lwip: fix some memp definitions

I presume these also need the new arguments

* TLS: Remove more non-NodeMCU code from our mbedtls

* TLS: drop support for 1.1

Depending on who you ask it's either EOL already or EOL soon, so
we may as well get rid of it now.
parent f5672207
......@@ -25,6 +25,12 @@
* This file is part of mbed TLS (https://tls.mbed.org)
*/
#if !defined(MBEDTLS_CONFIG_FILE)
#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
#if defined(MBEDTLS_DEPRECATED_WARNING)
......@@ -1378,7 +1384,8 @@
#define SSL_ANTI_REPLAY_ENABLED MBEDTLS_SSL_ANTI_REPLAY_ENABLED
#define SSL_ARC4_DISABLED MBEDTLS_SSL_ARC4_DISABLED
#define SSL_ARC4_ENABLED MBEDTLS_SSL_ARC4_ENABLED
#define SSL_BUFFER_LEN MBEDTLS_SSL_BUFFER_LEN
#define SSL_BUFFER_LEN ( ( ( MBEDTLS_SSL_IN_BUFFER_LEN ) < ( MBEDTLS_SSL_OUT_BUFFER_LEN ) ) \
? ( MBEDTLS_SSL_IN_BUFFER_LEN ) : ( MBEDTLS_SSL_OUT_BUFFER_LEN ) )
#define SSL_CACHE_DEFAULT_MAX_ENTRIES MBEDTLS_SSL_CACHE_DEFAULT_MAX_ENTRIES
#define SSL_CACHE_DEFAULT_TIMEOUT MBEDTLS_SSL_CACHE_DEFAULT_TIMEOUT
#define SSL_CBC_RECORD_SPLITTING_DISABLED MBEDTLS_SSL_CBC_RECORD_SPLITTING_DISABLED
......
......@@ -8,7 +8,7 @@
* memory footprint.
*/
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* Copyright (C) 2006-2018, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may
......@@ -48,10 +48,14 @@
* Requires support for asm() in compiler.
*
* Used in:
* library/aria.c
* library/timing.c
* library/padlock.c
* include/mbedtls/bn_mul.h
*
* Required by:
* MBEDTLS_AESNI_C
* MBEDTLS_PADLOCK_C
*
* Comment to disable the use of assembly code.
*/
#define MBEDTLS_HAVE_ASM
......@@ -84,6 +88,28 @@
*/
//#define MBEDTLS_NO_UDBL_DIVISION
/**
* \def MBEDTLS_NO_64BIT_MULTIPLICATION
*
* The platform lacks support for 32x32 -> 64-bit multiplication.
*
* Used in:
* library/poly1305.c
*
* Some parts of the library may use multiplication of two unsigned 32-bit
* operands with a 64-bit result in order to speed up computations. On some
* platforms, this is not available in hardware and has to be implemented in
* software, usually in a library provided by the toolchain.
*
* Sometimes it is not desirable to have to link to that library. This option
* removes the dependency of that library on platforms that lack a hardware
* 64-bit multiplier by embedding a software implementation in Mbed TLS.
*
* Note that depending on the compiler, this may decrease performance compared
* to using the library function provided by the toolchain.
*/
//#define MBEDTLS_NO_64BIT_MULTIPLICATION
/**
* \def MBEDTLS_HAVE_SSE2
*
......@@ -111,12 +137,21 @@
/**
* \def MBEDTLS_HAVE_TIME_DATE
*
* System has time.h and time(), gmtime() and the clock is correct.
* The time needs to be correct (not necesarily very accurate, but at least
* System has time.h, time(), and an implementation for
* mbedtls_platform_gmtime_r() (see below).
* The time needs to be correct (not necessarily very accurate, but at least
* the date should be correct). This is used to verify the validity period of
* X.509 certificates.
*
* Comment if your system does not have a correct clock.
*
* \note mbedtls_platform_gmtime_r() is an abstraction in platform_util.h that
* behaves similarly to the gmtime_r() function from the C standard. Refer to
* the documentation for mbedtls_platform_gmtime_r() for more information.
*
* \note It is possible to configure an implementation for
* mbedtls_platform_gmtime_r() at compile-time by using the macro
* MBEDTLS_PLATFORM_GMTIME_R_ALT.
*/
#define MBEDTLS_HAVE_TIME_DATE
......@@ -221,6 +256,72 @@
*/
//#define MBEDTLS_DEPRECATED_REMOVED
/**
* \def MBEDTLS_CHECK_PARAMS
*
* This configuration option controls whether the library validates more of
* the parameters passed to it.
*
* When this flag is not defined, the library only attempts to validate an
* input parameter if: (1) they may come from the outside world (such as the
* network, the filesystem, etc.) or (2) not validating them could result in
* internal memory errors such as overflowing a buffer controlled by the
* library. On the other hand, it doesn't attempt to validate parameters whose
* values are fully controlled by the application (such as pointers).
*
* When this flag is defined, the library additionally attempts to validate
* parameters that are fully controlled by the application, and should always
* be valid if the application code is fully correct and trusted.
*
* For example, when a function accepts as input a pointer to a buffer that may
* contain untrusted data, and its documentation mentions that this pointer
* must not be NULL:
* - The pointer is checked to be non-NULL only if this option is enabled.
* - The content of the buffer is always validated.
*
* When this flag is defined, if a library function receives a parameter that
* is invalid:
* 1. The function will invoke the macro MBEDTLS_PARAM_FAILED().
* 2. If MBEDTLS_PARAM_FAILED() did not terminate the program, the function
* will immediately return. If the function returns an Mbed TLS error code,
* the error code in this case is MBEDTLS_ERR_xxx_BAD_INPUT_DATA.
*
* When defining this flag, you also need to arrange a definition for
* MBEDTLS_PARAM_FAILED(). You can do this by any of the following methods:
* - By default, the library defines MBEDTLS_PARAM_FAILED() to call a
* function mbedtls_param_failed(), but the library does not define this
* function. If you do not make any other arrangements, you must provide
* the function mbedtls_param_failed() in your application.
* See `platform_util.h` for its prototype.
* - If you enable the macro #MBEDTLS_CHECK_PARAMS_ASSERT, then the
* library defines #MBEDTLS_PARAM_FAILED(\c cond) to be `assert(cond)`.
* You can still supply an alternative definition of
* MBEDTLS_PARAM_FAILED(), which may call `assert`.
* - If you define a macro MBEDTLS_PARAM_FAILED() before including `config.h`
* or you uncomment the definition of MBEDTLS_PARAM_FAILED() in `config.h`,
* the library will call the macro that you defined and will not supply
* its own version. Note that if MBEDTLS_PARAM_FAILED() calls `assert`,
* you need to enable #MBEDTLS_CHECK_PARAMS_ASSERT so that library source
* files include `<assert.h>`.
*
* Uncomment to enable validation of application-controlled parameters.
*/
//#define MBEDTLS_CHECK_PARAMS
/**
* \def MBEDTLS_CHECK_PARAMS_ASSERT
*
* Allow MBEDTLS_PARAM_FAILED() to call `assert`, and make it default to
* `assert`. This macro is only used if #MBEDTLS_CHECK_PARAMS is defined.
*
* If this macro is not defined, then MBEDTLS_PARAM_FAILED() defaults to
* calling a function mbedtls_param_failed(). See the documentation of
* #MBEDTLS_CHECK_PARAMS for details.
*
* Uncomment to allow MBEDTLS_PARAM_FAILED() to call `assert`.
*/
//#define MBEDTLS_CHECK_PARAMS_ASSERT
/* \} name SECTION: System support */
/**
......@@ -271,23 +372,29 @@
*/
//#define MBEDTLS_AES_ALT
//#define MBEDTLS_ARC4_ALT
//#define MBEDTLS_ARIA_ALT
//#define MBEDTLS_BLOWFISH_ALT
//#define MBEDTLS_CAMELLIA_ALT
//#define MBEDTLS_CCM_ALT
//#define MBEDTLS_CHACHA20_ALT
//#define MBEDTLS_CHACHAPOLY_ALT
//#define MBEDTLS_CMAC_ALT
//#define MBEDTLS_DES_ALT
//#define MBEDTLS_DHM_ALT
//#define MBEDTLS_ECJPAKE_ALT
//#define MBEDTLS_GCM_ALT
//#define MBEDTLS_NIST_KW_ALT
//#define MBEDTLS_MD2_ALT
//#define MBEDTLS_MD4_ALT
//#define MBEDTLS_MD5_ALT
//#define MBEDTLS_POLY1305_ALT
//#define MBEDTLS_RIPEMD160_ALT
//#define MBEDTLS_RSA_ALT
//#define MBEDTLS_SHA1_ALT
//#define MBEDTLS_SHA256_ALT
//#define MBEDTLS_SHA512_ALT
//#define MBEDTLS_XTEA_ALT
/*
* When replacing the elliptic curve module, pleace consider, that it is
* implemented with two .c files:
......@@ -318,7 +425,7 @@
* \note Because of a signature change, the core AES encryption and decryption routines are
* currently named mbedtls_aes_internal_encrypt and mbedtls_aes_internal_decrypt,
* respectively. When setting up alternative implementations, these functions should
* be overriden, but the wrapper functions mbedtls_aes_decrypt and mbedtls_aes_encrypt
* be overridden, but the wrapper functions mbedtls_aes_decrypt and mbedtls_aes_encrypt
* must stay untouched.
*
* \note If you use the AES_xxx_ALT macros, then is is recommended to also set
......@@ -333,6 +440,16 @@
* dependencies on them, and considering stronger message digests
* and ciphers instead.
*
* \warning If both MBEDTLS_ECDSA_SIGN_ALT and MBEDTLS_ECDSA_DETERMINISTIC are
* enabled, then the deterministic ECDH signature functions pass the
* the static HMAC-DRBG as RNG to mbedtls_ecdsa_sign(). Therefore
* alternative implementations should use the RNG only for generating
* the ephemeral key and nothing else. If this is not possible, then
* MBEDTLS_ECDSA_DETERMINISTIC should be disabled and an alternative
* implementation should be provided for mbedtls_ecdsa_sign_det_ext()
* (and for mbedtls_ecdsa_sign_det() too if backward compatibility is
* desirable).
*
*/
//#define MBEDTLS_MD2_PROCESS_ALT
//#define MBEDTLS_MD4_PROCESS_ALT
......@@ -373,11 +490,11 @@
* unsigned char mbedtls_internal_ecp_grp_capable(
* const mbedtls_ecp_group *grp )
* int mbedtls_internal_ecp_init( const mbedtls_ecp_group *grp )
* void mbedtls_internal_ecp_deinit( const mbedtls_ecp_group *grp )
* void mbedtls_internal_ecp_free( const mbedtls_ecp_group *grp )
* The mbedtls_internal_ecp_grp_capable function should return 1 if the
* replacement functions implement arithmetic for the given group and 0
* otherwise.
* The functions mbedtls_internal_ecp_init and mbedtls_internal_ecp_deinit are
* The functions mbedtls_internal_ecp_init and mbedtls_internal_ecp_free are
* called before and after each point operation and provide an opportunity to
* implement optimized set up and tear down instructions.
*
......@@ -440,12 +557,45 @@
/**
* \def MBEDTLS_AES_ROM_TABLES
*
* Store the AES tables in ROM.
* Use precomputed AES tables stored in ROM.
*
* Uncomment this macro to use precomputed AES tables stored in ROM.
* Comment this macro to generate AES tables in RAM at runtime.
*
* Tradeoff: Using precomputed ROM tables reduces RAM usage by ~8kb
* (or ~2kb if \c MBEDTLS_AES_FEWER_TABLES is used) and reduces the
* initialization time before the first AES operation can be performed.
* It comes at the cost of additional ~8kb ROM use (resp. ~2kb if \c
* MBEDTLS_AES_FEWER_TABLES below is used), and potentially degraded
* performance if ROM access is slower than RAM access.
*
* This option is independent of \c MBEDTLS_AES_FEWER_TABLES.
*
* Uncomment this macro to store the AES tables in ROM.
*/
//#define MBEDTLS_AES_ROM_TABLES
/**
* \def MBEDTLS_AES_FEWER_TABLES
*
* Use less ROM/RAM for AES tables.
*
* Uncommenting this macro omits 75% of the AES tables from
* ROM / RAM (depending on the value of \c MBEDTLS_AES_ROM_TABLES)
* by computing their values on the fly during operations
* (the tables are entry-wise rotations of one another).
*
* Tradeoff: Uncommenting this reduces the RAM / ROM footprint
* by ~6kb but at the cost of more arithmetic operations during
* runtime. Specifically, one has to compare 4 accesses within
* different tables to 4 accesses with additional arithmetic
* operations within the same table. The performance gain/loss
* depends on the system and memory details.
*
* This option is independent of \c MBEDTLS_AES_ROM_TABLES.
*
*/
//#define MBEDTLS_AES_FEWER_TABLES
/**
* \def MBEDTLS_CAMELLIA_SMALL_MEMORY
*
......@@ -476,6 +626,20 @@
*/
#define MBEDTLS_CIPHER_MODE_CTR
/**
* \def MBEDTLS_CIPHER_MODE_OFB
*
* Enable Output Feedback mode (OFB) for symmetric ciphers.
*/
#define MBEDTLS_CIPHER_MODE_OFB
/**
* \def MBEDTLS_CIPHER_MODE_XTS
*
* Enable Xor-encrypt-xor with ciphertext stealing mode (XTS) for AES.
*/
#define MBEDTLS_CIPHER_MODE_XTS
/**
* \def MBEDTLS_CIPHER_NULL_CIPHER
*
......@@ -525,6 +689,13 @@
#define MBEDTLS_CIPHER_PADDING_ZEROS_AND_LEN
#define MBEDTLS_CIPHER_PADDING_ZEROS
/** \def MBEDTLS_CTR_DRBG_USE_128_BIT_KEY
*
* Uncomment this macro to use a 128-bit key in the CTR_DRBG module.
* By default, CTR_DRBG uses a 256-bit key.
*/
//#define MBEDTLS_CTR_DRBG_USE_128_BIT_KEY
/**
* \def MBEDTLS_ENABLE_WEAK_CIPHERSUITES
*
......@@ -556,6 +727,26 @@
*/
#define MBEDTLS_REMOVE_ARC4_CIPHERSUITES
/**
* \def MBEDTLS_REMOVE_3DES_CIPHERSUITES
*
* Remove 3DES ciphersuites by default in SSL / TLS.
* This flag removes the ciphersuites based on 3DES from the default list as
* returned by mbedtls_ssl_list_ciphersuites(). However, it is still possible
* to enable (some of) them with mbedtls_ssl_conf_ciphersuites() by including
* them explicitly.
*
* A man-in-the-browser attacker can recover authentication tokens sent through
* a TLS connection using a 3DES based cipher suite (see "On the Practical
* (In-)Security of 64-bit Block Ciphers" by Karthikeyan Bhargavan and Gaëtan
* Leurent, see https://sweet32.info/SWEET32_CCS16.pdf). If this attack falls
* in your threat model or you are unsure, then you should keep this option
* enabled to remove 3DES based cipher suites.
*
* Comment this macro to keep 3DES in the default ciphersuite list.
*/
#define MBEDTLS_REMOVE_3DES_CIPHERSUITES
/**
* \def MBEDTLS_ECP_DP_SECP192R1_ENABLED
*
......@@ -576,6 +767,7 @@
#define MBEDTLS_ECP_DP_BP384R1_ENABLED
#define MBEDTLS_ECP_DP_BP512R1_ENABLED
#define MBEDTLS_ECP_DP_CURVE25519_ENABLED
#define MBEDTLS_ECP_DP_CURVE448_ENABLED
/**
* \def MBEDTLS_ECP_NIST_OPTIM
......@@ -588,6 +780,30 @@
*/
#define MBEDTLS_ECP_NIST_OPTIM
/**
* \def MBEDTLS_ECP_RESTARTABLE
*
* Enable "non-blocking" ECC operations that can return early and be resumed.
*
* This allows various functions to pause by returning
* #MBEDTLS_ERR_ECP_IN_PROGRESS (or, for functions in the SSL module,
* #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS) and then be called later again in
* order to further progress and eventually complete their operation. This is
* controlled through mbedtls_ecp_set_max_ops() which limits the maximum
* number of ECC operations a function may perform before pausing; see
* mbedtls_ecp_set_max_ops() for more information.
*
* This is useful in non-threaded environments if you want to avoid blocking
* for too long on ECC (and, hence, X.509 or SSL/TLS) operations.
*
* Uncomment this macro to enable restartable ECC computations.
*
* \note This option only works with the default software implementation of
* elliptic curve functionality. It is incompatible with
* MBEDTLS_ECP_ALT, MBEDTLS_ECDH_XXX_ALT and MBEDTLS_ECDSA_XXX_ALT.
*/
//#define MBEDTLS_ECP_RESTARTABLE
/**
* \def MBEDTLS_ECDSA_DETERMINISTIC
*
......@@ -1094,6 +1310,17 @@
*/
#define MBEDTLS_SSL_ALL_ALERT_MESSAGES
/**
* \def MBEDTLS_SSL_ASYNC_PRIVATE
*
* Enable asynchronous external private key operations in SSL. This allows
* you to configure an SSL connection to call an external cryptographic
* module to perform private key operations instead of performing the
* operation inside the library.
*
*/
//#define MBEDTLS_SSL_ASYNC_PRIVATE
/**
* \def MBEDTLS_SSL_DEBUG_ALL
*
......@@ -1372,7 +1599,7 @@
* \def MBEDTLS_SSL_SESSION_TICKETS
*
* Enable support for RFC 5077 session tickets in SSL.
* Client-side, provides full support for session tickets (maintainance of a
* Client-side, provides full support for session tickets (maintenance of a
* session store remains the responsibility of the application, though).
* Server-side, you also need to provide callbacks for writing and parsing
* tickets, including authenticated encryption and key management. Example
......@@ -1538,10 +1765,13 @@
*
* \warning TLS-level compression MAY REDUCE SECURITY! See for example the
* CRIME attack. Before enabling this option, you should examine with care if
* CRIME or similar exploits may be a applicable to your use case.
* CRIME or similar exploits may be applicable to your use case.
*
* \note Currently compression can't be used with DTLS.
*
* \deprecated This feature is deprecated and will be removed
* in the next major revision of the library.
*
* Used in: library/ssl_tls.c
* library/ssl_cli.c
* library/ssl_srv.c
......@@ -1580,7 +1810,7 @@
* Enable the AES block cipher.
*
* Module: library/aes.c
* Caller: library/ssl_tls.c
* Caller: library/cipher.c
* library/pem.c
* library/ctr_drbg.c
*
......@@ -1655,7 +1885,7 @@
* Enable the ARCFOUR stream cipher.
*
* Module: library/arc4.c
* Caller: library/ssl_tls.c
* Caller: library/cipher.c
*
* This module enables the following ciphersuites (if other requisites are
* enabled as well):
......@@ -1749,7 +1979,7 @@
* Enable the Camellia block cipher.
*
* Module: library/camellia.c
* Caller: library/ssl_tls.c
* Caller: library/cipher.c
*
* This module enables the following ciphersuites (if other requisites are
* enabled as well):
......@@ -1798,6 +2028,58 @@
*/
#define MBEDTLS_CAMELLIA_C
/**
* \def MBEDTLS_ARIA_C
*
* Enable the ARIA block cipher.
*
* Module: library/aria.c
* Caller: library/cipher.c
*
* This module enables the following ciphersuites (if other requisites are
* enabled as well):
*
* MBEDTLS_TLS_RSA_WITH_ARIA_128_CBC_SHA256
* MBEDTLS_TLS_RSA_WITH_ARIA_256_CBC_SHA384
* MBEDTLS_TLS_DHE_RSA_WITH_ARIA_128_CBC_SHA256
* MBEDTLS_TLS_DHE_RSA_WITH_ARIA_256_CBC_SHA384
* MBEDTLS_TLS_ECDHE_ECDSA_WITH_ARIA_128_CBC_SHA256
* MBEDTLS_TLS_ECDHE_ECDSA_WITH_ARIA_256_CBC_SHA384
* MBEDTLS_TLS_ECDH_ECDSA_WITH_ARIA_128_CBC_SHA256
* MBEDTLS_TLS_ECDH_ECDSA_WITH_ARIA_256_CBC_SHA384
* MBEDTLS_TLS_ECDHE_RSA_WITH_ARIA_128_CBC_SHA256
* MBEDTLS_TLS_ECDHE_RSA_WITH_ARIA_256_CBC_SHA384
* MBEDTLS_TLS_ECDH_RSA_WITH_ARIA_128_CBC_SHA256
* MBEDTLS_TLS_ECDH_RSA_WITH_ARIA_256_CBC_SHA384
* MBEDTLS_TLS_RSA_WITH_ARIA_128_GCM_SHA256
* MBEDTLS_TLS_RSA_WITH_ARIA_256_GCM_SHA384
* MBEDTLS_TLS_DHE_RSA_WITH_ARIA_128_GCM_SHA256
* MBEDTLS_TLS_DHE_RSA_WITH_ARIA_256_GCM_SHA384
* MBEDTLS_TLS_ECDHE_ECDSA_WITH_ARIA_128_GCM_SHA256
* MBEDTLS_TLS_ECDHE_ECDSA_WITH_ARIA_256_GCM_SHA384
* MBEDTLS_TLS_ECDH_ECDSA_WITH_ARIA_128_GCM_SHA256
* MBEDTLS_TLS_ECDH_ECDSA_WITH_ARIA_256_GCM_SHA384
* MBEDTLS_TLS_ECDHE_RSA_WITH_ARIA_128_GCM_SHA256
* MBEDTLS_TLS_ECDHE_RSA_WITH_ARIA_256_GCM_SHA384
* MBEDTLS_TLS_ECDH_RSA_WITH_ARIA_128_GCM_SHA256
* MBEDTLS_TLS_ECDH_RSA_WITH_ARIA_256_GCM_SHA384
* MBEDTLS_TLS_PSK_WITH_ARIA_128_CBC_SHA256
* MBEDTLS_TLS_PSK_WITH_ARIA_256_CBC_SHA384
* MBEDTLS_TLS_DHE_PSK_WITH_ARIA_128_CBC_SHA256
* MBEDTLS_TLS_DHE_PSK_WITH_ARIA_256_CBC_SHA384
* MBEDTLS_TLS_RSA_PSK_WITH_ARIA_128_CBC_SHA256
* MBEDTLS_TLS_RSA_PSK_WITH_ARIA_256_CBC_SHA384
* MBEDTLS_TLS_PSK_WITH_ARIA_128_GCM_SHA256
* MBEDTLS_TLS_PSK_WITH_ARIA_256_GCM_SHA384
* MBEDTLS_TLS_DHE_PSK_WITH_ARIA_128_GCM_SHA256
* MBEDTLS_TLS_DHE_PSK_WITH_ARIA_256_GCM_SHA384
* MBEDTLS_TLS_RSA_PSK_WITH_ARIA_128_GCM_SHA256
* MBEDTLS_TLS_RSA_PSK_WITH_ARIA_256_GCM_SHA384
* MBEDTLS_TLS_ECDHE_PSK_WITH_ARIA_128_CBC_SHA256
* MBEDTLS_TLS_ECDHE_PSK_WITH_ARIA_256_CBC_SHA384
*/
//#define MBEDTLS_ARIA_C
/**
* \def MBEDTLS_CCM_C
*
......@@ -1824,6 +2106,26 @@
*/
#define MBEDTLS_CERTS_C
/**
* \def MBEDTLS_CHACHA20_C
*
* Enable the ChaCha20 stream cipher.
*
* Module: library/chacha20.c
*/
#define MBEDTLS_CHACHA20_C
/**
* \def MBEDTLS_CHACHAPOLY_C
*
* Enable the ChaCha20-Poly1305 AEAD algorithm.
*
* Module: library/chachapoly.c
*
* This module requires: MBEDTLS_CHACHA20_C, MBEDTLS_POLY1305_C
*/
#define MBEDTLS_CHACHAPOLY_C
/**
* \def MBEDTLS_CIPHER_C
*
......@@ -1852,14 +2154,20 @@
/**
* \def MBEDTLS_CTR_DRBG_C
*
* Enable the CTR_DRBG AES-256-based random generator.
* Enable the CTR_DRBG AES-based random generator.
* The CTR_DRBG generator uses AES-256 by default.
* To use AES-128 instead, enable \c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY above.
*
* \note To achieve a 256-bit security strength with CTR_DRBG,
* you must use AES-256 *and* use sufficient entropy.
* See ctr_drbg.h for more details.
*
* Module: library/ctr_drbg.c
* Caller:
*
* Requires: MBEDTLS_AES_C
*
* This module provides the CTR_DRBG AES-256 random number generator.
* This module provides the CTR_DRBG AES random number generator.
*/
#define MBEDTLS_CTR_DRBG_C
......@@ -1884,7 +2192,7 @@
*
* Module: library/des.c
* Caller: library/pem.c
* library/ssl_tls.c
* library/cipher.c
*
* This module enables the following ciphersuites (if other requisites are
* enabled as well):
......@@ -2054,6 +2362,21 @@
*/
//#define MBEDTLS_HAVEGE_C
/**
* \def MBEDTLS_HKDF_C
*
* Enable the HKDF algorithm (RFC 5869).
*
* Module: library/hkdf.c
* Caller:
*
* Requires: MBEDTLS_MD_C
*
* This module adds support for the Hashed Message Authentication Code
* (HMAC)-based key derivation function (HKDF).
*/
#define MBEDTLS_HKDF_C
/**
* \def MBEDTLS_HMAC_DRBG_C
*
......@@ -2068,6 +2391,19 @@
*/
#define MBEDTLS_HMAC_DRBG_C
/**
* \def MBEDTLS_NIST_KW_C
*
* Enable the Key Wrapping mode for 128-bit block ciphers,
* as defined in NIST SP 800-38F. Only KW and KWP modes
* are supported. At the moment, only AES is approved by NIST.
*
* Module: library/nist_kw.c
*
* Requires: MBEDTLS_AES_C and MBEDTLS_CIPHER_C
*/
//#define MBEDTLS_NIST_KW_C
/**
* \def MBEDTLS_MD_C
*
......@@ -2351,6 +2687,16 @@
*/
#define MBEDTLS_PLATFORM_C
/**
* \def MBEDTLS_POLY1305_C
*
* Enable the Poly1305 MAC algorithm.
*
* Module: library/poly1305.c
* Caller: library/chachapoly.c
*/
#define MBEDTLS_POLY1305_C
/**
* \def MBEDTLS_RIPEMD160_C
*
......@@ -2734,7 +3080,7 @@
//#define MBEDTLS_PLATFORM_STD_TIME time /**< Default time to use, can be undefined. MBEDTLS_HAVE_TIME must be enabled */
//#define MBEDTLS_PLATFORM_STD_FPRINTF fprintf /**< Default fprintf to use, can be undefined */
//#define MBEDTLS_PLATFORM_STD_PRINTF printf /**< Default printf to use, can be undefined */
/* Note: your snprintf must correclty zero-terminate the buffer! */
/* Note: your snprintf must correctly zero-terminate the buffer! */
//#define MBEDTLS_PLATFORM_STD_SNPRINTF snprintf /**< Default snprintf to use, can be undefined */
//#define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS 0 /**< Default exit value to use, can be undefined */
//#define MBEDTLS_PLATFORM_STD_EXIT_FAILURE 1 /**< Default exit value to use, can be undefined */
......@@ -2751,17 +3097,145 @@
//#define MBEDTLS_PLATFORM_TIME_TYPE_MACRO time_t /**< Default time macro to use, can be undefined. MBEDTLS_HAVE_TIME must be enabled */
//#define MBEDTLS_PLATFORM_FPRINTF_MACRO fprintf /**< Default fprintf macro to use, can be undefined */
//#define MBEDTLS_PLATFORM_PRINTF_MACRO printf /**< Default printf macro to use, can be undefined */
/* Note: your snprintf must correclty zero-terminate the buffer! */
/* Note: your snprintf must correctly zero-terminate the buffer! */
//#define MBEDTLS_PLATFORM_SNPRINTF_MACRO snprintf /**< Default snprintf macro to use, can be undefined */
//#define MBEDTLS_PLATFORM_NV_SEED_READ_MACRO mbedtls_platform_std_nv_seed_read /**< Default nv_seed_read function to use, can be undefined */
//#define MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO mbedtls_platform_std_nv_seed_write /**< Default nv_seed_write function to use, can be undefined */
/**
* \brief This macro is invoked by the library when an invalid parameter
* is detected that is only checked with #MBEDTLS_CHECK_PARAMS
* (see the documentation of that option for context).
*
* When you leave this undefined here, the library provides
* a default definition. If the macro #MBEDTLS_CHECK_PARAMS_ASSERT
* is defined, the default definition is `assert(cond)`,
* otherwise the default definition calls a function
* mbedtls_param_failed(). This function is declared in
* `platform_util.h` for the benefit of the library, but
* you need to define in your application.
*
* When you define this here, this replaces the default
* definition in platform_util.h (which no longer declares the
* function mbedtls_param_failed()) and it is your responsibility
* to make sure this macro expands to something suitable (in
* particular, that all the necessary declarations are visible
* from within the library - you can ensure that by providing
* them in this file next to the macro definition).
* If you define this macro to call `assert`, also define
* #MBEDTLS_CHECK_PARAMS_ASSERT so that library source files
* include `<assert.h>`.
*
* Note that you may define this macro to expand to nothing, in
* which case you don't have to worry about declarations or
* definitions. However, you will then be notified about invalid
* parameters only in non-void functions, and void function will
* just silently return early on invalid parameters, which
* partially negates the benefits of enabling
* #MBEDTLS_CHECK_PARAMS in the first place, so is discouraged.
*
* \param cond The expression that should evaluate to true, but doesn't.
*/
//#define MBEDTLS_PARAM_FAILED( cond ) assert( cond )
/* SSL Cache options */
//#define MBEDTLS_SSL_CACHE_DEFAULT_TIMEOUT 86400 /**< 1 day */
//#define MBEDTLS_SSL_CACHE_DEFAULT_MAX_ENTRIES 50 /**< Maximum entries in cache */
/* SSL options */
//#define MBEDTLS_SSL_MAX_CONTENT_LEN 16384 /**< Maxium fragment length in bytes, determines the size of each of the two internal I/O buffers */
/** \def MBEDTLS_SSL_MAX_CONTENT_LEN
*
* Maximum length (in bytes) of incoming and outgoing plaintext fragments.
*
* This determines the size of both the incoming and outgoing TLS I/O buffers
* in such a way that both are capable of holding the specified amount of
* plaintext data, regardless of the protection mechanism used.
*
* To configure incoming and outgoing I/O buffers separately, use
* #MBEDTLS_SSL_IN_CONTENT_LEN and #MBEDTLS_SSL_OUT_CONTENT_LEN,
* which overwrite the value set by this option.
*
* \note When using a value less than the default of 16KB on the client, it is
* recommended to use the Maximum Fragment Length (MFL) extension to
* inform the server about this limitation. On the server, there
* is no supported, standardized way of informing the client about
* restriction on the maximum size of incoming messages, and unless
* the limitation has been communicated by other means, it is recommended
* to only change the outgoing buffer size #MBEDTLS_SSL_OUT_CONTENT_LEN
* while keeping the default value of 16KB for the incoming buffer.
*
* Uncomment to set the maximum plaintext size of both
* incoming and outgoing I/O buffers.
*/
//#define MBEDTLS_SSL_MAX_CONTENT_LEN 16384
/** \def MBEDTLS_SSL_IN_CONTENT_LEN
*
* Maximum length (in bytes) of incoming plaintext fragments.
*
* This determines the size of the incoming TLS I/O buffer in such a way
* that it is capable of holding the specified amount of plaintext data,
* regardless of the protection mechanism used.
*
* If this option is undefined, it inherits its value from
* #MBEDTLS_SSL_MAX_CONTENT_LEN.
*
* \note When using a value less than the default of 16KB on the client, it is
* recommended to use the Maximum Fragment Length (MFL) extension to
* inform the server about this limitation. On the server, there
* is no supported, standardized way of informing the client about
* restriction on the maximum size of incoming messages, and unless
* the limitation has been communicated by other means, it is recommended
* to only change the outgoing buffer size #MBEDTLS_SSL_OUT_CONTENT_LEN
* while keeping the default value of 16KB for the incoming buffer.
*
* Uncomment to set the maximum plaintext size of the incoming I/O buffer
* independently of the outgoing I/O buffer.
*/
//#define MBEDTLS_SSL_IN_CONTENT_LEN 16384
/** \def MBEDTLS_SSL_OUT_CONTENT_LEN
*
* Maximum length (in bytes) of outgoing plaintext fragments.
*
* This determines the size of the outgoing TLS I/O buffer in such a way
* that it is capable of holding the specified amount of plaintext data,
* regardless of the protection mechanism used.
*
* If this option undefined, it inherits its value from
* #MBEDTLS_SSL_MAX_CONTENT_LEN.
*
* It is possible to save RAM by setting a smaller outward buffer, while keeping
* the default inward 16384 byte buffer to conform to the TLS specification.
*
* The minimum required outward buffer size is determined by the handshake
* protocol's usage. Handshaking will fail if the outward buffer is too small.
* The specific size requirement depends on the configured ciphers and any
* certificate data which is sent during the handshake.
*
* Uncomment to set the maximum plaintext size of the outgoing I/O buffer
* independently of the incoming I/O buffer.
*/
//#define MBEDTLS_SSL_OUT_CONTENT_LEN 16384
/** \def MBEDTLS_SSL_DTLS_MAX_BUFFERING
*
* Maximum number of heap-allocated bytes for the purpose of
* DTLS handshake message reassembly and future message buffering.
*
* This should be at least 9/8 * MBEDTLSSL_IN_CONTENT_LEN
* to account for a reassembled handshake message of maximum size,
* together with its reassembly bitmap.
*
* A value of 2 * MBEDTLS_SSL_IN_CONTENT_LEN (32768 by default)
* should be sufficient for all practical situations as it allows
* to reassembly a large handshake message (such as a certificate)
* while buffering multiple smaller handshake messages.
*
*/
//#define MBEDTLS_SSL_DTLS_MAX_BUFFERING 32768
//#define MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME 86400 /**< Lifetime of session tickets (if enabled) */
//#define MBEDTLS_PSK_MAX_LEN 32 /**< Max size of TLS pre-shared keys, in bytes (default 256 bits) */
//#define MBEDTLS_SSL_COOKIE_TIMEOUT 60 /**< Default expiration delay of DTLS cookies, in seconds if HAVE_TIME, or in number of cookies issued */
......@@ -2815,25 +3289,53 @@
*/
#define MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE
/* \} name SECTION: Customisation configuration options */
/* Target and application specific configurations */
//#define YOTTA_CFG_MBEDTLS_TARGET_CONFIG_FILE "target_config.h"
/**
* Uncomment the macro to let mbed TLS use your alternate implementation of
* mbedtls_platform_zeroize(). This replaces the default implementation in
* platform_util.c.
*
* mbedtls_platform_zeroize() is a widely used function across the library to
* zero a block of memory. The implementation is expected to be secure in the
* sense that it has been written to prevent the compiler from removing calls
* to mbedtls_platform_zeroize() as part of redundant code elimination
* optimizations. However, it is difficult to guarantee that calls to
* mbedtls_platform_zeroize() will not be optimized by the compiler as older
* versions of the C language standards do not provide a secure implementation
* of memset(). Therefore, MBEDTLS_PLATFORM_ZEROIZE_ALT enables users to
* configure their own implementation of mbedtls_platform_zeroize(), for
* example by using directives specific to their compiler, features from newer
* C standards (e.g using memset_s() in C11) or calling a secure memset() from
* their system (e.g explicit_bzero() in BSD).
*/
//#define MBEDTLS_PLATFORM_ZEROIZE_ALT
/**
* Uncomment the macro to let Mbed TLS use your alternate implementation of
* mbedtls_platform_gmtime_r(). This replaces the default implementation in
* platform_util.c.
*
* gmtime() is not a thread-safe function as defined in the C standard. The
* library will try to use safer implementations of this function, such as
* gmtime_r() when available. However, if Mbed TLS cannot identify the target
* system, the implementation of mbedtls_platform_gmtime_r() will default to
* using the standard gmtime(). In this case, calls from the library to
* gmtime() will be guarded by the global mutex mbedtls_threading_gmtime_mutex
* if MBEDTLS_THREADING_C is enabled. We recommend that calls from outside the
* library are also guarded with this mutex to avoid race conditions. However,
* if the macro MBEDTLS_PLATFORM_GMTIME_R_ALT is defined, Mbed TLS will
* unconditionally use the implementation for mbedtls_platform_gmtime_r()
* supplied at compile time.
*/
//#define MBEDTLS_PLATFORM_GMTIME_R_ALT
#if defined(TARGET_LIKE_MBED) && defined(YOTTA_CFG_MBEDTLS_TARGET_CONFIG_FILE)
#include YOTTA_CFG_MBEDTLS_TARGET_CONFIG_FILE
#endif
/* \} name SECTION: Customisation configuration options */
/*
/* Target and application specific configurations
*
* Allow user to override any previous default.
*
* Use two macro names for that, as:
* - with yotta the prefix YOTTA_CFG_ is forced
* - without yotta is looks weird to have a YOTTA prefix.
*/
#if defined(YOTTA_CFG_MBEDTLS_USER_CONFIG_FILE)
#include YOTTA_CFG_MBEDTLS_USER_CONFIG_FILE
#elif defined(MBEDTLS_USER_CONFIG_FILE)
#if defined(MBEDTLS_USER_CONFIG_FILE)
#include MBEDTLS_USER_CONFIG_FILE
#endif
......
/**
* \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 definitions and functions for the
* CTR_DRBG pseudorandom generator.
*
* 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 (default) or AES-128
* (if \c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled at compile time)
* as the underlying block cipher, with a derivation function.
* The initial seeding grabs #MBEDTLS_CTR_DRBG_ENTROPY_LEN bytes of entropy.
* See the documentation of mbedtls_ctr_drbg_seed() for more details.
*
* Based on NIST SP 800-90A §10.2.1 table 3 and NIST SP 800-57 part 1 table 2,
* here are the security strengths achieved in typical configuration:
* - 256 bits under the default configuration of the library, with AES-256
* and with #MBEDTLS_CTR_DRBG_ENTROPY_LEN set to 48 or more.
* - 256 bits if AES-256 is used, #MBEDTLS_CTR_DRBG_ENTROPY_LEN is set
* to 32 or more, and the DRBG is initialized with an explicit
* nonce in the \c custom parameter to mbedtls_ctr_drbg_seed().
* - 128 bits if AES-256 is used but #MBEDTLS_CTR_DRBG_ENTROPY_LEN is
* between 24 and 47 and the DRBG is not initialized with an explicit
* nonce (see mbedtls_ctr_drbg_seed()).
* - 128 bits if AES-128 is used (\c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY enabled)
* and #MBEDTLS_CTR_DRBG_ENTROPY_LEN is set to 24 or more (which is
* always the case unless it is explicitly set to a different value
* in config.h).
*
* Note that the value of #MBEDTLS_CTR_DRBG_ENTROPY_LEN defaults to:
* - \c 48 if the module \c MBEDTLS_SHA512_C is enabled and the symbol
* \c MBEDTLS_ENTROPY_FORCE_SHA256 is disabled at compile time.
* This is the default configuration of the library.
* - \c 32 if the module \c MBEDTLS_SHA512_C is disabled at compile time.
* - \c 32 if \c MBEDTLS_ENTROPY_FORCE_SHA256 is enabled at compile time.
*/
/*
* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
* Copyright (C) 2006-2019, 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
......@@ -46,7 +77,23 @@
#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A /**< Read or write error in file. */
#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16 /**< The block size used by the cipher. */
#define MBEDTLS_CTR_DRBG_KEYSIZE 32 /**< The key size used by the cipher. */
#if defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY)
#define MBEDTLS_CTR_DRBG_KEYSIZE 16
/**< The key size in bytes used by the cipher.
*
* Compile-time choice: 16 bytes (128 bits)
* because #MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled.
*/
#else
#define MBEDTLS_CTR_DRBG_KEYSIZE 32
/**< The key size in bytes used by the cipher.
*
* Compile-time choice: 32 bytes (256 bits)
* because \c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is disabled.
*/
#endif
#define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 ) /**< The key size for the DRBG operation, in bits. */
#define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE ) /**< The seed length, calculated as (counter + AES key). */
......@@ -59,21 +106,31 @@
* \{
*/
/** \def MBEDTLS_CTR_DRBG_ENTROPY_LEN
*
* \brief The amount of entropy used per seed by default, in bytes.
*/
#if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN)
#if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256)
/** This is 48 bytes because the entropy module uses SHA-512
* (\c MBEDTLS_ENTROPY_FORCE_SHA256 is disabled).
*/
#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48
/**< The amount of entropy used per seed by default:
* <ul><li>48 with SHA-512.</li>
* <li>32 with SHA-256.</li></ul>
#else /* defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256) */
/** This is 32 bytes because the entropy module uses SHA-256
* (the SHA512 module is disabled or
* \c MBEDTLS_ENTROPY_FORCE_SHA256 is enabled).
*/
#else
#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32
/**< Amount of entropy used per seed by default:
* <ul><li>48 with SHA-512.</li>
* <li>32 with SHA-256.</li></ul>
#if !defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY)
/** \warning To achieve a 256-bit security strength, you must pass a nonce
* to mbedtls_ctr_drbg_seed().
*/
#endif
#endif
#endif /* !defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY) */
#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32
#endif /* defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256) */
#endif /* !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN) */
#if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000
......@@ -92,7 +149,7 @@
#if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT)
#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384
/**< The maximum size of seed or reseed buffer. */
/**< The maximum size of seed or reseed buffer in bytes. */
#endif
/* \} name SECTION: Module settings */
......@@ -109,7 +166,7 @@ extern "C" {
/**
* \brief The CTR_DRBG context structure.
*/
typedef struct
typedef struct mbedtls_ctr_drbg_context
{
unsigned char counter[16]; /*!< The counter (V). */
int reseed_counter; /*!< The reseed counter. */
......@@ -150,20 +207,71 @@ void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
* \brief This function seeds and sets up the CTR_DRBG
* entropy source for future reseeds.
*
* \note Personalization data can be provided in addition to the more generic
* A typical choice for the \p f_entropy and \p p_entropy parameters is
* to use the entropy module:
* - \p f_entropy is mbedtls_entropy_func();
* - \p p_entropy is an instance of ::mbedtls_entropy_context initialized
* with mbedtls_entropy_init() (which registers the platform's default
* entropy sources).
*
* The entropy length is #MBEDTLS_CTR_DRBG_ENTROPY_LEN by default.
* You can override it by calling mbedtls_ctr_drbg_set_entropy_len().
*
* You can provide a personalization string in addition to the
* entropy source, to make this instantiation as unique as possible.
*
* \note The _seed_material_ value passed to the derivation
* function in the CTR_DRBG Instantiate Process
* described in NIST SP 800-90A §10.2.1.3.2
* is the concatenation of the string obtained from
* calling \p f_entropy and the \p custom string.
* The origin of the nonce depends on the value of
* the entropy length relative to the security strength.
* - If the entropy length is at least 1.5 times the
* security strength then the nonce is taken from the
* string obtained with \p f_entropy.
* - If the entropy length is less than the security
* strength, then the nonce is taken from \p custom.
* In this case, for compliance with SP 800-90A,
* you must pass a unique value of \p custom at
* each invocation. See SP 800-90A §8.6.7 for more
* details.
*/
#if MBEDTLS_CTR_DRBG_ENTROPY_LEN < MBEDTLS_CTR_DRBG_KEYSIZE * 3 / 2
/** \warning When #MBEDTLS_CTR_DRBG_ENTROPY_LEN is less than
* #MBEDTLS_CTR_DRBG_KEYSIZE * 3 / 2, to achieve the
* maximum security strength permitted by CTR_DRBG,
* you must pass a value of \p custom that is a nonce:
* this value must never be repeated in subsequent
* runs of the same application or on a different
* device.
*/
#endif
/**
* \param ctx The CTR_DRBG context to seed.
* It must have been initialized with
* mbedtls_ctr_drbg_init().
* After a successful call to mbedtls_ctr_drbg_seed(),
* you may not call mbedtls_ctr_drbg_seed() again on
* the same context unless you call
* mbedtls_ctr_drbg_free() and mbedtls_ctr_drbg_init()
* again first.
* \param f_entropy The entropy callback, taking as arguments the
* \p p_entropy context, the buffer to fill, and the
length of the buffer.
* \param p_entropy The entropy context.
* \param custom Personalization data, that is device-specific
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.
* length of the buffer.
* \p f_entropy is always called with a buffer size
* equal to the entropy length.
* \param p_entropy The entropy context to pass to \p f_entropy.
* \param custom The personalization string.
* This can be \c NULL, in which case the personalization
* string is empty regardless of the value of \p len.
* \param len The length of the personalization string.
* This must be at most
* #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT
* - #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
*
* \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),
......@@ -183,7 +291,8 @@ void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx );
* The default value is off.
*
* \note If enabled, entropy is gathered at the beginning of
* every call to mbedtls_ctr_drbg_random_with_add().
* every call to mbedtls_ctr_drbg_random_with_add()
* or mbedtls_ctr_drbg_random().
* Only use this if your entropy source has sufficient
* throughput.
*
......@@ -195,17 +304,36 @@ void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
/**
* \brief This function sets the amount of entropy grabbed on each
* seed or reseed. The default value is
* #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
* seed or reseed.
*
* The default value is #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
*
* \note The security strength of CTR_DRBG is bounded by the
* entropy length. Thus:
* - When using AES-256
* (\c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is disabled,
* which is the default),
* \p len must be at least 32 (in bytes)
* to achieve a 256-bit strength.
* - When using AES-128
* (\c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled)
* \p len must be at least 16 (in bytes)
* to achieve a 128-bit strength.
*
* \param ctx The CTR_DRBG context.
* \param len The amount of entropy to grab.
* \param len The amount of entropy to grab, in bytes.
* This must be at most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
*/
void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx,
size_t len );
/**
* \brief This function sets the reseed interval.
*
* The reseed interval is the number of calls to mbedtls_ctr_drbg_random()
* or mbedtls_ctr_drbg_random_with_add() after which the entropy function
* is called again.
*
* The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL.
*
* \param ctx The CTR_DRBG context.
......@@ -219,11 +347,15 @@ void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx,
* extracts data from the entropy source.
*
* \param ctx The CTR_DRBG context.
* \param additional Additional data to add to the state. Can be NULL.
* \param additional Additional data to add to the state. Can be \c NULL.
* \param len The length of the additional data.
* This must be less than
* #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - \c entropy_len
* where \c entropy_len is the entropy length
* configured for the context.
*
* \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 );
......@@ -232,7 +364,8 @@ int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
* \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 additional The data to update the state with. This must not be
* \c NULL unless \p add_len is \c 0.
* \param add_len Length of \p additional in bytes. This must be at
* most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
*
......@@ -246,40 +379,30 @@ int mbedtls_ctr_drbg_update_ret( mbedtls_ctr_drbg_context *ctx,
const unsigned char *additional,
size_t add_len );
/**
* \brief This function updates the state of the CTR_DRBG context.
*
* \warning This function cannot report errors. You should use
* mbedtls_ctr_drbg_update_ret() instead.
*
* \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 );
/**
* \brief This function updates a CTR_DRBG instance with additional
* data and uses it to generate random data.
*
* \note The function automatically reseeds if the reseed counter is exceeded.
* This function automatically reseeds if the reseed counter is exceeded
* or prediction resistance is enabled.
*
* \param p_rng The CTR_DRBG context. This must be a pointer to a
* #mbedtls_ctr_drbg_context structure.
* \param output The buffer to fill.
* \param output_len The length of the buffer.
* \param additional Additional data to update. Can be NULL.
* \param add_len The length of the additional data.
* \param output_len The length of the buffer in bytes.
* \param additional Additional data to update. Can be \c NULL, in which
* case the additional data is empty regardless of
* the value of \p add_len.
* \param add_len The length of the additional data
* if \p additional is not \c NULL.
* This must be less than #MBEDTLS_CTR_DRBG_MAX_INPUT
* and less than
* #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - \c entropy_len
* where \c entropy_len is the entropy length
* configured for the context.
*
* \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,
......@@ -289,20 +412,51 @@ int mbedtls_ctr_drbg_random_with_add( void *p_rng,
/**
* \brief This function uses CTR_DRBG to generate random data.
*
* \note The function automatically reseeds if the reseed counter is exceeded.
* This function automatically reseeds if the reseed counter is exceeded
* or prediction resistance is enabled.
*
*
* \param p_rng The CTR_DRBG context. This must be a pointer to a
* #mbedtls_ctr_drbg_context structure.
* \param output The buffer to fill.
* \param output_len The length of the buffer.
* \param output_len The length of the buffer in bytes.
*
* \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,
unsigned char *output, size_t output_len );
#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
#if defined(MBEDTLS_DEPRECATED_WARNING)
#define MBEDTLS_DEPRECATED __attribute__((deprecated))
#else
#define MBEDTLS_DEPRECATED
#endif
/**
* \brief This function updates the state of the CTR_DRBG context.
*
* \deprecated Superseded by mbedtls_ctr_drbg_update_ret()
* in 2.16.0.
*
* \note If \p add_len is greater than
* #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first
* #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used.
* The remaining Bytes are silently discarded.
*
* \param ctx The CTR_DRBG context.
* \param additional The data to update the state with.
* \param add_len Length of \p additional data.
*/
MBEDTLS_DEPRECATED void mbedtls_ctr_drbg_update(
mbedtls_ctr_drbg_context *ctx,
const unsigned char *additional,
size_t add_len );
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
#if defined(MBEDTLS_FS_IO)
/**
* \brief This function writes a seed file.
......@@ -310,9 +464,9 @@ int mbedtls_ctr_drbg_random( void *p_rng,
* \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 reseed
* failure.
*/
int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
......@@ -324,21 +478,28 @@ int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char
* \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
* #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG on failure.
* \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
* reseed failure.
* \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if the existing
* seed file is too large.
*/
int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
#endif /* MBEDTLS_FS_IO */
#if defined(MBEDTLS_SELF_TEST)
/**
* \brief The CTR_DRBG checkup routine.
*
* \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 );
#endif /* MBEDTLS_SELF_TEST */
/* Internal functions (do not call directly) */
int mbedtls_ctr_drbg_seed_entropy_len( mbedtls_ctr_drbg_context *,
int (*)(void *, unsigned char *, size_t), void *,
......
......@@ -65,6 +65,11 @@
mbedtls_debug_print_crt( ssl, level, __FILE__, __LINE__, text, crt )
#endif
#if defined(MBEDTLS_ECDH_C)
#define MBEDTLS_SSL_DEBUG_ECDH( level, ecdh, attr ) \
mbedtls_debug_printf_ecdh( ssl, level, __FILE__, __LINE__, ecdh, attr )
#endif
#else /* MBEDTLS_DEBUG_C */
#define MBEDTLS_SSL_DEBUG_MSG( level, args ) do { } while( 0 )
......@@ -73,6 +78,7 @@
#define MBEDTLS_SSL_DEBUG_MPI( level, text, X ) do { } while( 0 )
#define MBEDTLS_SSL_DEBUG_ECP( level, text, X ) do { } while( 0 )
#define MBEDTLS_SSL_DEBUG_CRT( level, text, crt ) do { } while( 0 )
#define MBEDTLS_SSL_DEBUG_ECDH( level, ecdh, attr ) do { } while( 0 )
#endif /* MBEDTLS_DEBUG_C */
......@@ -221,6 +227,36 @@ void mbedtls_debug_print_crt( const mbedtls_ssl_context *ssl, int level,
const char *text, const mbedtls_x509_crt *crt );
#endif
#if defined(MBEDTLS_ECDH_C)
typedef enum
{
MBEDTLS_DEBUG_ECDH_Q,
MBEDTLS_DEBUG_ECDH_QP,
MBEDTLS_DEBUG_ECDH_Z,
} mbedtls_debug_ecdh_attr;
/**
* \brief Print a field of the ECDH structure in the SSL context to the debug
* output. This function is always used through the
* MBEDTLS_SSL_DEBUG_ECDH() macro, which supplies the ssl context, file
* and line number parameters.
*
* \param ssl SSL context
* \param level error level of the debug message
* \param file file the error has occurred in
* \param line line number the error has occurred in
* \param ecdh the ECDH context
* \param attr the identifier of the attribute being output
*
* \attention This function is intended for INTERNAL usage within the
* library only.
*/
void mbedtls_debug_printf_ecdh( const mbedtls_ssl_context *ssl, int level,
const char *file, int line,
const mbedtls_ecdh_context *ecdh,
mbedtls_debug_ecdh_attr attr );
#endif
#ifdef __cplusplus
}
#endif
......
......@@ -42,18 +42,20 @@
#define MBEDTLS_DES_DECRYPT 0
#define MBEDTLS_ERR_DES_INVALID_INPUT_LENGTH -0x0032 /**< The data input has an invalid length. */
/* MBEDTLS_ERR_DES_HW_ACCEL_FAILED is deprecated and should not be used. */
#define MBEDTLS_ERR_DES_HW_ACCEL_FAILED -0x0033 /**< DES hardware accelerator failed. */
#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
*
......@@ -61,7 +63,7 @@ extern "C" {
* security risk. We recommend considering stronger ciphers
* instead.
*/
typedef struct
typedef struct mbedtls_des_context
{
uint32_t sk[32]; /*!< DES subkeys */
}
......@@ -70,12 +72,16 @@ mbedtls_des_context;
/**
* \brief Triple-DES context structure
*/
typedef struct
typedef struct mbedtls_des3_context
{
uint32_t sk[96]; /*!< 3DES subkeys */
}
mbedtls_des3_context;
#else /* MBEDTLS_DES_ALT */
#include "des_alt.h"
#endif /* MBEDTLS_DES_ALT */
/**
* \brief Initialize DES context
*
......@@ -331,17 +337,8 @@ int mbedtls_des3_crypt_cbc( mbedtls_des3_context *ctx,
*/
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
#if defined(MBEDTLS_SELF_TEST)
/**
* \brief Checkup routine
......@@ -350,6 +347,8 @@ extern "C" {
*/
int mbedtls_des_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus
}
#endif
......
/**
* \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
......@@ -79,17 +84,22 @@
#define MBEDTLS_ERR_DHM_INVALID_FORMAT -0x3380 /**< The ASN.1 data is not formatted correctly. */
#define MBEDTLS_ERR_DHM_ALLOC_FAILED -0x3400 /**< Allocation of memory failed. */
#define MBEDTLS_ERR_DHM_FILE_IO_ERROR -0x3480 /**< Read or write of file failed. */
/* MBEDTLS_ERR_DHM_HW_ACCEL_FAILED is deprecated and should not be used. */
#define MBEDTLS_ERR_DHM_HW_ACCEL_FAILED -0x3500 /**< DHM hardware accelerator failed. */
#define MBEDTLS_ERR_DHM_SET_GROUP_FAILED -0x3580 /**< Setting the modulus and generator failed. */
#ifdef __cplusplus
extern "C" {
#endif
#if !defined(MBEDTLS_DHM_ALT)
/**
* \brief The DHM context structure.
*/
typedef struct
typedef struct mbedtls_dhm_context
{
size_t len; /*!< The size of \p P in Bytes. */
mbedtls_mpi P; /*!< The prime modulus. */
......@@ -105,6 +115,10 @@ typedef struct
}
mbedtls_dhm_context;
#else /* MBEDTLS_DHM_ALT */
#include "dhm_alt.h"
#endif /* MBEDTLS_DHM_ALT */
/**
* \brief This function initializes the DHM context.
*
......@@ -113,9 +127,15 @@ mbedtls_dhm_context;
void mbedtls_dhm_init( mbedtls_dhm_context *ctx );
/**
* \brief This function parses the ServerKeyExchange parameters.
* \brief This function parses the DHM parameters in a
* TLS ServerKeyExchange handshake message
* (DHM modulus, generator, and public key).
*
* \note In a TLS handshake, this is the how the client
* sets up its DHM context from the server's public
* DHM key material.
*
* \param ctx The DHM context.
* \param ctx The DHM context to use. This must be initialized.
* \param p On input, *p must be the start of the input buffer.
* On output, *p is updated to point to the end of the data
* that has been read. On success, this is the first byte
......@@ -125,38 +145,44 @@ void mbedtls_dhm_init( mbedtls_dhm_context *ctx );
* 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,
const unsigned char *end );
/**
* \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.
* \brief This function generates a DHM key pair and exports its
* public part together with the DHM parameters in the format
* used in a TLS ServerKeyExchange handshake message.
*
* \note The destination buffer must be large enough to hold
* the reduced binary presentation of the modulus, the generator
* and the public key, each wrapped with a 2-byte length field.
* It is the responsibility of the caller to ensure that enough
* space is available. Refer to \c mbedtls_mpi_size to computing
* the byte-size of an MPI.
*
* \note This function assumes that \c ctx->P and \c ctx->G
* have already been properly set. For that, use
* \note This function assumes that the DHM parameters \c ctx->P
* and \c ctx->G have already been properly set. For that, use
* mbedtls_dhm_set_group() below in conjunction with
* mbedtls_mpi_read_binary() and mbedtls_mpi_read_string().
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
* on failure.
* \note In a TLS handshake, this is the how the server generates
* and exports its DHM key material.
*
* \param ctx The DHM context to use. This must be initialized
* and have the DHM parameters set. It may or may not
* already have imported the peer's public key.
* \param x_size The private key size in Bytes.
* \param olen The address at which to store the number of Bytes
* written on success. This must not be \c NULL.
* \param output The destination buffer. This must be a writable buffer of
* sufficient size to hold the reduced binary presentation of
* the modulus, the generator and the public key, each wrapped
* with a 2-byte length field. It is the responsibility of the
* caller to ensure that enough space is available. Refer to
* mbedtls_mpi_size() to computing the byte-size of an MPI.
* \param f_rng The RNG function. Must not be \c NULL.
* \param p_rng The RNG context to be passed to \p f_rng. This may be
* \c NULL if \p f_rng doesn't need a context parameter.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
*/
int mbedtls_dhm_make_params( mbedtls_dhm_context *ctx, int x_size,
unsigned char *output, size_t *olen,
......@@ -164,54 +190,66 @@ int mbedtls_dhm_make_params( mbedtls_dhm_context *ctx, int x_size,
void *p_rng );
/**
* \brief Set prime modulus and generator
* \brief This function sets the prime modulus and generator.
*
* \param ctx The DHM context.
* \param P The MPI holding DHM prime modulus.
* \param G The MPI holding DHM generator.
* \note This function can be used to set \c ctx->P, \c ctx->G
* in preparation for mbedtls_dhm_make_params().
*
* \note This function can be used to set P, G
* in preparation for \c mbedtls_dhm_make_params.
* \param ctx The DHM context to configure. This must be initialized.
* \param P The MPI holding the DHM prime modulus. This must be
* an initialized MPI.
* \param G The MPI holding the DHM generator. This must be an
* initialized MPI.
*
* \return \c 0 if successful, 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 raw public value of the peer.
*
* \note In a TLS handshake, this is the how the server imports
* the Client's public DHM key.
*
* \param ctx The DHM context.
* \param input The input buffer.
* \param ilen The size of the input buffer.
* \param ctx The DHM context to use. This must be initialized and have
* its DHM parameters set, e.g. via mbedtls_dhm_set_group().
* It may or may not already have generated its own private key.
* \param input The input buffer containing the \c G^Y value of the peer.
* This must be a readable buffer of size \p ilen Bytes.
* \param ilen The size of the input buffer \p input in Bytes.
*
* \return \c 0 on success, 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
* exports \c G^X.
* \brief This function creates a DHM key pair and exports
* the raw public key in big-endian format.
*
* \param ctx The DHM context.
* \param x_size The private value size in Bytes.
* \param output The destination buffer.
* \param olen The length of the destination buffer. Must be at least
equal to ctx->len (the size of \c P).
* \param f_rng The RNG function.
* \param p_rng The RNG parameter.
* \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 \c ctx->len, it is padded accordingly
* with zero-bytes at the beginning.
*
* \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.
* \param ctx The DHM context to use. This must be initialized and
* have the DHM parameters set. It may or may not already
* have imported the peer's public key.
* \param x_size The private key size in Bytes.
* \param output The destination buffer. This must be a writable buffer of
* size \p olen Bytes.
* \param olen The length of the destination buffer. This must be at least
* equal to `ctx->len` (the size of \c P).
* \param f_rng The RNG function. This must not be \c NULL.
* \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL
* if \p f_rng doesn't need a context argument.
*
* \return \c 0 on success, 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 +260,27 @@ int mbedtls_dhm_make_public( mbedtls_dhm_context *ctx, int x_size,
* \brief This function derives and exports the shared secret
* \c (G^Y)^X mod \c P.
*
* \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.
* \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.
* \note If \p f_rng is not \c NULL, it is used to blind the input as
* a countermeasure against timing attacks. Blinding is used
* only if our private key \c X is re-used, and not used
* otherwise. We recommend always passing a non-NULL
* \p f_rng argument.
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
* on failure.
* \param ctx The DHM context to use. This must be initialized
* and have its own private key generated and the peer's
* public key imported.
* \param output The buffer to write the generated shared key to. This
* must be a writable buffer of size \p output_size Bytes.
* \param output_size The size of the destination buffer. This must be at
* least the size of \c ctx->len (the size of \c P).
* \param olen On exit, holds the actual number of Bytes written.
* \param f_rng The RNG function, for blinding purposes. This may
* b \c NULL if blinding isn't needed.
* \param p_rng The RNG context. This may be \c NULL if \p f_rng
* doesn't need a context argument.
*
* \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,9 +288,12 @@ int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx,
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.
* \param ctx The DHM context to free and clear. This may be \c NULL,
* in which case this function is a no-op. If it is not \c NULL,
* it must point to an initialized DHM context.
*/
void mbedtls_dhm_free( mbedtls_dhm_context *ctx );
......@@ -256,13 +302,16 @@ void mbedtls_dhm_free( mbedtls_dhm_context *ctx );
/**
* \brief This function parses DHM parameters in PEM or DER format.
*
* \param dhm The DHM context to initialize.
* \param dhmin The input buffer.
* \param dhminlen The size of the buffer, including the terminating null
* Byte for PEM data.
* \param dhm The DHM context to import the DHM parameters into.
* This must be initialized.
* \param dhmin The input buffer. This must be a readable buffer of
* length \p dhminlen Bytes.
* \param dhminlen The size of the input buffer \p dhmin, including the
* terminating \c NULL Byte for PEM data.
*
* \return \c 0 on success, 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 on failure.
*/
int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin,
size_t dhminlen );
......@@ -273,34 +322,29 @@ int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin,
* \brief This function loads and parses DHM parameters from a file.
*
* \param dhm The DHM context to load the parameters to.
* This must be initialized.
* \param path The filename to read the DHM parameters from.
* This must not be \c NULL.
*
* \return \c 0 on success, 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 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
#if defined(MBEDTLS_SELF_TEST)
/**
* \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 );
#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus
}
#endif
......@@ -348,15 +392,6 @@ int mbedtls_dhm_self_test( int verbose );
#if !defined(MBEDTLS_DEPRECATED_REMOVED)
#if defined(MBEDTLS_DEPRECATED_WARNING)
#define MBEDTLS_DEPRECATED __attribute__((deprecated))
MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_constant_t;
#define MBEDTLS_DEPRECATED_STRING_CONSTANT( VAL ) \
( (mbedtls_deprecated_constant_t) ( VAL ) )
#else
#define MBEDTLS_DEPRECATED_STRING_CONSTANT( VAL ) VAL
#endif /* ! MBEDTLS_DEPRECATED_WARNING */
/**
* \warning The origin of the primes in RFC 5114 is not documented and
* their use therefore constitutes a security risk!
......
/**
* \file ecdh.h
*
* \brief The Elliptic Curve Diffie-Hellman (ECDH) protocol APIs.
* \brief This file contains ECDH definitions and functions.
*
* ECDH is an anonymous key agreement protocol allowing two parties to
* establish a shared secret over an insecure channel. Each party must have an
* 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
......@@ -33,28 +34,82 @@
#ifndef MBEDTLS_ECDH_H
#define MBEDTLS_ECDH_H
#if !defined(MBEDTLS_CONFIG_FILE)
#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#include "ecp.h"
/*
* Use a backward compatible ECDH context.
*
* This flag is always enabled for now and future versions might add a
* configuration option that conditionally undefines this flag.
* The configuration option in question may have a different name.
*
* Features undefining this flag, must have a warning in their description in
* config.h stating that the feature breaks backward compatibility.
*/
#define MBEDTLS_ECDH_LEGACY_CONTEXT
#ifdef __cplusplus
extern "C" {
#endif
/**
* 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;
#if !defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
/**
* Defines the ECDH implementation used.
*
* Later versions of the library may add new variants, therefore users should
* not make any assumptions about them.
*/
typedef enum
{
MBEDTLS_ECDH_VARIANT_NONE = 0, /*!< Implementation not defined. */
MBEDTLS_ECDH_VARIANT_MBEDTLS_2_0,/*!< The default Mbed TLS implementation */
} mbedtls_ecdh_variant;
/**
* The context used by the default ECDH implementation.
*
* Later versions might change the structure of this context, therefore users
* should not make any assumptions about the structure of
* mbedtls_ecdh_context_mbed.
*/
typedef struct mbedtls_ecdh_context_mbed
{
mbedtls_ecp_group grp; /*!< The elliptic curve used. */
mbedtls_mpi d; /*!< The private key. */
mbedtls_ecp_point Q; /*!< The public key. */
mbedtls_ecp_point Qp; /*!< The value of the public key of the peer. */
mbedtls_mpi z; /*!< The shared secret. */
#if defined(MBEDTLS_ECP_RESTARTABLE)
mbedtls_ecp_restart_ctx rs; /*!< The restart context for EC computations. */
#endif
} mbedtls_ecdh_context_mbed;
#endif
/**
*
* \warning Performing multiple operations concurrently on the same
* ECDSA context is not supported; objects of this type
* should not be shared between multiple threads.
* \brief The ECDH context structure.
*/
typedef struct
typedef struct mbedtls_ecdh_context
{
#if defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
mbedtls_ecp_group grp; /*!< The elliptic curve used. */
mbedtls_mpi d; /*!< The private key. */
mbedtls_ecp_point Q; /*!< The public key. */
......@@ -64,6 +119,29 @@ typedef struct
mbedtls_ecp_point Vi; /*!< The blinding value. */
mbedtls_ecp_point Vf; /*!< The unblinding value. */
mbedtls_mpi _d; /*!< The previous \p d. */
#if defined(MBEDTLS_ECP_RESTARTABLE)
int restart_enabled; /*!< The flag for restartable mode. */
mbedtls_ecp_restart_ctx rs; /*!< The restart context for EC computations. */
#endif /* MBEDTLS_ECP_RESTARTABLE */
#else
uint8_t point_format; /*!< The format of point export in TLS messages
as defined in RFC 4492. */
mbedtls_ecp_group_id grp_id;/*!< The elliptic curve used. */
mbedtls_ecdh_variant var; /*!< The ECDH implementation/structure used. */
union
{
mbedtls_ecdh_context_mbed mbed_ecdh;
} ctx; /*!< Implementation-specific context. The
context in use is specified by the \c var
field. */
#if defined(MBEDTLS_ECP_RESTARTABLE)
uint8_t restart_enabled; /*!< The flag for restartable mode. Functions of
an alternative implementation not supporting
restartable mode must return
MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED error
if this flag is set. */
#endif /* MBEDTLS_ECP_RESTARTABLE */
#endif /* MBEDTLS_ECDH_LEGACY_CONTEXT */
}
mbedtls_ecdh_context;
......@@ -75,16 +153,22 @@ mbedtls_ecdh_context;
* implemented during the ECDH key exchange. The second core
* computation is performed by mbedtls_ecdh_compute_shared().
*
* \param grp The ECP group.
* \see ecp.h
*
* \param grp The ECP group to use. This must be initialized and have
* domain parameters loaded, for example through
* mbedtls_ecp_load() or mbedtls_ecp_tls_read_group().
* \param d The destination MPI (private key).
* This must be initialized.
* \param Q The destination point (public key).
* \param f_rng The RNG function.
* \param p_rng The RNG parameter.
* This must be initialized.
* \param f_rng The RNG function to use. This must not be \c NULL.
* \param p_rng The RNG context to be passed to \p f_rng. This may be
* \c NULL in case \p f_rng doesn't need a context argument.
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
* \return \c 0 on success.
* \return Another \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 +181,32 @@ int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp
* implemented during the ECDH key exchange. The first core
* computation is performed by mbedtls_ecdh_gen_public().
*
* \param grp The ECP group.
* \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 to use. This must be initialized and have
* domain parameters loaded, for example through
* mbedtls_ecp_load() or mbedtls_ecp_tls_read_group().
* \param z The destination MPI (shared secret).
* This must be initialized.
* \param Q The public key from another party.
* This must be initialized.
* \param d Our secret exponent (private key).
* \param f_rng The RNG function.
* \param p_rng The RNG parameter.
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
* This must be initialized.
* \param f_rng The RNG function. This may be \c NULL if randomization
* of intermediate results during the ECP computations is
* not needed (discouraged). See the documentation of
* mbedtls_ecp_mul() for more.
* \param p_rng The RNG context to be passed to \p f_rng. This may be
* \c NULL if \p f_rng is \c NULL or doesn't need a
* context argument.
*
* \return \c 0 on success.
* \return Another \c MBEDTLS_ERR_ECP_XXX or
* \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,
......@@ -121,39 +216,62 @@ int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
/**
* \brief This function initializes an ECDH context.
*
* \param ctx The ECDH context to initialize.
* \param ctx The ECDH context to initialize. This must not be \c NULL.
*/
void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
/**
* \brief This function frees a context.
* \brief This function sets up the ECDH context with the information
* given.
*
* \param ctx The context to free.
*/
void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
/**
* \brief This function generates a public key and a TLS
* ServerKeyExchange payload.
* This function should be called after mbedtls_ecdh_init() but
* before mbedtls_ecdh_make_params(). There is no need to call
* this function before mbedtls_ecdh_read_params().
*
* This is the first function used by a TLS server for ECDHE
* ciphersuites.
*
* \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 ctx The ECDH context to set up. This must be initialized.
* \param grp_id The group id of the group to set up the context for.
*
* \return \c 0 on success.
*/
int mbedtls_ecdh_setup( mbedtls_ecdh_context *ctx,
mbedtls_ecp_group_id grp_id );
/**
* \brief This function frees a context.
*
* \note This function assumes that the ECP group (grp) of the
* \p ctx context has already been properly set,
* for example, using mbedtls_ecp_group_load().
* \param ctx The context to free. This may be \c NULL, in which
* case this function does nothing. If it is not \c NULL,
* it must point to an initialized ECDH context.
*/
void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
/**
* \brief This function generates an EC key pair and exports its
* in the format used in a TLS ServerKeyExchange handshake
* message.
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
* on failure.
* This is the second function used by a TLS server for ECDHE
* ciphersuites. (It is called after mbedtls_ecdh_setup().)
*
* \see ecp.h
*
* \param ctx The ECDH context to use. This must be initialized
* and bound to a group, for example via mbedtls_ecdh_setup().
* \param olen The address at which to store the number of Bytes written.
* \param buf The destination buffer. This must be a writable buffer of
* length \p blen Bytes.
* \param blen The length of the destination buffer \p buf in Bytes.
* \param f_rng The RNG function to use. This must not be \c NULL.
* \param p_rng The RNG context to be passed to \p f_rng. This may be
* \c NULL in case \p f_rng doesn't need a context argument.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
* operations was reached: see \c mbedtls_ecp_set_max_ops().
* \return Another \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,
......@@ -161,23 +279,32 @@ int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
void *p_rng );
/**
* \brief This function parses and processes a TLS ServerKeyExhange
* payload.
* \brief This function parses the ECDHE parameters in a
* TLS ServerKeyExchange handshake message.
*
* This is the first function used by a TLS client for ECDHE
* ciphersuites.
* \note In a TLS handshake, this is the how the client
* sets up its ECDHE context from the server's public
* ECDHE key material.
*
* \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.
* \see ecp.h
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
* on failure.
* \param ctx The ECDHE context to use. This must be initialized.
* \param buf On input, \c *buf must be the start of the input buffer.
* On output, \c *buf is updated to point to the end of the
* data that has been read. On success, this is the first byte
* past the end of the ServerKeyExchange parameters.
* On error, this is the point at which an error has been
* detected, which is usually not useful except to debug
* failures.
* \param end The end of the input buffer.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
*
* \see ecp.h
*/
int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
const unsigned char **buf, const unsigned char *end );
const unsigned char **buf,
const unsigned char *end );
/**
* \brief This function sets up an ECDH context from an EC key.
......@@ -186,38 +313,47 @@ int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
* ServerKeyEchange for static ECDH, and imports ECDH
* parameters from the EC key information of a certificate.
*
* \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>
* \see ecp.h
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
* on failure.
* \param ctx The ECDH context to set up. This must be initialized.
* \param key The EC key to use. This must be initialized.
* \param side Defines the source of the key. Possible values are:
* - #MBEDTLS_ECDH_OURS: The key is ours.
* - #MBEDTLS_ECDH_THEIRS: The key is that of the peer.
*
* \return \c 0 on success.
* \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
*
* \see ecp.h
*/
int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx,
const mbedtls_ecp_keypair *key,
mbedtls_ecdh_side side );
/**
* \brief This function generates a public key and a TLS
* ClientKeyExchange payload.
* \brief This function generates a public key and exports it
* as a TLS ClientKeyExchange payload.
*
* This is the second function used by a TLS client for ECDH(E)
* ciphersuites.
*
* \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.
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
* on failure.
*
* \see ecp.h
*
* \param ctx The ECDH context to use. This must be initialized
* and bound to a group, the latter usually by
* mbedtls_ecdh_read_params().
* \param olen The address at which to store the number of Bytes written.
* This must not be \c NULL.
* \param buf The destination buffer. This must be a writable buffer
* of length \p blen Bytes.
* \param blen The size of the destination buffer \p buf in Bytes.
* \param f_rng The RNG function to use. This must not be \c NULL.
* \param p_rng The RNG context to be passed to \p f_rng. This may be
* \c NULL in case \p f_rng doesn't need a context argument.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
* operations was reached: see \c mbedtls_ecp_set_max_ops().
* \return Another \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,
......@@ -225,20 +361,23 @@ int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
void *p_rng );
/**
* \brief This function parses and processes a TLS ClientKeyExchange
* payload.
* \brief This function parses and processes the ECDHE payload of a
* TLS ClientKeyExchange message.
*
* This is the second function used by a TLS server for ECDH(E)
* ciphersuites.
* This is the third function used by a TLS server for ECDH(E)
* ciphersuites. (It is called after mbedtls_ecdh_setup() and
* mbedtls_ecdh_make_params().)
*
* \param ctx The ECDH context.
* \param buf The start of the input buffer.
* \param blen The length of the input buffer.
* \see ecp.h
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
* on failure.
* \param ctx The ECDH context to use. This must be initialized
* and bound to a group, for example via mbedtls_ecdh_setup().
* \param buf The pointer to the ClientKeyExchange payload. This must
* be a readable buffer of length \p blen Bytes.
* \param blen The length of the input buffer \p buf in Bytes.
*
* \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,27 +388,51 @@ int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
* This is the last function used by both TLS client
* and servers.
*
* \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.
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
* on failure.
* \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
*
* \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().
* \param ctx The ECDH context to use. This must be initialized
* and have its own private key generated and the peer's
* public key imported.
* \param olen The address at which to store the total number of
* Bytes written on success. This must not be \c NULL.
* \param buf The buffer to write the generated shared key to. This
* must be a writable buffer of size \p blen Bytes.
* \param blen The length of the destination buffer \p buf in Bytes.
* \param f_rng The RNG function, for blinding purposes. This may
* b \c NULL if blinding isn't needed.
* \param p_rng The RNG context. This may be \c NULL if \p f_rng
* doesn't need a context argument.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
* operations was reached: see \c mbedtls_ecp_set_max_ops().
* \return Another \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,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng );
#if defined(MBEDTLS_ECP_RESTARTABLE)
/**
* \brief This function enables restartable EC computations for this
* context. (Default: disabled.)
*
* \see \c mbedtls_ecp_set_max_ops()
*
* \note It is not possible to safely disable restartable
* computations once enabled, except by free-ing the context,
* which cancels possible in-progress operations.
*
* \param ctx The ECDH context to use. This must be initialized.
*/
void mbedtls_ecdh_enable_restart( mbedtls_ecdh_context *ctx );
#endif /* MBEDTLS_ECP_RESTARTABLE */
#ifdef __cplusplus
}
#endif
......
/**
* \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>.
......@@ -31,6 +32,12 @@
#ifndef MBEDTLS_ECDSA_H
#define MBEDTLS_ECDSA_H
#if !defined(MBEDTLS_CONFIG_FILE)
#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#include "ecp.h"
#include "md.h"
......@@ -54,29 +61,71 @@
/** The maximal size of an ECDSA signature in Bytes. */
#define MBEDTLS_ECDSA_MAX_LEN ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) )
#ifdef __cplusplus
extern "C" {
#endif
/**
* \brief The ECDSA context structure.
*
* \warning Performing multiple operations concurrently on the same
* ECDSA context is not supported; objects of this type
* should not be shared between multiple threads.
*/
typedef mbedtls_ecp_keypair mbedtls_ecdsa_context;
#ifdef __cplusplus
extern "C" {
#if defined(MBEDTLS_ECP_RESTARTABLE)
/**
* \brief Internal restart context for ecdsa_verify()
*
* \note Opaque struct, defined in ecdsa.c
*/
typedef struct mbedtls_ecdsa_restart_ver mbedtls_ecdsa_restart_ver_ctx;
/**
* \brief Internal restart context for ecdsa_sign()
*
* \note Opaque struct, defined in ecdsa.c
*/
typedef struct mbedtls_ecdsa_restart_sig mbedtls_ecdsa_restart_sig_ctx;
#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
/**
* \brief Internal restart context for ecdsa_sign_det()
*
* \note Opaque struct, defined in ecdsa.c
*/
typedef struct mbedtls_ecdsa_restart_det mbedtls_ecdsa_restart_det_ctx;
#endif
/**
* \brief General context for resuming ECDSA operations
*/
typedef struct
{
mbedtls_ecp_restart_ctx ecp; /*!< base context for ECP restart and
shared administrative info */
mbedtls_ecdsa_restart_ver_ctx *ver; /*!< ecdsa_verify() sub-context */
mbedtls_ecdsa_restart_sig_ctx *sig; /*!< ecdsa_sign() sub-context */
#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
mbedtls_ecdsa_restart_det_ctx *det; /*!< ecdsa_sign_det() sub-context */
#endif
} mbedtls_ecdsa_restart_ctx;
#else /* MBEDTLS_ECP_RESTARTABLE */
/* Now we can declare functions that take a pointer to that */
typedef void mbedtls_ecdsa_restart_ctx;
#endif /* MBEDTLS_ECP_RESTARTABLE */
/**
* \brief This function computes the ECDSA signature of a
* previously-hashed message.
*
* \note The deterministic version is usually preferred.
*
* \param grp The ECP group.
* \param r The first output integer.
* \param s The second output integer.
* \param d The private signing key.
* \param buf The message hash.
* \param blen The length of \p buf.
* \param f_rng The RNG function.
* \param p_rng The RNG parameter.
* \note The deterministic version implemented in
* mbedtls_ecdsa_sign_det() is usually preferred.
*
* \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated
......@@ -84,10 +133,28 @@ extern "C" {
* (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 error code on failure.
*
* \see ecp.h
*
* \param grp The context for the elliptic curve to use.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param r The MPI context in which to store the first part
* the signature. This must be initialized.
* \param s The MPI context in which to store the second part
* the signature. This must be initialized.
* \param d The private signing key. This must be initialized.
* \param buf The content to be signed. This is usually the hash of
* the original data to be signed. This must be a readable
* buffer of length \p blen Bytes. It may be \c NULL if
* \p blen is zero.
* \param blen The length of \p buf in Bytes.
* \param f_rng The RNG function. This must not be \c NULL.
* \param p_rng The RNG context to be passed to \p f_rng. This may be
* \c NULL if \p f_rng doesn't need a context parameter.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX
* or \c MBEDTLS_MPI_XXX error code on failure.
*/
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,62 +164,139 @@ int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
/**
* \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>.
*
* \param grp The ECP group.
* \param r The first output integer.
* \param s The second output integer.
* \param d The private signing key.
* \param buf The message hash.
* \param blen The length of \p buf.
* \param md_alg The MD algorithm used to hash the message.
*
* \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
* error code on failure.
* \warning Since the output of the internal RNG is always the same for
* the same key and message, this limits the efficiency of
* blinding and leaks information through side channels. For
* secure behavior use mbedtls_ecdsa_sign_det_ext() instead.
*
* (Optimally the blinding is a random value that is different
* on every execution. In this case the blinding is still
* random from the attackers perspective, but is the same on
* each execution. This means that this blinding does not
* prevent attackers from recovering secrets by combining
* several measurement traces, but may prevent some attacks
* that exploit relationships between secret data.)
*
* \see ecp.h
*
* \param grp The context for the elliptic curve to use.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param r The MPI context in which to store the first part
* the signature. This must be initialized.
* \param s The MPI context in which to store the second part
* the signature. This must be initialized.
* \param d The private signing key. This must be initialized
* and setup, for example through mbedtls_ecp_gen_privkey().
* \param buf The hashed content to be signed. This must be a readable
* buffer of length \p blen Bytes. It may be \c NULL if
* \p blen is zero.
* \param blen The length of \p buf in Bytes.
* \param md_alg The hash algorithm used to hash the original data.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
* error code on failure.
*/
int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r,
mbedtls_mpi *s, const mbedtls_mpi *d,
const unsigned char *buf, size_t blen,
mbedtls_md_type_t md_alg );
/**
* \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 context for the elliptic curve to use.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param r The MPI context in which to store the first part
* the signature. This must be initialized.
* \param s The MPI context in which to store the second part
* the signature. This must be initialized.
* \param d The private signing key. This must be initialized
* and setup, for example through mbedtls_ecp_gen_privkey().
* \param buf The hashed content to be signed. This must be a readable
* buffer of length \p blen Bytes. It may be \c NULL if
* \p blen is zero.
* \param blen The length of \p buf in Bytes.
* \param md_alg The hash algorithm used to hash the original data.
* \param f_rng_blind The RNG function used for blinding. This must not be
* \c NULL.
* \param p_rng_blind The RNG context to be passed to \p f_rng. This may be
* \c NULL if \p f_rng doesn't need a context parameter.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
* error code on failure.
*/
int mbedtls_ecdsa_sign_det_ext( mbedtls_ecp_group *grp, mbedtls_mpi *r,
mbedtls_mpi *s, const mbedtls_mpi *d,
const unsigned char *buf, size_t blen,
mbedtls_md_type_t md_alg,
int (*f_rng_blind)(void *, unsigned char *,
size_t),
void *p_rng_blind );
#endif /* MBEDTLS_ECDSA_DETERMINISTIC */
/**
* \brief This function verifies the ECDSA signature of a
* previously-hashed message.
*
* \param grp The ECP group.
* \param buf The message hash.
* \param blen The length of \p buf.
* \param Q The public key to use for verification.
* \param 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
* error code on failure for any other reason.
*
* \see ecp.h
*
* \param grp The ECP group to use.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param buf The hashed content that was signed. This must be a readable
* buffer of length \p blen Bytes. It may be \c NULL if
* \p blen is zero.
* \param blen The length of \p buf in Bytes.
* \param Q The public key to use for verification. This must be
* initialized and setup.
* \param r The first integer of the signature.
* This must be initialized.
* \param s The second integer of the signature.
* This must be initialized.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature
* is invalid.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
* error code on failure for any other reason.
*/
int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
const unsigned char *buf, size_t blen,
const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s);
const mbedtls_ecp_point *Q, const mbedtls_mpi *r,
const mbedtls_mpi *s);
/**
* \brief This function computes the ECDSA signature and writes it
......@@ -169,38 +313,92 @@ int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
* 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
* #MBEDTLS_ECDSA_MAX_LEN is always safe.
*
* \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as
* defined in <em>Standards for Efficient Cryptography Group
* (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 to use. This must be initialized
* and have a group and private key bound to it, for example
* via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
* \param md_alg The message digest that was used to hash the message.
* \param hash The message hash to be signed. This must be a readable
* buffer of length \p blen Bytes.
* \param hlen The length of the hash \p hash in Bytes.
* \param sig The buffer to which to write the signature. This must be a
* writable buffer of length at least twice as large as the
* size of the curve used, plus 9. For example, 73 Bytes if
* a 256-bit curve is used. A buffer length of
* #MBEDTLS_ECDSA_MAX_LEN is always safe.
* \param slen The address at which to store the actual length of
* the signature written. Must not be \c NULL.
* \param f_rng The RNG function. This must not be \c NULL if
* #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise,
* it is unused and may be set to \c NULL.
* \param p_rng The RNG context to be passed to \p f_rng. This may be
* \c NULL if \p f_rng is \c NULL or doesn't use a context.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
* \c MBEDTLS_ERR_ASN1_XXX error code on failure.
*/
int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx,
mbedtls_md_type_t md_alg,
const unsigned char *hash, size_t hlen,
unsigned char *sig, size_t *slen,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng );
/**
* \brief This function computes the ECDSA signature and writes it
* to a buffer, in a restartable way.
*
* \see \c mbedtls_ecdsa_write_signature()
*
* \note This function is like \c mbedtls_ecdsa_write_signature()
* but it can return early and restart according to the limit
* set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
*
* \param ctx The ECDSA context to use. This must be initialized
* and have a group and private key bound to it, for example
* via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
* \param md_alg The message digest that was used to hash the message.
* \param hash The message hash to be signed. This must be a readable
* buffer of length \p blen Bytes.
* \param hlen The length of the hash \p hash in Bytes.
* \param sig The buffer to which to write the signature. This must be a
* writable buffer of length at least twice as large as the
* size of the curve used, plus 9. For example, 73 Bytes if
* a 256-bit curve is used. A buffer length of
* #MBEDTLS_ECDSA_MAX_LEN is always safe.
* \param slen The address at which to store the actual length of
* the signature written. Must not be \c NULL.
* \param f_rng The RNG function. This must not be \c NULL if
* #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise,
* it is unused and may be set to \c NULL.
* \param p_rng The RNG context to be passed to \p f_rng. This may be
* \c NULL if \p f_rng is \c NULL or doesn't use a context.
* \param rs_ctx The restart context to use. This may be \c NULL to disable
* restarting. If it is not \c NULL, it must point to an
* initialized restart context.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
* operations was reached: see \c mbedtls_ecp_set_max_ops().
* \return Another \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_restartable( mbedtls_ecdsa_context *ctx,
mbedtls_md_type_t md_alg,
const unsigned char *hash, size_t hlen,
unsigned char *sig, size_t *slen,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng,
mbedtls_ecdsa_restart_ctx *rs_ctx );
#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
#if defined(MBEDTLS_DEPRECATED_WARNING)
......@@ -209,31 +407,17 @@ int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t
#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>.
* 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
* 256-bit curve is used. A buffer length of
* #MBEDTLS_ECDSA_MAX_LEN is always safe.
*
* \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as
......@@ -241,11 +425,29 @@ int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t
* (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 to use. This must be initialized
* and have a group and private key bound to it, for example
* via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
* \param hash The message hash to be signed. This must be a readable
* buffer of length \p blen Bytes.
* \param hlen The length of the hash \p hash in Bytes.
* \param sig The buffer to which to write the signature. This must be a
* writable buffer of length at least twice as large as the
* size of the curve used, plus 9. For example, 73 Bytes if
* a 256-bit curve is used. A buffer length of
* #MBEDTLS_ECDSA_MAX_LEN is always safe.
* \param slen The address at which to store the actual length of
* the signature written. Must not be \c NULL.
* \param md_alg The message digest that was used to hash the message.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
* \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,75 +460,143 @@ int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
/**
* \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 to use. This must be initialized
* and have a group and public key bound to it.
* \param hash The message hash that was signed. This must be a readable
* buffer of length \p size Bytes.
* \param hlen The size of the hash \p hash.
* \param sig The signature to read and verify. This must be a readable
* buffer of length \p slen Bytes.
* \param slen The size of \p sig in Bytes.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
* \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,
const unsigned char *sig, size_t slen );
/**
* \brief This function reads and verifies an ECDSA signature,
* in a restartable way.
*
* \see \c mbedtls_ecdsa_read_signature()
*
* \note This function is like \c mbedtls_ecdsa_read_signature()
* but it can return early and restart according to the limit
* set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
*
* \param ctx The ECDSA context to use. This must be initialized
* and have a group and public key bound to it.
* \param hash The message hash that was signed. This must be a readable
* buffer of length \p size Bytes.
* \param hlen The size of the hash \p hash.
* \param sig The signature to read and verify. This must be a readable
* buffer of length \p slen Bytes.
* \param slen The size of \p sig in Bytes.
* \param rs_ctx The restart context to use. This may be \c NULL to disable
* restarting. If it is not \c NULL, it must point to an
* initialized restart context.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
* \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 #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
* operations was reached: see \c mbedtls_ecp_set_max_ops().
* \return Another \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
* error code on failure for any other reason.
*/
int mbedtls_ecdsa_read_signature_restartable( mbedtls_ecdsa_context *ctx,
const unsigned char *hash, size_t hlen,
const unsigned char *sig, size_t slen,
mbedtls_ecdsa_restart_ctx *rs_ctx );
/**
* \brief This function generates an ECDSA keypair on the given curve.
*
* \see ecp.h
*
* \param ctx The ECDSA context to store the keypair in.
* This must be initialized.
* \param gid The elliptic curve to use. One of the various
* \c MBEDTLS_ECP_DP_XXX macros depending on configuration.
* \param f_rng The RNG function.
* \param p_rng The RNG parameter.
* \param f_rng The RNG function to use. This must not be \c NULL.
* \param p_rng The RNG context to be passed to \p f_rng. This may be
* \c NULL if \p f_rng doesn't need a context argument.
*
* \return \c 0 on success, 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 );
/**
* \brief This function sets an ECDSA context from an EC key pair.
* \brief This function sets up an ECDSA context from an EC key pair.
*
* \param ctx The ECDSA context to set.
* \param key The EC key to use.
* \see ecp.h
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on
* failure.
* \param ctx The ECDSA context to setup. This must be initialized.
* \param key The EC key to use. This must be initialized and hold
* a private-public key pair or a public key. In the former
* case, the ECDSA context may be used for signature creation
* and verification after this call. In the latter case, it
* may be used for signature verification.
*
* \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 );
int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx,
const mbedtls_ecp_keypair *key );
/**
* \brief This function initializes an ECDSA context.
*
* \param ctx The ECDSA context to initialize.
* This must not be \c NULL.
*/
void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx );
/**
* \brief This function frees an ECDSA context.
*
* \param ctx The ECDSA context to free.
* \param ctx The ECDSA context to free. This may be \c NULL,
* in which case this function does nothing. If it
* is not \c NULL, it must be initialized.
*/
void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );
#if defined(MBEDTLS_ECP_RESTARTABLE)
/**
* \brief Initialize a restart context.
*
* \param ctx The restart context to initialize.
* This must not be \c NULL.
*/
void mbedtls_ecdsa_restart_init( mbedtls_ecdsa_restart_ctx *ctx );
/**
* \brief Free the components of a restart context.
*
* \param ctx The restart context to free. This may be \c NULL,
* in which case this function does nothing. If it
* is not \c NULL, it must be initialized.
*/
void mbedtls_ecdsa_restart_free( mbedtls_ecdsa_restart_ctx *ctx );
#endif /* MBEDTLS_ECP_RESTARTABLE */
#ifdef __cplusplus
}
#endif
......
......@@ -40,12 +40,15 @@
* The payloads are serialized in a way suitable for use in TLS, but could
* also be use outside TLS.
*/
#if !defined(MBEDTLS_CONFIG_FILE)
#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#include "ecp.h"
#include "md.h"
#if !defined(MBEDTLS_ECJPAKE_ALT)
#ifdef __cplusplus
extern "C" {
#endif
......@@ -58,6 +61,7 @@ typedef enum {
MBEDTLS_ECJPAKE_SERVER, /**< Server */
} mbedtls_ecjpake_role;
#if !defined(MBEDTLS_ECJPAKE_ALT)
/**
* EC J-PAKE context structure.
*
......@@ -69,7 +73,7 @@ typedef enum {
* convetion from the Thread v1.0 spec. Correspondance is indicated in the
* description as a pair C: client name, S: server name
*/
typedef struct
typedef struct mbedtls_ecjpake_context
{
const mbedtls_md_info_t *md_info; /**< Hash to use */
mbedtls_ecp_group grp; /**< Elliptic curve */
......@@ -88,29 +92,38 @@ typedef struct
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()).
* \brief Initialize an ECJPAKE context.
*
* \param ctx context to initialize
* \param ctx The ECJPAKE context to initialize.
* This must not be \c NULL.
*/
void mbedtls_ecjpake_init( mbedtls_ecjpake_context *ctx );
/**
* \brief Set up a context for use
* \brief Set up an ECJPAKE context for use.
*
* \note Currently the only values for hash/curve allowed by the
* standard are MBEDTLS_MD_SHA256/MBEDTLS_ECP_DP_SECP256R1.
* standard are #MBEDTLS_MD_SHA256/#MBEDTLS_ECP_DP_SECP256R1.
*
* \param ctx context to set up
* \param role Our role: client or server
* \param hash hash function to use (MBEDTLS_MD_XXX)
* \param curve elliptic curve identifier (MBEDTLS_ECP_DP_XXX)
* \param secret pre-shared secret (passphrase)
* \param len length of the shared secret
* \param ctx The ECJPAKE context to set up. This must be initialized.
* \param role The role of the caller. This must be either
* #MBEDTLS_ECJPAKE_CLIENT or #MBEDTLS_ECJPAKE_SERVER.
* \param hash The identifier of the hash function to use,
* for example #MBEDTLS_MD_SHA256.
* \param curve The identifier of the elliptic curve to use,
* for example #MBEDTLS_ECP_DP_SECP256R1.
* \param secret The pre-shared secret (passphrase). This must be
* a readable buffer of length \p len Bytes. It need
* only be valid for the duration of this call.
* \param len The length of the pre-shared secret \p secret.
*
* \return 0 if successfull,
* a negative error code otherwise
* \return \c 0 if successful.
* \return A negative error code on failure.
*/
int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx,
mbedtls_ecjpake_role role,
......@@ -120,29 +133,34 @@ int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx,
size_t len );
/**
* \brief Check if a context is ready for use
* \brief Check if an ECJPAKE context is ready for use.
*
* \param ctx Context to check
* \param ctx The ECJPAKE context to check. This must be
* initialized.
*
* \return 0 if the context is ready for use,
* MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise
* \return \c 0 if the context is ready for use.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise.
*/
int mbedtls_ecjpake_check( const mbedtls_ecjpake_context *ctx );
/**
* \brief Generate and write the first round message
* (TLS: contents of the Client/ServerHello extension,
* excluding extension type and length bytes)
* excluding extension type and length bytes).
*
* \param ctx Context to use
* \param buf Buffer to write the contents to
* \param len Buffer size
* \param olen Will be updated with the number of bytes written
* \param f_rng RNG function
* \param p_rng RNG parameter
* \param ctx The ECJPAKE context to use. This must be
* initialized and set up.
* \param buf The buffer to write the contents to. This must be a
* writable buffer of length \p len Bytes.
* \param len The length of \p buf in Bytes.
* \param olen The address at which to store the total number
* of Bytes written to \p buf. This must not be \c NULL.
* \param f_rng The RNG function to use. This must not be \c NULL.
* \param p_rng The RNG parameter to be passed to \p f_rng. This
* may be \c NULL if \p f_rng doesn't use a context.
*
* \return 0 if successfull,
* a negative error code otherwise
* \return \c 0 if successful.
* \return A negative error code on failure.
*/
int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx,
unsigned char *buf, size_t len, size_t *olen,
......@@ -152,14 +170,16 @@ int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx,
/**
* \brief Read and process the first round message
* (TLS: contents of the Client/ServerHello extension,
* excluding extension type and length bytes)
* excluding extension type and length bytes).
*
* \param ctx Context to use
* \param buf Pointer to extension contents
* \param len Extension length
* \param ctx The ECJPAKE context to use. This must be initialized
* and set up.
* \param buf The buffer holding the first round message. This must
* be a readable buffer of length \p len Bytes.
* \param len The length in Bytes of \p buf.
*
* \return 0 if successfull,
* a negative error code otherwise
* \return \c 0 if successful.
* \return A negative error code on failure.
*/
int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx,
const unsigned char *buf,
......@@ -167,17 +187,21 @@ int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx,
/**
* \brief Generate and write the second round message
* (TLS: contents of the Client/ServerKeyExchange)
* (TLS: contents of the Client/ServerKeyExchange).
*
* \param ctx Context to use
* \param buf Buffer to write the contents to
* \param len Buffer size
* \param olen Will be updated with the number of bytes written
* \param f_rng RNG function
* \param p_rng RNG parameter
* \param ctx The ECJPAKE context to use. This must be initialized,
* set up, and already have performed round one.
* \param buf The buffer to write the round two contents to.
* This must be a writable buffer of length \p len Bytes.
* \param len The size of \p buf in Bytes.
* \param olen The address at which to store the total number of Bytes
* written to \p buf. This must not be \c NULL.
* \param f_rng The RNG function to use. This must not be \c NULL.
* \param p_rng The RNG parameter to be passed to \p f_rng. This
* may be \c NULL if \p f_rng doesn't use a context.
*
* \return 0 if successfull,
* a negative error code otherwise
* \return \c 0 if successful.
* \return A negative error code on failure.
*/
int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx,
unsigned char *buf, size_t len, size_t *olen,
......@@ -186,14 +210,16 @@ int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx,
/**
* \brief Read and process the second round message
* (TLS: contents of the Client/ServerKeyExchange)
* (TLS: contents of the Client/ServerKeyExchange).
*
* \param ctx Context to use
* \param buf Pointer to the message
* \param len Message length
* \param ctx The ECJPAKE context to use. This must be initialized
* and set up and already have performed round one.
* \param buf The buffer holding the second round message. This must
* be a readable buffer of length \p len Bytes.
* \param len The length in Bytes of \p buf.
*
* \return 0 if successfull,
* a negative error code otherwise
* \return \c 0 if successful.
* \return A negative error code on failure.
*/
int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
const unsigned char *buf,
......@@ -201,17 +227,21 @@ int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
/**
* \brief Derive the shared secret
* (TLS: Pre-Master Secret)
* (TLS: Pre-Master Secret).
*
* \param ctx Context to use
* \param buf Buffer to write the contents to
* \param len Buffer size
* \param olen Will be updated with the number of bytes written
* \param f_rng RNG function
* \param p_rng RNG parameter
* \param ctx The ECJPAKE context to use. This must be initialized,
* set up and have performed both round one and two.
* \param buf The buffer to write the derived secret to. This must
* be a writable buffer of length \p len Bytes.
* \param len The length of \p buf in Bytes.
* \param olen The address at which to store the total number of Bytes
* written to \p buf. This must not be \c NULL.
* \param f_rng The RNG function to use. This must not be \c NULL.
* \param p_rng The RNG parameter to be passed to \p f_rng. This
* may be \c NULL if \p f_rng doesn't use a context.
*
* \return 0 if successfull,
* a negative error code otherwise
* \return \c 0 if successful.
* \return A negative error code on failure.
*/
int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
unsigned char *buf, size_t len, size_t *olen,
......@@ -219,26 +249,17 @@ int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
void *p_rng );
/**
* \brief Free a context's content
* \brief This clears an ECJPAKE context and frees any
* embedded data structure.
*
* \param ctx context to free
* \param ctx The ECJPAKE context to free. This may be \c NULL,
* in which case this function does nothing. If it is not
* \c NULL, it must point to an initialized ECJPAKE context.
*/
void mbedtls_ecjpake_free( mbedtls_ecjpake_context *ctx );
#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 +267,11 @@ extern "C" {
*/
int mbedtls_ecjpake_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus
}
#endif
#endif /* MBEDTLS_SELF_TEST */
#endif /* ecjpake.h */
/**
* \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,11 +30,18 @@
* 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
#if !defined(MBEDTLS_CONFIG_FILE)
#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#include "bignum.h"
/*
......@@ -31,160 +49,165 @@
*/
#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. */
#if !defined(MBEDTLS_ECP_ALT)
/*
* default mbed TLS elliptic curve arithmetic implementation
*
* (in case MBEDTLS_ECP_ALT is defined then the developer has to provide an
* alternative implementation for the whole module and it will replace this
* one.)
*/
/* MBEDTLS_ERR_ECP_HW_ACCEL_FAILED is deprecated and should not be used. */
#define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED -0x4B80 /**< The ECP hardware accelerator failed. */
#define MBEDTLS_ERR_ECP_IN_PROGRESS -0x4B00 /**< Operation in progress, call again with the same parameters to continue. */
#ifdef __cplusplus
extern "C" {
#endif
/**
* Domain parameters (curve, subgroup and generator) identifiers.
* Domain-parameter identifiers: curve, subgroup, and generator.
*
* Only curves over prime fields are supported.
* \note Only curves over prime fields are supported.
*
* \warning This library does not support validation of arbitrary domain
* parameters. Therefore, only well-known domain parameters from trusted
* parameters. Therefore, only standardized 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_SECP192K1, /*!< 192-bits "Koblitz" curve */
MBEDTLS_ECP_DP_SECP224K1, /*!< 224-bits "Koblitz" curve */
MBEDTLS_ECP_DP_SECP256K1, /*!< 256-bits "Koblitz" curve */
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;
/**
* Number of supported curves (plus one for NONE).
* The number of supported curves, plus one for #MBEDTLS_ECP_DP_NONE.
*
* (Montgomery curves excluded for now.)
* \note Montgomery curves are currently excluded.
*/
#define MBEDTLS_ECP_DP_MAX 12
/**
* Curve information for use by other modules
* Curve information, for use by other modules.
*/
typedef struct
typedef struct mbedtls_ecp_curve_info
{
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_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 ECP point structure (jacobian coordinates)
* \brief The ECP point structure, in 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.
* 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
typedef struct mbedtls_ecp_point
{
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_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;
/**
* \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 !defined(MBEDTLS_ECP_ALT)
/*
* default mbed TLS elliptic curve arithmetic implementation
*
* 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.
* (in case MBEDTLS_ECP_ALT is defined then the developer has to provide an
* alternative implementation for the whole module and it will replace this
* one.)
*/
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; /*!< 1. the order of G, or 2. unused */
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;
/**
* \brief ECP key pair structure
*
* A generic key pair that could be used for ECDSA, fixed ECDH, etc.
* \brief The ECP group structure.
*
* 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.
*
* 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.
*
* 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.
*
* \note Alternative implementations must keep the group IDs distinct. If
* two group structures have the same ID, then they must be
* identical.
*
* \note Members purposefully in the same order as struc mbedtls_ecdsa_context.
*/
typedef struct
typedef struct mbedtls_ecp_group
{
mbedtls_ecp_group grp; /*!< Elliptic curve and base point */
mbedtls_mpi d; /*!< our secret value */
mbedtls_ecp_point Q; /*!< our public value */
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_keypair;
mbedtls_ecp_group;
/**
* \name SECTION: Module settings
*
* The configuration options you can set for this module are in this section.
* Either change them in config.h or define them 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 )
......@@ -207,11 +230,10 @@ mbedtls_ecp_keypair;
* 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)
......@@ -226,33 +248,188 @@ mbedtls_ecp_keypair;
*
* 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 */
#if defined(MBEDTLS_ECP_RESTARTABLE)
/**
* \brief Internal restart context for multiplication
*
* \note Opaque struct
*/
typedef struct mbedtls_ecp_restart_mul mbedtls_ecp_restart_mul_ctx;
/**
* \brief Internal restart context for ecp_muladd()
*
* \note Opaque struct
*/
typedef struct mbedtls_ecp_restart_muladd mbedtls_ecp_restart_muladd_ctx;
/**
* \brief General context for resuming ECC operations
*/
typedef struct
{
unsigned ops_done; /*!< current ops count */
unsigned depth; /*!< call depth (0 = top-level) */
mbedtls_ecp_restart_mul_ctx *rsm; /*!< ecp_mul_comb() sub-context */
mbedtls_ecp_restart_muladd_ctx *ma; /*!< ecp_muladd() sub-context */
} mbedtls_ecp_restart_ctx;
/*
* Operation counts for restartable functions
*/
#define MBEDTLS_ECP_OPS_CHK 3 /*!< basic ops count for ecp_check_pubkey() */
#define MBEDTLS_ECP_OPS_DBL 8 /*!< basic ops count for ecp_double_jac() */
#define MBEDTLS_ECP_OPS_ADD 11 /*!< basic ops count for see ecp_add_mixed() */
#define MBEDTLS_ECP_OPS_INV 120 /*!< empirical equivalent for mpi_mod_inv() */
/**
* \brief Internal; for restartable functions in other modules.
* Check and update basic ops budget.
*
* \param grp Group structure
* \param rs_ctx Restart context
* \param ops Number of basic ops to do
*
* \return \c 0 if doing \p ops basic ops is still allowed,
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS otherwise.
*/
int mbedtls_ecp_check_budget( const mbedtls_ecp_group *grp,
mbedtls_ecp_restart_ctx *rs_ctx,
unsigned ops );
/* Utility macro for checking and updating ops budget */
#define MBEDTLS_ECP_BUDGET( ops ) \
MBEDTLS_MPI_CHK( mbedtls_ecp_check_budget( grp, rs_ctx, \
(unsigned) (ops) ) );
#else /* MBEDTLS_ECP_RESTARTABLE */
#define MBEDTLS_ECP_BUDGET( ops ) /* no-op; for compatibility */
/* We want to declare restartable versions of existing functions anyway */
typedef void mbedtls_ecp_restart_ctx;
#endif /* MBEDTLS_ECP_RESTARTABLE */
/**
* \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_keypair
{
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. */
#if defined(MBEDTLS_ECP_RESTARTABLE)
/**
* \brief Set the maximum number of basic operations done in a row.
*
* If more operations are needed to complete a computation,
* #MBEDTLS_ERR_ECP_IN_PROGRESS will be returned by the
* function performing the computation. It is then the
* caller's responsibility to either call again with the same
* parameters until it returns 0 or an error code; or to free
* the restart context if the operation is to be aborted.
*
* It is strictly required that all input parameters and the
* restart context be the same on successive calls for the
* same operation, but output parameters need not be the
* same; they must not be used until the function finally
* returns 0.
*
* This only applies to functions whose documentation
* mentions they may return #MBEDTLS_ERR_ECP_IN_PROGRESS (or
* #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS for functions in the
* SSL module). For functions that accept a "restart context"
* argument, passing NULL disables restart and makes the
* function equivalent to the function with the same name
* with \c _restartable removed. For functions in the ECDH
* module, restart is disabled unless the function accepts
* an "ECDH context" argument and
* mbedtls_ecdh_enable_restart() was previously called on
* that context. For function in the SSL module, restart is
* only enabled for specific sides and key exchanges
* (currently only for clients and ECDHE-ECDSA).
*
* \param max_ops Maximum number of basic operations done in a row.
* Default: 0 (unlimited).
* Lower (non-zero) values mean ECC functions will block for
* a lesser maximum amount of time.
*
* \note A "basic operation" is defined as a rough equivalent of a
* multiplication in GF(p) for the NIST P-256 curve.
* As an indication, with default settings, a scalar
* multiplication (full run of \c mbedtls_ecp_mul()) is:
* - about 3300 basic operations for P-256
* - about 9400 basic operations for P-384
*
* \note Very low values are not always respected: sometimes
* functions need to block for a minimum number of
* operations, and will do so even if max_ops is set to a
* lower value. That minimum depends on the curve size, and
* can be made lower by decreasing the value of
* \c MBEDTLS_ECP_WINDOW_SIZE. As an indication, here is the
* lowest effective value for various curves and values of
* that parameter (w for short):
* w=6 w=5 w=4 w=3 w=2
* P-256 208 208 160 136 124
* P-384 682 416 320 272 248
* P-521 1364 832 640 544 496
*
* \note This setting is currently ignored by Curve25519.
*/
void mbedtls_ecp_set_max_ops( unsigned max_ops );
/**
* \brief Get the list of supported curves in order of preferrence
* (full information)
* \brief Check if restart is enabled (max_ops != 0)
*
* \return A statically allocated array, the last entry is 0.
* \return \c 0 if \c max_ops == 0 (restart disabled)
* \return \c 1 otherwise (restart enabled)
*/
int mbedtls_ecp_restart_is_enabled( void );
#endif /* MBEDTLS_ECP_RESTARTABLE */
/**
* \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.
*/
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.
......@@ -260,357 +437,610 @@ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void );
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_group_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. This may be \c NULL, in which
* case this function returns immediately. If it is not
* \c NULL, it must point to an initialized ECP group.
*/
void mbedtls_ecp_group_free( mbedtls_ecp_group *grp );
/**
* \brief Free the components of a key pair
* \brief This function frees the components of a key pair.
*
* \param key The key pair to free. This may be \c NULL, in which
* case this function returns immediately. If it is not
* \c NULL, it must point to an initialized ECP key pair.
*/
void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key );
#if defined(MBEDTLS_ECP_RESTARTABLE)
/**
* \brief Initialize a restart context.
*
* \param ctx The restart context to initialize. This must
* not be \c NULL.
*/
void mbedtls_ecp_restart_init( mbedtls_ecp_restart_ctx *ctx );
/**
* \brief Free the components of a restart context.
*
* \param ctx The restart context to free. This may be \c NULL, in which
* case this function returns immediately. If it is not
* \c NULL, it must point to an initialized restart context.
*/
void mbedtls_ecp_restart_free( mbedtls_ecp_restart_ctx *ctx );
#endif /* MBEDTLS_ECP_RESTARTABLE */
/**
* \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. This must be initialized.
* \param Q The source point. This must be initialized.
*
* \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.
* \return Another negative error code for other kinds of 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. This must be initialized.
* \param src The source group. This must be initialized.
*
* \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.
* \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src );
int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst,
const mbedtls_ecp_group *src );
/**
* \brief Set a point to zero
* \brief This function sets a point to the point at infinity.
*
* \param pt Destination point
* \param pt The point to set. This must be initialized.
*
* \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.
* \return Another negative error code on other kinds of 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 the point at infinity.
*
* \param pt Point to test
* \param pt The point to test. This must be initialized.
*
* \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.
* \return A negative error code on failure.
*/
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. This must be initialized.
* \param Q The second point to compare. This must be initialized.
*
* \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. This must be initialized.
* \param radix The numeric base of the input.
* \param x The first affine coordinate, as a null-terminated string.
* \param y The second affine coordinate, as a null-terminated string.
*
* \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
*
* \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
*
* \return 0 if successful,
* or MBEDTLS_ERR_ECP_BAD_INPUT_DATA
* or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
* \brief This function exports a point into unsigned binary data.
*
* \param grp The group to which the point should belong.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param P The point to export. This must be initialized.
* \param format The point format. This must be either
* #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
* \param olen The address at which to store the length of
* the output in Bytes. This must not be \c NULL.
* \param buf The output buffer. This must be a writable buffer
* of length \p buflen Bytes.
* \param buflen The length of the output buffer \p buf in Bytes.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output buffer
* is too small to hold the point.
* \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *P,
int format, size_t *olen,
unsigned char *buf, size_t buflen );
/**
* \brief Import 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
*
* \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
* \brief This function imports a point from unsigned binary data.
*
* \note This function does not check that the point actually
* belongs to the given group, see mbedtls_ecp_check_pubkey()
* for that.
*
* \param grp The group to which the point should belong.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param P The destination context to import the point to.
* This must be initialized.
* \param buf The input buffer. This must be a readable buffer
* of length \p ilen Bytes.
* \param ilen The length of the input buffer \p buf in Bytes.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
* \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
* is not implemented.
*
* \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,
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
*
* \param grp ECP group used
* \param pt Destination point
* \param buf $(Start of input buffer)
* \param len Buffer length
*
* \note buf is updated to point right after the ECPoint on exit
*
* \return 0 if successful,
* MBEDTLS_ERR_MPI_XXX if initialization failed
* MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid
* \brief This function imports a point from a TLS ECPoint record.
*
* \note On function return, \p *buf is updated to point immediately
* after the ECPoint record.
*
* \param grp The ECP group to use.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param pt The destination point.
* \param buf The address of the pointer to the start of the input buffer.
* \param len The length of the buffer.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization
* failure.
* \return #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,
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
*
* \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
*
* \return 0 if successful,
* or MBEDTLS_ERR_ECP_BAD_INPUT_DATA
* or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
* \brief This function exports a point as a TLS ECPoint record
* defined in RFC 4492, Section 5.4.
*
* \param grp The ECP group to use.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param pt The point to be exported. This must be initialized.
* \param format The point format to use. This must be either
* #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
* \param olen The address at which to store the length in Bytes
* of the data written.
* \param buf The target buffer. This must be a writable buffer of
* length \p blen Bytes.
* \param blen The length of the target buffer \p buf in Bytes.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
* \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the target buffer
* is too small to hold the exported point.
* \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt,
int 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 up an ECP group context
* from a standardized set of 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 group context to setup. This must be initialized.
* \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 #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if \p id doesn't
* correspond to a known group.
* \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id );
/**
* \brief Set a group from a TLS ECParameters record
* \brief This function sets up an ECP group context from a TLS
* ECParameters record as defined in RFC 4492, Section 5.4.
*
* \param grp Destination group
* \param buf &(Start of input buffer)
* \param len Buffer length
* \note The read pointer \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 group context to setup. This must be initialized.
* \param buf The address of the pointer to the start of the input buffer.
* \param len The length of the input buffer \c *buf in Bytes.
*
* \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 #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
* \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not
* recognized.
* \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp, const unsigned char **buf, size_t len );
int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp,
const unsigned char **buf, size_t len );
/**
* \brief Write 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
*
* \return 0 if successful,
* or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
* \brief This function extracts an elliptic curve group ID from a
* TLS ECParameters record as defined in RFC 4492, Section 5.4.
*
* \note The read pointer \p buf is updated to point right after
* the ECParameters record on exit.
*
* \param grp The address at which to store the group id.
* This must not be \c NULL.
* \param buf The address of the pointer to the start of the input buffer.
* \param len The length of the input buffer \c *buf in Bytes.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
* \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not
* recognized.
* \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_tls_read_group_id( mbedtls_ecp_group_id *grp,
const unsigned char **buf,
size_t len );
/**
* \brief This function exports an elliptic curve as a TLS
* ECParameters record as defined in RFC 4492, Section 5.4.
*
* \param grp The ECP group to be exported.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param olen The address at which to store the number of Bytes written.
* This must not be \c NULL.
* \param buf The buffer to write to. This must be a writable buffer
* of length \p blen Bytes.
* \param blen The length of the output buffer \p buf in Bytes.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output
* buffer is too small to hold the exported group.
* \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen,
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)
*
* \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.
*
* \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).
*
* \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
*
* \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
* \brief This function performs a scalar multiplication of a point
* by an integer: \p R = \p m * \p P.
*
* It is not thread-safe to use same group in multiple threads.
*
* \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.
*
* \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.
*
* \param grp The ECP group to use.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param R The point in which to store the result of the calculation.
* This must be initialized.
* \param m The integer by which to multiply. This must be initialized.
* \param P The point to multiply. This must be initialized.
* \param f_rng The RNG function. This may be \c NULL if randomization
* of intermediate results isn't desired (discouraged).
* \param p_rng The RNG context to be passed to \p p_rng.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
* key, or \p P is not a valid public key.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
* \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
const mbedtls_mpi *m, const mbedtls_ecp_point *P,
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)
*
* \note In contrast to mbedtls_ecp_mul(), this function does not guarantee
* a constant execution flow and timing.
*
* \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
*
* \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
* \brief This function performs multiplication of a point by
* an integer: \p R = \p m * \p P in a restartable way.
*
* \see mbedtls_ecp_mul()
*
* \note This function does the same as \c mbedtls_ecp_mul(), but
* it can return early and restart according to the limit set
* with \c mbedtls_ecp_set_max_ops() to reduce blocking.
*
* \param grp The ECP group to use.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param R The point in which to store the result of the calculation.
* This must be initialized.
* \param m The integer by which to multiply. This must be initialized.
* \param P The point to multiply. This must be initialized.
* \param f_rng The RNG function. This may be \c NULL if randomization
* of intermediate results isn't desired (discouraged).
* \param p_rng The RNG context to be passed to \p p_rng.
* \param rs_ctx The restart context (NULL disables restart).
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
* key, or \p P is not a valid public key.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
* operations was reached: see \c mbedtls_ecp_set_max_ops().
* \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_mul_restartable( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
const mbedtls_mpi *m, const mbedtls_ecp_point *P,
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
mbedtls_ecp_restart_ctx *rs_ctx );
/**
* \brief This function performs multiplication and addition of two
* points by integers: \p R = \p m * \p P + \p n * \p Q
*
* It is not thread-safe to use same group in multiple threads.
*
* \note In contrast to mbedtls_ecp_mul(), this function does not
* guarantee a constant execution flow and timing.
*
* \param grp The ECP group to use.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param R The point in which to store the result of the calculation.
* This must be initialized.
* \param m The integer by which to multiply \p P.
* This must be initialized.
* \param P The point to multiply by \p m. This must be initialized.
* \param n The integer by which to multiply \p Q.
* This must be initialized.
* \param Q The point to be multiplied by \p n.
* This must be initialized.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
* valid private keys, or \p P or \p Q are not valid public
* keys.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
* \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
const mbedtls_mpi *m, const mbedtls_ecp_point *P,
const mbedtls_mpi *n, const mbedtls_ecp_point *Q );
/**
* \brief Check 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
*
* \return 0 if point is a valid public key,
* MBEDTLS_ERR_ECP_INVALID_KEY otherwise.
*
* \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.
*
* \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.
* \brief This function performs multiplication and addition of two
* points by integers: \p R = \p m * \p P + \p n * \p Q in a
* restartable way.
*
* \see \c mbedtls_ecp_muladd()
*
* \note This function works the same as \c mbedtls_ecp_muladd(),
* but it can return early and restart according to the limit
* set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
*
* \param grp The ECP group to use.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param R The point in which to store the result of the calculation.
* This must be initialized.
* \param m The integer by which to multiply \p P.
* This must be initialized.
* \param P The point to multiply by \p m. This must be initialized.
* \param n The integer by which to multiply \p Q.
* This must be initialized.
* \param Q The point to be multiplied by \p n.
* This must be initialized.
* \param rs_ctx The restart context (NULL disables restart).
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
* valid private keys, or \p P or \p Q are not valid public
* keys.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
* operations was reached: see \c mbedtls_ecp_set_max_ops().
* \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt );
int mbedtls_ecp_muladd_restartable(
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,
mbedtls_ecp_restart_ctx *rs_ctx );
/**
* \brief Check that an mbedtls_mpi is a valid private key for this curve
*
* \param grp Group used
* \param d Integer to check
*
* \return 0 if point is a valid private key,
* MBEDTLS_ERR_ECP_INVALID_KEY otherwise.
*
* \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.
* \brief This function checks that a point is a valid public key
* on this curve.
*
* 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.
*
* \note This function uses bare components rather than an
* ::mbedtls_ecp_keypair structure, to ease use with other
* structures, such as ::mbedtls_ecdh_context or
* ::mbedtls_ecdsa_context.
*
* \param grp The ECP group the point should belong to.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param pt The point to check. This must be initialized.
*
* \return \c 0 if the point is a valid public key.
* \return #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not
* a valid public key for the given curve.
* \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d );
int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp,
const mbedtls_ecp_point *pt );
/**
* \brief Generate a keypair with 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
*
* \return 0 if successful,
* or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
*
* \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.
* \brief This function checks that an \p mbedtls_mpi is a
* valid private key for this curve.
*
* \note This function uses bare components rather than an
* ::mbedtls_ecp_keypair structure to ease use with other
* structures, such as ::mbedtls_ecdh_context or
* ::mbedtls_ecdsa_context.
*
* \param grp The ECP group the private key should belong to.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param d The integer to check. This must be initialized.
*
* \return \c 0 if the point is a valid private key.
* \return #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not a valid
* private key for the given curve.
* \return Another negative error code on other kinds of failure.
*/
int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp,
const mbedtls_mpi *d );
/**
* \brief This function generates a private key.
*
* \param grp The ECP group to generate a private key for.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param d The destination MPI (secret part). This must be initialized.
* \param f_rng The RNG function. This must not be \c NULL.
* \param p_rng The RNG parameter to be passed to \p f_rng. This may be
* \c NULL if \p f_rng doesn't need a context argument.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
* on failure.
*/
int mbedtls_ecp_gen_privkey( const mbedtls_ecp_group *grp,
mbedtls_mpi *d,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng );
/**
* \brief This function generates a keypair with a configurable base
* point.
*
* \note This function uses bare components rather than an
* ::mbedtls_ecp_keypair structure to ease use with other
* structures, such as ::mbedtls_ecdh_context or
* ::mbedtls_ecdsa_context.
*
* \param grp The ECP group to generate a key pair for.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param G The base point to use. This must be initialized
* and belong to \p grp. It replaces the default base
* point \c grp->G used by mbedtls_ecp_gen_keypair().
* \param d The destination MPI (secret part).
* This must be initialized.
* \param Q The destination point (public part).
* This must be initialized.
* \param f_rng The RNG function. This must not be \c NULL.
* \param p_rng The RNG context to be passed to \p f_rng. This may
* be \c NULL if \p f_rng doesn't need a context argument.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
* on failure.
*/
int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp,
const mbedtls_ecp_point *G,
......@@ -619,57 +1049,77 @@ int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp,
void *p_rng );
/**
* \brief Generate a 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
*
* \return 0 if successful,
* or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
*
* \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.
* \brief This function generates an ECP keypair.
*
* \note This function uses bare components rather than an
* ::mbedtls_ecp_keypair structure to ease use with other
* structures, such as ::mbedtls_ecdh_context or
* ::mbedtls_ecdsa_context.
*
* \param grp The ECP group to generate a key pair for.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param d The destination MPI (secret part).
* This must be initialized.
* \param Q The destination point (public part).
* This must be initialized.
* \param f_rng The RNG function. This must not be \c NULL.
* \param p_rng The RNG context to be passed to \p f_rng. This may
* be \c NULL if \p f_rng doesn't need a context argument.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
* on failure.
*/
int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
int 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. This must be initialized.
* \param f_rng The RNG function to use. This must not be \c NULL.
* \param p_rng The RNG context to be passed to \p f_rng. This may
* be \c NULL if \p f_rng doesn't need a context argument.
*
* \return 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 );
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng );
/**
* \brief Check a public-private key pair
*
* \param pub Keypair structure holding a public key
* \param prv Keypair structure holding a private (plus public) key
*
* \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.
* \brief This function checks that the keypair objects
* \p pub and \p prv have the same group and the
* same public point, and that the private key in
* \p prv is consistent with the public key.
*
* \param pub The keypair structure holding the public key. This
* must be initialized. If it contains a private key, that
* part is ignored.
* \param prv The keypair structure holding the full keypair.
* This must be initialized.
*
* \return \c 0 on success, meaning that the keys are valid and match.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match.
* \return An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX
* error code on calculation failure.
*/
int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv );
int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub,
const mbedtls_ecp_keypair *prv );
#if defined(MBEDTLS_SELF_TEST)
/**
* \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 );
......@@ -679,8 +1129,4 @@ int mbedtls_ecp_self_test( int verbose );
}
#endif
#else /* MBEDTLS_ECP_ALT */
#include "ecp_alt.h"
#endif /* MBEDTLS_ECP_ALT */
#endif /* ecp.h */
......@@ -61,6 +61,12 @@
#ifndef MBEDTLS_ECP_INTERNAL_H
#define MBEDTLS_ECP_INTERNAL_H
#if !defined(MBEDTLS_CONFIG_FILE)
#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#if defined(MBEDTLS_ECP_INTERNAL_ALT)
/**
......
......@@ -107,7 +107,7 @@ typedef int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output, s
/**
* \brief Entropy source state
*/
typedef struct
typedef struct mbedtls_entropy_source_state
{
mbedtls_entropy_f_source_ptr f_source; /**< The entropy source callback */
void * p_source; /**< The callback data pointer */
......@@ -120,7 +120,7 @@ mbedtls_entropy_source_state;
/**
* \brief Entropy context structure
*/
typedef struct
typedef struct mbedtls_entropy_context
{
int accumulator_started;
#if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR)
......@@ -166,7 +166,7 @@ void mbedtls_entropy_free( mbedtls_entropy_context *ctx );
* \param threshold Minimum required from source before entropy is released
* ( with mbedtls_entropy_func() ) (in bytes)
* \param strong MBEDTLS_ENTROPY_SOURCE_STRONG or
* MBEDTSL_ENTROPY_SOURCE_WEAK.
* MBEDTLS_ENTROPY_SOURCE_WEAK.
* At least one strong source needs to be added.
* Weaker sources (such as the cycle counter) can be used as
* a complement.
......
......@@ -4,7 +4,7 @@
* \brief Error to string translation
*/
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* Copyright (C) 2006-2018, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may
......@@ -24,6 +24,12 @@
#ifndef MBEDTLS_ERROR_H
#define MBEDTLS_ERROR_H
#if !defined(MBEDTLS_CONFIG_FILE)
#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#include <stddef.h>
/**
......@@ -53,7 +59,7 @@
* GCM 3 0x0012-0x0014 0x0013-0x0013
* BLOWFISH 3 0x0016-0x0018 0x0017-0x0017
* THREADING 3 0x001A-0x001E
* AES 4 0x0020-0x0022 0x0023-0x0025
* AES 5 0x0020-0x0022 0x0021-0x0025
* CAMELLIA 3 0x0024-0x0026 0x0027-0x0027
* XTEA 2 0x0028-0x0028 0x0029-0x0029
* BASE64 2 0x002A-0x002C
......@@ -62,7 +68,8 @@
* DES 2 0x0032-0x0032 0x0033-0x0033
* CTR_DBRG 4 0x0034-0x003A
* ENTROPY 3 0x003C-0x0040 0x003D-0x003F
* NET 11 0x0042-0x0052 0x0043-0x0045
* NET 13 0x0042-0x0052 0x0043-0x0049
* ARIA 4 0x0058-0x005E
* ASN1 7 0x0060-0x006C
* CMAC 1 0x007A-0x007A
* PBKDF2 1 0x007C-0x007C
......@@ -73,9 +80,13 @@
* MD4 1 0x002D-0x002D
* MD5 1 0x002F-0x002F
* RIPEMD160 1 0x0031-0x0031
* SHA1 1 0x0035-0x0035
* SHA256 1 0x0037-0x0037
* SHA512 1 0x0039-0x0039
* SHA1 1 0x0035-0x0035 0x0073-0x0073
* SHA256 1 0x0037-0x0037 0x0074-0x0074
* SHA512 1 0x0039-0x0039 0x0075-0x0075
* CHACHA20 3 0x0051-0x0055
* POLY1305 3 0x0057-0x005B
* CHACHAPOLY 2 0x0054-0x0056
* PLATFORM 1 0x0070-0x0072
*
* High-level module nr (3 bits - 0x0...-0x7...)
* Name ID Nr of Errors
......@@ -86,11 +97,12 @@
* DHM 3 11
* PK 3 15 (Started from top)
* RSA 4 11
* ECP 4 9 (Started from top)
* ECP 4 10 (Started from top)
* MD 5 5
* HKDF 5 1 (Started from top)
* CIPHER 6 8
* SSL 6 17 (Started from top)
* SSL 7 31
* SSL 6 23 (Started from top)
* SSL 7 32
*
* Module dependent error code (5 bits 0x.00.-0x.F8.)
*/
......
/**
* \file gcm.h
*
* \brief Galois/Counter Mode (GCM) for 128-bit block ciphers, as defined
* \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>
*
......@@ -31,6 +33,12 @@
#ifndef MBEDTLS_GCM_H
#define MBEDTLS_GCM_H
#if !defined(MBEDTLS_CONFIG_FILE)
#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#include "cipher.h"
#include <stdint.h>
......@@ -39,19 +47,23 @@
#define MBEDTLS_GCM_DECRYPT 0
#define MBEDTLS_ERR_GCM_AUTH_FAILED -0x0012 /**< Authenticated decryption failed. */
/* MBEDTLS_ERR_GCM_HW_ACCEL_FAILED is deprecated and should not be used. */
#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)
#define MBEDTLS_ERR_GCM_BAD_INPUT -0x0014 /**< Bad input parameters to function. */
#ifdef __cplusplus
extern "C" {
#endif
#if !defined(MBEDTLS_GCM_ALT)
/**
* \brief The GCM context structure.
*/
typedef struct {
typedef struct mbedtls_gcm_context
{
mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */
uint64_t HL[16]; /*!< Precalculated HTable low. */
uint64_t HH[16]; /*!< Precalculated HTable high. */
......@@ -66,6 +78,10 @@ typedef struct {
}
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
......@@ -75,7 +91,7 @@ mbedtls_gcm_context;
* cipher, nor set the key. For this purpose, use
* mbedtls_gcm_setkey().
*
* \param ctx The GCM context to initialize.
* \param ctx The GCM context to initialize. This must not be \c NULL.
*/
void mbedtls_gcm_init( mbedtls_gcm_context *ctx );
......@@ -83,15 +99,17 @@ void mbedtls_gcm_init( mbedtls_gcm_context *ctx );
* \brief This function associates a GCM context with a
* cipher algorithm and a key.
*
* \param ctx The GCM context to initialize.
* \param ctx The GCM context. This must be initialized.
* \param cipher The 128-bit block cipher to use.
* \param key The encryption key.
* \param key The encryption key. This must be a readable buffer of at
* least \p keybits bits.
* \param keybits The key size in bits. Valid options are:
* <ul><li>128 bits</li>
* <li>192 bits</li>
* <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,17 +119,18 @@ int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
/**
* \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.
*
* \warning When this function performs a decryption, it outputs the
* authentication tag and does not verify that the data is
* authentic. You should use this function to perform encryption
* only. For decryption, use mbedtls_gcm_auth_decrypt() instead.
*
* \param ctx The GCM context to use for encryption or decryption.
* \param ctx The GCM context to use for encryption or decryption. This
* must be initialized.
* \param mode The operation to perform:
* - #MBEDTLS_GCM_ENCRYPT to perform authenticated encryption.
* The ciphertext is written to \p output and the
......@@ -125,22 +144,28 @@ int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
* calling this function in decryption mode.
* \param length The length of the input data, which is equal to the length
* of the output data.
* \param iv The initialization vector.
* \param iv The initialization vector. This must be a readable buffer of
* at least \p iv_len Bytes.
* \param iv_len The length of the IV.
* \param add The buffer holding the additional data.
* \param add The buffer holding the additional data. This must be of at
* least that size in Bytes.
* \param add_len The length of the additional data.
* \param input The buffer holding the input data. Its size is \b length.
* \param output The buffer for holding the output data. It must have room
* for \b length bytes.
* \param input The buffer holding the input data. If \p length is greater
* than zero, this must be a readable buffer of at least that
* size in Bytes.
* \param output The buffer for holding the output data. If \p length is greater
* than zero, this must be a writable buffer of at least that
* size in Bytes.
* \param tag_len The length of the tag to generate.
* \param tag The buffer for holding the tag.
* \param tag The buffer for holding the tag. This must be a readable
* buffer of at least \p tag_len Bytes.
*
* \return \c 0 if the encryption or decryption was performed
* successfully. Note that in #MBEDTLS_GCM_DECRYPT mode,
* this does not indicate that the data is authentic.
* \return #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths are not valid.
* \return #MBEDTLS_ERR_GCM_HW_ACCEL_FAILED or a cipher-specific
* error code if the encryption or decryption failed.
* \return #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths or pointers are
* not valid or a cipher-specific error code if the encryption
* or decryption failed.
*/
int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
int mode,
......@@ -158,28 +183,34 @@ int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
* \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 ctx The GCM context. This must be initialized.
* \param length The length of the ciphertext to decrypt, which is also
* the length of the decrypted plaintext.
* \param iv The initialization vector.
* \param iv The initialization vector. This must be a readable buffer
* of at least \p iv_len Bytes.
* \param iv_len The length of the IV.
* \param add The buffer holding the additional data.
* \param add The buffer holding the additional data. This must be of at
* least that size in Bytes.
* \param add_len The length of the additional data.
* \param tag The buffer holding the tag to verify.
* \param tag The buffer holding the tag to verify. This must be a
* readable buffer of at least \p tag_len Bytes.
* \param tag_len The length of the tag to verify.
* \param input The buffer holding the ciphertext. Its size is \b length.
* \param output The buffer for holding the decrypted plaintext. It must
* have room for \b length bytes.
* \param input The buffer holding the ciphertext. If \p length is greater
* than zero, this must be a readable buffer of at least that
* size.
* \param output The buffer for holding the decrypted plaintext. If \p length
* is greater than zero, this must be a writable buffer of at
* least that size.
*
* \return \c 0 if successful and authenticated.
* \return #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match.
* \return #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths are not valid.
* \return #MBEDTLS_ERR_GCM_HW_ACCEL_FAILED or a cipher-specific
* error code if the decryption failed.
* \return #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths or pointers are
* not valid or a cipher-specific error code if the decryption
* failed.
*/
int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
size_t length,
......@@ -196,13 +227,16 @@ int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
* \brief This function starts a GCM encryption or decryption
* operation.
*
* \param ctx The GCM context.
* \param ctx The GCM context. This must be initialized.
* \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or
* #MBEDTLS_GCM_DECRYPT.
* \param iv The initialization vector.
* \param iv The initialization vector. This must be a readable buffer of
* at least \p iv_len Bytes.
* \param iv_len The length of the IV.
* \param add The buffer holding the additional data, or NULL if \p add_len is 0.
* \param add_len The length of the additional data. If 0, \p add is NULL.
* \param add The buffer holding the additional data, or \c NULL
* if \p add_len is \c 0.
* \param add_len The length of the additional data. If \c 0,
* \p add may be \c NULL.
*
* \return \c 0 on success.
*/
......@@ -221,16 +255,22 @@ int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
* 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 input The buffer holding the input data.
* \param output The buffer for holding the output data.
* \param ctx The GCM context. This must be initialized.
* \param length The length of the input data. This must be a multiple of
* 16 except in the last call before mbedtls_gcm_finish().
* \param input The buffer holding the input data. If \p length is greater
* than zero, this must be a readable buffer of at least that
* size in Bytes.
* \param output The buffer for holding the output data. If \p length is
* greater than zero, this must be a writable buffer of at
* least that size in Bytes.
*
* \return \c 0 on success, 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,
......@@ -244,11 +284,14 @@ int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
* It wraps up the GCM stream, and generates the
* tag. The tag can have a maximum length of 16 Bytes.
*
* \param ctx The GCM context.
* \param tag The buffer for holding the tag.
* \param tag_len The length of the tag to generate. Must be at least four.
* \param ctx The GCM context. This must be initialized.
* \param tag The buffer for holding the tag. This must be a readable
* buffer of at least \p tag_len Bytes.
* \param tag_len The length of the tag to generate. This must be at least
* four.
*
* \return \c 0 on success, 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,
......@@ -258,29 +301,23 @@ int mbedtls_gcm_finish( mbedtls_gcm_context *ctx,
* \brief This function clears a GCM context and the underlying
* cipher sub-context.
*
* \param ctx The GCM context to clear.
* \param ctx The GCM context to clear. If this is \c NULL, the call has
* no effect. Otherwise, this must be initialized.
*/
void mbedtls_gcm_free( mbedtls_gcm_context *ctx );
#ifdef __cplusplus
}
#endif
#else /* !MBEDTLS_GCM_ALT */
#include "gcm_alt.h"
#endif /* !MBEDTLS_GCM_ALT */
#ifdef __cplusplus
extern "C" {
#endif
#if defined(MBEDTLS_SELF_TEST)
/**
* \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 );
#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus
}
#endif
......
......@@ -24,6 +24,12 @@
#ifndef MBEDTLS_HAVEGE_H
#define MBEDTLS_HAVEGE_H
#if !defined(MBEDTLS_CONFIG_FILE)
#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#include <stddef.h>
#define MBEDTLS_HAVEGE_COLLECT_SIZE 1024
......@@ -35,7 +41,7 @@ extern "C" {
/**
* \brief HAVEGE state structure
*/
typedef struct
typedef struct mbedtls_havege_state
{
int PT1, PT2, offset[2];
int pool[MBEDTLS_HAVEGE_COLLECT_SIZE];
......
/**
* \file hkdf.h
*
* \brief This file contains the HKDF interface.
*
* The HMAC-based Extract-and-Expand Key Derivation Function (HKDF) is
* specified by RFC 5869.
*/
/*
* Copyright (C) 2016-2019, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may
* not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* This file is part of mbed TLS (https://tls.mbed.org)
*/
#ifndef MBEDTLS_HKDF_H
#define MBEDTLS_HKDF_H
#if !defined(MBEDTLS_CONFIG_FILE)
#include "config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#include "md.h"
/**
* \name HKDF Error codes
* \{
*/
#define MBEDTLS_ERR_HKDF_BAD_INPUT_DATA -0x5F80 /**< Bad input parameters to function. */
/* \} name */
#ifdef __cplusplus
extern "C" {
#endif
/**
* \brief This is the HMAC-based Extract-and-Expand Key Derivation Function
* (HKDF).
*
* \param md A hash function; md.size denotes the length of the hash
* function output in bytes.
* \param salt An optional salt value (a non-secret random value);
* if the salt is not provided, a string of all zeros of
* md.size length is used as the salt.
* \param salt_len The length in bytes of the optional \p salt.
* \param ikm The input keying material.
* \param ikm_len The length in bytes of \p ikm.
* \param info An optional context and application specific information
* string. This can be a zero-length string.
* \param info_len The length of \p info in bytes.
* \param okm The output keying material of \p okm_len bytes.
* \param okm_len The length of the output keying material in bytes. This
* must be less than or equal to 255 * md.size bytes.
*
* \return 0 on success.
* \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
* \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
* MD layer.
*/
int mbedtls_hkdf( const mbedtls_md_info_t *md, const unsigned char *salt,
size_t salt_len, const unsigned char *ikm, size_t ikm_len,
const unsigned char *info, size_t info_len,
unsigned char *okm, size_t okm_len );
/**
* \brief Take the input keying material \p ikm and extract from it a
* fixed-length pseudorandom key \p prk.
*
* \warning This function should only be used if the security of it has been
* studied and established in that particular context (eg. TLS 1.3
* key schedule). For standard HKDF security guarantees use
* \c mbedtls_hkdf instead.
*
* \param md A hash function; md.size denotes the length of the
* hash function output in bytes.
* \param salt An optional salt value (a non-secret random value);
* if the salt is not provided, a string of all zeros
* of md.size length is used as the salt.
* \param salt_len The length in bytes of the optional \p salt.
* \param ikm The input keying material.
* \param ikm_len The length in bytes of \p ikm.
* \param[out] prk A pseudorandom key of at least md.size bytes.
*
* \return 0 on success.
* \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
* \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
* MD layer.
*/
int mbedtls_hkdf_extract( const mbedtls_md_info_t *md,
const unsigned char *salt, size_t salt_len,
const unsigned char *ikm, size_t ikm_len,
unsigned char *prk );
/**
* \brief Expand the supplied \p prk into several additional pseudorandom
* keys, which is the output of the HKDF.
*
* \warning This function should only be used if the security of it has been
* studied and established in that particular context (eg. TLS 1.3
* key schedule). For standard HKDF security guarantees use
* \c mbedtls_hkdf instead.
*
* \param md A hash function; md.size denotes the length of the hash
* function output in bytes.
* \param prk A pseudorandom key of at least md.size bytes. \p prk is
* usually the output from the HKDF extract step.
* \param prk_len The length in bytes of \p prk.
* \param info An optional context and application specific information
* string. This can be a zero-length string.
* \param info_len The length of \p info in bytes.
* \param okm The output keying material of \p okm_len bytes.
* \param okm_len The length of the output keying material in bytes. This
* must be less than or equal to 255 * md.size bytes.
*
* \return 0 on success.
* \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
* \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
* MD layer.
*/
int mbedtls_hkdf_expand( const mbedtls_md_info_t *md, const unsigned char *prk,
size_t prk_len, const unsigned char *info,
size_t info_len, unsigned char *okm, size_t okm_len );
#ifdef __cplusplus
}
#endif
#endif /* hkdf.h */
/**
* \file hmac_drbg.h
*
* \brief HMAC_DRBG (NIST SP 800-90A)
* \brief The HMAC_DRBG pseudorandom generator.
*
* This module implements the HMAC_DRBG pseudorandom generator described
* in <em>NIST SP 800-90A: Recommendation for Random Number Generation Using
* Deterministic Random Bit Generators</em>.
*/
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* Copyright (C) 2006-2019, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may
......@@ -80,9 +84,9 @@ extern "C" {
/**
* HMAC_DRBG context.
*/
typedef struct
typedef struct mbedtls_hmac_drbg_context
{
/* Working state: the key K is not stored explicitely,
/* Working state: the key K is not stored explicitly,
* but is implied by the HMAC context */
mbedtls_md_context_t md_ctx; /*!< HMAC context (inc. K) */
unsigned char V[MBEDTLS_MD_MAX_SIZE]; /*!< V in the spec */
......@@ -104,38 +108,72 @@ typedef struct
} mbedtls_hmac_drbg_context;
/**
* \brief HMAC_DRBG context initialization
* Makes the context ready for mbedtls_hmac_drbg_seed(),
* mbedtls_hmac_drbg_seed_buf() or
* mbedtls_hmac_drbg_free().
* \brief HMAC_DRBG context initialization.
*
* This function makes the context ready for mbedtls_hmac_drbg_seed(),
* mbedtls_hmac_drbg_seed_buf() or mbedtls_hmac_drbg_free().
*
* \param ctx HMAC_DRBG context to be initialized
* \param ctx HMAC_DRBG context to be initialized.
*/
void mbedtls_hmac_drbg_init( mbedtls_hmac_drbg_context *ctx );
/**
* \brief HMAC_DRBG initial seeding
* Seed and setup entropy source for future reseeds.
*
* \param ctx HMAC_DRBG context to be seeded
* \param md_info MD algorithm to use for HMAC_DRBG
* \param f_entropy Entropy callback (p_entropy, buffer to fill, buffer
* length)
* \param p_entropy Entropy context
* \param custom Personalization data (Device specific identifiers)
* (Can be NULL)
* \param len Length of personalization data
*
* \note The "security strength" as defined by NIST is set to:
* 128 bits if md_alg is SHA-1,
* 192 bits if md_alg is SHA-224,
* 256 bits if md_alg is SHA-256 or higher.
* Note that SHA-256 is just as efficient as SHA-224.
* \brief HMAC_DRBG initial seeding.
*
* Set the initial seed and set up the entropy source for future reseeds.
*
* A typical choice for the \p f_entropy and \p p_entropy parameters is
* to use the entropy module:
* - \p f_entropy is mbedtls_entropy_func();
* - \p p_entropy is an instance of ::mbedtls_entropy_context initialized
* with mbedtls_entropy_init() (which registers the platform's default
* entropy sources).
*
* \return 0 if successful, or
* MBEDTLS_ERR_MD_BAD_INPUT_DATA, or
* MBEDTLS_ERR_MD_ALLOC_FAILED, or
* MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED.
* You can provide a personalization string in addition to the
* entropy source, to make this instantiation as unique as possible.
*
* \note By default, the security strength as defined by NIST is:
* - 128 bits if \p md_info is SHA-1;
* - 192 bits if \p md_info is SHA-224;
* - 256 bits if \p md_info is SHA-256, SHA-384 or SHA-512.
* Note that SHA-256 is just as efficient as SHA-224.
* The security strength can be reduced if a smaller
* entropy length is set with
* mbedtls_hmac_drbg_set_entropy_len().
*
* \note The default entropy length is the security strength
* (converted from bits to bytes). You can override
* it by calling mbedtls_hmac_drbg_set_entropy_len().
*
* \note During the initial seeding, this function calls
* the entropy source to obtain a nonce
* whose length is half the entropy length.
*
* \param ctx HMAC_DRBG context to be seeded.
* \param md_info MD algorithm to use for HMAC_DRBG.
* \param f_entropy The entropy callback, taking as arguments the
* \p p_entropy context, the buffer to fill, and the
* length of the buffer.
* \p f_entropy is always called with a length that is
* less than or equal to the entropy length.
* \param p_entropy The entropy context to pass to \p f_entropy.
* \param custom The personalization string.
* This can be \c NULL, in which case the personalization
* string is empty regardless of the value of \p len.
* \param len The length of the personalization string.
* This must be at most #MBEDTLS_HMAC_DRBG_MAX_INPUT
* and also at most
* #MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT - \p entropy_len * 3 / 2
* where \p entropy_len is the entropy length
* described above.
*
* \return \c 0 if successful.
* \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info is
* invalid.
* \return #MBEDTLS_ERR_MD_ALLOC_FAILED if there was not enough
* memory to allocate context data.
* \return #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
* if the call to \p f_entropy failed.
*/
int mbedtls_hmac_drbg_seed( mbedtls_hmac_drbg_context *ctx,
const mbedtls_md_info_t * md_info,
......@@ -146,115 +184,131 @@ int mbedtls_hmac_drbg_seed( mbedtls_hmac_drbg_context *ctx,
/**
* \brief Initilisation of simpified HMAC_DRBG (never reseeds).
* (For use with deterministic ECDSA.)
*
* \param ctx HMAC_DRBG context to be initialised
* \param md_info MD algorithm to use for HMAC_DRBG
* \param data Concatenation of entropy string and additional data
* \param data_len Length of data in bytes
* This function is meant for use in algorithms that need a pseudorandom
* input such as deterministic ECDSA.
*
* \param ctx HMAC_DRBG context to be initialised.
* \param md_info MD algorithm to use for HMAC_DRBG.
* \param data Concatenation of the initial entropy string and
* the additional data.
* \param data_len Length of \p data in bytes.
*
* \return 0 if successful, or
* MBEDTLS_ERR_MD_BAD_INPUT_DATA, or
* MBEDTLS_ERR_MD_ALLOC_FAILED.
* \return \c 0 if successful. or
* \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info is
* invalid.
* \return #MBEDTLS_ERR_MD_ALLOC_FAILED if there was not enough
* memory to allocate context data.
*/
int mbedtls_hmac_drbg_seed_buf( mbedtls_hmac_drbg_context *ctx,
const mbedtls_md_info_t * md_info,
const unsigned char *data, size_t data_len );
/**
* \brief Enable / disable prediction resistance (Default: Off)
* \brief This function turns prediction resistance on or off.
* The default value is off.
*
* Note: If enabled, entropy is used for ctx->entropy_len before each call!
* Only use this if you have ample supply of good entropy!
* \note If enabled, entropy is gathered at the beginning of
* every call to mbedtls_hmac_drbg_random_with_add()
* or mbedtls_hmac_drbg_random().
* Only use this if your entropy source has sufficient
* throughput.
*
* \param ctx HMAC_DRBG context
* \param resistance MBEDTLS_HMAC_DRBG_PR_ON or MBEDTLS_HMAC_DRBG_PR_OFF
* \param ctx The HMAC_DRBG context.
* \param resistance #MBEDTLS_HMAC_DRBG_PR_ON or #MBEDTLS_HMAC_DRBG_PR_OFF.
*/
void mbedtls_hmac_drbg_set_prediction_resistance( mbedtls_hmac_drbg_context *ctx,
int resistance );
/**
* \brief Set the amount of entropy grabbed on each reseed
* (Default: given by the security strength, which
* depends on the hash used, see \c mbedtls_hmac_drbg_init() )
* \brief This function sets the amount of entropy grabbed on each
* seed or reseed.
*
* \param ctx HMAC_DRBG context
* \param len Amount of entropy to grab, in bytes
* See the documentation of mbedtls_hmac_drbg_seed() for the default value.
*
* \param ctx The HMAC_DRBG context.
* \param len The amount of entropy to grab, in bytes.
*/
void mbedtls_hmac_drbg_set_entropy_len( mbedtls_hmac_drbg_context *ctx,
size_t len );
/**
* \brief Set the reseed interval
* (Default: MBEDTLS_HMAC_DRBG_RESEED_INTERVAL)
* \brief Set the reseed interval.
*
* The reseed interval is the number of calls to mbedtls_hmac_drbg_random()
* or mbedtls_hmac_drbg_random_with_add() after which the entropy function
* is called again.
*
* \param ctx HMAC_DRBG context
* \param interval Reseed interval
* The default value is #MBEDTLS_HMAC_DRBG_RESEED_INTERVAL.
*
* \param ctx The HMAC_DRBG context.
* \param interval The reseed interval.
*/
void mbedtls_hmac_drbg_set_reseed_interval( mbedtls_hmac_drbg_context *ctx,
int interval );
/**
* \brief HMAC_DRBG update state
* \brief This function updates the state of the HMAC_DRBG context.
*
* \param ctx HMAC_DRBG context
* \param additional Additional data to update state with, or NULL
* \param add_len Length of additional data, or 0
* \param ctx The HMAC_DRBG context.
* \param additional The data to update the state with.
* If this is \c NULL, there is no additional data.
* \param add_len Length of \p additional in bytes.
* Unused if \p additional is \c NULL.
*
* \return \c 0 on success, or an error from the underlying
* hash calculation.
*
* \note Additional data is optional, pass NULL and 0 as second
* third argument if no additional data is being used.
*/
int mbedtls_hmac_drbg_update_ret( mbedtls_hmac_drbg_context *ctx,
const unsigned char *additional, size_t add_len );
/**
* \brief HMAC_DRBG update state
*
* \warning This function cannot report errors. You should use
* mbedtls_hmac_drbg_update_ret() instead.
*
* \param ctx HMAC_DRBG context
* \param additional Additional data to update state with, or NULL
* \param add_len Length of additional data, or 0
*
* \note Additional data is optional, pass NULL and 0 as second
* third argument if no additional data is being used.
*/
void mbedtls_hmac_drbg_update( mbedtls_hmac_drbg_context *ctx,
const unsigned char *additional,
size_t add_len );
/**
* \brief HMAC_DRBG reseeding (extracts data from entropy source)
*
* \param ctx HMAC_DRBG context
* \param additional Additional data to add to state (Can be NULL)
* \param len Length of additional data
*
* \return 0 if successful, or
* MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
* \brief This function reseeds the HMAC_DRBG context, that is
* extracts data from the entropy source.
*
* \param ctx The HMAC_DRBG context.
* \param additional Additional data to add to the state.
* If this is \c NULL, there is no additional data
* and \p len should be \c 0.
* \param len The length of the additional data.
* This must be at most #MBEDTLS_HMAC_DRBG_MAX_INPUT
* and also at most
* #MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT - \p entropy_len
* where \p entropy_len is the entropy length
* (see mbedtls_hmac_drbg_set_entropy_len()).
*
* \return \c 0 if successful.
* \return #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
* if a call to the entropy function failed.
*/
int mbedtls_hmac_drbg_reseed( mbedtls_hmac_drbg_context *ctx,
const unsigned char *additional, size_t len );
/**
* \brief HMAC_DRBG generate random with additional update input
*
* Note: Automatically reseeds if reseed_counter is reached or PR is enabled.
*
* \param p_rng HMAC_DRBG context
* \param output Buffer to fill
* \param output_len Length of the buffer
* \param additional Additional data to update with (can be NULL)
* \param add_len Length of additional data (can be 0)
*
* \return 0 if successful, or
* MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED, or
* MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG, or
* MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG.
* \brief This function updates an HMAC_DRBG instance with additional
* data and uses it to generate random data.
*
* This function automatically reseeds if the reseed counter is exceeded
* or prediction resistance is enabled.
*
* \param p_rng The HMAC_DRBG context. This must be a pointer to a
* #mbedtls_hmac_drbg_context structure.
* \param output The buffer to fill.
* \param output_len The length of the buffer in bytes.
* This must be at most #MBEDTLS_HMAC_DRBG_MAX_REQUEST.
* \param additional Additional data to update with.
* If this is \c NULL, there is no additional data
* and \p add_len should be \c 0.
* \param add_len The length of the additional data.
* This must be at most #MBEDTLS_HMAC_DRBG_MAX_INPUT.
*
* \return \c 0 if successful.
* \return #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
* if a call to the entropy source failed.
* \return #MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG if
* \p output_len > #MBEDTLS_HMAC_DRBG_MAX_REQUEST.
* \return #MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG if
* \p add_len > #MBEDTLS_HMAC_DRBG_MAX_INPUT.
*/
int mbedtls_hmac_drbg_random_with_add( void *p_rng,
unsigned char *output, size_t output_len,
......@@ -262,49 +316,83 @@ int mbedtls_hmac_drbg_random_with_add( void *p_rng,
size_t add_len );
/**
* \brief HMAC_DRBG generate random
*
* Note: Automatically reseeds if reseed_counter is reached or PR is enabled.
*
* \param p_rng HMAC_DRBG context
* \param output Buffer to fill
* \param out_len Length of the buffer
*
* \return 0 if successful, or
* MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED, or
* MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG
* \brief This function uses HMAC_DRBG to generate random data.
*
* This function automatically reseeds if the reseed counter is exceeded
* or prediction resistance is enabled.
*
* \param p_rng The HMAC_DRBG context. This must be a pointer to a
* #mbedtls_hmac_drbg_context structure.
* \param output The buffer to fill.
* \param out_len The length of the buffer in bytes.
* This must be at most #MBEDTLS_HMAC_DRBG_MAX_REQUEST.
*
* \return \c 0 if successful.
* \return #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
* if a call to the entropy source failed.
* \return #MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG if
* \p out_len > #MBEDTLS_HMAC_DRBG_MAX_REQUEST.
*/
int mbedtls_hmac_drbg_random( void *p_rng, unsigned char *output, size_t out_len );
/**
* \brief Free an HMAC_DRBG context
*
* \param ctx HMAC_DRBG context to free.
* \param ctx The HMAC_DRBG context to free.
*/
void mbedtls_hmac_drbg_free( mbedtls_hmac_drbg_context *ctx );
#if defined(MBEDTLS_FS_IO)
#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
#if defined(MBEDTLS_DEPRECATED_WARNING)
#define MBEDTLS_DEPRECATED __attribute__((deprecated))
#else
#define MBEDTLS_DEPRECATED
#endif
/**
* \brief Write a seed file
* \brief This function updates the state of the HMAC_DRBG context.
*
* \param ctx HMAC_DRBG context
* \param path Name of the file
* \deprecated Superseded by mbedtls_hmac_drbg_update_ret()
* in 2.16.0.
*
* \return 0 if successful, 1 on file error, or
* MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
* \param ctx The HMAC_DRBG context.
* \param additional The data to update the state with.
* If this is \c NULL, there is no additional data.
* \param add_len Length of \p additional in bytes.
* Unused if \p additional is \c NULL.
*/
int mbedtls_hmac_drbg_write_seed_file( mbedtls_hmac_drbg_context *ctx, const char *path );
MBEDTLS_DEPRECATED void mbedtls_hmac_drbg_update(
mbedtls_hmac_drbg_context *ctx,
const unsigned char *additional, size_t add_len );
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
#if defined(MBEDTLS_FS_IO)
/**
* \brief Read and update a seed file. Seed is added to this
* instance
* \brief This function writes a seed file.
*
* \param ctx HMAC_DRBG context
* \param path Name of the file
* \param ctx The HMAC_DRBG context.
* \param path The name of the file.
*
* \return 0 if successful, 1 on file error,
* MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED or
* MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG
* \return \c 0 on success.
* \return #MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR on file error.
* \return #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED on reseed
* failure.
*/
int mbedtls_hmac_drbg_write_seed_file( mbedtls_hmac_drbg_context *ctx, const char *path );
/**
* \brief This function reads and updates a seed file. The seed
* is added to this instance.
*
* \param ctx The HMAC_DRBG context.
* \param path The name of the file.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR on file error.
* \return #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED on
* reseed failure.
* \return #MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG if the existing
* seed file is too large.
*/
int mbedtls_hmac_drbg_update_seed_file( mbedtls_hmac_drbg_context *ctx, const char *path );
#endif /* MBEDTLS_FS_IO */
......@@ -312,9 +400,10 @@ int mbedtls_hmac_drbg_update_seed_file( mbedtls_hmac_drbg_context *ctx, const ch
#if defined(MBEDTLS_SELF_TEST)
/**
* \brief Checkup routine
* \brief The HMAC_DRBG Checkup routine.
*
* \return 0 if successful, or 1 if the test failed
* \return \c 0 if successful.
* \return \c 1 if the test failed.
*/
int mbedtls_hmac_drbg_self_test( int verbose );
#endif
......
/**
* \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>
*/
......@@ -39,6 +39,8 @@
#define MBEDTLS_ERR_MD_BAD_INPUT_DATA -0x5100 /**< Bad input parameters to function. */
#define MBEDTLS_ERR_MD_ALLOC_FAILED -0x5180 /**< Failed to allocate memory. */
#define MBEDTLS_ERR_MD_FILE_IO_ERROR -0x5200 /**< Opening or reading of file failed. */
/* MBEDTLS_ERR_MD_HW_ACCEL_FAILED is deprecated and should not be used. */
#define MBEDTLS_ERR_MD_HW_ACCEL_FAILED -0x5280 /**< MD hardware accelerator failed. */
#ifdef __cplusplus
......@@ -46,7 +48,7 @@ extern "C" {
#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 +56,16 @@ extern "C" {
*
*/
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)
......@@ -80,7 +82,8 @@ typedef struct mbedtls_md_info_t mbedtls_md_info_t;
/**
* The generic message-digest context.
*/
typedef struct {
typedef struct mbedtls_md_context_t
{
/** Information about the associated message digest. */
const mbedtls_md_info_t *md_info;
......@@ -108,8 +111,8 @@ const int *mbedtls_md_list( void );
*
* \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 +122,8 @@ const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name );
*
* \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 +171,10 @@ void mbedtls_md_free( mbedtls_md_context_t *ctx );
* \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 +191,13 @@ int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_
* \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 +217,8 @@ int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_inf
* \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 +265,9 @@ const char *mbedtls_md_get_name( const mbedtls_md_info_t *md_info );
*
* \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 +283,9 @@ int mbedtls_md_starts( mbedtls_md_context_t *ctx );
* \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 +303,9 @@ int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, si
* \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 +323,9 @@ int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output );
* \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 +343,10 @@ int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, si
* \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 +366,9 @@ int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path,
* \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 +388,9 @@ int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key,
* \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 +409,9 @@ int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *inpu
* 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 +426,9 @@ int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output);
* \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 +450,9 @@ int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx );
* \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,
......
......@@ -37,16 +37,17 @@
#include <stddef.h>
/* MBEDTLS_ERR_MD2_HW_ACCEL_FAILED is deprecated and should not be used. */
#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
*
......@@ -55,7 +56,7 @@ extern "C" {
* stronger message digests instead.
*
*/
typedef struct
typedef struct mbedtls_md2_context
{
unsigned char cksum[16]; /*!< checksum of the data block */
unsigned char state[48]; /*!< intermediate digest state */
......@@ -64,6 +65,10 @@ typedef struct
}
mbedtls_md2_context;
#else /* MBEDTLS_MD2_ALT */
#include "md2_alt.h"
#endif /* MBEDTLS_MD2_ALT */
/**
* \brief Initialize MD2 context
*
......@@ -235,18 +240,6 @@ MBEDTLS_DEPRECATED void mbedtls_md2_process( mbedtls_md2_context *ctx );
#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 )
*
......@@ -290,6 +283,8 @@ MBEDTLS_DEPRECATED void mbedtls_md2( const unsigned char *input,
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
#if defined(MBEDTLS_SELF_TEST)
/**
* \brief Checkup routine
*
......@@ -302,6 +297,8 @@ MBEDTLS_DEPRECATED void mbedtls_md2( const unsigned char *input,
*/
int mbedtls_md2_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus
}
#endif
......
......@@ -38,16 +38,17 @@
#include <stddef.h>
#include <stdint.h>
/* MBEDTLS_ERR_MD4_HW_ACCEL_FAILED is deprecated and should not be used. */
#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
*
......@@ -56,7 +57,7 @@ extern "C" {
* stronger message digests instead.
*
*/
typedef struct
typedef struct mbedtls_md4_context
{
uint32_t total[2]; /*!< number of bytes processed */
uint32_t state[4]; /*!< intermediate digest state */
......@@ -64,6 +65,10 @@ typedef struct
}
mbedtls_md4_context;
#else /* MBEDTLS_MD4_ALT */
#include "md4_alt.h"
#endif /* MBEDTLS_MD4_ALT */
/**
* \brief Initialize MD4 context
*
......@@ -238,18 +243,6 @@ MBEDTLS_DEPRECATED void mbedtls_md4_process( mbedtls_md4_context *ctx,
#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 )
*
......@@ -295,6 +288,8 @@ MBEDTLS_DEPRECATED void mbedtls_md4( const unsigned char *input,
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
#if defined(MBEDTLS_SELF_TEST)
/**
* \brief Checkup routine
*
......@@ -307,6 +302,8 @@ MBEDTLS_DEPRECATED void mbedtls_md4( const unsigned char *input,
*/
int mbedtls_md4_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST */
#ifdef __cplusplus
}
#endif
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment