PolarSSL v1.3.1
Data Structures | Macros | Enumerations | Functions
ecp.h File Reference

Elliptic curves over GF(p) More...

#include "bignum.h"
Include dependency graph for ecp.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ecp_curve_info
 Curve information for use by other modules. More...
 
struct  ecp_point
 ECP point structure (jacobian coordinates) More...
 
struct  ecp_group
 ECP group structure. More...
 
struct  ecp_keypair
 ECP key pair structure. More...
 

Macros

#define POLARSSL_ERR_ECP_BAD_INPUT_DATA   -0x4F80
 Bad input parameters to function. More...
 
#define POLARSSL_ERR_ECP_BUFFER_TOO_SMALL   -0x4F00
 The buffer is too small to write to. More...
 
#define POLARSSL_ERR_ECP_FEATURE_UNAVAILABLE   -0x4E80
 Requested curve not available. More...
 
#define POLARSSL_ERR_ECP_VERIFY_FAILED   -0x4E00
 The signature is not valid. More...
 
#define POLARSSL_ERR_ECP_MALLOC_FAILED   -0x4D80
 Memory allocation failed. More...
 
#define POLARSSL_ERR_ECP_RANDOM_FAILED   -0x4D00
 Generation of random value, such as (ephemeral) key, failed. More...
 
#define POLARSSL_ERR_ECP_INVALID_KEY   -0x4C80
 Invalid private or public key. More...
 
#define POLARSSL_ECP_DP_MAX   9
 Number of supported curves (plus one for NONE) More...
 
#define POLARSSL_ECP_MAX_BITS   521
 Maximum size of the groups (that is, of N and P) More...
 
#define POLARSSL_ECP_MAX_BYTES   ( ( POLARSSL_ECP_MAX_BITS + 7 ) / 8 )
 
#define POLARSSL_ECP_MAX_PT_LEN   ( 2 * POLARSSL_ECP_MAX_BYTES + 1 )
 
#define POLARSSL_ECP_WINDOW_SIZE   8
 Maximum NAF width used. More...
 
#define POLARSSL_ECP_PF_UNCOMPRESSED   0
 Uncompressed point format. More...
 
#define POLARSSL_ECP_PF_COMPRESSED   1
 Compressed point format. More...
 
#define POLARSSL_ECP_TLS_NAMED_CURVE   3
 ECCurveType's named_curve. More...
 

Enumerations

enum  ecp_group_id {
  POLARSSL_ECP_DP_NONE = 0, POLARSSL_ECP_DP_SECP192R1, POLARSSL_ECP_DP_SECP224R1, POLARSSL_ECP_DP_SECP256R1,
  POLARSSL_ECP_DP_SECP384R1, POLARSSL_ECP_DP_SECP521R1, POLARSSL_ECP_DP_BP256R1, POLARSSL_ECP_DP_BP384R1,
  POLARSSL_ECP_DP_BP512R1
}
 Domain parameters (curve, subgroup and generator) identifiers. More...
 

Functions

const ecp_curve_infoecp_curve_list (void)
 Return the list of supported curves with associated info. More...
 
void ecp_point_init (ecp_point *pt)
 Initialize a point (as zero) More...
 
void ecp_group_init (ecp_group *grp)
 Initialize a group (to something meaningless) More...
 
void ecp_keypair_init (ecp_keypair *key)
 Initialize a key pair (as an invalid one) More...
 
void ecp_point_free (ecp_point *pt)
 Free the components of a point. More...
 
void ecp_group_free (ecp_group *grp)
 Free the components of an ECP group. More...
 
void ecp_keypair_free (ecp_keypair *key)
 Free the components of a key pair. More...
 
int ecp_set_zero (ecp_point *pt)
 Set a point to zero. More...
 
int ecp_is_zero (ecp_point *pt)
 Tell if a point is zero. More...
 
int ecp_copy (ecp_point *P, const ecp_point *Q)
 Copy the contents of point Q into P. More...
 
int ecp_group_copy (ecp_group *dst, const ecp_group *src)
 Copy the contents of a group object. More...
 
int ecp_point_read_string (ecp_point *P, int radix, const char *x, const char *y)
 Import a non-zero point from two ASCII strings. More...
 
int ecp_group_read_string (ecp_group *grp, int radix, const char *p, const char *b, const char *gx, const char *gy, const char *n)
 Import an ECP group from null-terminated ASCII strings. More...
 
int ecp_point_write_binary (const ecp_group *grp, const ecp_point *P, int format, size_t *olen, unsigned char *buf, size_t buflen)
 Export a point into unsigned binary data. More...
 
int ecp_point_read_binary (const ecp_group *grp, ecp_point *P, const unsigned char *buf, size_t ilen)
 Import a point from unsigned binary data. More...
 
int ecp_use_known_dp (ecp_group *grp, ecp_group_id index)
 Set a group using well-known domain parameters. More...
 
int ecp_tls_read_group (ecp_group *grp, const unsigned char **buf, size_t len)
 Set a group from a TLS ECParameters record. More...
 
int ecp_tls_write_group (const ecp_group *grp, size_t *olen, unsigned char *buf, size_t blen)
 Write the TLS ECParameters record for a group. More...
 
const ecp_curve_infoecp_curve_info_from_grp_id (ecp_group_id grp_id)
 Get curve information from an internal group identifier. More...
 
const ecp_curve_infoecp_curve_info_from_tls_id (uint16_t tls_id)
 Get curve information from a TLS NamedCurve value. More...
 
int ecp_tls_read_point (const ecp_group *grp, ecp_point *pt, const unsigned char **buf, size_t len)
 Import a point from a TLS ECPoint record. More...
 
int ecp_tls_write_point (const ecp_group *grp, const ecp_point *pt, int format, size_t *olen, unsigned char *buf, size_t blen)
 Export a point as a TLS ECPoint record. More...
 
int ecp_add (const ecp_group *grp, ecp_point *R, const ecp_point *P, const ecp_point *Q)
 Addition: R = P + Q. More...
 
int ecp_sub (const ecp_group *grp, ecp_point *R, const ecp_point *P, const ecp_point *Q)
 Subtraction: R = P - Q. More...
 
int ecp_mul (ecp_group *grp, ecp_point *R, const mpi *m, const ecp_point *P, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
 Multiplication by an integer: R = m * P (Not thread-safe to use same group in multiple threads) More...
 
int ecp_check_pubkey (const ecp_group *grp, const ecp_point *pt)
 Check that a point is a valid public key on this curve. More...
 
int ecp_check_privkey (const ecp_group *grp, const mpi *d)
 Check that an mpi is a valid private key for this curve. More...
 
int ecp_gen_keypair (ecp_group *grp, mpi *d, ecp_point *Q, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
 Generate a keypair. More...
 
int ecp_self_test (int verbose)
 Checkup routine. More...
 

Detailed Description

Elliptic curves over GF(p)

Copyright (C) 2006-2013, Brainspark B.V.

This file is part of PolarSSL (http://www.polarssl.org) Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Definition in file ecp.h.

Macro Definition Documentation

#define POLARSSL_ECP_DP_MAX   9

Number of supported curves (plus one for NONE)

Definition at line 72 of file ecp.h.

#define POLARSSL_ECP_MAX_BITS   521

Maximum size of the groups (that is, of N and P)

Definition at line 155 of file ecp.h.

#define POLARSSL_ECP_MAX_BYTES   ( ( POLARSSL_ECP_MAX_BITS + 7 ) / 8 )

Definition at line 156 of file ecp.h.

#define POLARSSL_ECP_MAX_PT_LEN   ( 2 * POLARSSL_ECP_MAX_BYTES + 1 )

Definition at line 157 of file ecp.h.

#define POLARSSL_ECP_PF_COMPRESSED   1

Compressed point format.

Definition at line 175 of file ecp.h.

#define POLARSSL_ECP_PF_UNCOMPRESSED   0

Uncompressed point format.

Definition at line 174 of file ecp.h.

#define POLARSSL_ECP_TLS_NAMED_CURVE   3

ECCurveType's named_curve.

Definition at line 180 of file ecp.h.

#define POLARSSL_ECP_WINDOW_SIZE   8

Maximum NAF width used.

Definition at line 169 of file ecp.h.

#define POLARSSL_ERR_ECP_BAD_INPUT_DATA   -0x4F80

Bad input parameters to function.

Definition at line 35 of file ecp.h.

#define POLARSSL_ERR_ECP_BUFFER_TOO_SMALL   -0x4F00

The buffer is too small to write to.

Definition at line 36 of file ecp.h.

#define POLARSSL_ERR_ECP_FEATURE_UNAVAILABLE   -0x4E80

Requested curve not available.

Definition at line 37 of file ecp.h.

#define POLARSSL_ERR_ECP_INVALID_KEY   -0x4C80

Invalid private or public key.

Definition at line 41 of file ecp.h.

#define POLARSSL_ERR_ECP_MALLOC_FAILED   -0x4D80

Memory allocation failed.

Definition at line 39 of file ecp.h.

#define POLARSSL_ERR_ECP_RANDOM_FAILED   -0x4D00

Generation of random value, such as (ephemeral) key, failed.

Definition at line 40 of file ecp.h.

#define POLARSSL_ERR_ECP_VERIFY_FAILED   -0x4E00

The signature is not valid.

Definition at line 38 of file ecp.h.

Enumeration Type Documentation

Domain parameters (curve, subgroup and generator) identifiers.

Only curves over prime fields are supported.

Warning
This library does not support validation of arbitrary domain parameters. Therefore, only well-known domain parameters from trusted sources should be used. See ecp_use_known_dp().
Enumerator
POLARSSL_ECP_DP_NONE 
POLARSSL_ECP_DP_SECP192R1 

192-bits NIST curve

POLARSSL_ECP_DP_SECP224R1 

224-bits NIST curve

POLARSSL_ECP_DP_SECP256R1 

256-bits NIST curve

POLARSSL_ECP_DP_SECP384R1 

384-bits NIST curve

POLARSSL_ECP_DP_SECP521R1 

521-bits NIST curve

POLARSSL_ECP_DP_BP256R1 

256-bits Brainpool curve

POLARSSL_ECP_DP_BP384R1 

384-bits Brainpool curve

POLARSSL_ECP_DP_BP512R1 

512-bits Brainpool curve

Definition at line 56 of file ecp.h.

Function Documentation

int ecp_add ( const ecp_group grp,
ecp_point R,
const ecp_point P,
const ecp_point Q 
)

Addition: R = P + Q.

Parameters
grpECP group
RDestination point
PLeft-hand point
QRight-hand point
Returns
0 if successful, POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed
int ecp_check_privkey ( const ecp_group grp,
const mpi d 
)

Check that an mpi is a valid private key for this curve.

Parameters
grpGroup used
dInteger to check
Returns
0 if point is a valid private key, POLARSSL_ERR_ECP_INVALID_KEY otherwise.
Note
Uses bare components rather than an ecp_keypair structure in order to ease use with other structures such as ecdh_context of ecdsa_context.
int ecp_check_pubkey ( const ecp_group grp,
const ecp_point pt 
)

Check that a point is a valid public key on this curve.

Parameters
grpCurve/group the point should belong to
ptPoint to check
Returns
0 if point is a valid public key, POLARSSL_ERR_ECP_INVALID_KEY otherwise.
Note
This function only checks the point is non-zero, has valid coordinates and lies on the curve, but not that it is indeed a multiple of G. This is additional check is more expensive, isn't required by standards, and shouldn't be necessary if the group used has a small cofactor. In particular, it is useless for the NIST groups which all have a cofactor of 1.
Uses bare components rather than an ecp_keypair structure in order to ease use with other structures such as ecdh_context of ecdsa_context.
int ecp_copy ( ecp_point P,
const ecp_point Q 
)

Copy the contents of point Q into P.

Parameters
PDestination point
QSource point
Returns
0 if successful, POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed
const ecp_curve_info* ecp_curve_info_from_grp_id ( ecp_group_id  grp_id)

Get curve information from an internal group identifier.

Parameters
grp_idA POLARSSL_ECP_DP_XXX value
Returns
The associated curve information or NULL
const ecp_curve_info* ecp_curve_info_from_tls_id ( uint16_t  tls_id)

Get curve information from a TLS NamedCurve value.

Parameters
grp_idA POLARSSL_ECP_DP_XXX value
Returns
The associated curve information or NULL
const ecp_curve_info* ecp_curve_list ( void  )

Return the list of supported curves with associated info.

Returns
A statically allocated array, the last entry is 0.
int ecp_gen_keypair ( ecp_group grp,
mpi d,
ecp_point Q,
int(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng 
)

Generate a keypair.

Parameters
grpECP group
dDestination MPI (secret part)
QDestination point (public part)
f_rngRNG function
p_rngRNG parameter
Returns
0 if successful, or a POLARSSL_ERR_ECP_XXX or POLARSSL_MPI_XXX error code
Note
Uses bare components rather than an ecp_keypair structure in order to ease use with other structures such as ecdh_context of ecdsa_context.
int ecp_group_copy ( ecp_group dst,
const ecp_group src 
)

Copy the contents of a group object.

Parameters
dstDestination group
srcSource group
Returns
0 if successful, POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed
void ecp_group_free ( ecp_group grp)

Free the components of an ECP group.

void ecp_group_init ( ecp_group grp)

Initialize a group (to something meaningless)

int ecp_group_read_string ( ecp_group grp,
int  radix,
const char *  p,
const char *  b,
const char *  gx,
const char *  gy,
const char *  n 
)

Import an ECP group from null-terminated ASCII strings.

Parameters
grpDestination group
radixInput numeric base
pPrime modulus of the base field
bConstant term in the equation
gxThe generator's X coordinate
gyThe generator's Y coordinate
nThe generator's order
Returns
0 if successful, or a POLARSSL_ERR_MPI_XXX error code
Note
Sets all fields except modp.
int ecp_is_zero ( ecp_point pt)

Tell if a point is zero.

Parameters
ptPoint to test
Returns
1 if point is zero, 0 otherwise
void ecp_keypair_free ( ecp_keypair key)

Free the components of a key pair.

void ecp_keypair_init ( ecp_keypair key)

Initialize a key pair (as an invalid one)

int ecp_mul ( ecp_group grp,
ecp_point R,
const mpi m,
const ecp_point P,
int(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng 
)

Multiplication by an integer: R = m * P (Not thread-safe to use same group in multiple threads)

Parameters
grpECP group
RDestination point
mInteger by which to multiply
PPoint to multiply
f_rngRNG function (see notes)
p_rngRNG parameter
Returns
0 if successful, POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed POLARSSL_ERR_ECP_BAD_INPUT_DATA if m < 0 of m has greater bit length than N, the number of points in the group.
Note
In order to prevent simple timing attacks, this function executes a constant number of operations (that is, point doubling and addition of distinct points) for random m in the allowed range.
If f_rng is not NULL, it is used to randomize projective coordinates of indermediate results, in order to prevent more elaborate timing attacks relying on intermediate operations. (This is a prophylactic measure since no such attack has been published yet.) Since this contermeasure has very low overhead, it is recommended to always provide a non-NULL f_rng parameter when using secret inputs.
void ecp_point_free ( ecp_point pt)

Free the components of a point.

void ecp_point_init ( ecp_point pt)

Initialize a point (as zero)

int ecp_point_read_binary ( const ecp_group grp,
ecp_point P,
const unsigned char *  buf,
size_t  ilen 
)

Import a point from unsigned binary data.

Parameters
grpGroup to which the point should belong
PPoint to import
bufInput buffer
ilenActual length of input
Returns
0 if successful, POLARSSL_ERR_ECP_BAD_INPUT_DATA if input is invalid POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed
Note
This function does NOT check that the point actually belongs to the given group, see ecp_check_pubkey() for that.
int ecp_point_read_string ( ecp_point P,
int  radix,
const char *  x,
const char *  y 
)

Import a non-zero point from two ASCII strings.

Parameters
PDestination point
radixInput numeric base
xFirst affine coordinate as a null-terminated string
ySecond affine coordinate as a null-terminated string
Returns
0 if successful, or a POLARSSL_ERR_MPI_XXX error code
int ecp_point_write_binary ( const ecp_group grp,
const ecp_point P,
int  format,
size_t *  olen,
unsigned char *  buf,
size_t  buflen 
)

Export a point into unsigned binary data.

Parameters
grpGroup to which the point should belong
PPoint to export
formatPoint format, should be a POLARSSL_ECP_PF_XXX macro
olenLength of the actual output
bufOutput buffer
buflenLength of the output buffer
Returns
0 if successful, or POLARSSL_ERR_ECP_BAD_INPUT_DATA or POLARSSL_ERR_ECP_BUFFER_TOO_SMALL
int ecp_self_test ( int  verbose)

Checkup routine.

Returns
0 if successful, or 1 if the test failed
int ecp_set_zero ( ecp_point pt)

Set a point to zero.

Parameters
ptDestination point
Returns
0 if successful, POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed
int ecp_sub ( const ecp_group grp,
ecp_point R,
const ecp_point P,
const ecp_point Q 
)

Subtraction: R = P - Q.

Parameters
grpECP group
RDestination point
PLeft-hand point
QRight-hand point
Returns
0 if successful, POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed
int ecp_tls_read_group ( ecp_group grp,
const unsigned char **  buf,
size_t  len 
)

Set a group from a TLS ECParameters record.

Parameters
grpDestination group
buf&(Start of input buffer)
lenBuffer length
Returns
O if successful, POLARSSL_ERR_MPI_XXX if initialization failed POLARSSL_ERR_ECP_BAD_INPUT_DATA if input is invalid
int ecp_tls_read_point ( const ecp_group grp,
ecp_point pt,
const unsigned char **  buf,
size_t  len 
)

Import a point from a TLS ECPoint record.

Parameters
grpECP group used
ptDestination point
buf$(Start of input buffer)
lenBuffer length
Returns
O if successful, POLARSSL_ERR_MPI_XXX if initialization failed POLARSSL_ERR_ECP_BAD_INPUT_DATA if input is invalid
int ecp_tls_write_group ( const ecp_group grp,
size_t *  olen,
unsigned char *  buf,
size_t  blen 
)

Write the TLS ECParameters record for a group.

Parameters
grpECP group used
olenNumber of bytes actually written
bufBuffer to write to
blenBuffer length
Returns
0 if successful, or POLARSSL_ERR_ECP_BUFFER_TOO_SMALL
int ecp_tls_write_point ( const ecp_group grp,
const ecp_point pt,
int  format,
size_t *  olen,
unsigned char *  buf,
size_t  blen 
)

Export a point as a TLS ECPoint record.

Parameters
grpECP group used
ptPoint to export
formatExport format
olenlength of data written
bufBuffer to write to
blenBuffer length
Returns
0 if successful, or POLARSSL_ERR_ECP_BAD_INPUT_DATA or POLARSSL_ERR_ECP_BUFFER_TOO_SMALL
int ecp_use_known_dp ( ecp_group grp,
ecp_group_id  index 
)

Set a group using well-known domain parameters.

Parameters
grpDestination group
indexIndex in the list of well-known domain parameters
Returns
O if successful, POLARSSL_ERR_MPI_XXX if initialization failed POLARSSL_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups
Note
Index should be a value of RFC 4492's enum NamdeCurve, possibly in the form of a POLARSSL_ECP_DP_XXX macro.