Doug Anson / mbedTLSLibrary

mbed TLS library

Dependents:   HTTPClient-SSL WS_SERVER

include/polarssl/ecdh.h@0:137634ff4186, 2015-06-11 (annotated)

Committer:
ansond
Date:
Thu Jun 11 03:27:03 2015 +0000
Revision:
0:137634ff4186
initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ansond 0:137634ff4186 1 /**
ansond 0:137634ff4186 2 * \file ecdh.h
ansond 0:137634ff4186 3 *
ansond 0:137634ff4186 4 * \brief Elliptic curve Diffie-Hellman
ansond 0:137634ff4186 5 *
ansond 0:137634ff4186 6 * Copyright (C) 2006-2013, ARM Limited, All Rights Reserved
ansond 0:137634ff4186 7 *
ansond 0:137634ff4186 8 * This file is part of mbed TLS (https://tls.mbed.org)
ansond 0:137634ff4186 9 *
ansond 0:137634ff4186 10 * This program is free software; you can redistribute it and/or modify
ansond 0:137634ff4186 11 * it under the terms of the GNU General Public License as published by
ansond 0:137634ff4186 12 * the Free Software Foundation; either version 2 of the License, or
ansond 0:137634ff4186 13 * (at your option) any later version.
ansond 0:137634ff4186 14 *
ansond 0:137634ff4186 15 * This program is distributed in the hope that it will be useful,
ansond 0:137634ff4186 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
ansond 0:137634ff4186 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
ansond 0:137634ff4186 18 * GNU General Public License for more details.
ansond 0:137634ff4186 19 *
ansond 0:137634ff4186 20 * You should have received a copy of the GNU General Public License along
ansond 0:137634ff4186 21 * with this program; if not, write to the Free Software Foundation, Inc.,
ansond 0:137634ff4186 22 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
ansond 0:137634ff4186 23 */
ansond 0:137634ff4186 24 #ifndef POLARSSL_ECDH_H
ansond 0:137634ff4186 25 #define POLARSSL_ECDH_H
ansond 0:137634ff4186 26
ansond 0:137634ff4186 27 #include "ecp.h"
ansond 0:137634ff4186 28
ansond 0:137634ff4186 29 #ifdef __cplusplus
ansond 0:137634ff4186 30 extern "C" {
ansond 0:137634ff4186 31 #endif
ansond 0:137634ff4186 32
ansond 0:137634ff4186 33 /**
ansond 0:137634ff4186 34 * When importing from an EC key, select if it is our key or the peer's key
ansond 0:137634ff4186 35 */
ansond 0:137634ff4186 36 typedef enum
ansond 0:137634ff4186 37 {
ansond 0:137634ff4186 38 POLARSSL_ECDH_OURS,
ansond 0:137634ff4186 39 POLARSSL_ECDH_THEIRS,
ansond 0:137634ff4186 40 } ecdh_side;
ansond 0:137634ff4186 41
ansond 0:137634ff4186 42 /**
ansond 0:137634ff4186 43 * \brief ECDH context structure
ansond 0:137634ff4186 44 */
ansond 0:137634ff4186 45 typedef struct
ansond 0:137634ff4186 46 {
ansond 0:137634ff4186 47 ecp_group grp; /*!< elliptic curve used */
ansond 0:137634ff4186 48 mpi d; /*!< our secret value (private key) */
ansond 0:137634ff4186 49 ecp_point Q; /*!< our public value (public key) */
ansond 0:137634ff4186 50 ecp_point Qp; /*!< peer's public value (public key) */
ansond 0:137634ff4186 51 mpi z; /*!< shared secret */
ansond 0:137634ff4186 52 int point_format; /*!< format for point export in TLS messages */
ansond 0:137634ff4186 53 ecp_point Vi; /*!< blinding value (for later) */
ansond 0:137634ff4186 54 ecp_point Vf; /*!< un-blinding value (for later) */
ansond 0:137634ff4186 55 mpi _d; /*!< previous d (for later) */
ansond 0:137634ff4186 56 }
ansond 0:137634ff4186 57 ecdh_context;
ansond 0:137634ff4186 58
ansond 0:137634ff4186 59 /**
ansond 0:137634ff4186 60 * \brief Generate a public key.
ansond 0:137634ff4186 61 * Raw function that only does the core computation.
ansond 0:137634ff4186 62 *
ansond 0:137634ff4186 63 * \param grp ECP group
ansond 0:137634ff4186 64 * \param d Destination MPI (secret exponent, aka private key)
ansond 0:137634ff4186 65 * \param Q Destination point (public key)
ansond 0:137634ff4186 66 * \param f_rng RNG function
ansond 0:137634ff4186 67 * \param p_rng RNG parameter
ansond 0:137634ff4186 68 *
ansond 0:137634ff4186 69 * \return 0 if successful,
ansond 0:137634ff4186 70 * or a POLARSSL_ERR_ECP_XXX or POLARSSL_MPI_XXX error code
ansond 0:137634ff4186 71 */
ansond 0:137634ff4186 72 int ecdh_gen_public( ecp_group *grp, mpi *d, ecp_point *Q,
ansond 0:137634ff4186 73 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 74 void *p_rng );
ansond 0:137634ff4186 75
ansond 0:137634ff4186 76 /**
ansond 0:137634ff4186 77 * \brief Compute shared secret
ansond 0:137634ff4186 78 * Raw function that only does the core computation.
ansond 0:137634ff4186 79 *
ansond 0:137634ff4186 80 * \param grp ECP group
ansond 0:137634ff4186 81 * \param z Destination MPI (shared secret)
ansond 0:137634ff4186 82 * \param Q Public key from other party
ansond 0:137634ff4186 83 * \param d Our secret exponent (private key)
ansond 0:137634ff4186 84 * \param f_rng RNG function (see notes)
ansond 0:137634ff4186 85 * \param p_rng RNG parameter
ansond 0:137634ff4186 86 *
ansond 0:137634ff4186 87 * \return 0 if successful,
ansond 0:137634ff4186 88 * or a POLARSSL_ERR_ECP_XXX or POLARSSL_MPI_XXX error code
ansond 0:137634ff4186 89 *
ansond 0:137634ff4186 90 * \note If f_rng is not NULL, it is used to implement
ansond 0:137634ff4186 91 * countermeasures against potential elaborate timing
ansond 0:137634ff4186 92 * attacks, see \c ecp_mul() for details.
ansond 0:137634ff4186 93 */
ansond 0:137634ff4186 94 int ecdh_compute_shared( ecp_group *grp, mpi *z,
ansond 0:137634ff4186 95 const ecp_point *Q, const mpi *d,
ansond 0:137634ff4186 96 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 97 void *p_rng );
ansond 0:137634ff4186 98
ansond 0:137634ff4186 99 /**
ansond 0:137634ff4186 100 * \brief Initialize context
ansond 0:137634ff4186 101 *
ansond 0:137634ff4186 102 * \param ctx Context to initialize
ansond 0:137634ff4186 103 */
ansond 0:137634ff4186 104 void ecdh_init( ecdh_context *ctx );
ansond 0:137634ff4186 105
ansond 0:137634ff4186 106 /**
ansond 0:137634ff4186 107 * \brief Free context
ansond 0:137634ff4186 108 *
ansond 0:137634ff4186 109 * \param ctx Context to free
ansond 0:137634ff4186 110 */
ansond 0:137634ff4186 111 void ecdh_free( ecdh_context *ctx );
ansond 0:137634ff4186 112
ansond 0:137634ff4186 113 /**
ansond 0:137634ff4186 114 * \brief Generate a public key and a TLS ServerKeyExchange payload.
ansond 0:137634ff4186 115 * (First function used by a TLS server for ECDHE.)
ansond 0:137634ff4186 116 *
ansond 0:137634ff4186 117 * \param ctx ECDH context
ansond 0:137634ff4186 118 * \param olen number of chars written
ansond 0:137634ff4186 119 * \param buf destination buffer
ansond 0:137634ff4186 120 * \param blen length of buffer
ansond 0:137634ff4186 121 * \param f_rng RNG function
ansond 0:137634ff4186 122 * \param p_rng RNG parameter
ansond 0:137634ff4186 123 *
ansond 0:137634ff4186 124 * \note This function assumes that ctx->grp has already been
ansond 0:137634ff4186 125 * properly set (for example using ecp_use_known_dp).
ansond 0:137634ff4186 126 *
ansond 0:137634ff4186 127 * \return 0 if successful, or an POLARSSL_ERR_ECP_XXX error code
ansond 0:137634ff4186 128 */
ansond 0:137634ff4186 129 int ecdh_make_params( ecdh_context *ctx, size_t *olen,
ansond 0:137634ff4186 130 unsigned char *buf, size_t blen,
ansond 0:137634ff4186 131 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 132 void *p_rng );
ansond 0:137634ff4186 133
ansond 0:137634ff4186 134 /**
ansond 0:137634ff4186 135 * \brief Parse and procress a TLS ServerKeyExhange payload.
ansond 0:137634ff4186 136 * (First function used by a TLS client for ECDHE.)
ansond 0:137634ff4186 137 *
ansond 0:137634ff4186 138 * \param ctx ECDH context
ansond 0:137634ff4186 139 * \param buf pointer to start of input buffer
ansond 0:137634ff4186 140 * \param end one past end of buffer
ansond 0:137634ff4186 141 *
ansond 0:137634ff4186 142 * \return 0 if successful, or an POLARSSL_ERR_ECP_XXX error code
ansond 0:137634ff4186 143 */
ansond 0:137634ff4186 144 int ecdh_read_params( ecdh_context *ctx,
ansond 0:137634ff4186 145 const unsigned char **buf, const unsigned char *end );
ansond 0:137634ff4186 146
ansond 0:137634ff4186 147 /**
ansond 0:137634ff4186 148 * \brief Setup an ECDH context from an EC key.
ansond 0:137634ff4186 149 * (Used by clients and servers in place of the
ansond 0:137634ff4186 150 * ServerKeyEchange for static ECDH: import ECDH parameters
ansond 0:137634ff4186 151 * from a certificate's EC key information.)
ansond 0:137634ff4186 152 *
ansond 0:137634ff4186 153 * \param ctx ECDH constext to set
ansond 0:137634ff4186 154 * \param key EC key to use
ansond 0:137634ff4186 155 * \param side Is it our key (1) or the peer's key (0) ?
ansond 0:137634ff4186 156 *
ansond 0:137634ff4186 157 * \return 0 if successful, or an POLARSSL_ERR_ECP_XXX error code
ansond 0:137634ff4186 158 */
ansond 0:137634ff4186 159 int ecdh_get_params( ecdh_context *ctx, const ecp_keypair *key,
ansond 0:137634ff4186 160 ecdh_side side );
ansond 0:137634ff4186 161
ansond 0:137634ff4186 162 /**
ansond 0:137634ff4186 163 * \brief Generate a public key and a TLS ClientKeyExchange payload.
ansond 0:137634ff4186 164 * (Second function used by a TLS client for ECDH(E).)
ansond 0:137634ff4186 165 *
ansond 0:137634ff4186 166 * \param ctx ECDH context
ansond 0:137634ff4186 167 * \param olen number of bytes actually written
ansond 0:137634ff4186 168 * \param buf destination buffer
ansond 0:137634ff4186 169 * \param blen size of destination buffer
ansond 0:137634ff4186 170 * \param f_rng RNG function
ansond 0:137634ff4186 171 * \param p_rng RNG parameter
ansond 0:137634ff4186 172 *
ansond 0:137634ff4186 173 * \return 0 if successful, or an POLARSSL_ERR_ECP_XXX error code
ansond 0:137634ff4186 174 */
ansond 0:137634ff4186 175 int ecdh_make_public( ecdh_context *ctx, size_t *olen,
ansond 0:137634ff4186 176 unsigned char *buf, size_t blen,
ansond 0:137634ff4186 177 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 178 void *p_rng );
ansond 0:137634ff4186 179
ansond 0:137634ff4186 180 /**
ansond 0:137634ff4186 181 * \brief Parse and process a TLS ClientKeyExchange payload.
ansond 0:137634ff4186 182 * (Second function used by a TLS server for ECDH(E).)
ansond 0:137634ff4186 183 *
ansond 0:137634ff4186 184 * \param ctx ECDH context
ansond 0:137634ff4186 185 * \param buf start of input buffer
ansond 0:137634ff4186 186 * \param blen length of input buffer
ansond 0:137634ff4186 187 *
ansond 0:137634ff4186 188 * \return 0 if successful, or an POLARSSL_ERR_ECP_XXX error code
ansond 0:137634ff4186 189 */
ansond 0:137634ff4186 190 int ecdh_read_public( ecdh_context *ctx,
ansond 0:137634ff4186 191 const unsigned char *buf, size_t blen );
ansond 0:137634ff4186 192
ansond 0:137634ff4186 193 /**
ansond 0:137634ff4186 194 * \brief Derive and export the shared secret.
ansond 0:137634ff4186 195 * (Last function used by both TLS client en servers.)
ansond 0:137634ff4186 196 *
ansond 0:137634ff4186 197 * \param ctx ECDH context
ansond 0:137634ff4186 198 * \param olen number of bytes written
ansond 0:137634ff4186 199 * \param buf destination buffer
ansond 0:137634ff4186 200 * \param blen buffer length
ansond 0:137634ff4186 201 * \param f_rng RNG function, see notes for \c ecdh_compute_shared()
ansond 0:137634ff4186 202 * \param p_rng RNG parameter
ansond 0:137634ff4186 203 *
ansond 0:137634ff4186 204 * \return 0 if successful, or an POLARSSL_ERR_ECP_XXX error code
ansond 0:137634ff4186 205 */
ansond 0:137634ff4186 206 int ecdh_calc_secret( ecdh_context *ctx, size_t *olen,
ansond 0:137634ff4186 207 unsigned char *buf, size_t blen,
ansond 0:137634ff4186 208 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 209 void *p_rng );
ansond 0:137634ff4186 210
ansond 0:137634ff4186 211 /**
ansond 0:137634ff4186 212 * \brief Checkup routine
ansond 0:137634ff4186 213 *
ansond 0:137634ff4186 214 * \return 0 if successful, or 1 if the test failed
ansond 0:137634ff4186 215 */
ansond 0:137634ff4186 216 int ecdh_self_test( int verbose );
ansond 0:137634ff4186 217
ansond 0:137634ff4186 218 #ifdef __cplusplus
ansond 0:137634ff4186 219 }
ansond 0:137634ff4186 220 #endif
ansond 0:137634ff4186 221
ansond 0:137634ff4186 222 #endif /* ecdh.h */
ansond 0:137634ff4186 223