Eric Tsai / mbedtls

Modified mbed TLS headers for AES functionality only to reduce build size

Dependents:   BLE_Gateway_Linker_fix BLE_Gateway

Fork of mbedtls by sandbox

mbedtls/ecdh.h@5:f09f5ed830ca, 2017-07-10 (annotated)

Committer:
electronichamsters
Date:
Mon Jul 10 04:00:25 2017 +0000
Revision:
5:f09f5ed830ca
Parent:
1:24750b9ad5ef 
working gateway

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Christopher Haster 1:24750b9ad5ef 1 /**
Christopher Haster 1:24750b9ad5ef 2 * \file ecdh.h
Christopher Haster 1:24750b9ad5ef 3 *
Christopher Haster 1:24750b9ad5ef 4 * \brief Elliptic curve Diffie-Hellman
Christopher Haster 1:24750b9ad5ef 5 *
Christopher Haster 1:24750b9ad5ef 6 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
Christopher Haster 1:24750b9ad5ef 7 * SPDX-License-Identifier: Apache-2.0
Christopher Haster 1:24750b9ad5ef 8 *
Christopher Haster 1:24750b9ad5ef 9 * Licensed under the Apache License, Version 2.0 (the "License"); you may
Christopher Haster 1:24750b9ad5ef 10 * not use this file except in compliance with the License.
Christopher Haster 1:24750b9ad5ef 11 * You may obtain a copy of the License at
Christopher Haster 1:24750b9ad5ef 12 *
Christopher Haster 1:24750b9ad5ef 13 * http://www.apache.org/licenses/LICENSE-2.0
Christopher Haster 1:24750b9ad5ef 14 *
Christopher Haster 1:24750b9ad5ef 15 * Unless required by applicable law or agreed to in writing, software
Christopher Haster 1:24750b9ad5ef 16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
Christopher Haster 1:24750b9ad5ef 17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Christopher Haster 1:24750b9ad5ef 18 * See the License for the specific language governing permissions and
Christopher Haster 1:24750b9ad5ef 19 * limitations under the License.
Christopher Haster 1:24750b9ad5ef 20 *
Christopher Haster 1:24750b9ad5ef 21 * This file is part of mbed TLS (https://tls.mbed.org)
Christopher Haster 1:24750b9ad5ef 22 */
Christopher Haster 1:24750b9ad5ef 23 #ifndef MBEDTLS_ECDH_H
Christopher Haster 1:24750b9ad5ef 24 #define MBEDTLS_ECDH_H
Christopher Haster 1:24750b9ad5ef 25
Christopher Haster 1:24750b9ad5ef 26 #include "ecp.h"
Christopher Haster 1:24750b9ad5ef 27
Christopher Haster 1:24750b9ad5ef 28 #ifdef __cplusplus
Christopher Haster 1:24750b9ad5ef 29 extern "C" {
Christopher Haster 1:24750b9ad5ef 30 #endif
Christopher Haster 1:24750b9ad5ef 31
Christopher Haster 1:24750b9ad5ef 32 /**
Christopher Haster 1:24750b9ad5ef 33 * When importing from an EC key, select if it is our key or the peer's key
Christopher Haster 1:24750b9ad5ef 34 */
Christopher Haster 1:24750b9ad5ef 35 typedef enum
Christopher Haster 1:24750b9ad5ef 36 {
Christopher Haster 1:24750b9ad5ef 37 MBEDTLS_ECDH_OURS,
Christopher Haster 1:24750b9ad5ef 38 MBEDTLS_ECDH_THEIRS,
Christopher Haster 1:24750b9ad5ef 39 } mbedtls_ecdh_side;
Christopher Haster 1:24750b9ad5ef 40
Christopher Haster 1:24750b9ad5ef 41 /**
Christopher Haster 1:24750b9ad5ef 42 * \brief ECDH context structure
Christopher Haster 1:24750b9ad5ef 43 */
Christopher Haster 1:24750b9ad5ef 44 typedef struct
Christopher Haster 1:24750b9ad5ef 45 {
Christopher Haster 1:24750b9ad5ef 46 mbedtls_ecp_group grp; /*!< elliptic curve used */
Christopher Haster 1:24750b9ad5ef 47 mbedtls_mpi d; /*!< our secret value (private key) */
Christopher Haster 1:24750b9ad5ef 48 mbedtls_ecp_point Q; /*!< our public value (public key) */
Christopher Haster 1:24750b9ad5ef 49 mbedtls_ecp_point Qp; /*!< peer's public value (public key) */
Christopher Haster 1:24750b9ad5ef 50 mbedtls_mpi z; /*!< shared secret */
Christopher Haster 1:24750b9ad5ef 51 int point_format; /*!< format for point export in TLS messages */
Christopher Haster 1:24750b9ad5ef 52 mbedtls_ecp_point Vi; /*!< blinding value (for later) */
Christopher Haster 1:24750b9ad5ef 53 mbedtls_ecp_point Vf; /*!< un-blinding value (for later) */
Christopher Haster 1:24750b9ad5ef 54 mbedtls_mpi _d; /*!< previous d (for later) */
Christopher Haster 1:24750b9ad5ef 55 }
Christopher Haster 1:24750b9ad5ef 56 mbedtls_ecdh_context;
Christopher Haster 1:24750b9ad5ef 57
Christopher Haster 1:24750b9ad5ef 58 /**
Christopher Haster 1:24750b9ad5ef 59 * \brief Generate a public key.
Christopher Haster 1:24750b9ad5ef 60 * Raw function that only does the core computation.
Christopher Haster 1:24750b9ad5ef 61 *
Christopher Haster 1:24750b9ad5ef 62 * \param grp ECP group
Christopher Haster 1:24750b9ad5ef 63 * \param d Destination MPI (secret exponent, aka private key)
Christopher Haster 1:24750b9ad5ef 64 * \param Q Destination point (public key)
Christopher Haster 1:24750b9ad5ef 65 * \param f_rng RNG function
Christopher Haster 1:24750b9ad5ef 66 * \param p_rng RNG parameter
Christopher Haster 1:24750b9ad5ef 67 *
Christopher Haster 1:24750b9ad5ef 68 * \return 0 if successful,
Christopher Haster 1:24750b9ad5ef 69 * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
Christopher Haster 1:24750b9ad5ef 70 */
Christopher Haster 1:24750b9ad5ef 71 int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
Christopher Haster 1:24750b9ad5ef 72 int (*f_rng)(void *, unsigned char *, size_t),
Christopher Haster 1:24750b9ad5ef 73 void *p_rng );
Christopher Haster 1:24750b9ad5ef 74
Christopher Haster 1:24750b9ad5ef 75 /**
Christopher Haster 1:24750b9ad5ef 76 * \brief Compute shared secret
Christopher Haster 1:24750b9ad5ef 77 * Raw function that only does the core computation.
Christopher Haster 1:24750b9ad5ef 78 *
Christopher Haster 1:24750b9ad5ef 79 * \param grp ECP group
Christopher Haster 1:24750b9ad5ef 80 * \param z Destination MPI (shared secret)
Christopher Haster 1:24750b9ad5ef 81 * \param Q Public key from other party
Christopher Haster 1:24750b9ad5ef 82 * \param d Our secret exponent (private key)
Christopher Haster 1:24750b9ad5ef 83 * \param f_rng RNG function (see notes)
Christopher Haster 1:24750b9ad5ef 84 * \param p_rng RNG parameter
Christopher Haster 1:24750b9ad5ef 85 *
Christopher Haster 1:24750b9ad5ef 86 * \return 0 if successful,
Christopher Haster 1:24750b9ad5ef 87 * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
Christopher Haster 1:24750b9ad5ef 88 *
Christopher Haster 1:24750b9ad5ef 89 * \note If f_rng is not NULL, it is used to implement
Christopher Haster 1:24750b9ad5ef 90 * countermeasures against potential elaborate timing
Christopher Haster 1:24750b9ad5ef 91 * attacks, see \c mbedtls_ecp_mul() for details.
Christopher Haster 1:24750b9ad5ef 92 */
Christopher Haster 1:24750b9ad5ef 93 int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
Christopher Haster 1:24750b9ad5ef 94 const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
Christopher Haster 1:24750b9ad5ef 95 int (*f_rng)(void *, unsigned char *, size_t),
Christopher Haster 1:24750b9ad5ef 96 void *p_rng );
Christopher Haster 1:24750b9ad5ef 97
Christopher Haster 1:24750b9ad5ef 98 /**
Christopher Haster 1:24750b9ad5ef 99 * \brief Initialize context
Christopher Haster 1:24750b9ad5ef 100 *
Christopher Haster 1:24750b9ad5ef 101 * \param ctx Context to initialize
Christopher Haster 1:24750b9ad5ef 102 */
Christopher Haster 1:24750b9ad5ef 103 void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
Christopher Haster 1:24750b9ad5ef 104
Christopher Haster 1:24750b9ad5ef 105 /**
Christopher Haster 1:24750b9ad5ef 106 * \brief Free context
Christopher Haster 1:24750b9ad5ef 107 *
Christopher Haster 1:24750b9ad5ef 108 * \param ctx Context to free
Christopher Haster 1:24750b9ad5ef 109 */
Christopher Haster 1:24750b9ad5ef 110 void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
Christopher Haster 1:24750b9ad5ef 111
Christopher Haster 1:24750b9ad5ef 112 /**
Christopher Haster 1:24750b9ad5ef 113 * \brief Generate a public key and a TLS ServerKeyExchange payload.
Christopher Haster 1:24750b9ad5ef 114 * (First function used by a TLS server for ECDHE.)
Christopher Haster 1:24750b9ad5ef 115 *
Christopher Haster 1:24750b9ad5ef 116 * \param ctx ECDH context
Christopher Haster 1:24750b9ad5ef 117 * \param olen number of chars written
Christopher Haster 1:24750b9ad5ef 118 * \param buf destination buffer
Christopher Haster 1:24750b9ad5ef 119 * \param blen length of buffer
Christopher Haster 1:24750b9ad5ef 120 * \param f_rng RNG function
Christopher Haster 1:24750b9ad5ef 121 * \param p_rng RNG parameter
Christopher Haster 1:24750b9ad5ef 122 *
Christopher Haster 1:24750b9ad5ef 123 * \note This function assumes that ctx->grp has already been
Christopher Haster 1:24750b9ad5ef 124 * properly set (for example using mbedtls_ecp_group_load).
Christopher Haster 1:24750b9ad5ef 125 *
Christopher Haster 1:24750b9ad5ef 126 * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
Christopher Haster 1:24750b9ad5ef 127 */
Christopher Haster 1:24750b9ad5ef 128 int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
Christopher Haster 1:24750b9ad5ef 129 unsigned char *buf, size_t blen,
Christopher Haster 1:24750b9ad5ef 130 int (*f_rng)(void *, unsigned char *, size_t),
Christopher Haster 1:24750b9ad5ef 131 void *p_rng );
Christopher Haster 1:24750b9ad5ef 132
Christopher Haster 1:24750b9ad5ef 133 /**
Christopher Haster 1:24750b9ad5ef 134 * \brief Parse and procress a TLS ServerKeyExhange payload.
Christopher Haster 1:24750b9ad5ef 135 * (First function used by a TLS client for ECDHE.)
Christopher Haster 1:24750b9ad5ef 136 *
Christopher Haster 1:24750b9ad5ef 137 * \param ctx ECDH context
Christopher Haster 1:24750b9ad5ef 138 * \param buf pointer to start of input buffer
Christopher Haster 1:24750b9ad5ef 139 * \param end one past end of buffer
Christopher Haster 1:24750b9ad5ef 140 *
Christopher Haster 1:24750b9ad5ef 141 * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
Christopher Haster 1:24750b9ad5ef 142 */
Christopher Haster 1:24750b9ad5ef 143 int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
Christopher Haster 1:24750b9ad5ef 144 const unsigned char **buf, const unsigned char *end );
Christopher Haster 1:24750b9ad5ef 145
Christopher Haster 1:24750b9ad5ef 146 /**
Christopher Haster 1:24750b9ad5ef 147 * \brief Setup an ECDH context from an EC key.
Christopher Haster 1:24750b9ad5ef 148 * (Used by clients and servers in place of the
Christopher Haster 1:24750b9ad5ef 149 * ServerKeyEchange for static ECDH: import ECDH parameters
Christopher Haster 1:24750b9ad5ef 150 * from a certificate's EC key information.)
Christopher Haster 1:24750b9ad5ef 151 *
Christopher Haster 1:24750b9ad5ef 152 * \param ctx ECDH constext to set
Christopher Haster 1:24750b9ad5ef 153 * \param key EC key to use
Christopher Haster 1:24750b9ad5ef 154 * \param side Is it our key (1) or the peer's key (0) ?
Christopher Haster 1:24750b9ad5ef 155 *
Christopher Haster 1:24750b9ad5ef 156 * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
Christopher Haster 1:24750b9ad5ef 157 */
Christopher Haster 1:24750b9ad5ef 158 int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
Christopher Haster 1:24750b9ad5ef 159 mbedtls_ecdh_side side );
Christopher Haster 1:24750b9ad5ef 160
Christopher Haster 1:24750b9ad5ef 161 /**
Christopher Haster 1:24750b9ad5ef 162 * \brief Generate a public key and a TLS ClientKeyExchange payload.
Christopher Haster 1:24750b9ad5ef 163 * (Second function used by a TLS client for ECDH(E).)
Christopher Haster 1:24750b9ad5ef 164 *
Christopher Haster 1:24750b9ad5ef 165 * \param ctx ECDH context
Christopher Haster 1:24750b9ad5ef 166 * \param olen number of bytes actually written
Christopher Haster 1:24750b9ad5ef 167 * \param buf destination buffer
Christopher Haster 1:24750b9ad5ef 168 * \param blen size of destination buffer
Christopher Haster 1:24750b9ad5ef 169 * \param f_rng RNG function
Christopher Haster 1:24750b9ad5ef 170 * \param p_rng RNG parameter
Christopher Haster 1:24750b9ad5ef 171 *
Christopher Haster 1:24750b9ad5ef 172 * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
Christopher Haster 1:24750b9ad5ef 173 */
Christopher Haster 1:24750b9ad5ef 174 int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
Christopher Haster 1:24750b9ad5ef 175 unsigned char *buf, size_t blen,
Christopher Haster 1:24750b9ad5ef 176 int (*f_rng)(void *, unsigned char *, size_t),
Christopher Haster 1:24750b9ad5ef 177 void *p_rng );
Christopher Haster 1:24750b9ad5ef 178
Christopher Haster 1:24750b9ad5ef 179 /**
Christopher Haster 1:24750b9ad5ef 180 * \brief Parse and process a TLS ClientKeyExchange payload.
Christopher Haster 1:24750b9ad5ef 181 * (Second function used by a TLS server for ECDH(E).)
Christopher Haster 1:24750b9ad5ef 182 *
Christopher Haster 1:24750b9ad5ef 183 * \param ctx ECDH context
Christopher Haster 1:24750b9ad5ef 184 * \param buf start of input buffer
Christopher Haster 1:24750b9ad5ef 185 * \param blen length of input buffer
Christopher Haster 1:24750b9ad5ef 186 *
Christopher Haster 1:24750b9ad5ef 187 * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
Christopher Haster 1:24750b9ad5ef 188 */
Christopher Haster 1:24750b9ad5ef 189 int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
Christopher Haster 1:24750b9ad5ef 190 const unsigned char *buf, size_t blen );
Christopher Haster 1:24750b9ad5ef 191
Christopher Haster 1:24750b9ad5ef 192 /**
Christopher Haster 1:24750b9ad5ef 193 * \brief Derive and export the shared secret.
Christopher Haster 1:24750b9ad5ef 194 * (Last function used by both TLS client en servers.)
Christopher Haster 1:24750b9ad5ef 195 *
Christopher Haster 1:24750b9ad5ef 196 * \param ctx ECDH context
Christopher Haster 1:24750b9ad5ef 197 * \param olen number of bytes written
Christopher Haster 1:24750b9ad5ef 198 * \param buf destination buffer
Christopher Haster 1:24750b9ad5ef 199 * \param blen buffer length
Christopher Haster 1:24750b9ad5ef 200 * \param f_rng RNG function, see notes for \c mbedtls_ecdh_compute_shared()
Christopher Haster 1:24750b9ad5ef 201 * \param p_rng RNG parameter
Christopher Haster 1:24750b9ad5ef 202 *
Christopher Haster 1:24750b9ad5ef 203 * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
Christopher Haster 1:24750b9ad5ef 204 */
Christopher Haster 1:24750b9ad5ef 205 int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
Christopher Haster 1:24750b9ad5ef 206 unsigned char *buf, size_t blen,
Christopher Haster 1:24750b9ad5ef 207 int (*f_rng)(void *, unsigned char *, size_t),
Christopher Haster 1:24750b9ad5ef 208 void *p_rng );
Christopher Haster 1:24750b9ad5ef 209
Christopher Haster 1:24750b9ad5ef 210 #ifdef __cplusplus
Christopher Haster 1:24750b9ad5ef 211 }
Christopher Haster 1:24750b9ad5ef 212 #endif
Christopher Haster 1:24750b9ad5ef 213
Christopher Haster 1:24750b9ad5ef 214 #endif /* ecdh.h */