ed5c8d3d1e
The modulus value won't change during normal operations, make this clear in the struct and the function signatures. This won't prevent the caller from modifying the passed buffer, but might give a hint and reinforces the message of the documentation. Signed-off-by: Janos Follath <janos.follath@arm.com>
142 lines
5.2 KiB
C
142 lines
5.2 KiB
C
/**
|
|
* Modular bignum functions
|
|
*
|
|
* Copyright The Mbed TLS Contributors
|
|
* 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.
|
|
*/
|
|
|
|
#ifndef MBEDTLS_BIGNUM_MOD_H
|
|
#define MBEDTLS_BIGNUM_MOD_H
|
|
|
|
#include "common.h"
|
|
|
|
#if defined(MBEDTLS_BIGNUM_C)
|
|
#include "mbedtls/bignum.h"
|
|
#endif
|
|
|
|
/* Skip 1 as it is slightly easier to accidentally pass to functions. */
|
|
typedef enum
|
|
{
|
|
MBEDTLS_MPI_MOD_REP_INVALID = 0,
|
|
MBEDTLS_MPI_MOD_REP_MONTGOMERY = 2,
|
|
MBEDTLS_MPI_MOD_REP_OPT_RED
|
|
} mbedtls_mpi_mod_rep_selector;
|
|
|
|
/* Make mbedtls_mpi_mod_rep_selector and mbedtls_mpi_mod_ext_rep disjoint to
|
|
* make it easier to catch when they are accidentally swapped. */
|
|
typedef enum
|
|
{
|
|
MBEDTLS_MPI_MOD_EXT_REP_INVALID = 0,
|
|
MBEDTLS_MPI_MOD_EXT_REP_LE = 8,
|
|
MBEDTLS_MPI_MOD_EXT_REP_BE
|
|
} mbedtls_mpi_mod_ext_rep;
|
|
|
|
typedef struct
|
|
{
|
|
mbedtls_mpi_uint *p;
|
|
size_t limbs;
|
|
} mbedtls_mpi_mod_residue;
|
|
|
|
typedef void *mbedtls_mpi_mont_struct;
|
|
typedef void *mbedtls_mpi_opt_red_struct;
|
|
|
|
typedef struct {
|
|
const mbedtls_mpi_uint *p;
|
|
size_t limbs; // number of limbs
|
|
size_t bits; // bitlen of p
|
|
mbedtls_mpi_mod_ext_rep ext_rep; // signals external representation (eg. byte order)
|
|
mbedtls_mpi_mod_rep_selector int_rep; // selector to signal the active member of the union
|
|
union rep
|
|
{
|
|
mbedtls_mpi_mont_struct mont;
|
|
mbedtls_mpi_opt_red_struct ored;
|
|
} rep;
|
|
} mbedtls_mpi_mod_modulus;
|
|
|
|
/** Setup a residue structure.
|
|
*
|
|
* \param r The address of residue to setup. The size is determined by \p m.
|
|
* (In particular, it must have at least as many limbs as the
|
|
* modulus \p m.)
|
|
* \param m The address of the modulus related to \p r.
|
|
* \param p The address of the limb array storing the value of \p r. The
|
|
* memory pointed to by \p p will be used by \p r and must not be
|
|
* modified in any way until after mbedtls_mpi_mod_residue_release()
|
|
* is called.
|
|
* \param pn The number of limbs of \p p.
|
|
*
|
|
* \return \c 0 if successful.
|
|
* \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \p pn is less than the limbs
|
|
* in \p m or if \p p is not less than \p m.
|
|
*/
|
|
int mbedtls_mpi_mod_residue_setup( mbedtls_mpi_mod_residue *r,
|
|
mbedtls_mpi_mod_modulus *m,
|
|
mbedtls_mpi_uint *p,
|
|
size_t pn );
|
|
|
|
/** Unbind elements of a residue structure.
|
|
*
|
|
* This function removes the reference to the limb array that was passed to
|
|
* mbedtls_mpi_mod_residue_setup() to make it safe to free or use again.
|
|
*
|
|
* This function invalidates \p r and it must not be used until after
|
|
* mbedtls_mpi_mod_residue_setup() is called on it again.
|
|
*
|
|
* \param r The address of residue to release.
|
|
*/
|
|
void mbedtls_mpi_mod_residue_release( mbedtls_mpi_mod_residue *r );
|
|
|
|
/** Initialize a modulus structure.
|
|
*
|
|
* \param m The address of a modulus.
|
|
*/
|
|
void mbedtls_mpi_mod_modulus_init( mbedtls_mpi_mod_modulus *m );
|
|
|
|
/** Setup a modulus structure.
|
|
*
|
|
* \param m The address of the modulus structure to populate.
|
|
* \param p The address of the limb array storing the value of \p m. The
|
|
* memory pointed to by \p p will be used by \p m and must not
|
|
* be modified in any way until after
|
|
* mbedtls_mpi_mod_modulus_free() is called.
|
|
* \param pn The number of limbs of \p p.
|
|
* \param ext_rep The external representation to be used for residues
|
|
* associated with \p m (see #mbedtls_mpi_mod_ext_rep).
|
|
* \param int_rep The internal representation to be used for residues
|
|
* associated with \p m (see #mbedtls_mpi_mod_rep_selector).
|
|
*
|
|
* \return \c 0 if successful.
|
|
* \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \p ext_rep or \p int_rep is
|
|
* invalid.
|
|
*/
|
|
int mbedtls_mpi_mod_modulus_setup( mbedtls_mpi_mod_modulus *m,
|
|
const mbedtls_mpi_uint *p,
|
|
size_t pn,
|
|
mbedtls_mpi_mod_ext_rep ext_rep,
|
|
mbedtls_mpi_mod_rep_selector int_rep );
|
|
|
|
/** Free elements of a modulus structure.
|
|
*
|
|
* This function frees any memory allocated by mbedtls_mpi_mod_modulus_setup().
|
|
*
|
|
* \warning This function does not free the limb array passed to
|
|
* mbedtls_mpi_mod_modulus_setup() only removes the reference to it,
|
|
* making it safe to free or to use it again.
|
|
*
|
|
* \param m The address of a modulus.
|
|
*/
|
|
void mbedtls_mpi_mod_modulus_free( mbedtls_mpi_mod_modulus *m );
|
|
|
|
#endif /* MBEDTLS_BIGNUM_MOD_H */
|