Elliptic curves over GF(p) More...

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...
Enumerations
enum	ecp_group_id { , 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, POLARSSL_ECP_DP_M221, POLARSSL_ECP_DP_M255, POLARSSL_ECP_DP_M383, POLARSSL_ECP_DP_M511, POLARSSL_ECP_DP_SECP192K1, POLARSSL_ECP_DP_SECP224K1, POLARSSL_ECP_DP_SECP256K1 }
	Domain parameters (curve, subgroup and generator) identifiers. More...
Functions
const ecp_curve_info *	ecp_curve_list (void)
	Get the list of supported curves in order of preferrence (full information)
const ecp_group_id *	ecp_grp_id_list (void)
	Get the list of supported curves in order of preferrence (grp_id only)
const ecp_curve_info *	ecp_curve_info_from_grp_id (ecp_group_id grp_id)
	Get curve information from an internal group identifier.
const ecp_curve_info *	ecp_curve_info_from_tls_id (uint16_t tls_id)
	Get curve information from a TLS NamedCurve value.
const ecp_curve_info *	ecp_curve_info_from_name (const char *name)
	Get curve information from a human-readable name.
void	ecp_point_init (ecp_point *pt)
	Initialize a point (as zero)
void	ecp_group_init (ecp_group *grp)
	Initialize a group (to something meaningless)
void	ecp_keypair_init (ecp_keypair *key)
	Initialize a key pair (as an invalid one)
void	ecp_point_free (ecp_point *pt)
	Free the components of a point.
void	ecp_group_free (ecp_group *grp)
	Free the components of an ECP group.
void	ecp_keypair_free (ecp_keypair *key)
	Free the components of a key pair.
int	ecp_copy (ecp_point P, const ecp_point Q)
	Copy the contents of point Q into P.
int	ecp_group_copy (ecp_group dst, const ecp_group src)
	Copy the contents of a group object.
int	ecp_set_zero (ecp_point *pt)
	Set a point to zero.
int	ecp_is_zero (ecp_point *pt)
	Tell if a point is zero.
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.
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.
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.
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.
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.
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.
int	ecp_use_known_dp (ecp_group *grp, ecp_group_id index)
	Set a group using well-known domain parameters.
int	ecp_tls_read_group (ecp_group grp, const unsigned char *buf, size_t len)
	Set a group from a TLS ECParameters record.
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.
int	ecp_add (const ecp_group grp, ecp_point R, const ecp_point P, const ecp_point Q)
	Addition: R = P + Q.
int	ecp_sub (const ecp_group grp, ecp_point R, const ecp_point P, const ecp_point Q)
	Subtraction: R = P - Q.
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)
int	ecp_check_pubkey (const ecp_group grp, const ecp_point pt)
	Check that a point is a valid public key on this curve.
int	ecp_check_privkey (const ecp_group grp, const mpi d)
	Check that an mpi is a valid private key for this curve.
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.
int	ecp_gen_key (ecp_group_id grp_id, ecp_keypair key, int(f_rng)(void , unsigned char , size_t), void *p_rng)
	Generate a keypair.
int	ecp_self_test (int verbose)
	Checkup routine.

Detailed Description

Elliptic curves over GF(p)

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

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.

Enumeration Type Documentation

enum ecp_group_id

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_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
POLARSSL_ECP_DP_M221	(not implemented yet)
POLARSSL_ECP_DP_M255	Curve25519
POLARSSL_ECP_DP_M383	(not implemented yet)
POLARSSL_ECP_DP_M511	(not implemented yet)
POLARSSL_ECP_DP_SECP192K1	192-bits "Koblitz" curve
POLARSSL_ECP_DP_SECP224K1	224-bits "Koblitz" curve
POLARSSL_ECP_DP_SECP256K1	256-bits "Koblitz" curve

Definition at line 57 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:

grp	ECP group
R	Destination point
P	Left-hand point
Q	Right-hand point

Returns:: 0 if successful, POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed

Note:: This function does not support Montgomery curves, such as Curve25519.

Definition at line 1066 of file ecp.c.

int ecp_check_privkey	(	const ecp_group *	grp,
		const mpi *	d
	)

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

Parameters:

grp	Group used
d	Integer 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.

Definition at line 1765 of file ecp.c.

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:

grp	Curve/group the point should belong to
pt	Point 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.

Definition at line 1745 of file ecp.c.

int ecp_copy	(	ecp_point *	P,
		const ecp_point *	Q
	)

Copy the contents of point Q into P.

Parameters:

P	Destination point
Q	Source point

Returns:: 0 if successful, POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed

Definition at line 366 of file ecp.c.

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_id A POLARSSL_ECP_DP_XXX value

Returns:: The associated curve information or NULL

Definition at line 206 of file ecp.c.

const ecp_curve_info* ecp_curve_info_from_name ( const char * name )

Get curve information from a human-readable name.

Parameters:

name The name

Returns:: The associated curve information or NULL

Definition at line 242 of file ecp.c.

const ecp_curve_info* ecp_curve_info_from_tls_id ( uint16_t tls_id )

Get curve information from a TLS NamedCurve value.

Parameters:

tls_id A POLARSSL_ECP_DP_XXX value

Returns:: The associated curve information or NULL

Definition at line 224 of file ecp.c.

const ecp_curve_info* ecp_curve_list ( void )

Get the list of supported curves in order of preferrence (full information)

Returns:: A statically allocated array, the last entry is 0.

Definition at line 172 of file ecp.c.

int ecp_gen_key	(	ecp_group_id	grp_id,
		ecp_keypair *	key,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

Generate a keypair.

Parameters:

grp_id	ECP group identifier
key	Destination keypair
f_rng	RNG function
p_rng	RNG parameter

Returns:: 0 if successful, or a POLARSSL_ERR_ECP_XXX or POLARSSL_MPI_XXX error code

Definition at line 1876 of file ecp.c.

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:

grp	ECP group
d	Destination MPI (secret part)
Q	Destination point (public part)
f_rng	RNG function
p_rng	RNG 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.

Definition at line 1798 of file ecp.c.

int ecp_group_copy	(	ecp_group *	dst,
		const ecp_group *	src
	)

Copy the contents of a group object.

Parameters:

dst	Destination group
src	Source group

Returns:: 0 if successful, POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed

Definition at line 381 of file ecp.c.

void ecp_group_free ( ecp_group * grp )

Free the components of an ECP group.

Definition at line 324 of file ecp.c.

void ecp_group_init ( ecp_group * grp )

Initialize a group (to something meaningless)

Definition at line 287 of file ecp.c.

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:

grp	Destination group
radix	Input numeric base
p	Prime modulus of the base field
b	Constant term in the equation
gx	The generator's X coordinate
gy	The generator's Y coordinate
n	The generator's order

Returns:: 0 if successful, or a POLARSSL_ERR_MPI_XXX error code

Note:: Sets all fields except modp.

Definition at line 579 of file ecp.c.

const ecp_group_id* ecp_grp_id_list ( void )

Get the list of supported curves in order of preferrence (grp_id only)

Returns:: A statically allocated array, terminated with POLARSSL_ECP_DP_NONE.

Definition at line 180 of file ecp.c.

int ecp_is_zero ( ecp_point * pt )

Tell if a point is zero.

Parameters:

pt	Point to test

Returns:: 1 if point is zero, 0 otherwise

Definition at line 404 of file ecp.c.

void ecp_keypair_free ( ecp_keypair * key )

Free the components of a key pair.

Definition at line 353 of file ecp.c.

void ecp_keypair_init ( ecp_keypair * key )

Initialize a key pair (as an invalid one)

Definition at line 298 of file ecp.c.

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:

grp	ECP group
R	Destination point
m	Integer by which to multiply
P	Point to multiply
f_rng	RNG function (see notes)
p_rng	RNG parameter

Returns:: 0 if successful, POLARSSL_ERR_ECP_INVALID_KEY if m is not a valid privkey or P is not a valid pubkey, POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed

Note:: In order to prevent timing attacks, this function executes the exact same sequence of (base field) operations for any valid m. It avoids any if-branch or array index depending on the value of m.; If f_rng is not NULL, it is used to randomize intermediate results in order to prevent potential timing attacks targeting these results. It is recommended to always provide a non-NULL f_rng (the overhead is negligible).

Definition at line 1652 of file ecp.c.

void ecp_point_free ( ecp_point * pt )

Free the components of a point.

Definition at line 311 of file ecp.c.

void ecp_point_init ( ecp_point * pt )

Initialize a point (as zero)

Definition at line 274 of file ecp.c.

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:

grp	Group to which the point should belong
P	Point to import
buf	Input buffer
ilen	Actual 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, POLARSSL_ERR_ECP_FEATURE_UNAVAILABLE if the point format is not implemented.

Note:: This function does NOT check that the point actually belongs to the given group, see ecp_check_pubkey() for that.

Definition at line 484 of file ecp.c.

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:

P	Destination point
radix	Input numeric base
x	First affine coordinate as a null-terminated string
y	Second affine coordinate as a null-terminated string

Returns:: 0 if successful, or a POLARSSL_ERR_MPI_XXX error code

Definition at line 412 of file ecp.c.

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:

grp	Group to which the point should belong
P	Point to export
format	Point format, should be a POLARSSL_ECP_PF_XXX macro
olen	Length of the actual output
buf	Output buffer
buflen	Length of the output buffer

Returns:: 0 if successful, or POLARSSL_ERR_ECP_BAD_INPUT_DATA or POLARSSL_ERR_ECP_BUFFER_TOO_SMALL

Definition at line 428 of file ecp.c.

int ecp_self_test ( int verbose )

Checkup routine.

Returns:: 0 if successful, or 1 if a test failed

Definition at line 1892 of file ecp.c.

int ecp_set_zero ( ecp_point * pt )

Set a point to zero.

Parameters:

pt	Destination point

Returns:: 0 if successful, POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed

Definition at line 389 of file ecp.c.

int ecp_sub	(	const ecp_group *	grp,
		ecp_point *	R,
		const ecp_point *	P,
		const ecp_point *	Q
	)

Subtraction: R = P - Q.

Parameters:

grp	ECP group
R	Destination point
P	Left-hand point
Q	Right-hand point

Returns:: 0 if successful, POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed

Note:: This function does not support Montgomery curves, such as Curve25519.

Definition at line 1084 of file ecp.c.

int ecp_tls_read_group	(	ecp_group *	grp,
		const unsigned char **	buf,
		size_t	len
	)

Set a group from a TLS ECParameters record.

Parameters:

grp	Destination group
buf	&(Start of input buffer)
len	Buffer length

Returns:: O if successful, POLARSSL_ERR_MPI_XXX if initialization failed POLARSSL_ERR_ECP_BAD_INPUT_DATA if input is invalid

Definition at line 603 of file ecp.c.

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:

grp	ECP group used
pt	Destination point
buf	$(Start of input buffer)
len	Buffer length

Returns:: O if successful, POLARSSL_ERR_MPI_XXX if initialization failed POLARSSL_ERR_ECP_BAD_INPUT_DATA if input is invalid

Definition at line 520 of file ecp.c.

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:

grp	ECP group used
olen	Number of bytes actually written
buf	Buffer to write to
blen	Buffer length

Returns:: 0 if successful, or POLARSSL_ERR_ECP_BUFFER_TOO_SMALL

Definition at line 636 of file ecp.c.

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:

grp	ECP group used
pt	Point to export
format	Export format
olen	length of data written
buf	Buffer to write to
blen	Buffer length

Returns:: 0 if successful, or POLARSSL_ERR_ECP_BAD_INPUT_DATA or POLARSSL_ERR_ECP_BUFFER_TOO_SMALL

Definition at line 551 of file ecp.c.

int ecp_use_known_dp	(	ecp_group *	grp,
		ecp_group_id	index
	)

Set a group using well-known domain parameters.

Parameters:

grp	Destination group
index	Index 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.

Definition at line 723 of file ecp_curves.c.

Type:	Program
Mbed OS support:	Mbed 2 deprecated
Created:	27 Sep 2018
Imports:	11
Forks:	0
Commits:	1
Dependents:	0
Dependencies:	1
Followers:	1

Important changes to repositories hosted on mbed.com

ecp.h File Reference

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

ecp.h File Reference

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning