Low Level Routines

In these routines a big parameter can also be used wherever a flash is specified, but not visa-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 .

Function:

void absol(x,y)

flash x,y;
Module Description Parameters Return value Restrictions
mrcore.c Gives absolute value of a big or flash number. Two big/flash variables x and y. On exit y=[absolute value of]x. None None

Function:

void add(x,y,z)

big x,y,z;
Module Description Parameters Return value Restrictions
mrarth0.c Adds two big numbers. Three big numbers x, y and z. On exit z=x+y. None None

Example:

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

Function:

int brand()
Module Description Parameters Return value Restrictions
mrcore.c Generates random integer number None A random integer number 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.

Function:

void bigbits(n,x)

int n;

big x;
Module Description Parameters Return value Restrictions
mrbits.c Generates a big random number of given length. Uses the built-in simple random number generator initialised by irand. A big number x and an integers n. On exit x contains a big random number n bits long. None None

Example:

bigbits(100,x);  /* This generates a 100-bit random number */

Function:

int big_to_bytes(max,x,ptr,justify)

int max;

big x;

char *ptr;

BOOL justify
Module Description Parameters Return value Restrictions
arth1.c Converts a positive big number x into a binary octet string A big number x and a byte array ptr of length max. 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 suppressed. The number of bytes generated in ptr. If justify=TRUE then the return value is max. max must be greater than 0 if justify=TRUE

Function:

void bytes_to_big(len,ptr,x)

int len;

char *ptr;

big x;
Module Description Parameters Return value Restrictions
mrarth1.c Converts a binary octet string to a big number. Binary to big conversion. A pointer to a byte array ptr of length len, and a big result x. None None

Example:

/*

 *  test program to exercise big_to_bytes() and bytes_to_big()

 */

#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");

    bytes_to_big(len,b,y);

 /* now convert it back to big format, and print it out again */

    mip->IOBASE=16;

    cotnum(y,stdout);

    return 0;

}

Function:

int cinnum(x,f)

flash x;

FILE *f;
Module Description Parameters Return value Restrictions
mrio2.c Inputs a flash number from the keyboard or a file, using as number base the current value of the instance variable IOBASE. Flash numbers can be entered using either a slash '/' to indicate numerator and denominator, or with a radix point. A big/flash number x and a file descriptor f. For input from the keyboard specify f as stdin, otherwise as the descriptor of some other opened file. To force input of a fixed number of bytes, set the instance variable INPLEN to the required number, just before calling cinnum. The number of input characters. None

Example:

mip->IOBASE=256;

mip->INPLEN=14;  /* This inputs 14 bytes from fp and */

cinnum(x,fp);  /* converts them into big number x  */

Function:

int cinstr(x,s)

flash x;

char *s;
Module Description Parameters Return value Restrictions
mrio2.c Inputs a flash number from a character string, using as number base the current value of the instance variable IOBASE. Flash numbers can be input using a slash '/' to indicate numerator and denominator, or with a radix point. A big/flash number x and a string s. The number of input characters. None

Example:

/* input large hex number into big x */

mip->IOBASE=16;

cinstr(x,"AF12398065BFE4C96DB723A");

Function:

int compare(x,y)

big x,y;
Module Description Parameters Return value Restrictions
mrcore.c Compares two big numbers. Two big numbers x and y. Returns +1 if x>y, returns 0 if x=y, returns -1 if x<y. None

Function:

void convert(n,x)

int n;

big x;
Module Description Parameters Return value Restrictions
mrcore.c Convert an integer number to big number format. An integer n and a big number x. None None

Function:

void copy(x,y)

flash x,y;
Module Description Parameters Return value Restrictions
mrcore.c Copies a big or flash number to another. Two big or flash numbers x and y. On exit y=x. Note that if x and y are the same variable, no operation is performed. None None

Function:

int cotnum(x,f)

flash x;

FILE *f;
Module Description Parameters Return value Restrictions
mrio2.c Output a big or flash number to the screen or to a file, using as number base the value currently assigned to the instance variable IOBASE. A flash number will be converted to radix-point representation if the instance variable RPOINT=ON. Otherwise it will be output as a fraction. A big/flash number x and a file descriptor f. If f is stdout then output will be to the screen, otherwise to the file opened with descriptor f. Number of output characters. None

Example:

mip->IOBASE=16;

cotnum(x,fp);

This outputs x in hex, to the file associated with fp.

Function:

int cotstr(x,s)

flash x;

char *s;
Module Description Parameters Return value Restrictions
mrio2.c Output a big or flash number to the specified string, using as number base the value currently assigned to the instance variable IOBASE. A flash number will be converted to radix-point representation if the instance variable RPOINT=ON. Otherwise it will be output as a fraction. A big/flash number x and a string s. On exit s will contain a representation of the number x. Number of output characters. Note that there is nothing to prevent this routine from overflowing the limits of the user supplied character array s, causing obscure runtime problems. It is the programmers responsibility to ensure that s is big enough to contain the number output to it. Alternatively use the internally declared instance string IOBUFF, which is of size IOBSIZ. If this array overflows a MIRACL error will be flagged.

Function:

void decr(x,n,z)

big x,z;

int n;
Module Description Parameters Return value Restrictions
mrarth0.c Decrement a big number by an integer amount. Big numbers x and z, and integer n. On exit z=x-n. None None

Function:

void divide(x,y,z)

big x,y,z;
Module Description Parameters Return value Restrictions
mrarth2.c Divides one big number by another. Three big numbers x, y and z. On exit 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. None Parameters x and y must be different, and y must be non-zero.

Example:

divide(x,y,y);  /* This sets x equal to the remainder when x is divided by y. The quotient is not returned. */

Function:

BOOL divisible(x,y)

big x,y;
Module Description Parameters Return value Restrictions
mrarth2.c Tests a big number for divisibility by another Two big numbers x and y. TRUE if y divides x exactly, otherwise FALSE The parameter y must be non-zero.

Function:

void ecp_memalloc(n)

int n;
Module Description Parameters Return value Restrictions
mrcore.c Reserves space for n elliptic curve points in one heap access. Individual points can subsequently be initialised from this memory by calling epoint_init_mem. The number n of elliptic curve points to reserve space for. A pointer to the allocated memory. None

Function:

void ecp_memkill(mem,n)

char *mem;

int n;
Module Description Parameters Return value Restrictions
mrcore.c Deletes and sets to zero the memory previously allocated by ecp_memalloc A pointer to the memory to be erased and deleted, and the size of that memory in elliptic curve points. None Must be preceded by a call to ecp_memalloc

Function:

int exsign(x)

flash x;
Module Description Parameters Return value Restrictions
mrcore.c Extracts the sign of a big/flash number. A big/flash number x. The sign of x, i.e. -1 if x is negative, +1 if x is zero or positive. None

Function:

int getdig(x,i)

big x;

int i;
Module Description Parameters Return value Restrictions
mrcore.c Extracts a digit from a big number. A big number x, and the required digit i. The value of the requested digit. Returns rubbish if required digit does not exist.

Function:

miracl get_mip(void)
Module Description Parameters Return value Restrictions
mrcore.c Get the current Miracl Instance Pointer None The mip - Miracl Instance Pointer – for the current thread. This function does not exist if MR_GENERIC_MT is defined.

Function:

int igcd(x,y)

int x,y;
Module Description Parameters Return value
mrcore.c Calculates the Greatest Common Divisor of two integers using Euclids Method. Two integers x and y The GCD of x and y

Function:

void incr(x,n,z)

big x,z;

int n;
Module Description Parameters Return value Restrictions
mrarth0.c Increment a big variable. Big numbers x and z, and an integer n. On exit z=x+n. None None

Example:

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

Function:

BOOL init_big_from_rom(big,int,const mr_small*,int,int*)

big x;

int len;

const mr_small *rom;

int romsize;

int *romptr;
Module Description Parameters Return value
mrcore.c Initialises a big variable from ROM memory. A big number x and its length in computer words. The address of ROM memory which stores up to romsize computer words, and a pointer into the ROM. This pointer is incremented internally as ROM memory is accessed to fill x. TRUE if successful, or FALSE if an attempt is made to read beyond the end of the ROM

Function:

BOOL init_point_from_rom(epoint *,int,const mr_small*,int,int*)

epoint *P;

int len;

const mr_small *rom;

int romsize;

int *romptr;
Module Description Parameters Return value
mrcore.c Initialises an elliptic curve point from ROM memory. An elliptic curve point P and its length of its two big coordinates in computer words. The address of ROM memory which stores up to romsize computer words, and a pointer into the ROM. This pointer is incremented internally as ROM memory is accessed to fill P. TRUE if successful, or FALSE if an attempt is made to read beyond the end of the ROM

Function:

int innum(x,f)
flash x;
FILE *f;
Module Description Parameters Return value Restrictions
mrio1.c Inputs a big or 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. A big/flash number x and a file descriptor f. For input from the keyboard specify f as stdin, otherwise as the descriptor of some other opened file. The number of characters input. 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.

Function:

void insign(s,x)

int s;

flash x;
Module Description Parameters Return value Restrictions
mrcore.c Forces a big/flash number to a particular sign. A big/flash number x, and the sign s that it is to take. On exit x=s.[absolute value of]x. None None

Example:

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

Function:

int instr(x,s)

flash x;

char *s;
Module Description Parameters Return value Restrictions
mrio1.c 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. A big/flash number x and a character string s. The number of characters input. The number base specified in mirsys must be less than or equal to 256. If not use cinstr instead.

Function:

void irand(seed)

long seed;
Module Description Parameters Return value Restrictions
mrcore.c Initializes internal random number system. Long integer types are used internally to yield a generator with maximum period. A long integer seed, which is used to start off the random number generator. None None

Function:

void lgconv(ln,x)

long ln;

big x;
Module Description Parameters Return value Restrictions
mrcore.c Converts a long integer to big number format A long integer ln and a big number x None None

Function:

void mad(x,y,z,w,q,r)

big x,y,z,w,q,r;
Module Description Parameters Return value Restrictions
mrarth2.c Multiply add and divide big numbers. The initial product is stored in a double-length internal variable to avoid the possibility of overflow at this stage. Six big numbers x,y,z,w,q and r. On exit q=(x.y+z)/w and r contains 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. None 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 */

Function:

void memalloc(n)

int n;
Module Description Parameters Return value Restrictions
mrcore.c Reserves space for n big variables in one heap access. Individual big/flash variables can subsequently be initialised from this memory by calling mirvar_mem. The number n of big/flash variables to reserve space for. A pointer to the allocated memory. None

Function:

void memkill(mem,n)

char *mem;

int n;
Module Description Parameters Return value Restrictions
mrcore.c Deletes and sets to zero the memory previously allocated by memalloc A pointer to the memory to be erased and deleted, and the size of that memory in bigs. None Must be preceded by a call to memalloc

Function:

void mirexit()
Module Description Parameters Return value Restrictions
mrcore.c Cleans up after the current instance of MIRACL, and frees all internal variables. A subsequent call to mirsys will re-initialise the MIRACL system. None None Must be called after mirsys.

Function:

void mirkill(x)

big x;
Module Description Parameters Return value Restrictions
mrcore.c Securely kills off a big/flash number by zeroising it, and freeing its memory. A big/flash number x. None None

Function:

miracl mirsys(nd,nb)

int nd,nb;
Module Description Parameters Return value Restrictions
mrcore.c Initialise 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). The number of digits nd to use for each big/flash variable and the number base nb. If nd is negative it is taken as indicating the size of big/flash numbers in 8-bit bytes. The Miracl Instance Pointer, via which all instance variables can be accessed, or NULL if there was not enough memory to create an instance. 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. (See mirdef.h)

Example:

miracl *mip=mirsys(500,10);

This initialises the MIRACL system to use 500 decimal digits for each big or flash number.

Function:

flash mirvar(iv)

int iv;
Module Description Parameters Return value Restrictions
mrcore.c 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. An integer initial value for the big/flash number. A pointer to the reserved memory. None

Example:

flash x;

x=mirvar(8);

Creates a flash variable x=8.

Function:

flash mirvar_mem(mem,index)

char *mem;

int index;
Module Description Parameters Return value Restrictions
mrcore.c 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. A pointer to the pre-allocated array mem, and an index into that array. Each index should be unique. An initialised big/flash variable Sufficient memory must have been allocated and pointed to by mem.

Example:

See brent.c for an example of use.

Function: void multiply(x,y,z)

big x,y,z;
Module Description Parameters Return value Restrictions
mrarth2.c Multiplies two big numbers Three big numbers x,y and z. On exit z=x.y None None

Function:

void negify(x,y)

flash x,y;
Module Description Parameters Return value Restrictions
mrcore.c Negates a big/flash number. Two big/flash numbers x and y. On exit y=-x. None None. Note that negify(x,x) is valid and sets x=-x

Function:

int normalise(x,y)

big x,y;
Module Description Parameters Return value Restrictions
mrarth2.c 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. Two big numbers x and y. On exit y=n.x. Returns n, the normalising multiplier. Use with care. Used internally.

Function:

int numdig(x)

big x;
Module Description Parameters Return value Restrictions
mrcore.c Determines the number of digits in a big number. A big number x. The number of digits in x. None

Function:

int otnum(x,f)

flash x;

FILE *f;
Module Description Parameters Return value Restrictions
mrio1.c Output a big or 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 RPOINT=ON. Otherwise it will be output as a fraction. A big/flash number x and a file descriptor f. If f is stdout then output will be to the screen, otherwise to the file opened with descriptor f. Number of output characters. The number base specified in mirsys must be less than or equal to 256. If not, use cotnum instead.

Function:

int otstr(x,s)

flash x;

char *s;
Module Description Parameters Return value Restrictions
mrio1.c Output 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 RPOINT=ON. Otherwise it will be output as a fraction. A big/flash number x and a character string s. On exit s will contain a representation of x. Number of output characters. The number base specified in mirsys must be less than or equal to 256. If not, use cotstr instead. Note that there is nothing to prevent this routine from overflowing the limits of the user supplied character array s, causing obscure runtime problems. It is the programmers responsibility to ensure that s is big enough to contain the number output to it. Alternatively use the internally declared instance string IOBUFF, which is of size IOBSIZ. If this array overflows a MIRACL error will be flagged.

Function:

void premult(x,n,z)

int n

big x,z;
Module Description Parameters Return value Restrictions
mrarth1.c Multiplies a big number by an integer Two big numbers x and z, and an integer n. On exit z=n.x None

Function:

void putdig(n,x,i)

big x;

int i,n;
Module Description Parameters Return value Restrictions
mrcore.c Set a digit of a big number to a given value A big number x, a digit number i, and its new value n. None The digit indicated must exist.

Function:

int remain(x,n)

big x;

int n;
Module Description Parameters Return value
mrarth1.c Finds the integer remainder, when a big number is divided by an integer. A big number x, and an integer n. The integer remainder

Function:

void set_io_buffer_size(len)

int len;
Module Description Parameters Return value Restrictions
mrcore.c 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. The size of I/O buffer required. None Destroys the current contents of the I/O buffer

Function:

void set_user_function(func)

BOOL (*user)(void);
Module Description Parameters Return value Restrictions
mrcore.c 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. A pointer to a user-supplied function, or NULL if not required. None

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);

Function:

int size(x)

big x;
Module Description Parameters Return value Restrictions
mrcore.c 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) ... A big number x. 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. None

Function:

int subdiv(x,n,z)

int n;

big x,z;
Module Description Parameters Return value Restrictions
mrarth1.c Divide a big number by an integer. Two big numbers x and z, and an integer n. On exit z=x/n. The integer remainder. The value of n must not be zero.

Function:

BOOL subdivisible(x,n)

big x;

int n;
Module Description Parameters Return value Restrictions
mrarth1.c Tests a big number for divisibility by an integer. A big number x and an integer n. TRUE is n divides x exactly, otherwise FALSE. The value of n must not be zero.

Function:

void subtract(x,y,z)

big x,y,z;
Module Description Parameters Return value Restrictions
mrarth0.c Subtracts two big numbers. Three big numbers x, y and z. On exit z=x-y. None None

Function:

void zero(x)

flash x;
Module Description Parameters Return value
mrcore.c Sets a big or flash number to zero A big or flash number x. None