miracl常用函数手册

把之前写过的md整理一下

最近某电的密码学实验需要用的miracl大数库，这里把官方文档里的一些常用函数做一个总结，便于查找使用。

absol

函数原型：void absol(x,y)

flash x,y or big x,y

功能：取x的绝对值，y=|x|

add

函数原型：void add(x,y,z)

参数类型：big x,y,z

功能：z=x+y

brand

函数原型：int brand()

功能：返回值一个随机整数

限制：首次使用前必须先调用irand。

注意：此生成器的加密能力不强。对于加密应用程序，请使用强例程。

bigbits

函数原型：void bigbits(n,x)

参数类型：int n, big x

功能：产生一个n位的大整数，初始化随机种子由irand函数实现

  irand(time(NULL));（头文件#include<time.h>）

big_to_bytes

函数原型：int big_to_bytes(max,x,ptr,justify)

参数类型：int max;big x;char *ptr;BOOL justify

功能：描述：将正数x转换为二进制八位字符串

参数：大数字x和字节数组ptr，长度最大。进行错误检查，以确保函数在最大值>0时不会超出ptr的限制。如果max=0，则不执行检查。如果max>0且justify=TRUE，则输出将正确对齐，否则将抑制前导零。

返回值：在ptr中生成的字节数。如果justify=TRUE，则返回值为max。

限制：如果“正当性”为TRUE，则最大值必须大于0

bytes_to_big

函数原型：void bytes_to_big(len,ptr,x)

参数类型：int len; char *ptr; big x;

功能：将二进制八位字节字符串转换为大数字。二进制到大的转换。

参数：指向长度为len的字节数组ptr的指针，以及一个大的结果x。

cinnum

函数原型：int cinnum(x,f)

参数类型：flash x; FILE *f

描述:从键盘或文件中输入一个flash数字，以实例变量IOBASE的当前值作为基数。可以使用斜杠“/”来表示分子和分母，也可以使用基数点输入闪存数。

参数：一个big/flash数字x和一个文件描述符f。从键盘输入时，将f指定为stdin，否则指定为其他打开文件的描述符。要强制输入固定数量的字节，请在调用cinnum之前将实例变量INPLEN设置为所需的数量。

返回值：输入字符数。

cinstr

函数原型：int cinstr(x,s)

参数类型：flash x; char *s

功能说明: 将大数字符串转换成大数

参数：一个大的/flash数字x和一个字符串s。

返回值：输入字符数

eg:

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

compare

函数原型：int compare(x,y)

参数类型：big x; big y

函数功能：比较两个大数的大小

返回值：x>y时返回+1, x=y时返回0, x<y时返回-1 在这里需要注意的是，compare()函数比较的是两个big类型的数，此函数的返回值是int型的+1和-1

注意:if(1)和if(-1)的结果相同

convert

函数原型：void convert (n,x)

参数类型：int n; big x

函数功能：将一个整数n转换成一个大数x

copy

函数原型：void copy(big x, big y);

参数类型：flash x,y big x ,y

函数功能：y=x

cotnum

函数原型：int cotnum(x,f)

参数类型：flash x;FILE *f

描述：将当前分配给实例变量IOBASE的值作为基数，输出一个大的或闪烁的数字到屏幕或文件中。如果实例变量RPOINT=ON，则flash数字将转换为基数点表示。否则它将作为分数输出。

参数一个大的/闪存号x和一个文件描述符f。如果f是stdout，则输出到屏幕，否则输出到用描述符f打开的文件。

返回值：输出字符数。

eg：

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

cotstr

函数原型：int cotstr(x,s)

参数类型：flash x; char *s

函数功能：将一个大数根据其进制转换成一个字符串

返回值: 字符串长度

decr

函数原型：void decr(x,n,z)

参数类型：big x,z; int n

功能说明: 将一个大数减去一个整数， z=x-n.

divide

函数原型：void divide(x,y,z)

参数类型：big x,y,z

功能：两个大数相除，z=x/y; x=x mod y，当变量y和z相同时，x为余数，商不返回（即y的值不变）；当x和z相同时，x为商，余数不返回。

注意：Example: divide(x,y,y);//x为余数，y值不

ecp_memalloc

ecp_memkill

exsign

getdig

函数原型：int getdig(x,i)

参数类型：big x; int i

描述：从一个大数字中提取一个数字。

参数：一个大的数字x，和所需的数字i。

返回值：请求的数字的值。

限制：如果所需数字不存在，则返回垃圾。

igcd

函数原型：int igcd(x,y)

参数类型：int x,y

功能：使用欧几里德方法计算两个整数的最大公约数

返回值：x和y的GCD

incr

函数原型：void incr(x,n,z)

参数类型：big x,z ; int n

功能：z=x+n

eg:

incr（x，2，x）；/*这将使x增加2。*/

innum

函数原型：int innum(x,f)

参数类型：flash x; FILE *f

insign

函数原型：void insign(s,x)

参数类型：int s; flash x

功能:

instr

函数原型：int instr(x,s)

参数类型：flash x; char *s

功能：

irand

函数原型：void irand(seed)

参数类型：long seed

功能：初始化内部随机数系统

lgconv

函数原型：void lgconv(ln,x)

参数类型：long ln; big x

功能：将长整数转换为大数格式

mad

函数原型：void mad(x,y,z,w,q,r)

参数类型：big x,y,z,w,q,r

功能：q=(x.y+z)/w，r为余数，如果w和q不是不同的变量，则只返回余数；如果q和r不是不同的，则只返回商。如果x和z（或y和z）相同，则不会进行z的加法。

memalloc

函数原型：void *memalloc(n)

参数类型：int n

功能：：在一个堆访问中为n个大变量保留空间。随后，可以通过调用mirvar_mem从该内存初始化单个大/闪存变量

返回值：指向已分配内存的指针

memkill

函数原型：void memkill(mem,n)

参数类型：char *mem; int n

功能：删除memalloc先前分配的内存并将其设置为

mirexit

函数原型：void mirexit()

功能：在MIRACL的当前实例之后清理，并释放所有内部变量。随后调用mirsys将重新初始化MIRACL系统（清除MIRACL系统，释放所有内部变量）

mirkill

函数原型：void mirkill(x)

参数类型：big x

功能：释放内存大数所占的内存清除MIRACL系统，释放所有内部变量。

mirsys

函数原型：miracl *mirsys（nd,nb）

参数类型：int nd,nb

功能：初始化MIRACL系统，该函数必须在调用MIRACL库函数之前先执行

 miracl *mip=mirsys(500,10);//初始化500位的10进行制数
//意思是我定义的这些变量最大长度都是500位（这个位是后面进制的位数），输入、输出、运算用的进制都是10进制。

mirvar

函数原型：flash mirvar(iv)

参数类型：int iv

功能：通过为big/flash变量保留适当数量的内存位置来初始化该变量。这个内存可以通过随后调用mirkill函数来释放

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

mirvar_mem

函数原型：flash mirvar_mem(mem,index)

参数类型：char *mem； int index

功能：从预先分配的字节数组mem初始化big/flash变量的内存

返回值：初始化的big/flash变量

限制：mem必须已经分配并指向足够的内存

multiply

函数原型：void multiply(x,y,z)

参数类型：big x,y,z

功能：z=x*y

negify

函数原型：void negify(x,y)

参数类型：flash x,y

功能：大数取反，y=-x

normalise

函数原型：int normalise(x,y)

参数类型：big x,y

功能：y=nx

返回值：n

nroot

函数原型：BOOL nroot(x,n,z)

参数类型：big x,z; int n;

功能:

返回值；如果找到的根是精确的，则返回布尔值TRUE，否则返回FALSE。

numdig

函数原型：int numdig(x)

参数类型：big x

功能：返回大数x中数字的个数（位数）

otnum

函数原型：int otnum(x,f)

参数类型：flash x; FILE *f

功能：使用mirsys初始调用中指定的值作为基数，向屏幕或文件输出一个big或flash数字如果实例变量RPOINT=ON，则flash数字将转换为基数点表示。否则它将作为分数输出

返回值：输出字符数。

限制：mirsys中指定的基数必须小于或等于256。如果没有，请改用cotnum

otstr

函数原型：int otstr(x,s)

参数类型：flash x; char *s

功能：将在对mirsys的初始调用中指定的值作为基数，向指定的字符串输出一个大big或flash数字如果实例变量RPOINT=ON，则flash数字将转换为基数点表示。否则它将作为分数输出

premult

函数原型：void premult(x,n,z)

参数类型：int n; big x,z

功能：z=nx

putdig

函数原型：void putdig(n,x,i)

参数类型：big x ; int i,n

功能：将一个大数的数字设置为给定值，n为新值

remian

函数原型：int remian(x,n)

参数类型：big x;int n

功能：当一个大数除以一个整数时，查找整数余数

返回值：余数

set_io_buffer_size

函数原型：void set_io_buffer_size(len)

参数类型：int len

功能：设置输入/输出缓冲区的大小。默认设置为1024，但需要处理非常大的数字的程序可能需要更大的I/O缓冲区

void set_user_function

函数原型：void set_user_function(func)

参数类型：BOOL (*user)(void)

功能：提供一个用户指定的函数，该函数在一些比较耗时的MIRACL函数中定期调用，特别是那些涉及模幂运算和寻找大素数的函数

size

函数原型：int size(x)

参数类型：big x

功能：尝试将大数转换为简单整数。也可用于测试big/flash变量的符号

subdivisible

函数原型：BOOL subdivisible(x,n)

参数类型：big x; int n;

功能：测试n能否整除x

返回值: x除以n余数为0，返回TRUE，否则返回FALSE

subtract

函数原型：void subtract(x,y,z)

参数类型：big x,y,z

功能：z=x-y

zero

函数类型：void zero(x)

参数类型：flash x

功能：将x置零

bigdig

函数原型：void bigdig(n,b,x)

参数类型：int n,b ; big x

功能：产生一个指定长度的进制的随机数，该函数使用内置的随机数发生器，初始化种子调用irand函数

x是生成的大数 n位长 b是进制

bigdig（100,10,x）；
//这将生成一个100位十进制随机数

bigrand

函数原型：void bigrand(w,x)

参数类型：big w,x;

功能：生成一个大的随机数。使用由irand初始化的内置简单随机数生成器，0<=x<w

两个函数的区别：

两个函数都是可以生成随机数的，但是它们的功能确实略有差异的。bigrand()是产生一个小于w的大数随机数，x<w，如果w是一个十位的十进制数，那么x可能是一个十位的十进制数，只有九位的十进制数，也可能使只有一位的十进制数；bigdig()是产生一个指定长度的进制的随机数，比如说指定了产生一个十位的十进制数，那么这个函数就会严格的产生一个十位的十进制数。

egcd

函数原型：int egcd(x,y,z)

参数类型：big x,y,z;

功能：计算两个大数的最大公约数， z=gcd(x,y)

expb2

函数原型：void expb2(n,x)

参数类型： int n; big x;

功能：计算2的n次方的大数 x=2^n.

expb2(1398269,x);   //2^1398269decr(x,1,x);        //x = x - 1mip->IOBASE=10;     //使用10进制cotnum(x,stdout);   //输出到屏幕

expint

函数原型：void expint（b, n, x）

参数类型：int b,n; big x;

功能：计算b的n次方的大数 x=b^n.

fft_mult

函数原型：void fft_mult(x,y,z)

参数类型：big x,y,z;

功能：使用Fast Fourier算法计算两个大数乘积，z=x*y

gprime

函数原型：void gprime(n)

参数类型：int n

功能：将达到某个限制的所有素数生成实例数组素数，并以零结尾

hamming

函数原型：int hamming(n)

参数类型：big n

功能：计算一个大数的汉明权重–汉明距离（实际上是二进制表示中的1的数目）

invers

函数原型：unsigned int invers(x,y)

参数原型：unsigned int x,y;

功能：计算两个无符号整数（要求互素）的模逆，返回x-1 mod y

isprime

函数原型：BOOL isprime(x)

参数类型：big x;

功能：判断一个大数是否为素数，使用概率测试算法

返回值：x为素数返回TRUE，否则返回FALSE

jac

函数原型：int jac(x,n)

参数类型：unsigned int x,n;

功能：计算雅可比符号的值

jack

函数原型：int jack(x,n)

参数类型：big x,n

功能：计算雅可比符号的值

logb2

函数原型：int logb2(x)

参数类型：big x;

功能：计算一个大数（实际上是其中的位数）的基数2的近似整数log

lucas

函数原型：void lucas(x,e,n,vp,v)

参数类型：big x,e,n,vp,v

功能：执行Lucas模幂运算。在内部使用蒙哥马利算法。通过调用特殊的汇编语言例程来实现Montgomery算法，可以为特定的模块进一步加速该函数。见powmod

power

函数原型： void power(x,n,z,w)

参数类型： long n; big x,z,w;

功能：w=xn.如果w≠z则w=xn mod z

powmod

函数原型：void powmod(x,y,z,w)

参数类型：big x,y,z,w;

功能：模幂运算，w=x^y mod z

sfbit

函数原型：void sftbit(x,n,z)

参数类型：big x,z;int n;

功能：将一个大数左移或右移n位，n为正数时左移，负数时右移

xgcd

函数原型：int xgcd(x,y,xd,yd,z)

参数类型： big x,y,xd,yd,z;

功能：计算两个大数的扩展最大公约数，也可以用来计算模逆，这个函数比mad 函数运算速度稍慢。z=gcd(x,y)=x.xd+y.yd

xgcd(x,p,x,x,x);  //计算x^-1 mod p
/* x = 1/x mod p  (p is prime) *

https://wenku.baidu.com/view/1738a6878762caaedd33d4b4.html?sxts=1602327937928&word=miracl%E5%BA%93%E6%89%8B%E5%86%8C

xgcd(Mi1, m1, Mj1, Mj1, Mj1);//Mj1为Mi1的逆
xgcd(Mi2, m2, Mj2, Mj2, Mj2);//Mj2为Mi2的逆
xgcd(Mi3, m3, Mj3, Mj3, Mj3);//Mj3为Mi3的逆

//扩展的欧几里得算法
//Input
x = 13
y = 17
xgcd(x, y, xd, yd, z)
//Output
xd = 4
yd = 3
z = 1

实例变量IOBASE

IOBASE是用于控制输入和输出的进制问题的，可以在程序中随意更改，必须大于或等于2且小于或等于256。使用实例是像这样的：mip->IOBASE=16，这样子输入的变量和输出的变量所使用的进制都是十六进制