MIRACL用户手册(译)Word文档格式.docx
《MIRACL用户手册(译)Word文档格式.docx》由会员分享，可在线阅读，更多相关《MIRACL用户手册(译)Word文档格式.docx（35页珍藏版）》请在冰点文库上搜索。
要生成一个库，必须使用编译器，文本编译器，链接器，库管理实用程序（librarianutility）以及汇编器
（assembler，可选），请阅读编译器文档以获取更多细节。
mrmuldv.any文件包含了时间关键（time-critical）的例程muldiv，muldvd，muldvd2和muldvm的汇编语言版本，它们可能需要根据配置作一些改动。
当编译器不支持一个可用于保存两个单字长整数乘积的双倍长度类型时，这些模块尤为必要。
许多现代编译器支持这一点（通常称为longlong），在这种情况下，一般使用这些模块的C版本mrmuldv.ccc（直接拷贝到mrmuldv.c）就足够了。
更多细节请仔细阅读手册以及mrmuldv.any的注释。
必须指定硬件/编译器规格文件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文件，其中包含建立相关库时应包含的MIRACL模块列表。
强烈建议尝试此程序。
编译它时请务必关掉所有编译器优化选项。
mirdef.h文件包含一些可选定义：
当无法满足muldvd，muldvd2和muldvm在mrmuldv.c中的版本时，定义MRNOFULLWIDTH；
若要在程序中使用flash变量，定义MR_FLASH；
MR_LITTLE_ENDIAN与
MR_BIG_ENDIAN，必须定义其中之一，config.c会自动决定哪一个适用于你的处理器。
省略MR_FLASH时，big变量可以更大，并且生成的库也更小。
定义MR_STRIPPED_DOWN将忽略错误消息，可以进一步节约生成的代码空间，请小心使用！
如果不想要任何汇编器，请定义MR_NOASM。
这将以内联的方式生成四个时间关键例程的标准C代码。
这稍快一些——节省了函数调用的开销——这也是最优编译器得考虑的一点（原文：
andalsogivesanoptimisingcompilersomethingtochewon）。
使用MicrosoftVisualC++时，msvisual.txt中提供了一些有用的建议。
Linux操作系统对应的是
linux.txt，Borland编译器用户则可以查看borland.txt。
预生成库或.txt文件中提供的建议不可用的时候，通过下列步骤多半能成功地生成MIRACL库：
1.在目标处理器上编译并运行config.c。
2.将生成的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允许访问当前目录中的所有头文件。
6.编译miracl.lst文件中列出的MIRACL模块并创建库文件，通常是miracl.a或miracl.lib。
这可以通过将miracl.lst编译为一个合适的批处理文件或make文件来实现。
在UNIX上可以像这样简单：
gcc-I.-c-O2mr*.carrcmiracl.amr*.o
7.若要使用MIRACL的C++包装，编译所需的模块，例如zzn.cpp和（或）big.cpp等。
8.将MIRACL库和所需的任意C++模块编译并链接到你的应用程序（原文：
CompileandlinkyourapplicationcodetoanyC++modulesitrequiresandtotheMIRACLlibrary）。
记住MIRACL是可移植软件，它可以移植到任意支持某个ANSIC编译器的计算机上。
请注意MIRACL是一个C库，而不是C++。
它总是应该作为一个C库来生成，否则你可能得到编译器错误。
为在C程序中包含MIRACL例程，请在程序的开始处include头文件miracl.h（在stdio.h之后）。
虽然大部分情况下使用C++包装更为可取，你也还是可以通过以下方式在C++程序中直接调用MIRACL例程：
extern"
C"
{
#include"
miracl.h"
}
2.1优化
在MIRACL的上下文中，这意味着更快的速度。
配置MIRACL时需要作的一个关键决策就是确定要使用的底层类型（经常是int类型）。
如config所要求的，通常应定义尽可能大的底层类型。
如果你有一个64位处理器，你就应该可以指定一个64位的底层类型。
在某些场合，使用一个双精度浮点型的底层类型可能更快。
显然纯C的MIRACL产品是最慢的（当然它依然相当地快），它也是最容易入门的。
这需要一种宽度是底层类型的两倍的整数类型。
在这样的背景下，请注意目前大多数的编译都支持一种longlong（有时称为
int64）类型，其尺寸是int的两倍。
如果你的处理器是低端的RISC类型并且不支持整数乘除指令，或需要使用非常大的模数，则Karatsuba-Montgomery-Comba快速模乘技术可以使乘幂加密系统（exponentiationcryptosystems）更快。
config程序将同样针对此点为你提供引导。
有时用汇编语言实现mrmuldv模块会更快。
这不需要双倍尺寸的数据类型。
如果够幸运你的编译器也支持自动调用内联汇编，则将更变更快。
可以在miracl.h中查看哪些编译器支持这种方法。
为获得终极速度，可以使用mrkcm.c，mrcomba.c中实现的非常（extreme，极品）技术，
kcmcomba.txt中有关于如何用mex实用程序自动生成这些文件的操作指南。
2.2从版本3升级
版本4引入了MIRACL实例指针（MIRACLInstancePointer，mip）。
之前的版本使用一些全局和静态变量存储内部状态信息。
这主要有两个问题。
首先是为了避免冲突，这些全局变量取了一些令人费解的名字；
其次是它使得开发多线程应用程序变得更困难。
所以从版本4开始，这些变量声明到一个miracl结构中，作为实例变量来引用，必须通过指向miracl结构的指针来访问它们。
现在全局指针是MIRACL维护的唯一全局/静态变量。
它的值由负责初始化MIRACL库的mirsys例程返回。
C++程序员应注意miracl与Miracl命名上的区别，mip可以通过对Miracl实例取址来获得：
Miraclprecision=50;
...
mip=&
precision;
etc
2.3多线程编程
从版本4.4开始，通过若干特性，MIRACL对多线程编程提供了完整的支持。
要解决的问题是MIRACL需要通过mip指针来访问许多实例相关的信息。
理想的状态是没有全局变量，但MIRACL有一个这样的指针。
不幸的是每个使用MIRACL的线程都需要一个属于自己的mip，用来指向它自己的独立状态信息。
这是多线程的一个众所周知的焦点（原文：
Thisisawell-knownissuethatariseswiththreads）。
第一个解决方案是修改MIRACL，将mip作为所有MIRACL函数的参数来传递，用来替代全局变量。
通过在mirdef.h中定义MR_GENERIC_MT，MIRACL将自动更改以支持此方式。
现在（几乎所有）MIRACL例程都改为第一个参数是mip。
一些简单的函数例外，它们不需要mip参数——参考手册中用星号来标识它们。
brent_mt.c是一个使用以这种方式建立的MIRACL库工作的示例程序。
请注意这种解决方案不适用于使用
MIRACL的C++包装的应用程序，只适用于直接访问MIRACL例程的C程序。
另一种可选方案是使用Key，这是一种线程特定的“全局”变量。
Key不是C/C++标准的一部分，而是操作系统的特殊扩展，通过特殊的函数调用来实现。
MIRACL对MicrosoftWindows和UNIX操作系统提供了支持。
对于前者，Key称为线程本地存储（Thread-LocalStorage）；
对于后者，MIRACL对POSIX标准接口提供了多线程支持。
一个对Windows和Unix都非常有用的参考是[Walmsley]。
对多线程的这种支持实现在模块mrcore.c中（位于文件的起始处的初始化例程mirsys中）。
对于Windows，在mirdef.h中定义MR_WINDOWS_MT。
对Unix则定义MR_UNIX_MT。
在两种场合都有一定的程序涵义（源文：
Ineithercasetherearesomeprogrammingimplications.）。
在第一种场合中，用于保存mip的Key必须由程序的主线程初始化和销毁（最后）。
这些功能通过调用相应的特殊例程mr_init_threading和mr_end_threading来完成。
在C++程序中，这些函数可能与全局变量的构造函数和析构函数相关联[Walmsley]——这将确保它们会在主线程创建新的线程分支前的一个适合的时候被调用。
它们必须在线程显式（或隐式）地调用missys（通过创建线程特定的Miracl实例）之前被调用。
强烈建议程序在开发时不要实现对多线程的支持。
只有程序经过完整的测试和调用，它才应转换到一个线程中（原文：
shoulditbeconvertedintoathread）。
线程编程可能要求其它的操作系统的特殊机制——在链接特殊的库或访问特殊的堆函数方面。
这里值得指出的是MIRACL堆访问都是通过mralloc.c模块完成的。
threadwn.cpp程序是一个WindowsC++多线程示例。
阅读其中的注释——它可以编译和从Windows
命令提示符运行。
类似地threaduc.cpp是一个Unix的多线程示例。
2.4受限环境
在版本5的中，有一个对在非常小和受限的环境中的MIRACL实现的新支持。
使用config实用程序，它现在支持各种时空交换（time/spacetrade-offs），最主要的革新是在一个不支持堆的环境中生成和使用
MIRACL。
通常big变量的空间从堆中分配，但通过在配置头文件中指定MR_STATIC，可以生成一个总是尝试从静态内存或栈，而不是堆中分配内存的版本。
这带来的主要负面影响是big变量的最大尺寸必须在编译时确定（生成库的时候）。
如往常一样，在这个过程中最好让config实用程序引导你创建一个合适的配置头文件mirdef.h。
对于C程序员，使用下列方式从栈中为big变量分配内存：
bigx,y,z;
charmem[MR_BIG_RESERVE（3）];
memset（mem,0,MR_BIG_RESERVE（3））;
为三个big变量分配的空间都在栈上并且被清零，然后每个变量应如下初始化：
x=mirvar_mem（mem,0）;
y=mirvar_mem（mem,1）;
z=mirvar_mem（mem,2）;
从单个内存块中为多个big变量分配所有空间是有意义的，那样可以更快的初始化，而且可以对变量对齐
进行完整的控制——编译器有时会出错。
请注意big初始化函数mirvar在这种模式中不再有效，分配操作应像上面描述的那样实现。
最后，可以选择性地在函数末尾调用memset来在离开前清空内存块——出于保密原因，这可能很重要。
请参考示例程序brent.c。
这种机制在实现一个使用椭圆曲线的非常小的程序时可能非常有用。
椭圆曲线要求的big数字要比其它加密技术的小得多。
从栈中为椭圆曲线的点分配内存：
epoint*x,*y,*z;
charmem[MR_ECP_RESERVE（3）];
memset（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来实现。
这种场合中的典型mirdef.h头文件可能是这个样子的：
/*
*MIRACLcompiler/hardwaredefinitions-mirdef.h
*Copyright（c）1988-2005ShamusSoftwareLtd.
*/
#defineMR_LITTLE_ENDIAN#defineMIRACL32
#definemr_utypeint#defineMR_IBITS32
#defineMR_LBITS32
#definemr_unsign32unsignedint#definemr_dltypeint64
#definemr_unsign64unsignedint64#defineMR_STATIC7
#defineMR_ALWAYS_BINARY#defineMR_NOASM
#defineMAXBASE（（mr_small）1<
<
（MIRACL-1））#defineMR_BITSINCHAR8
#defineMR_SHORT_OF_MEMORY#defineMR_GENERIC_MT
#defineMR_STRIPPED_DOWN
关于使用这种类型的头文件的示例程序，请查看
ecsgen_s.c，ecsign_s.c，ecsver_s.c，ecsgen2s.c，ecsign2s.c和ecsver2s.c。
这些程序使用Microsoft
C++在Pentium上实现了非常小而快速的ECDSA密码生成，数字签名以及校验算法。
ecdh.c是另一个很棒的示例，它使用导航预行计算（precomputation）来加速一个ECDiffie-Hellman实现。
注意：
不使用堆有一些小问题：
结构不能再是可变大小的，因此在这种模式中MIRACL的许多特性都不再可用。
例如中国剩余定理（Chineseremaindertheorem）程序要求的导航预行计算（precomputation）就无法支持。
但在一个受限环境中，有理由假定诸如导航预行计算（precomputation）将脱机实现，以使将程序固化到ROM中成为可能。
MIRACL模块经过了周密的设计以使对于给定的任务，应用程序都只需要从库中引入最少的模块。
这可以帮助应用程序保持最小的尺寸。
但是如果程序的尺寸是一个大话题（bigissue），则可以手工从模块中删除不需要的函数来达到额外的节约。
2.5平台特定的信息
2.5.5MicrosoftVisualC++
在MicrosoftC++6.0上创建MIRACL应用程序的步骤如下：
1.创建一个Win32ConsoleApplication的空工程。
2.选择菜单“Project”——“AddtoProject”——“File”。
3.选择“Libraryfiles（.lib）”文件类型，查找预编译的MIRACL库文件ms32.lib，将它添加到工程。
4.添加一个工程的主文件（例如limlee.cpp）。
5.如果是C++主工程文件，则再添加其它所需的文件，如big.cpp、zzn.cpp等。
主文件的头部注释中列出了所需的文件。
6.选择菜单“Project”——“Setting”。
选中C/C++Tab页，选择“Preprocesser”目录，在
“AdditionalIncludeDirectoryies”中指定MIRACL头文件路径。
7.确保应用程序运行目录中的所有程序所需文件均可用，如*.key，*.dss或*.ecs等文件。
8.生成并运行程序。
在MicrosoftC++6.0上创建MIRACL库的步骤：
1.编译并运行config.c实用程序，将生成的mirdef.tst重命名为mirdef.h。
注意MicrosoftC拥有一个
64位整数类型int64。
2.新一个“Win32StaticLibrary”类型的工程。
3.添加适当的mr*.c文件，它们在miracl.lst中列出。
4.选择菜单“Project”——“Setting”。
5.编译工程生成MIRACL库。
在MicrosoftC++.NET上创建MIRACL应用程序的步骤：
2.去掉工程中的空主文件，用MIRACL提供的文件（如limlee.cpp）将其替换。
请注意现在主函数称为
_tmain。
3.选择菜单“Project”——“AddtoProject”——“File”。
选择“Allfiles”文件类型，查找预编译的
MIRACL库文件ms32.lib，将它添加到工程。
4.如果是C++主工程文件，则则再添加其它所需的文件，如big.cpp、zzn.cpp等。
5.选择菜单“Project”——“Properties”。
打开C++标签页，到“PrecompiledHeaders”，选择“Notusingprecompiledheaders”。
再打开“General”标签页，指定MIRACL头文件的路径。
6.生成并运行程序。
在MicrosoftC++.NET上创建MIRACL库的步骤：
创建一个“Win32Project”类型的VisualC++工程。
选择“ApplicationSettings“，选择”StaticLibrary“。
添加相应的mr*.c文件。
选择“Project”——“Properties”。
打开C++标签页，到“PrecompiledHeaders”，选择“Not
usingprecompiledheaders”。
生成工程。
若要在基于MFCWin32工程中使用MIRACL，这里有一些相关建议：
1.使用config.c实例程序生成mirdef.h，并在其中定义MR_NO_STANDARD_IO，再生成MIRACL库。
2.如果使用C++MIRACL类，别忘了在工程设置中将big.cpp等MIRACL实现文件设置为“notusingpre-compiledheaders”。
3.别忘了MIRACL是一个C库，若要直接调用MIRACL例程，必须：
使用C++时，通过C++包装来访问MIRACL可能更合适。
4.要显示一个big值
升级会员 