Low Level Routines

In these routines a big parameter can also be used wherever a flash is specified, but not vice versa. Further information may be gleaned from the (lightly) commented source code. An asterisk after the name indicates that the function does not take a mip parameter if MR_GENERIC_MT is defined in mirdef.h.

Gives absolute value of a big or flash number.

Parameters:

←|x The number whose absolute value is to be computed
→y = |x|

Adds two big numbers.

Parameters:

←x
→y
→z = x + y

Example:

add(x, x, x); // This doubles the value of x

Converts a positive big number into a binary octet string. Error checking is carried out to ensure that the function does not write beyond the limits of ptr if max > 0. If max = 0, no checking is carried out. If max > 0 and justify = TRUE, the output is right-justified, otherwise leading zeros are supressed.

Parameters:

←max Maximum number of octets to be written in ptr
←x The original big number
→ptr Destination of the binary octet string
→justify If TRUE, the output is right-justified, otherwise leading zeros are supressed.

Returns:

The number of bytes generated in ptr. If justify = TRUE then the return value is max.

Precondition:

max must be greater than 0 if justify = TRUE

Generates a big random number of given length. Uses the built-in simple random number generator initialised by irand().

Parameters:

←n The desired length of the random big number
→x The random number

Generates random integer number.

Returns:

A random integer number.

Precondition:

First use must be preceded by an initial call to irand().

This generator is not cryptographically strong. For cryptographic applications, use the strong_rng() routine.

Converts a binary octet string to a big number. Binary to big conversion.

Parameters:

←len Length of ptr
←ptr Byte array of the binary octet string
→x Big result

Example:

#include <stdio.h>
#include "miracl.h"

int main()
{
int i, len;
miracl *mip = mirsys(100, 0);
big x, y;
char b[200]; // b needs space allocated to it
x = mirvar(0); // all big variables need to be "mirvar"ed
y = mirvar(0);

expb2(100, x);
incr(x, 3, x); // x = 2^100 + 3

len = big_to_bytes(200, x, b, FALSE);
// Now b contains big number x in raw binary
// It is len bytes in length

// now print out the raw binary number b in hex
for (i = 0; i < len; i++) printf("%02x", b[i]);
printf("n");

// now convert it back to big format, and print it out again
bytes_to_big(len, b, y);
mip->IOBASE = 16;
cotnum(y, stdout);

return 0;
}

Inputs a flash/big number from the keyboard or a file, using as number base the current value of the instance variable miracl::IOBASE. Flash numbers can be entered using either a slash '/' to indicate numerator and denominator, or with a radix point.

Parameters:

→x Big/flash number

←filep File descriptor. For input from the keyboard specify stdin, otherwise as the descriptor of some other opened file.

To force input of a fixed number of bytes, set the instance variable miracl::INPLEN to the required number, just before calling cinnum().

Example:

mip->IOBASE = 256;
mip->INPLEN = 14; // this inputs 14 bytes from fp and
cinnum(x, fp); // converts them into big number x

Inputs a flash/big number from a character string, using as number base the current value of the instance variable miracl::IOBASE. Flash numbers can be input using a slash '/' to indicate numerator and denominator, or with a radix point.

Parameters:

→x
←string

Returns:

The number of input characters.

Example:

// input large hex number into big x
mip->IOBASE = 16;
cinstr(x, "AF12398065BFE4C96DB723A");

Compares two big numbers.

Parameters:

←x
→y

Returns:

+1 if x > y; 0 if x = y; -1 if x < y

Converts an integer number to big number format.

Parameters:

←n
→x

Copies a big/flash number to another.

Parameters:

←x
→y= x

Parameters:If x and y are the same variable, no operation is performed.[/notice]

Outputs a big/flash number to the screen or to a file, using as number base the value currently assigned to the instance variable miracl::IOBASE. A flash number will be converted to radix-point representation if the instance variable miracl::RPOINT = ON. Otherwise it will output as a fraction.

Parameters:

←x Big/flash number to be output
→filep File descriptor. If stdout then output will be to the screen, otherwise to the file opened with descriptor filep.

Returns:

Number of output characters.

Example:

// This outputs x in hex, to the file associated with fp
mip->IOBASE = 16;
cotnum(x, fp);

Outputs a big/flash number to the specified string, using as number base the value currently assigned to the instance variable miracl::IOBASE. A flash number will be converted to radix-point representation if the instance variable miracl::RPOINT = ON. Otherwise it will be output as a fraction.

Parameters:

←x
→string

Returns:

Number of output characters.

There is nothing to prevent this routine from overflowing the limits of the user supplied character array string, causing obscure runtime problems. It is the programmer's responsibility to ensure that string is big enough to contain the number output to it. Alternatively use the internally declared instance string miracl::IOBUFF, which is of size miracl::IOBSIZ. If this array overflows a MIRACL error will be flagged.

Decrements a big number by an integer amount.

Parameters:

←x
←n
→z = x − n

Divides one big number by another: z = x/y, x = x (mod y). The quotient only is returned if x and z are the same, the remainder only if y and z are the same.

Parameters:

←→x
→y
→z

Precondition:

Parameters x and y must be different, and y must be non-zero.

See also: normalise()

Tests a big number for divisibility by another.

Parameters:

←x
→y

Returns:

TRUE if y divides x exactly, otherwise FALSE.

Precondition:

The parameter y must be non-zero.

Reserves space for a number elliptic curve points in one heap access. Individual points can subsequently be initialised from this memory by calling epoint_init_mem().

Parameters:

←num The number of elliptic curve points to reserve space for.

Returns:

A pointer to the allocated memory.

Deletes and sets to zero the memory previously allocated by ecp_memalloc().

Parameters:

→mem Pointer to the memory to be erased and deleted
←num The size of the memory in elliptic curve points

Precondition:

Must be preceded by a call to ecp_memalloc().

Extracts the sign of a big/flash number.

Parameters:

←x A big/flash number

Returns:

The sign of x, i.e. -1 if x is negative, +1 if x is zero or positive.

Gets the current Miracl Instance Pointer.

Returns:

The mip (Miracl Instance Pointer) for the current thread.

Precondition:

This function does not exist if MR_GENERIC_MT is defined.

Extracts a digit from a big number.

Parameters:

←x A big number
→i The position of the digit to be extracted from x

Returns:

The value of the requested digit.

Returns rubbish if required digit does not exist.

Calculates the Greatest Common Divisor of two integers using Euclid's Method.

Parameters:

←x
←y

Returns:

The GCD of x and y.

Increments a big number.

Parameters:

←x
←n
→z = x + n

Example:

incr(x, 2, x); // This increments x by 2

Initialises a big variable from ROM memory.

Parameters:

→rx A big number
←len Length of the big number in computer words
←rom Address of ROM memory which stores up to romsize computer words
←romsize
←→romptr A pointer into ROM. This pointer is incremented internally as ROM memory is accessed to fill x

Returns:

TRUE if successful, or FALSE if an attempt is made to read beyond the end of the ROM.

Initialises an elliptic curve point from ROM memory.

Parameters:

→P An elliptic curve point
←len Length of the two big coordinates of P, in computer words
←rom Address of ROM memory which stores up to romsize computer words
←romsize
←→romptr A pointer into ROM. This pointer is incremented internally as ROM memory is accessed to fill P

Returns:

TRUE if successful, or FALSE if an attempt is made to read beyond the end of the ROM.

Inputs a big/flash number from a file or the keyboard, using as number base the value specified in the initial call to mirsys(). Flash numbers can be entered using either a slash '/' to indicate numerator and denominator, or with a radix point.

Parameters:

→x A big/flash number
←filep A file descriptor. For input from the keyboard specify stdin, otherwise the descriptor of some other opened file.

Returns:

The number of characters input.

Precondition:

The number base specified in mirsys() must be less than or equal to 256. If not use cinnum() instead.

For fastest inputting of ASCII text to a big number, and if a full-width base is possible, use mirsys(...,256) initially. This has the same effect as specifying mirsys(...,0), except that now ASCII bytes may be input directly via innum(x, fp) without the time-consuming change of base implicit in the use of cinnum().

Forces a big/flash number to a particular sign.

Parameters:

←s The sign the big/flash is to take
→x = s|x|

Example:

insign(PLUS, x); // force x to be positive

Inputs a big or flash number from a character string, using as number base the value specified in the initial call to mirsys(). Flash numbers can be entered using either a slash '/' to indicate numerator and denominator, or with a radix point.

Parameters:

→x
←string

Returns:

The number of characters input.

Precondition:

The number base specified in mirsys() must be less than or equal to 256. If not use cinstr() instead.

Initialises internal random number system. Long integer types are used internally to yield a generator with maximum period.

Parameters:

←seed A seed used to start off the random number generator.

Converts a long integer to big number format.

Parameters:

←n
→x

Multiplies, adds and divides big numbers. The initial product is stored in a double-length internal variable to avoid the possibility of overflow at this stage.

Parameters:

←x
←y
←z
←w
→q = (xy + z)/w
→r The remainder

If w and q are not distinct variables then only the remainder is returned; if q and r are not distinct then only the quotient is returned. The addition of z is not done if x and z (or y and z) are the same.

Precondition:

Parameters w and r must be distinct. The value of w must not be zero.

Example:

mad(x, x, x, w, x, x,); // x = x^2 / w

Reserves space for big/flash variables in one heap access. Individual big/flash variables can subsequently be initialised from this memory by calling mirvar_mem().

Parameters:

←num The number of big/flash variables to reserve space for.

Returns:

A pointer to the allocated memory

Deletes and sets to zero the memory previously allocated by memalloc().

Parameters:

→mem A pointer to the memory to be erased and deleted
←len The size of that memory in bigs

Precondition:

Must be preceded by a call to memalloc()

Cleans up after the current instance of MIRACL, and frees all internal variables. A subsequent call to mirsys() will re-initialise the MIRACL system.

Precondition:

Must be called after mirsys().

Securely kills off a big/flash number by zeroising it, and freeing its memory.

Parameters:

←x.

Initialises the MIRACL system for the current program thread, as described below. Must be called before attempting to use any other MIRACL routines

  1. The error tracing mechanism is initialised.
  2. The number of computer words to use for each big/flash number is calculated from nd and nb.
  3. Sixteen big work variables (four of them double length) are initialised.
  4. Certain instance variables are given default initial values.
  5. The random number generator is started by calling irand(0L).

Parameters:

←nd The number of digits to use for each big/flash variable. If negative, it is taken as indicating the size of big/flash numbers in 8-bit bytes
→nb The number base

Returns:

The Miracl Instance Pointer, via which all instance variables can be accessed, or NULL if there was not enough memory to create an instance

Precondition:

The number base nb should normally be greater than 1 and less than or equal to MAXBASE. A base of 0 implies that the 'full-width' number base should be used. The number of digits nd must be less than a certain maximum, depending on the underlying type mr_utype and on whether or not MR_FLASH is defined

Example:

// This initialises the MIRACL system to use 500 decimal digits for each
// big or flash number
miracl *mip = mirsys(500, 10);

Initialises a big/flash variable by reserving a suitable number of memory locations for it. This memory may be released by a subsequent call to the function mirkill().

Parameters:

←iv An integer initial value for the big/flash number

Returns:

A pointer to the reserved memory

Example:

flash x;
x = mirvar(8); // Creates a flash variable x = 8

Initialises memory for a big/flash variable from a pre-allocated byte array mem. This array may be created from the heap by a call to memalloc(), or in some other way. This is quicker than multiple calls to mirvar().

Parameters:

←mem A pointer to the pre-allocated array
←index An index into that array. Each index should be unique

Returns:

An initialised big/flash variable

Precondition:

Sufficient memory must have been allocated and pointed to by mem.

Multiplies two big numbers.

Parameters:

←x
←y
→z = xy

Negates a big/flash number.

Parameters:

←x
→y = - x

negify(x,x) is valid and sets x = - x

Multiplies a big number such that its most significant word is greater than half the number base. If such a number is used as a divisor by divide(), the division will be carried out faster. If many divisions by the same divisor are required, it makes sense to normalise the divisor just once beforehand.

Parameters:

←x
→y = nx

Returns:

n, the normalising multiplier

Use with care. Used internally.

Determines the number of digits in a big number.

Parameters:

←x

Returns:

The number of digits in x.

Outputs a big/flash number to the screen or to a file, using as number base the value specified in the initial call to mirsys(). A flash number will be converted to radix-point representation if the instance variable miracl::RPOINT = ON. Otherwise it will be output as a fraction.

Parameters:

←x A big/flash number
←filep A file descriptor. If stdout then output will be to the screen, otherwise to the file opened with descriptor filep

Returns:

Number of output characters

Precondition:

The number base specified in mirsys() must be less than or equal to 256. If not, use cotnum() instead.

Outputs a big or flash number to the specified string, using as number base the value specified in the initial call to mirsys(). A flash number will be converted to radix-point representation if the instance variable miracl::RPOINT = ON. Otherwise it will be output as a fraction.

Parameters:

←x A big/flash number
→string A representation of x

Returns:

Number of output characters

Precondition:

The number base specified in mirsys() must be less than or equal to 256. If not, use cotstr() instead

There is nothing to prevent this routine from overflowing the limits of the user supplied character array string, causing obscure runtime problems. It is the programmer's responsibility to ensure that string is big enough to contain the number output to it. Alternatively use the internally declared instance string miracl::IOBUFF, which is of size miracl::IOBSIZ. If this array overflows a MIRACL error will be flagged.

Multiplies a big number by an integer.

Parameters:

←x
←n
→z = nx

Sets a digit of a big number to a given value.

Parameters:

←n The new value for the digit
→x A big number
←i A digit position

Precondition:

The digit indicated must exist.

Finds the integer remainder, when a big number is divided by an integer.

Parameters:

←x
←n

Returns:

The integer remainder.

Sets the size of the input/output buffer. By default this is set to 1024, but programs that need to handle very large numbers may require a larger I/O buffer.

Parameters:

←len The size of I/O buffer required

Destroys the current contents of the I/O buffer.

Supplies a user-specified function, which is periodically called during some of the more time-consuming MIRACL functions, particularly those involved in modular exponentiation and in finding large prime numbers. The supplied function must take no parameters and return a BOOL value. Normally this should be TRUE. If FALSE then MIRACL will attempt to abort its current operation. In this case the function should continue to return FALSE until control is returned to the calling program. The user-supplied function should normally include only a few instructions, and no loops, otherwise it may adversely impact the speed of MIRACL functions

Once MIRACL is initialised, this function may be called multiple times with a new supplied function. If no longer required, call with a NULL parameter.

Parameters:

←user A pointer to a user-supplied function, or NULL if not required

Example:

// Windows Message Pump
static BOOL idle()
{
MSG msg;
if (PeekMessage(&msg, NULL, 0, 0, PM_NOREMOVE))
{
if (msg.message != WM_QUIT)
{
if (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE))
{
// do a Message Pump
TranslateMessage(&msg);
DispatchMessage(&msg);
}
}
else
return FALSE;
}
return TRUE;
}
...
set_user_function(idle);

Tries to convert big number to a simple integer. Also useful for testing the sign of big/flash variable as in: if (size(x) < 0) ...

Parameters:

←x A big number

Returns:

The value of x as an integer. If this is not possible (because x is too big) it returns the value plus or minus MR_TOOBIG.

Divides a big number by an integer

Parameters:

←x
←n
→z = x/n

Returns:

The integer remainder

Precondition:

The value of n must not be zero.

Tests a big number for divisibility by an integer.

Parameters:

←x
←n

Returns:

TRUE if n divides x exactly, otherwise FALSE

Precondition:

The value of n must not be zero.

Subtracts two big numbers.

Parameters:

←x
←y
→z = x − y

Sets a big/flash number to zero.

Parameters:

→x