mpi.h File Reference

MPI (Multiple Precision Integer Arithmetic) More...

#include <stdio.h>
#include "core/crypto.h"

Go to the source code of this file.

Data Structures

struct  Mpi
 Arbitrary precision integer. More...
 

Macros

#define MPI_MAX_BIT_SIZE   4096
 
#define MPI_INT_SIZE   sizeof(uint_t)
 
#define MPI_MAX_INT_SIZE   ((MPI_MAX_BIT_SIZE + (MPI_INT_SIZE * 8) - 1) / (MPI_INT_SIZE * 8))
 
#define MPI_CHECK(f)   if((error = f) != NO_ERROR) goto end
 
#define mpiIsEven(a)   !mpiGetBitValue(a, 0)
 
#define mpiIsOdd(a)   mpiGetBitValue(a, 0)
 

Enumerations

enum  MpiFormat { MPI_FORMAT_LITTLE_ENDIAN = 0, MPI_FORMAT_BIG_ENDIAN = 1 }
 MPI import/export format. More...
 

Functions

void mpiInit (Mpi *r)
 Initialize a multiple precision integer. More...
 
void mpiFree (Mpi *r)
 Release a multiple precision integer. More...
 
error_t mpiGrow (Mpi *r, uint_t size)
 Adjust the size of multiple precision integer. More...
 
uint_t mpiGetLength (const Mpi *a)
 Get the actual length in words. More...
 
uint_t mpiGetByteLength (const Mpi *a)
 Get the actual length in bytes. More...
 
uint_t mpiGetBitLength (const Mpi *a)
 Get the actual length in bits. More...
 
error_t mpiSetBitValue (Mpi *r, uint_t index, uint_t value)
 Set the bit value at the specified index. More...
 
uint_t mpiGetBitValue (const Mpi *a, uint_t index)
 Get the bit value at the specified index. More...
 
int_t mpiComp (const Mpi *a, const Mpi *b)
 Compare two multiple precision integers. More...
 
int_t mpiCompInt (const Mpi *a, int_t b)
 Compare a multiple precision integer with an integer. More...
 
int_t mpiCompAbs (const Mpi *a, const Mpi *b)
 Compare the absolute value of two multiple precision integers. More...
 
error_t mpiCopy (Mpi *r, const Mpi *a)
 Copy a multiple precision integer. More...
 
error_t mpiSetValue (Mpi *a, int_t b)
 Set the value of a multiple precision integer. More...
 
error_t mpiRand (Mpi *r, uint_t length, const PrngAlgo *prngAlgo, void *prngContext)
 Generate a random value. More...
 
error_t mpiRandRange (Mpi *r, const Mpi *p, const PrngAlgo *prngAlgo, void *prngContext)
 Generate a random value in the range 1 to p-1. More...
 
error_t mpiCheckProbablePrime (const Mpi *a)
 Test whether a number is probable prime. More...
 
error_t mpiImport (Mpi *r, const uint8_t *data, uint_t length, MpiFormat format)
 Octet string to integer conversion. More...
 
error_t mpiExport (const Mpi *a, uint8_t *data, uint_t length, MpiFormat format)
 Integer to octet string conversion. More...
 
error_t mpiAdd (Mpi *r, const Mpi *a, const Mpi *b)
 Multiple precision addition. More...
 
error_t mpiAddInt (Mpi *r, const Mpi *a, int_t b)
 Add an integer to a multiple precision integer. More...
 
error_t mpiSub (Mpi *r, const Mpi *a, const Mpi *b)
 Multiple precision subtraction. More...
 
error_t mpiSubInt (Mpi *r, const Mpi *a, int_t b)
 Subtract an integer from a multiple precision integer. More...
 
error_t mpiAddAbs (Mpi *r, const Mpi *a, const Mpi *b)
 Helper routine for multiple precision addition. More...
 
error_t mpiSubAbs (Mpi *r, const Mpi *a, const Mpi *b)
 Helper routine for multiple precision subtraction. More...
 
error_t mpiShiftLeft (Mpi *r, uint_t n)
 Left shift operation. More...
 
error_t mpiShiftRight (Mpi *r, uint_t n)
 Right shift operation. More...
 
error_t mpiMul (Mpi *r, const Mpi *a, const Mpi *b)
 Multiple precision multiplication. More...
 
error_t mpiMulInt (Mpi *r, const Mpi *a, int_t b)
 Multiply a multiple precision integer by an integer. More...
 
error_t mpiDiv (Mpi *q, Mpi *r, const Mpi *a, const Mpi *b)
 Multiple precision division. More...
 
error_t mpiDivInt (Mpi *q, Mpi *r, const Mpi *a, int_t b)
 Divide a multiple precision integer by an integer. More...
 
error_t mpiMod (Mpi *r, const Mpi *a, const Mpi *p)
 Modulo operation. More...
 
error_t mpiAddMod (Mpi *r, const Mpi *a, const Mpi *b, const Mpi *p)
 Modular addition. More...
 
error_t mpiSubMod (Mpi *r, const Mpi *a, const Mpi *b, const Mpi *p)
 Modular subtraction. More...
 
error_t mpiMulMod (Mpi *r, const Mpi *a, const Mpi *b, const Mpi *p)
 Modular multiplication. More...
 
error_t mpiInvMod (Mpi *r, const Mpi *a, const Mpi *p)
 Modular inverse. More...
 
error_t mpiExpMod (Mpi *r, const Mpi *a, const Mpi *e, const Mpi *p)
 Modular exponentiation. More...
 
error_t mpiExpModFast (Mpi *r, const Mpi *a, const Mpi *e, const Mpi *p)
 Modular exponentiation (fast calculation) More...
 
error_t mpiExpModRegular (Mpi *r, const Mpi *a, const Mpi *e, const Mpi *p)
 Modular exponentiation (regular calculation) More...
 
error_t mpiMontgomeryMul (Mpi *r, const Mpi *a, const Mpi *b, uint_t k, const Mpi *p, Mpi *t)
 Montgomery multiplication. More...
 
error_t mpiMontgomeryRed (Mpi *r, const Mpi *a, uint_t k, const Mpi *p, Mpi *t)
 Montgomery reduction. More...
 
void mpiMulAccCore (uint_t *r, const uint_t *a, int_t m, const uint_t b)
 Multiply-accumulate operation. More...
 
void mpiDump (FILE *stream, const char_t *prepend, const Mpi *a)
 Display the contents of a multiple precision integer. More...
 

Detailed Description

MPI (Multiple Precision Integer Arithmetic)

License

SPDX-License-Identifier: GPL-2.0-or-later

Copyright (C) 2010-2024 Oryx Embedded SARL. All rights reserved.

This file is part of CycloneCRYPTO Open.

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.

Author
Oryx Embedded SARL (www.oryx-embedded.com)
Version
2.4.4

Definition in file mpi.h.

Macro Definition Documentation

◆ MPI_CHECK

#define MPI_CHECK (   f)    if((error = f) != NO_ERROR) goto end

Definition at line 52 of file mpi.h.

◆ MPI_INT_SIZE

#define MPI_INT_SIZE   sizeof(uint_t)

Definition at line 46 of file mpi.h.

◆ MPI_MAX_BIT_SIZE

#define MPI_MAX_BIT_SIZE   4096

Definition at line 40 of file mpi.h.

◆ MPI_MAX_INT_SIZE

#define MPI_MAX_INT_SIZE   ((MPI_MAX_BIT_SIZE + (MPI_INT_SIZE * 8) - 1) / (MPI_INT_SIZE * 8))

Definition at line 49 of file mpi.h.

◆ mpiIsEven

#define mpiIsEven (   a)    !mpiGetBitValue(a, 0)

Definition at line 55 of file mpi.h.

◆ mpiIsOdd

#define mpiIsOdd (   a)    mpiGetBitValue(a, 0)

Definition at line 56 of file mpi.h.

Enumeration Type Documentation

◆ MpiFormat

enum MpiFormat

MPI import/export format.

Enumerator
MPI_FORMAT_LITTLE_ENDIAN 
MPI_FORMAT_BIG_ENDIAN 

Definition at line 68 of file mpi.h.

Function Documentation

◆ mpiAdd()

error_t mpiAdd ( Mpi r,
const Mpi a,
const Mpi b 
)

Multiple precision addition.

Parameters
[out]rResulting integer R = A + B
[in]aFirst operand A
[in]bSecond operand B
Returns
Error code

Definition at line 787 of file mpi.c.

◆ mpiAddAbs()

error_t mpiAddAbs ( Mpi r,
const Mpi a,
const Mpi b 
)

Helper routine for multiple precision addition.

Parameters
[out]rResulting integer R = |A + B|
[in]aFirst operand A
[in]bSecond operand B
Returns
Error code

Definition at line 941 of file mpi.c.

◆ mpiAddInt()

error_t mpiAddInt ( Mpi r,
const Mpi a,
int_t  b 
)

Add an integer to a multiple precision integer.

Parameters
[out]rResulting integer R = A + B
[in]aFirst operand A
[in]bSecond operand B
Returns
Error code

Definition at line 836 of file mpi.c.

◆ mpiAddMod()

error_t mpiAddMod ( Mpi r,
const Mpi a,
const Mpi b,
const Mpi p 
)

Modular addition.

Parameters
[out]rResulting integer R = A + B mod P
[in]aThe first operand A
[in]bThe second operand B
[in]pThe modulus P
Returns
Error code

Definition at line 1509 of file mpi.c.

◆ mpiCheckProbablePrime()

error_t mpiCheckProbablePrime ( const Mpi a)

Test whether a number is probable prime.

Parameters
[in]aPointer to a multiple precision integer
Returns
Error code

Definition at line 581 of file pic32cx_bz_crypto_pkc.c.

◆ mpiComp()

int_t mpiComp ( const Mpi a,
const Mpi b 
)

Compare two multiple precision integers.

Parameters
[in]aThe first multiple precision integer to be compared
[in]bThe second multiple precision integer to be compared
Returns
Comparison result

Definition at line 338 of file mpi.c.

◆ mpiCompAbs()

int_t mpiCompAbs ( const Mpi a,
const Mpi b 
)

Compare the absolute value of two multiple precision integers.

Parameters
[in]aThe first multiple precision integer to be compared
[in]bThe second multiple precision integer to be compared
Returns
Comparison result

Definition at line 409 of file mpi.c.

◆ mpiCompInt()

int_t mpiCompInt ( const Mpi a,
int_t  b 
)

Compare a multiple precision integer with an integer.

Parameters
[in]aMultiple precision integer to be compared
[in]bInteger to be compared
Returns
Comparison result

Definition at line 382 of file mpi.c.

◆ mpiCopy()

error_t mpiCopy ( Mpi r,
const Mpi a 
)

Copy a multiple precision integer.

Parameters
[out]rPointer to a multiple precision integer (destination)
[in]aPointer to a multiple precision integer (source)
Returns
Error code

Definition at line 447 of file mpi.c.

◆ mpiDiv()

error_t mpiDiv ( Mpi q,
Mpi r,
const Mpi a,
const Mpi b 
)

Multiple precision division.

Parameters
[out]qThe quotient Q = A / B
[out]rThe remainder R = A mod B
[in]aThe dividend A
[in]bThe divisor B
Returns
Error code

Definition at line 1343 of file mpi.c.

◆ mpiDivInt()

error_t mpiDivInt ( Mpi q,
Mpi r,
const Mpi a,
int_t  b 
)

Divide a multiple precision integer by an integer.

Parameters
[out]qThe quotient Q = A / B
[out]rThe remainder R = A mod B
[in]aThe dividend A
[in]bThe divisor B
Returns
Error code

Definition at line 1416 of file mpi.c.

◆ mpiDump()

void mpiDump ( FILE *  stream,
const char_t prepend,
const Mpi a 
)

Display the contents of a multiple precision integer.

Parameters
[in]streamPointer to a FILE object that identifies an output stream
[in]prependString to prepend to the left of each line
[in]aPointer to a multiple precision integer

Definition at line 2028 of file mpi.c.

◆ mpiExpMod()

error_t mpiExpMod ( Mpi r,
const Mpi a,
const Mpi e,
const Mpi p 
)

Modular exponentiation.

Parameters
[out]rResulting integer R = A ^ E mod P
[in]aPointer to a multiple precision integer
[in]eExponent
[in]pModulus
Returns
Error code

Definition at line 202 of file esp32_crypto_pkc.c.

◆ mpiExpModFast()

error_t mpiExpModFast ( Mpi r,
const Mpi a,
const Mpi e,
const Mpi p 
)

Modular exponentiation (fast calculation)

Parameters
[out]rResulting integer R = A ^ E mod P
[in]aPointer to a multiple precision integer
[in]eExponent
[in]pModulus
Returns
Error code

Definition at line 143 of file m460_crypto_pkc.c.

◆ mpiExpModRegular()

error_t mpiExpModRegular ( Mpi r,
const Mpi a,
const Mpi e,
const Mpi p 
)

Modular exponentiation (regular calculation)

Parameters
[out]rResulting integer R = A ^ E mod P
[in]aPointer to a multiple precision integer
[in]eExponent
[in]pModulus
Returns
Error code

Definition at line 225 of file m460_crypto_pkc.c.

◆ mpiExport()

error_t mpiExport ( const Mpi a,
uint8_t *  data,
uint_t  length,
MpiFormat  format 
)

Integer to octet string conversion.

Converts an integer to an octet string of a specified length

Parameters
[in]aNon-negative integer to be converted
[out]dataOctet string resulting from the conversion
[in]lengthIntended length of the resulting octet string
[in]formatOutput format
Returns
Error code

Definition at line 709 of file mpi.c.

◆ mpiFree()

void mpiFree ( Mpi r)

Release a multiple precision integer.

Parameters
[in,out]rPointer to the multiple precision integer to be freed

Definition at line 64 of file mpi.c.

◆ mpiGetBitLength()

uint_t mpiGetBitLength ( const Mpi a)

Get the actual length in bits.

Parameters
[in]aPointer to a multiple precision integer
Returns
The actual bit count

Definition at line 234 of file mpi.c.

◆ mpiGetBitValue()

uint_t mpiGetBitValue ( const Mpi a,
uint_t  index 
)

Get the bit value at the specified index.

Parameters
[in]aPointer to a multiple precision integer
[in]indexPosition where to read the bit
Returns
The actual bit value

Definition at line 313 of file mpi.c.

◆ mpiGetByteLength()

uint_t mpiGetByteLength ( const Mpi a)

Get the actual length in bytes.

Parameters
[in]aPointer to a multiple precision integer
Returns
The actual byte count

Definition at line 195 of file mpi.c.

◆ mpiGetLength()

uint_t mpiGetLength ( const Mpi a)

Get the actual length in words.

Parameters
[in]aPointer to a multiple precision integer
Returns
The actual length in words

Definition at line 168 of file mpi.c.

◆ mpiGrow()

error_t mpiGrow ( Mpi r,
uint_t  size 
)

Adjust the size of multiple precision integer.

Parameters
[in,out]rA multiple precision integer whose size is to be increased
[in]sizeDesired size in words
Returns
Error code

Definition at line 94 of file mpi.c.

◆ mpiImport()

error_t mpiImport ( Mpi r,
const uint8_t *  data,
uint_t  length,
MpiFormat  format 
)

Octet string to integer conversion.

Converts an octet string to a non-negative integer

Parameters
[out]rNon-negative integer resulting from the conversion
[in]dataOctet string to be converted
[in]lengthLength of the octet string
[in]formatInput format
Returns
Error code

Definition at line 624 of file mpi.c.

◆ mpiInit()

void mpiInit ( Mpi r)

Initialize a multiple precision integer.

Parameters
[in,out]rPointer to the multiple precision integer to be initialized

Definition at line 48 of file mpi.c.

◆ mpiInvMod()

error_t mpiInvMod ( Mpi r,
const Mpi a,
const Mpi p 
)

Modular inverse.

Parameters
[out]rResulting integer R = A^-1 mod P
[in]aThe multiple precision integer A
[in]pThe modulus P
Returns
Error code

Definition at line 356 of file pic32cx_bz_crypto_pkc.c.

◆ mpiMod()

error_t mpiMod ( Mpi r,
const Mpi a,
const Mpi p 
)

Modulo operation.

Parameters
[out]rResulting integer R = A mod P
[in]aThe multiple precision integer to be reduced
[in]pThe modulus P
Returns
Error code

Definition at line 1444 of file mpi.c.

◆ mpiMontgomeryMul()

error_t mpiMontgomeryMul ( Mpi r,
const Mpi a,
const Mpi b,
uint_t  k,
const Mpi p,
Mpi t 
)

Montgomery multiplication.

Parameters
[out]rResulting integer R = A * B / 2^k mod P
[in]aAn integer A such as 0 <= A < 2^k
[in]bAn integer B such as 0 <= B < 2^k
[in]kAn integer k such as P < 2^k
[in]pModulus P
[in]tAn preallocated integer T (for internal operation)
Returns
Error code

Definition at line 1877 of file mpi.c.

◆ mpiMontgomeryRed()

error_t mpiMontgomeryRed ( Mpi r,
const Mpi a,
uint_t  k,
const Mpi p,
Mpi t 
)

Montgomery reduction.

Parameters
[out]rResulting integer R = A / 2^k mod P
[in]aAn integer A such as 0 <= A < 2^k
[in]kAn integer k such as P < 2^k
[in]pModulus P
[in]tAn preallocated integer T (for internal operation)
Returns
Error code

Definition at line 1950 of file mpi.c.

◆ mpiMul()

error_t mpiMul ( Mpi r,
const Mpi a,
const Mpi b 
)

Multiple precision multiplication.

Parameters
[out]rResulting integer R = A * B
[in]aFirst operand A
[in]bSecond operand B
Returns
Error code

Definition at line 75 of file esp32_crypto_pkc.c.

◆ mpiMulAccCore()

void mpiMulAccCore ( uint_t r,
const uint_t a,
int_t  m,
const uint_t  b 
)

Multiply-accumulate operation.

Parameters
[out]rResulting integer
[in]aFirst operand A
[in]mSize of A in words
[in]bSecond operand B

Definition at line 1980 of file mpi.c.

◆ mpiMulInt()

error_t mpiMulInt ( Mpi r,
const Mpi a,
int_t  b 
)

Multiply a multiple precision integer by an integer.

Parameters
[out]rResulting integer R = A * B
[in]aFirst operand A
[in]bSecond operand B
Returns
Error code

Definition at line 1314 of file mpi.c.

◆ mpiMulMod()

error_t mpiMulMod ( Mpi r,
const Mpi a,
const Mpi b,
const Mpi p 
)

Modular multiplication.

Parameters
[out]rResulting integer R = A * B mod P
[in]aThe first operand A
[in]bThe second operand B
[in]pThe modulus P
Returns
Error code

Definition at line 60 of file mimxrt1160_crypto_pkc.c.

◆ mpiRand()

error_t mpiRand ( Mpi r,
uint_t  length,
const PrngAlgo prngAlgo,
void *  prngContext 
)

Generate a random value.

Parameters
[out]rPointer to a multiple precision integer
[in]lengthDesired length in bits
[in]prngAlgoPRNG algorithm
[in]prngContextPointer to the PRNG context
Returns
Error code

Definition at line 515 of file mpi.c.

◆ mpiRandRange()

error_t mpiRandRange ( Mpi r,
const Mpi p,
const PrngAlgo prngAlgo,
void *  prngContext 
)

Generate a random value in the range 1 to p-1.

Parameters
[out]rPointer to a multiple precision integer
[in]pThe upper bound of the range
[in]prngAlgoPRNG algorithm
[in]prngContextPointer to the PRNG context
Returns
Error code

Definition at line 564 of file mpi.c.

◆ mpiSetBitValue()

error_t mpiSetBitValue ( Mpi r,
uint_t  index,
uint_t  value 
)

Set the bit value at the specified index.

Parameters
[in]rPointer to a multiple precision integer
[in]indexPosition of the bit to be written
[in]valueBit value
Returns
Error code

Definition at line 275 of file mpi.c.

◆ mpiSetValue()

error_t mpiSetValue ( Mpi r,
int_t  a 
)

Set the value of a multiple precision integer.

Parameters
[out]rPointer to a multiple precision integer
[in]aValue to be assigned to the multiple precision integer
Returns
Error code

Definition at line 484 of file mpi.c.

◆ mpiShiftLeft()

error_t mpiShiftLeft ( Mpi r,
uint_t  n 
)

Left shift operation.

Parameters
[in,out]rThe multiple precision integer to be shifted to the left
[in]nThe number of bits to shift
Returns
Error code

Definition at line 1111 of file mpi.c.

◆ mpiShiftRight()

error_t mpiShiftRight ( Mpi r,
uint_t  n 
)

Right shift operation.

Parameters
[in,out]rThe multiple precision integer to be shifted to the right
[in]nThe number of bits to shift
Returns
Error code

Definition at line 1178 of file mpi.c.

◆ mpiSub()

error_t mpiSub ( Mpi r,
const Mpi a,
const Mpi b 
)

Multiple precision subtraction.

Parameters
[out]rResulting integer R = A - B
[in]aFirst operand A
[in]bSecond operand B
Returns
Error code

Definition at line 864 of file mpi.c.

◆ mpiSubAbs()

error_t mpiSubAbs ( Mpi r,
const Mpi a,
const Mpi b 
)

Helper routine for multiple precision subtraction.

Parameters
[out]rResulting integer R = |A - B|
[in]aFirst operand A
[in]bSecond operand B
Returns
Error code

Definition at line 1021 of file mpi.c.

◆ mpiSubInt()

error_t mpiSubInt ( Mpi r,
const Mpi a,
int_t  b 
)

Subtract an integer from a multiple precision integer.

Parameters
[out]rResulting integer R = A - B
[in]aFirst operand A
[in]bSecond operand B
Returns
Error code

Definition at line 913 of file mpi.c.

◆ mpiSubMod()

error_t mpiSubMod ( Mpi r,
const Mpi a,
const Mpi b,
const Mpi p 
)

Modular subtraction.

Parameters
[out]rResulting integer R = A - B mod P
[in]aThe first operand A
[in]bThe second operand B
[in]pThe modulus P
Returns
Error code

Definition at line 1532 of file mpi.c.