miracl用户手册译 1.docx

1、miracl用户手册译 1MIRACL用户手册译：叶道全 yedaoq摘要Miracl库包含100余个例程，涉及多倍精度运算（multiprecision arithmetic）的各个方面。定义了两种新的数据类型表示大整数的big类型和表示有理数的flash（short for floating-slash）类型。大整数例程基于Knuth算法（在他的著作“The Art of Computer Programming”第四章中提出）。floating-slash（不固定斜杠？）算法基于圆整小数，最初由D.Matula和P.Kornerup提出。所有例程都针对速度和效率进行了全面的优化，同时也是

2、标准的，可移植的C程序。另外，对于某些时间要求非常严格的算法，Miracl也针对流行的Intel 80x86系列处理器提供了汇编语言实现。Miracl还提供了C+接口。Miracl的所有源代码都包含于此。第二章 安装通过Microsft C/C+、Borlands Turbo C/C+、Watcom C以及DJGPP GNU编译器，MIRACL库已经成功安装到VAX11/780，各种UNIX工作站（Sun，SPARC、Next以及IBM RS/6000），IBM PC等机器上。还有ARM机器和Apple Macintosh。最近MIRACL也已经在Itanium和AMD 64位处理器上运行过了

3、。MIRACL分发包中包含了库中所有模块的完整源代码以及各自的示例程序。大部分是用标准的ANSI C编写的，可用任意规范的ANSI C编译器进行编译。一些模块包含大量的内联汇编代码，用于优化在某些特定编译器/处理器组合上的性能。通过条件编译，它们可以透明地调用，并且不会影响到其它编译器。批处理文件xxdoit.xxx包含在多种编译器上生成库文件和示例程序的命令。请打开并检查与你的配置相关的文件。分发包包含了部分流行的编译器的预编译库文件：ready-to-run版本，它们可立即使用，为了节省空间，其中并没有包含所有的示例程序。要生成一个库，必须使用编译器，文本编译器，链接器，库管理实用程序（l

4、ibrarian utility）以及汇编器（assembler，可选），请阅读编译器文档以获取更多细节。mrmuldv.any文件包含了时间关键（time-critical）的例程muldiv，muldvd，muldvd2和muldvm的汇编语言版本，它们可能需要根据配置作一些改动。当编译器不支持一个可用于保存两个单字长整数乘积的双倍长度类型时，这些模块尤为必要。许多现代编译器支持这一点（通常称为long long），在这种情况下，一般使用这些模块的C版本mrmuldv.ccc（直接拷贝到mrmuldv.c）就足够了。更多细节请仔细阅读手册以及mrmuldv.any的注释。必须指定硬件/编译

5、器规格文件mirdef.h。为了协助此过程，提供了此头文件的五个示例：mirdef.h16（16位处理器）、mirdef.h32（32位处理器）、mirdef.haf（工作在16位模式的32位处理器）以及mirdef.hpc（工作在16位环境中的伪32位）。请注意完整的32位版本是最快的，但只是在使用一个32位处理器及一个32位编译器的时候如此。在Unix环境中使用gcc和g+时尽量用mirdef.gcc。config.c用于协助配置过程。在目标处理器上编译和运行它，它会自动生成mirdef.h文件，并给出常规的配置建议。它还生成一个miracl.lst文件，其中包含建立相关库时应包含的MIR

6、ACL模块列表。强烈建议尝试此程序。编译它时请务必关掉所有编译器优化选项。mirdef.h文件包含一些可选定义：当无法满足muldvd，muldvd2和muldvm在mrmuldv.c中的版本时，定义MR NOFULLWIDTH；若要在程序中使用flash变量，定义MR_FLASH；MR_LITTLE_ENDIAN 与 MR_BIG_ENDIAN，必须定义其中之一，config.c会自动决定哪一个适用于你的处理器。省略MR_FLASH时，big变量可以更大，并且生成的库也更小。定义MR_STRIPPED_DOWN将忽略错误消息，可以进一步节约生成的代码空间，请小心使用！如果不想要任何汇编器，请

7、定义MR_NOASM。这将以内联的方式生成四个时间关键例程的标准C代码。这稍快一些节省了函数调用的开销这也是最优编译器得考虑的一点（原文：and also gives an optimising compiler something to chew on）。使用Microsoft Visual C+时，msvisual.txt中提供了一些有用的建议。Linux操作系统对应的是linux.txt，Borland编译器用户则可以查看borland.txt。预生成库或.txt文件中提供的建议不可用的时候，通过下列步骤多半能成功地生成MIRACL库：1. 在目标处理器上编译并运行config.c。2.

8、 将生成的mirdef.tst重命名为mirdef.h。3. 根据config程序的建议，从mrmuldv.any中提取一个合适的mrmuldv.c或将标准C版本的mrmuldv.ccc拷贝到mrmuldv.c）。如果是纯汇编，则可以命名为mrmuldv.s或mrmuldv.asm。4. 如果选择了快速KCM或Comba模乘算法，则编译并运行mex.c实用程序（在任意工作站上）。使用它自动生成mrcomba.c或mrkcm.c，其中需要一个处理器/编译器规格文件xxx.mcs，同时编译器必须支持内联汇编。5. 确保编译器能访问所有MIRACL头文件。通常标志-I或/I允许访问当前目录中的所有头

9、文件。6. 编译miracl.lst文件中列出的MIRACL模块并创建库文件，通常是miracl.a或miracl.lib。这可以通过将miracl.lst编译为一个合适的批处理文件或make文件来实现。在UNIX上可以像这样简单：gcc -I. -c -O2 mr*.car rc miracl.a mr*.o7. 若要使用MIRACL的C+包装，编译所需的模块，例如zzn.cpp和（或）big.cpp等。8. 将MIRACL库和所需的任意C+模块编译并链接到你的应用程序（原文：Compile and link your application code to any C+ modules i

10、t requires and to the MIRACL library）。记住MIRACL是可移植软件，它可以移植到任意支持某个ANSI C编译器的计算机上。请注意MIRACL是一个C库，而不是C+。它总是应该作为一个C库来生成，否则你可能得到编译器错误。为在C程序中包含MIRACL例程，请在程序的开始处include头文件miracl.h（在stdio.h之后）。虽然大部分情况下使用C+包装更为可取，你也还是可以通过以下方式在C+程序中直接调用MIRACL例程：extern C#include miracl.h2.1 优化在MIRACL的上下文中，这意味着更快的速度。配置MIRACL时需要

11、作的一个关键决策就是确定要使用的底层类型（经常是int类型）。如config所要求的，通常应定义尽可能大的底层类型。如果你有一个64位处理器，你就应该可以指定一个64位的底层类型。在某些场合，使用一个双精度浮点型的底层类型可能更快。显然纯C的MIRACL产品是最慢的（当然它依然相当地快），它也是最容易入门的。这需要一种宽度是底层类型的两倍的整数类型。在这样的背景下，请注意目前大多数的编译都支持一种long long（有时称为_int64）类型，其尺寸是int的两倍。如果你的处理器是低端的RISC类型并且不支持整数乘除指令，或需要使用非常大的模数，则Karatsuba-Montgomery-Co

12、mba快速模乘技术可以使乘幂加密系统（exponentiation cryptosystems）更快。config程序将同样针对此点为你提供引导。有时用汇编语言实现mrmuldv模块会更快。这不需要双倍尺寸的数据类型。如果够幸运你的编译器也支持自动调用内联汇编，则将更变更快。可以在miracl.h中查看哪些编译器支持这种方法。为获得终极速度，可以使用mrkcm.c，mrcomba.c中实现的非常（extreme，极品）技术，kcmcomba.txt中有关于如何用mex实用程序自动生成这些文件的操作指南。2.2 从版本3升级版本4引入了MIRACL实例指针（MIRACL Instance Poi

13、nter，mip）。之前的版本使用一些全局和静态变量存储内部状态信息。这主要有两个问题。首先是为了避免冲突，这些全局变量取了一些令人费解的名字；其次是它使得开发多线程应用程序变得更困难。所以从版本4开始，这些变量声明到一个miracl结构中，作为实例变量来引用，必须通过指向miracl结构的指针来访问它们。现在全局指针是MIRACL维护的唯一全局/静态变量。它的值由负责初始化MIRACL库的mirsys例程返回。C+程序员应注意miracl与Miracl命名上的区别，mip可以通过对Miracl实例取址来获得：Miracl precision = 50;.mip = &precision;.e

14、tc2.3 多线程编程从版本4.4开始，通过若干特性，MIRACL对多线程编程提供了完整的支持。要解决的问题是MIRACL需要通过mip指针来访问许多实例相关的信息。理想的状态是没有全局变量，但MIRACL有一个这样的指针。不幸的是每个使用MIRACL的线程都需要一个属于自己的mip，用来指向它自己的独立状态信息。这是多线程的一个众所周知的焦点（原文：This is a well-known issue that arises with threads）。第一个解决方案是修改MIRACL，将mip作为所有MIRACL函数的参数来传递，用来替代全局变量。通过在mirdef.h中定义MR_GENE

15、RIC_MT，MIRACL将自动更改以支持此方式。现在（几乎所有）MIRACL例程都改为第一个参数是mip。一些简单的函数例外，它们不需要mip参数参考手册中用星号来标识它们。brent_mt.c是一个使用以这种方式建立的MIRACL库工作的示例程序。请注意这种解决方案不适用于使用MIRACL的C+包装的应用程序，只适用于直接访问MIRACL例程的C程序。另一种可选方案是使用Key，这是一种线程特定的“全局”变量。Key不是C/C+标准的一部分，而是操作系统的特殊扩展，通过特殊的函数调用来实现。MIRACL对Microsoft Windows和UNIX操作系统提供了支持。对于前者，Key称为线

16、程本地存储（Thread-Local Storage）；对于后者，MIRACL对POSIX标准接口提供了多线程支持。一个对Windows和Unix都非常有用的参考是Walmsley。对多线程的这种支持实现在模块mrcore.c中（位于文件的起始处的初始化例程mirsys中）。对于Windows，在mirdef.h中定义MR_WINDOWS_MT。对Unix则定义MR_UNIX_MT。在两种场合都有一定的程序涵义（源文：In either case there are some programming implications.）。在第一种场合中，用于保存mip的Key必须由程序的主线程初始化和

17、销毁（最后）。这些功能通过调用相应的特殊例程mr_init_threading和mr_end_threading来完成。在C+程序中，这些函数可能与全局变量的构造函数和析构函数相关联Walmsley这将确保它们会在主线程创建新的线程分支前的一个适合的时候被调用。它们必须在线程显式（或隐式）地调用missys（通过创建线程特定的Miracl实例）之前被调用。强烈建议程序在开发时不要实现对多线程的支持。只有程序经过完整的测试和调用，它才应转换到一个线程中（原文：should it be converted into a thread）。线程编程可能要求其它的操作系统的特殊机制在链接特殊的库或访问特

18、殊的堆函数方面。这里值得指出的是MIRACL堆访问都是通过mralloc.c模块完成的。threadwn.cpp程序是一个Windows C+多线程示例。阅读其中的注释它可以编译和从Windows命令提示符运行。类似地threaduc.cpp是一个Unix的多线程示例。2.4 受限环境在版本5的中，有一个对在非常小和受限的环境中的MIRACL实现的新支持。使用config实用程序，它现在支持各种时空交换（time/space trade-offs），最主要的革新是在一个不支持堆的环境中生成和使用MIRACL。通常big变量的空间从堆中分配，但通过在配置头文件中指定MR_STATIC，可以生成一

19、个总是尝试从静态内存或栈，而不是堆中分配内存的版本。这带来的主要负面影响是big变量的最大尺寸必须在编译时确定（生成库的时候）。如往常一样，在这个过程中最好让config实用程序引导你创建一个合适的配置头文件mirdef.h。对于C程序员，使用下列方式从栈中为big变量分配内存：big x, y, z;char memMR_BIG_RESERVE(3);memset(mem, 0, MR_BIG_RESERVE(3);为三个big变量分配的空间都在栈上并且被清零，然后每个变量应如下初始化：x = mirvar_mem(mem, 0);y = mirvar_mem(mem, 1);z = mir

20、var_mem(mem, 2);从单个内存块中为多个big变量分配所有空间是有意义的，那样可以更快的初始化，而且可以对变量对齐进行完整的控制编译器有时会出错。请注意big初始化函数mirvar在这种模式中不再有效，分配操作应像上面描述的那样实现。最后，可以选择性地在函数末尾调用memset来在离开前清空内存块出于保密原因，这可能很重要。请参考示例程序brent.c。这种机制在实现一个使用椭圆曲线的非常小的程序时可能非常有用。椭圆曲线要求的big数字要比其它加密技术的小得多。从栈中为椭圆曲线的点分配内存：epoint *x, *y, *z;char memMR_ECP_RESERVE(3);me

21、mset(mem, 0, MR_ECP_RESERVE(3);初始化这些点：x = epoint_init_mem(mem, 0);y = epoint_init_mem(mem, 1);z = epoint_init_mem(mem, 2);同样，在离开函数前清空相关内存是明智的。此机制对C+编程同样支持得很好，它与第7章描述的栈分配方法联合工作。pk-demo.cpp是一个使用示例。在一些极端场合中，可能要求从栈中分配所有内存。这允许使用和重用最多的内存，并且避免宝贵的RAM出现碎片。对于C程序，这可以通过在mirdef.h中定义MR_GENERIC_MT来实现。这种场合中的典型mirde

22、f.h头文件可能是这个样子的：/* MIRACL compiler/hardware definitions - mirdef.h* Copyright (c) 1988-2005 Shamus Software Ltd.*/#define MR_LITTLE_ENDIAN#define MIRACL 32#define mr_utype int#define MR_IBITS 32#define MR_LBITS 32#define mr_unsign32 unsigned int#define mr_dltype _int64#define mr_unsign64 unsigned _in

23、t64#define MR_STATIC 7#define MR_ALWAYS_BINARY#define MR_NOASM#define MAXBASE (mr_small)1(MIRACL-1)#define MR_BITSINCHAR 8#define MR_SHORT_OF_MEMORY#define MR_GENERIC_MT#define MR_STRIPPED_DOWN关于使用这种类型的头文件的示例程序，请查看ecsgen_s.c，ecsign_s.c，ecsver_s.c，ecsgen2s.c，ecsign2s.c和ecsver2s.c。这些程序使用Microsoft C+在P

24、entium上实现了非常小而快速的ECDSA密码生成，数字签名以及校验算法。ecdh.c是另一个很棒的示例，它使用导航预行计算（precomputation）来加速一个EC Diffie-Hellman实现。注意：不使用堆有一些小问题：结构不能再是可变大小的，因此在这种模式中MIRACL的许多特性都不再可用。例如中国剩余定理（Chinese remainder theorem）程序要求的导航预行计算（precomputation）就无法支持。但在一个受限环境中，有理由假定诸如导航预行计算（precomputation）将脱机实现，以使将程序固化到ROM中成为可能。MIRACL模块经过了周密的设

25、计以使对于给定的任务，应用程序都只需要从库中引入最少的模块。这可以帮助应用程序保持最小的尺寸。但是如果程序的尺寸是一个大话题（big issue），则可以手工从模块中删除不需要的函数来达到额外的节约。2.5 平台特定的信息2.5.5 Microsoft Visual C+在Microsoft C+6.0上创建MIRACL应用程序的步骤如下：1. 创建一个Win32 Console Application的空工程。2. 选择菜单“Project”“Add to Project”“File”。3. 选择“Library files(.lib)”文件类型，查找预编译的MIRACL库文件ms32.li

26、b，将它添加到工程。4. 添加一个工程的主文件（例如limlee.cpp）。5. 如果是C+主工程文件，则再添加其它所需的文件，如big.cpp、zzn.cpp等。主文件的头部注释中列出了所需的文件。6. 选择菜单“Project”“Setting”。选中C/C+ Tab页，选择“Preprocesser”目录，在“Additional Include Directoryies”中指定MIRACL头文件路径。7. 确保应用程序运行目录中的所有程序所需文件均可用，如*.key，*.dss或*.ecs等文件。8. 生成并运行程序。在Microsoft C+6.0上创建MIRACL库的步骤：1. 编

27、译并运行config.c实用程序，将生成的mirdef.tst重命名为mirdef.h。注意Microsoft C拥有一个64位整数类型_int64。2. 新一个“Win32 Static Library”类型的工程。3. 添加适当的mr*.c文件，它们在miracl.lst中列出。4. 选择菜单“Project”“Setting”。选中C/C+ Tab页，选择“Preprocesser”目录，在“Additional Include Directoryies”中指定MIRACL头文件路径。5. 编译工程生成MIRACL库。在Microsoft C+.NET上创建MIRACL应用程序的步骤：1

28、. 创建一个Win32 Console Application的空工程。2. 去掉工程中的空主文件，用MIRACL提供的文件（如limlee.cpp）将其替换。请注意现在主函数称为_tmain。3. 选择菜单“Project”“Add to Project”“File”。选择“All files”文件类型，查找预编译的MIRACL库文件ms32.lib，将它添加到工程。4. 如果是C+主工程文件，则则再添加其它所需的文件，如big.cpp、zzn.cpp等。主文件的头部注释中列出了所需的文件。5. 选择菜单“Project”“Properties”。打开C+标签页，到“Precompiled

29、Headers”，选择“Not using precompiled headers”。再打开“General”标签页，指定MIRACL头文件的路径。6. 生成并运行程序。在Microsoft C+.NET上创建MIRACL库的步骤：创建一个“Win32 Project”类型的Visual C+工程。选择“Application Settings“，选择”Static Library“。添加相应的mr*.c文件。选择“Project”“Properties”。打开C+标签页，到“Precompiled Headers”，选择“Not using precompiled headers”。再打开“

30、General”标签页，指定MIRACL头文件的路径。生成工程。若要在基于MFC Win32工程中使用MIRACL，这里有一些相关建议：1. 使用config.c实例程序生成mirdef.h，并在其中定义MR_NO_STANDARD_IO，再生成MIRACL库。2. 如果使用C+ MIRACL类，别忘了在工程设置中将big.cpp等MIRACL实现文件设置为“not using pre-compiled headers”。3. 别忘了MIRACL是一个C库，若要直接调用MIRACL例程，必须：extern C#include miracl.h使用C+时，通过C+包装来访问MIRACL可能更合适

31、。4. 要显示一个big值，先将它转换为string。见big.h头部的注释。对于Visual C+8.0，预编译的ms32.lib无法工作，必须首先生成一个新的库文件。第三章 接口 下面是一个一个计算并输出1000!（1000的阶乘）的程序：/* Program to calculate factorials.*/#include #include miracl.h /* include MIRACL system */void main()/* calculate factorial of number */big nf; /* declare big variable nf */int n;miracl *mip = mirsys(5000, 10);/* base 10, 5000 digits per big */nf = mirvar(1); /* initialise big variable nf=1 */printf(factorial programn);printf(input number n= n);scanf(%d, &n);getchar();while (n 1)premult(nf, n-, nf);