mbed TLS v3.1.0
ecdh.h
Go to the documentation of this file.
1 
15 /*
16  * Copyright The Mbed TLS Contributors
17  * SPDX-License-Identifier: Apache-2.0
18  *
19  * Licensed under the Apache License, Version 2.0 (the "License"); you may
20  * not use this file except in compliance with the License.
21  * You may obtain a copy of the License at
22  *
23  * http://www.apache.org/licenses/LICENSE-2.0
24  *
25  * Unless required by applicable law or agreed to in writing, software
26  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
27  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
28  * See the License for the specific language governing permissions and
29  * limitations under the License.
30  */
31 
32 #ifndef MBEDTLS_ECDH_H
33 #define MBEDTLS_ECDH_H
34 #include "mbedtls/private_access.h"
35 
36 #include "mbedtls/build_info.h"
37 
38 #include "mbedtls/ecp.h"
39 
40 /*
41  * Mbed TLS supports two formats for ECDH contexts (#mbedtls_ecdh_context
42  * defined in `ecdh.h`). For most applications, the choice of format makes
43  * no difference, since all library functions can work with either format,
44  * except that the new format is incompatible with MBEDTLS_ECP_RESTARTABLE.
45 
46  * The new format used when this option is disabled is smaller
47  * (56 bytes on a 32-bit platform). In future versions of the library, it
48  * will support alternative implementations of ECDH operations.
49  * The new format is incompatible with applications that access
50  * context fields directly and with restartable ECP operations.
51  */
52 
53 #if defined(MBEDTLS_ECP_RESTARTABLE)
54 #define MBEDTLS_ECDH_LEGACY_CONTEXT
55 #else
56 #undef MBEDTLS_ECDH_LEGACY_CONTEXT
57 #endif
58 
59 #if defined(MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED)
60 #undef MBEDTLS_ECDH_LEGACY_CONTEXT
61 #include "everest/everest.h"
62 #endif
63 
64 #ifdef __cplusplus
65 extern "C" {
66 #endif
67 
71 typedef enum
72 {
76 
77 #if !defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
78 
84 typedef enum
85 {
86  MBEDTLS_ECDH_VARIANT_NONE = 0,
87  MBEDTLS_ECDH_VARIANT_MBEDTLS_2_0,
88 #if defined(MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED)
89  MBEDTLS_ECDH_VARIANT_EVEREST
90 #endif
91 } mbedtls_ecdh_variant;
92 
100 typedef struct mbedtls_ecdh_context_mbed
101 {
102  mbedtls_ecp_group MBEDTLS_PRIVATE(grp);
107 #if defined(MBEDTLS_ECP_RESTARTABLE)
109 #endif
110 } mbedtls_ecdh_context_mbed;
111 #endif
112 
120 typedef struct mbedtls_ecdh_context
121 {
122 #if defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
123  mbedtls_ecp_group MBEDTLS_PRIVATE(grp);
128  int MBEDTLS_PRIVATE(point_format);
132 #if defined(MBEDTLS_ECP_RESTARTABLE)
133  int MBEDTLS_PRIVATE(restart_enabled);
135 #endif /* MBEDTLS_ECP_RESTARTABLE */
136 #else
137  uint8_t MBEDTLS_PRIVATE(point_format);
140  mbedtls_ecdh_variant MBEDTLS_PRIVATE(var);
141  union
142  {
143  mbedtls_ecdh_context_mbed MBEDTLS_PRIVATE(mbed_ecdh);
144 #if defined(MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED)
145  mbedtls_ecdh_context_everest MBEDTLS_PRIVATE(everest_ecdh);
146 #endif
147  } MBEDTLS_PRIVATE(ctx);
150 #if defined(MBEDTLS_ECP_RESTARTABLE)
151  uint8_t MBEDTLS_PRIVATE(restart_enabled);
156 #endif /* MBEDTLS_ECP_RESTARTABLE */
157 #endif /* MBEDTLS_ECDH_LEGACY_CONTEXT */
158 }
160 
169 
195 int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
196  int (*f_rng)(void *, unsigned char *, size_t),
197  void *p_rng );
198 
230 int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
231  const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
232  int (*f_rng)(void *, unsigned char *, size_t),
233  void *p_rng );
234 
241 
259  mbedtls_ecp_group_id grp_id );
260 
269 
295 int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
296  unsigned char *buf, size_t blen,
297  int (*f_rng)(void *, unsigned char *, size_t),
298  void *p_rng );
299 
325  const unsigned char **buf,
326  const unsigned char *end );
327 
348  const mbedtls_ecp_keypair *key,
349  mbedtls_ecdh_side side );
350 
377 int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
378  unsigned char *buf, size_t blen,
379  int (*f_rng)(void *, unsigned char *, size_t),
380  void *p_rng );
381 
402  const unsigned char *buf, size_t blen );
403 
433 int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
434  unsigned char *buf, size_t blen,
435  int (*f_rng)(void *, unsigned char *, size_t),
436  void *p_rng );
437 
438 #if defined(MBEDTLS_ECP_RESTARTABLE)
439 
452 #endif /* MBEDTLS_ECP_RESTARTABLE */
453 
454 #ifdef __cplusplus
455 }
456 #endif
457 
458 #endif /* ecdh.h */
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)
This function generates an EC key pair and exports its in the format used in a TLS ServerKeyExchange ...
This file provides an API for Elliptic Curves over GF(P) (ECP).
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)
This function generates a public key and exports it as a TLS ClientKeyExchange payload.
The ECP key-pair structure.
Definition: ecp.h:421
void mbedtls_ecdh_free(mbedtls_ecdh_context *ctx)
This function frees a context.
int mbedtls_ecdh_setup(mbedtls_ecdh_context *ctx, mbedtls_ecp_group_id grp_id)
This function sets up the ECDH context with the information given.
#define MBEDTLS_PRIVATE(member)
int mbedtls_ecdh_read_public(mbedtls_ecdh_context *ctx, const unsigned char *buf, size_t blen)
This function parses and processes the ECDHE payload of a TLS ClientKeyExchange message.
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)
This function computes the shared secret.
void mbedtls_ecdh_init(mbedtls_ecdh_context *ctx)
This function initializes an ECDH context.
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)
This function generates an ECDH keypair on an elliptic curve.
mbedtls_ecdh_side
Definition: ecdh.h:71
Macro wrapper for struct's memebrs.
int mbedtls_ecdh_read_params(mbedtls_ecdh_context *ctx, const unsigned char **buf, const unsigned char *end)
This function parses the ECDHE parameters in a TLS ServerKeyExchange handshake message.
void mbedtls_ecdh_enable_restart(mbedtls_ecdh_context *ctx)
This function enables restartable EC computations for this context. (Default: disabled.)
mbedtls_ecp_group_id
Definition: ecp.h:113
struct mbedtls_ecdh_context mbedtls_ecdh_context
The ECDH context structure.
The ECDH context structure.
Definition: ecdh.h:120
Build-time configuration info.
MPI structure.
Definition: bignum.h:189
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)
This function derives and exports the shared secret.
General context for resuming ECC operations.
Definition: ecp.h:368
int mbedtls_ecdh_can_do(mbedtls_ecp_group_id gid)
Check whether a given group can be used for ECDH.
The ECP point structure, in Jacobian coordinates.
Definition: ecp.h:172
int mbedtls_ecdh_get_params(mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key, mbedtls_ecdh_side side)
This function sets up an ECDH context from an EC key.