Arcola / mbedtls

Fork of mbedtls by Mark Radbourne

Embed: (wiki syntax)

« Back to documentation index

ecp_internal.h File Reference

ecp_internal.h File Reference

Function declarations for alternative implementation of elliptic curve point arithmetic. More...

Go to the source code of this file.

Functions

unsigned char mbedtls_internal_ecp_grp_capable (const mbedtls_ecp_group *grp)
 Indicate if the Elliptic Curve Point module extension can handle the group.
int mbedtls_internal_ecp_init (const mbedtls_ecp_group *grp)
 Initialise the Elliptic Curve Point module extension.
void mbedtls_internal_ecp_free (const mbedtls_ecp_group *grp)
 Frees and deallocates the Elliptic Curve Point module extension.
int mbedtls_internal_ecp_randomize_jac (const mbedtls_ecp_group *grp, mbedtls_ecp_point *pt, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
 Randomize jacobian coordinates: (X, Y, Z) -> (l^2 X, l^3 Y, l Z) for random l.
int mbedtls_internal_ecp_add_mixed (const mbedtls_ecp_group *grp, mbedtls_ecp_point *R, const mbedtls_ecp_point *P, const mbedtls_ecp_point *Q)
 Addition: R = P + Q, mixed affine-Jacobian coordinates.
int mbedtls_internal_ecp_double_jac (const mbedtls_ecp_group *grp, mbedtls_ecp_point *R, const mbedtls_ecp_point *P)
 Point doubling R = 2 P, Jacobian coordinates.
int mbedtls_internal_ecp_normalize_jac_many (const mbedtls_ecp_group *grp, mbedtls_ecp_point *T[], size_t t_len)
 Normalize jacobian coordinates of an array of (pointers to) points.
int mbedtls_internal_ecp_normalize_jac (const mbedtls_ecp_group *grp, mbedtls_ecp_point *pt)
 Normalize jacobian coordinates so that Z == 0 || Z == 1.
int mbedtls_internal_ecp_randomize_mxz (const mbedtls_ecp_group *grp, mbedtls_ecp_point *P, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
 Randomize projective x/z coordinates: (X, Z) -> (l X, l Z) for random l.
int mbedtls_internal_ecp_normalize_mxz (const mbedtls_ecp_group *grp, mbedtls_ecp_point *P)
 Normalize Montgomery x/z coordinates: X = X/Z, Z = 1.

Detailed Description

Function declarations for alternative implementation of elliptic curve point arithmetic.

Copyright (C) 2016, ARM Limited, All Rights Reserved SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This file is part of mbed TLS (https://tls.mbed.org)

Definition in file ecp_internal.h.


Function Documentation

int mbedtls_internal_ecp_add_mixed ( const mbedtls_ecp_group grp,
mbedtls_ecp_point R,
const mbedtls_ecp_point P,
const mbedtls_ecp_point Q 
)

Addition: R = P + Q, mixed affine-Jacobian coordinates.

The coordinates of Q must be normalized (= affine), but those of P don't need to. R is not normalized.

This function is used only as a subrutine of ecp_mul_comb().

Special cases: (1) P or Q is zero, (2) R is zero, (3) P == Q. None of these cases can happen as intermediate step in ecp_mul_comb():

  • at each step, P, Q and R are multiples of the base point, the factor being less than its order, so none of them is zero;
  • Q is an odd multiple of the base point, P an even multiple, due to the choice of precomputed points in the modified comb method. So branches for these cases do not leak secret information.

We accept Q->Z being unset (saving memory in tables) as meaning 1.

Cost in field operations if done by [5] 3.22: 1A := 8M + 3S

Parameters:
grpPointer to the group representing the curve.
RPointer to a point structure to hold the result.
PPointer to the first summand, given with Jacobian coordinates
QPointer to the second summand, given with affine coordinates.
Returns:
0 if successful.
int mbedtls_internal_ecp_double_jac ( const mbedtls_ecp_group grp,
mbedtls_ecp_point R,
const mbedtls_ecp_point P 
)

Point doubling R = 2 P, Jacobian coordinates.

Cost: 1D := 3M + 4S (A == 0) 4M + 4S (A == -3) 3M + 6S + 1a otherwise when the implementation is based on the "dbl-1998-cmo-2" doubling formulas in [8] and standard optimizations are applied when curve parameter A is one of { 0, -3 }.

Parameters:
grpPointer to the group representing the curve.
RPointer to a point structure to hold the result.
PPointer to the point that has to be doubled, given with Jacobian coordinates.
Returns:
0 if successful.
void mbedtls_internal_ecp_free ( const mbedtls_ecp_group grp )

Frees and deallocates the Elliptic Curve Point module extension.

Parameters:
grpThe pointer to the group the module was initialised for.
unsigned char mbedtls_internal_ecp_grp_capable ( const mbedtls_ecp_group grp )

Indicate if the Elliptic Curve Point module extension can handle the group.

Parameters:
grpThe pointer to the elliptic curve group that will be the basis of the cryptographic computations.
Returns:
Non-zero if successful.
int mbedtls_internal_ecp_init ( const mbedtls_ecp_group grp )

Initialise the Elliptic Curve Point module extension.

If mbedtls_internal_ecp_grp_capable returns true for a group, this function has to be able to initialise the module for it.

This module can be a driver to a crypto hardware accelerator, for which this could be an initialise function.

Parameters:
grpThe pointer to the group the module needs to be initialised for.
Returns:
0 if successful.
int mbedtls_internal_ecp_normalize_jac ( const mbedtls_ecp_group grp,
mbedtls_ecp_point pt 
)

Normalize jacobian coordinates so that Z == 0 || Z == 1.

Cost in field operations if done by [5] 3.2.1: 1N := 1I + 3M + 1S

Parameters:
grpPointer to the group representing the curve.
ptpointer to the point to be normalised. This is an input/output parameter.
Returns:
0 if successful.
int mbedtls_internal_ecp_normalize_jac_many ( const mbedtls_ecp_group grp,
mbedtls_ecp_point T[],
size_t  t_len 
)

Normalize jacobian coordinates of an array of (pointers to) points.

Using Montgomery's trick to perform only one inversion mod P the cost is: 1N(t) := 1I + (6t - 3)M + 1S (See for example Algorithm 10.3.4. in [9])

This function is used only as a subrutine of ecp_mul_comb().

Warning: fails (returning an error) if one of the points is zero! This should never happen, see choice of w in ecp_mul_comb().

Parameters:
grpPointer to the group representing the curve.
TArray of pointers to the points to normalise.
t_lenNumber of elements in the array.
Returns:
0 if successful, an error if one of the points is zero.
int mbedtls_internal_ecp_normalize_mxz ( const mbedtls_ecp_group grp,
mbedtls_ecp_point P 
)

Normalize Montgomery x/z coordinates: X = X/Z, Z = 1.

Parameters:
grppointer to the group representing the curve
Ppointer to the point to be normalised. This is an input/output parameter.
Returns:
0 if successful
int mbedtls_internal_ecp_randomize_jac ( const mbedtls_ecp_group grp,
mbedtls_ecp_point pt,
int(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng 
)

Randomize jacobian coordinates: (X, Y, Z) -> (l^2 X, l^3 Y, l Z) for random l.

Parameters:
grpPointer to the group representing the curve.
ptThe point on the curve to be randomised, given with Jacobian coordinates.
f_rngA function pointer to the random number generator.
p_rngA pointer to the random number generator state.
Returns:
0 if successful.
int mbedtls_internal_ecp_randomize_mxz ( const mbedtls_ecp_group grp,
mbedtls_ecp_point P,
int(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng 
)

Randomize projective x/z coordinates: (X, Z) -> (l X, l Z) for random l.

Parameters:
grppointer to the group representing the curve
Pthe point on the curve to be randomised given with projective coordinates. This is an input/output parameter.
f_rnga function pointer to the random number generator
p_rnga pointer to the random number generator state
Returns:
0 if successful