mirror of
https://github.com/Mbed-TLS/mbedtls.git
synced 2025-03-31 10:20:45 +00:00
c9c32f3f63
We want to support alternative software implementations and we extend the ECDH context to enable this. The actual functional change that makes use of the new context is out of scope for this commit. Changing the context breaks the API and therefore it has to be excluded from the default configuration by a compile time flag. We add the compile time flag to the module header instead of `config.h`, because this is not a standalone feature, it only enables adding new implementations in the future. The new context features a union of the individual implementations and a selector that chooses the implementation in use. An alternative is to use an opaque context and function pointers, like for example the PK module does it, but it is more dangerous, error prone and tedious to implement. We leave the group ID and the point format at the top level of the structure, because they are very simple and adding an abstraction layer around them away does not come with any obvious benefit. Other alternatives considered: - Using the module level replacement mechanism in the ECP module. This would have made the use of the replacement feature more difficult and the benefit limited. - Replacing our Montgomery implementations with a new one directly. This would have prevented using Montgomery curves across implementations. (For example use implementation A for Curve448 and implementation B for Curve22519.) Also it would have been inflexible and limited to Montgomery curves. - Encoding the implementation selector and the alternative context in `mbedtls_ecp_point` somehow and rewriting `mbedtls_ecp_mul()` to dispatch between implementations. This would have been a dangerous and ugly hack, and very likely to break legacy applications. - Same as above just with hardcoding the selector and using a compile time option to make the selection. Rejected for the same reasons as above. - Using the PK module to provide to provide an entry point for alternative implementations. Like most of the above options this wouldn't have come with a new compile time option, but conceptually would have been very out of place and would have meant much more work to complete the abstraction around the context. In retrospect: - We could have used the group ID as the selector, but this would have made the code less flexible and only marginally simpler. On the other hand it would have allowed to get rid of the compile time option if a tight integration of the alternative is possible. (It does not seem possible at this point.) - We could have used the same approach we do in this commit to the `mbedtls_ecp_point` structure. Completing the abstraction around this structure would have been a much bigger and much riskier code change with increase in memory footprint, potential decrease in performance and no immediate benefit.
394 lines
14 KiB
C
394 lines
14 KiB
C
/**
|
||
* \file ecdh.h
|
||
*
|
||
* \brief This file contains ECDH definitions and functions.
|
||
*
|
||
* The Elliptic Curve Diffie-Hellman (ECDH) protocol is an anonymous
|
||
* key agreement protocol allowing two parties to establish a shared
|
||
* secret over an insecure channel. Each party must have an
|
||
* elliptic-curve public–private key pair.
|
||
*
|
||
* For more information, see <em>NIST SP 800-56A Rev. 2: Recommendation for
|
||
* Pair-Wise Key Establishment Schemes Using Discrete Logarithm
|
||
* Cryptography</em>.
|
||
*/
|
||
/*
|
||
* 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
|
||
* 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_ECDH_H
|
||
#define MBEDTLS_ECDH_H
|
||
|
||
#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.
|
||
*/
|
||
typedef enum
|
||
{
|
||
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 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. */
|
||
mbedtls_ecp_point Qp; /*!< The value of the public key of the peer. */
|
||
mbedtls_mpi z; /*!< The shared secret. */
|
||
int point_format; /*!< The format of point export in TLS messages. */
|
||
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;
|
||
|
||
/**
|
||
* \brief This function generates an ECDH keypair on an elliptic
|
||
* curve.
|
||
*
|
||
* This function performs the first of two core computations
|
||
* implemented during the ECDH key exchange. The second core
|
||
* computation is performed by mbedtls_ecdh_compute_shared().
|
||
*
|
||
* \see ecp.h
|
||
*
|
||
* \param grp The ECP group.
|
||
* \param d The destination MPI (private key).
|
||
* \param Q The destination point (public key).
|
||
* \param f_rng The RNG function.
|
||
* \param p_rng The RNG context.
|
||
*
|
||
* \return \c 0 on success.
|
||
* \return Another \c MBEDTLS_ERR_ECP_XXX or
|
||
* \c MBEDTLS_MPI_XXX error code on failure.
|
||
*/
|
||
int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
|
||
int (*f_rng)(void *, unsigned char *, size_t),
|
||
void *p_rng );
|
||
|
||
/**
|
||
* \brief This function computes the shared secret.
|
||
*
|
||
* This function performs the second of two core computations
|
||
* implemented during the ECDH key exchange. The first core
|
||
* computation is performed by mbedtls_ecdh_gen_public().
|
||
*
|
||
* \see ecp.h
|
||
*
|
||
* \note If \p f_rng is not NULL, it is used to implement
|
||
* countermeasures against side-channel attacks.
|
||
* For more information, see mbedtls_ecp_mul().
|
||
*
|
||
* \param grp The ECP group.
|
||
* \param z The destination MPI (shared secret).
|
||
* \param Q The public key from another party.
|
||
* \param d Our secret exponent (private key).
|
||
* \param f_rng The RNG function.
|
||
* \param p_rng The RNG context.
|
||
*
|
||
* \return \c 0 on success.
|
||
* \return Another \c MBEDTLS_ERR_ECP_XXX or
|
||
* \c MBEDTLS_MPI_XXX error code on failure.
|
||
*/
|
||
int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
|
||
const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
|
||
int (*f_rng)(void *, unsigned char *, size_t),
|
||
void *p_rng );
|
||
|
||
/**
|
||
* \brief This function initializes an ECDH context.
|
||
*
|
||
* \param ctx The ECDH context to initialize.
|
||
*/
|
||
void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
|
||
|
||
/**
|
||
* \brief This function sets up the ECDH context with the information
|
||
* given.
|
||
*
|
||
* 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 to set up.
|
||
* \param grp_id The group id of the group to set up the context for.
|
||
*
|
||
* \return \c 0 on success.
|
||
*/
|
||
int mbedtls_ecdh_setup( mbedtls_ecdh_context *ctx, mbedtls_ecp_group_id grp_id );
|
||
|
||
/**
|
||
* \brief This function frees a context.
|
||
*
|
||
* \param ctx The context to free.
|
||
*/
|
||
void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
|
||
|
||
/**
|
||
* \brief This function generates a public key and a TLS
|
||
* ServerKeyExchange payload.
|
||
*
|
||
* This is the second function used by a TLS server for ECDHE
|
||
* ciphersuites. (It is called after mbedtls_ecdh_setup().)
|
||
*
|
||
* \note This function assumes that the ECP group (grp) of the
|
||
* \p ctx context has already been properly set,
|
||
* for example, using mbedtls_ecp_group_load().
|
||
*
|
||
* \see ecp.h
|
||
*
|
||
* \param ctx The ECDH context.
|
||
* \param olen The number of characters written.
|
||
* \param buf The destination buffer.
|
||
* \param blen The length of the destination buffer.
|
||
* \param f_rng The RNG function.
|
||
* \param p_rng The RNG 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 error code on failure.
|
||
*/
|
||
int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
|
||
unsigned char *buf, size_t blen,
|
||
int (*f_rng)(void *, unsigned char *, size_t),
|
||
void *p_rng );
|
||
|
||
/**
|
||
* \brief This function parses and processes a TLS ServerKeyExhange
|
||
* payload.
|
||
*
|
||
* This is the first function used by a TLS client for ECDHE
|
||
* ciphersuites.
|
||
*
|
||
* \see ecp.h
|
||
*
|
||
* \param ctx The ECDH context.
|
||
* \param buf The pointer to the start of the input buffer.
|
||
* \param end The address for one Byte past the end of the buffer.
|
||
*
|
||
* \return \c 0 on success.
|
||
* \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
|
||
*
|
||
*/
|
||
int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
|
||
const unsigned char **buf, const unsigned char *end );
|
||
|
||
/**
|
||
* \brief This function sets up an ECDH context from an EC key.
|
||
*
|
||
* It is used by clients and servers in place of the
|
||
* ServerKeyEchange for static ECDH, and imports ECDH
|
||
* parameters from the EC key information of a certificate.
|
||
*
|
||
* \see ecp.h
|
||
*
|
||
* \param ctx The ECDH context to set up.
|
||
* \param key The EC key to use.
|
||
* \param side Defines the source of the key: 1: Our key, or
|
||
* 0: The key of the peer.
|
||
*
|
||
* \return \c 0 on success.
|
||
* \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
|
||
*
|
||
*/
|
||
int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
|
||
mbedtls_ecdh_side side );
|
||
|
||
/**
|
||
* \brief This function generates a public key and a TLS
|
||
* ClientKeyExchange payload.
|
||
*
|
||
* This is the second function used by a TLS client for ECDH(E)
|
||
* ciphersuites.
|
||
*
|
||
* \see ecp.h
|
||
*
|
||
* \param ctx The ECDH context.
|
||
* \param olen The number of Bytes written.
|
||
* \param buf The destination buffer.
|
||
* \param blen The size of the destination buffer.
|
||
* \param f_rng The RNG function.
|
||
* \param p_rng The RNG context.
|
||
*
|
||
* \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,
|
||
int (*f_rng)(void *, unsigned char *, size_t),
|
||
void *p_rng );
|
||
|
||
/**
|
||
* \brief This function parses and processes a TLS ClientKeyExchange
|
||
* payload.
|
||
*
|
||
* This is the third function used by a TLS server for ECDH(E)
|
||
* ciphersuites. (It is called after mbedtls_ecdh_setup() and
|
||
* mbedtls_ecdh_make_params().)
|
||
*
|
||
* \see ecp.h
|
||
*
|
||
* \param ctx The ECDH context.
|
||
* \param buf The start of the input buffer.
|
||
* \param blen The length of the input buffer.
|
||
*
|
||
* \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 );
|
||
|
||
/**
|
||
* \brief This function derives and exports the shared secret.
|
||
*
|
||
* This is the last function used by both TLS client
|
||
* and servers.
|
||
*
|
||
* \note If \p f_rng is not NULL, it is used to implement
|
||
* countermeasures against side-channel attacks.
|
||
* For more information, see mbedtls_ecp_mul().
|
||
*
|
||
* \see ecp.h
|
||
*
|
||
* \param ctx The ECDH context.
|
||
* \param olen The number of Bytes written.
|
||
* \param buf The destination buffer.
|
||
* \param blen The length of the destination buffer.
|
||
* \param f_rng The RNG function.
|
||
* \param p_rng The RNG 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 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.
|
||
*/
|
||
void mbedtls_ecdh_enable_restart( mbedtls_ecdh_context *ctx );
|
||
#endif /* MBEDTLS_ECP_RESTARTABLE */
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* ecdh.h */
|