mirror of
https://github.com/cuberite/polarssl.git
synced 2025-11-03 20:22:59 -05:00
da19f4c79f
Summary of merge conflicts:
include/mbedtls/ecdh.h -> documentation style
include/mbedtls/ecdsa.h -> documentation style
include/mbedtls/ecp.h -> alt style, new error codes, documentation style
include/mbedtls/error.h -> new error codes
library/error.c -> new error codes (generated anyway)
library/ecp.c:
- code of an extracted function was changed
library/ssl_cli.c:
- code addition on one side near code change on the other side
(ciphersuite validation)
library/x509_crt.c -> various things
- top fo file: helper structure added near old zeroize removed
- documentation of find_parent_in()'s signature: improved on one side,
added arguments on the other side
- documentation of find_parent()'s signature: same as above
- verify_chain(): variables initialised later to give compiler an
opportunity to warn us if not initialised on a code path
- find_parent(): funcion structure completely changed, for some reason git
tried to insert a paragraph of the old structure...
- merge_flags_with_cb(): data structure changed, one line was fixed with a
cast to keep MSVC happy, this cast is already in the new version
- in verify_restratable(): adjacent independent changes (function
signature on one line, variable type on the next)
programs/ssl/ssl_client2.c:
- testing for IN_PROGRESS return code near idle() (event-driven):
don't wait for data in the the socket if ECP_IN_PROGRESS
tests/data_files/Makefile: adjacent independent additions
tests/suites/test_suite_ecdsa.data: adjacent independent additions
tests/suites/test_suite_x509parse.data: adjacent independent additions
* development: (1059 commits)
Change symlink to hardlink to avoid permission issues
Fix out-of-tree testing symlinks on Windows
Updated version number to 2.10.0 for release
Add a disabled CMAC define in the no-entropy configuration
Adapt the ARIA test cases for new ECB function
Fix file permissions for ssl.h
Add ChangeLog entry for PR#1651
Fix MicroBlaze register typo.
Fix typo in doc and copy missing warning
Fix edit mistake in cipher_wrap.c
Update CTR doc for the 64-bit block cipher
Update CTR doc for other 128-bit block ciphers
Slightly tune ARIA CTR documentation
Remove double declaration of mbedtls_ssl_list_ciphersuites
Update CTR documentation
Use zeroize function from new platform_util
Move to new header style for ALT implementations
Add ifdef for selftest in header file
Fix typo in comments
Use more appropriate type for local variable
...
316 lines
11 KiB
C
316 lines
11 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"
|
||
|
||
#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;
|
||
|
||
/**
|
||
*
|
||
* \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_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_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 An \c MBEDTLS_ERR_ECP_XXX or
|
||
* \c MBEDTLS_MPI_XXX error code on failure.
|
||
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
|
||
* operations was reached: see \c mbedtls_ecp_set_max_ops().
|
||
*/
|
||
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 An \c MBEDTLS_ERR_ECP_XXX or
|
||
* \c MBEDTLS_MPI_XXX error code on failure.
|
||
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
|
||
* operations was reached: see \c mbedtls_ecp_set_max_ops().
|
||
*/
|
||
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 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 first function used by a TLS server for ECDHE
|
||
* ciphersuites.
|
||
*
|
||
* \note This function assumes that the ECP group (grp) of the
|
||
* \p ctx context has already been properly set,
|
||
* for example, using mbedtls_ecp_group_load().
|
||
*
|
||
* \see ecp.h
|
||
*
|
||
* \param ctx The ECDH context.
|
||
* \param olen The number of characters written.
|
||
* \param buf The destination buffer.
|
||
* \param blen The length of the destination buffer.
|
||
* \param f_rng The RNG function.
|
||
* \param p_rng The RNG context.
|
||
*
|
||
* \return \c 0 on success.
|
||
* \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
|
||
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
|
||
* operations was reached: see \c mbedtls_ecp_set_max_ops().
|
||
*/
|
||
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 An \c MBEDTLS_ERR_ECP_XXX error code on failure.
|
||
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
|
||
* operations was reached: see \c mbedtls_ecp_set_max_ops().
|
||
*
|
||
*/
|
||
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 An \c MBEDTLS_ERR_ECP_XXX error code on failure.
|
||
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
|
||
* operations was reached: see \c mbedtls_ecp_set_max_ops().
|
||
*/
|
||
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 second function used by a TLS server for ECDH(E)
|
||
* ciphersuites.
|
||
*
|
||
* \see ecp.h
|
||
*
|
||
* \param ctx The ECDH context.
|
||
* \param buf The start of the input buffer.
|
||
* \param blen The length of the input buffer.
|
||
*
|
||
* \return \c 0 on success.
|
||
* \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 An \c MBEDTLS_ERR_ECP_XXX error code on failure.
|
||
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
|
||
* operations was reached: see \c mbedtls_ecp_set_max_ops().
|
||
*/
|
||
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 */
|