Apple FEE Library Source, v. 1.0 Last Update: 26 Sep 2001 NOTICE: USE OF THE MATERIALS ACCOMPANYING THIS NOTICE IS SUBJECT TO THE TERMS OF THE SIGNED "FAST ELLIPTIC ENCRYPTION (FEE) REFERENCE SOURCE CODE EVALUATION AGREEMENT" BETWEEN APPLE COMPUTER, INC. AND THE ORIGINAL LICENSEE THAT OBTAINED THESE MATERIALS FROM APPLE COMPUTER, INC. ANY USE OF THESE MATERIALS NOT PERMITTED BY SUCH AGREEMENT WILL EXPOSE YOU TO LIABILITY. This directory contains the source code for Apple's Fast Elliptic Encryption (FEE) library. All code is written in ANSI C. A UNIX Makefile is provided. Note that all source files in this directory are best viewed with an editor configured for 8-space tabs, a fixed pitch font, and a window of at least 80 characters in width. Public Header Files ------------------- These files contain the public API used by clients of the FEE library. Crypt.h ------- A top-level header which includes all of the other public headers. Typically a client application will only include this file. feeTypes.h ---------- Common #defines and typedefs used throughout the library. feePublicKey.h -------------- Functions for generating and manipulating FEE public and private keys, performing key exchange, and high-level digital signature operations. feeDigitalSignature.h --------------------- Low-level primitives for performing ElGamal digital signature operations. Not normally used by clients; high-level functions for performing signature operations are provided in feePublicKey.h. feeECDSA.h ---------- Low-level primitives for performing ECDSA digital signature operations. Not normally used by clients; high-level functions for performing signature operations are provided in feePublicKey.h. feeDES.h -------- DES symmetric encryption and decryption functions. feeHash.h --------- MD5 Hash functions. ckSHA1.h ------ SHA-1 hash functions. feeRandom.h ----------- Pseudo-random number generator. feeFunctions.h -------------- General-purpose C functions. feeFEED.h --------- Asymmetric encryption functions using the FEE Direct Embedding, or FEED, algorithm. feeFEEDExp.h ------------ Asymmetric encryption functions using the Expanding FEED algorithm. enc64.h ------- Functions for performing encoding and decoding via base-64 IA5 format, per RFC 1421. feeCipherFile.h CipherFileTypes.h ------------------ High-level CipherFile support. Provides encapsulation of ciphertext, digital signature, and public key strings in a portable format. falloc.h -------- Memory alloc/free routines. All memory mallocd by CryptKit and returned to called must be freed via ffree(), declared here. 'C' Files --------- In addition to the '.c' files associated with the abovementioned public headers (e.g., feePublicKey.c, feeCipherFile.c), the FEE library contains the following source files: giantIntegers.[ch] -------------------- Large-precision integer arithmetic package. elliptic.[ch] ------------- Elliptic Curve algebra, Apple "FEE" style. ellipticProj.[ch] ----------------- Elliptic Curve Algebra using projective coordinates. curveParams.[ch], curveParamData.h ---------------------------------- Elliptic curve parameters. Declarations of known curves. byteRep.[ch] ------------ Platform-independent implement implementation of portable representation of all aggregate data types used in FEE library. ckutilities.[ch] -------------- Miscellaneous C utilities. feeCipherFileAtom.c CipherFileDES.c CipherFileFEED.c ---------------- CipherFile support. ckDES.c ckMD5.c ckSHA1_priv.c ----------- Low-level primitives for DES, MD5, SHA-1 algorithms. Porting to other platforms -------------------------- The FEE library has been built and tested on the Macintosh platform using Metrowerks CodeWarrior, on the OpenStep OS on both the 68k and Pentium platforms, and on Windows NT (on which it was built using the Gnu gcc compiler). There are at least 3 files which need to be edited in order to port the FEE library to other platforms. One is platform.c. This file has two platform-specific functions: void NSGiantRaise(const char *reason); This function is called interally in the library in the unlikely event of a fatal runtime error. The current versions of this function use printf() to log the reason and call exit(1). unsigned createRandomSeed(); This function obtains a 32-bit number with which FEE's pseudo-random number generator is seeded. The implementation of this function is highly platform-specific and also depends on the amount of security required from the RNG in a particular application. Common (and simple) implementations involve obtaining a high-precision system clock, process ID values. etc. Note that this function is called during a call to feeRandAlloc() in feeRandom.c. Clients of the FEE library can also avoid this mechanism by instantiating the RNG via feeRandAllocWithSeed(), passing in an application-specific seed. The file platform.h contains a definition for the endianness of the current platform. Either __BIG_ENDIAN__ or __LITTLE_ENDIAN__ must be #defined at compile time. If your compiler does not implicitly define one of these symbols, edit platform.h appropriately. Another file which may be modified during a port is falloc.c. All memory allocation calls in the library are performed via fmalloc() and ffree() in falloc.c. The current implementation of falloc.c merely passes these calls on to the standard malloc() and free(). A port to another platform may require the use of different memory allocators. The giantIntegers module, which implements large integer arithmetic, allows for specification of platform-dependent digit size. In addition, provisions are made for implementation of platform-dependent routines to perform low-level digit arithmetic (single and double precision add, subtract with carry, double precision multiply, multiply an array of digits by another digit). The current library contains assembly languange macros for the Intel and PPC platforms. The specification of the size of a giant digit, type giantDigit, is found in giantIntegers.h. The files which use low-level platform-dependent giant arithmentic include giantPortCommon.h, which select one of several possible header files. The header giantPortGeneric.h can be specified; this has no assembly language, but implements the necessary functions using the C "unsigned long long" type and static lines functions. The API for the low-level digit functions is the same in all three of the following files: giantPortGeneric.h giantPort_i486.h giantPort_PPC.h Currently, the implementation of the PPC-specific giant digit routines is in giantPort_PPC.c; the implementation of the Intels-specific giant routines is found in both giantPort_i486.h and giantPort_i486.s. Building the library -------------------- This directory contains a UNIX Makefile. Just type 'make' in the current (writable) directory to build the library. The result is libFEE.a. Copyright (c) 1998 Apple Computer, Inc. All rights reserved. Apple and Macintosh are trademarks of Apple Computer, Inc., registered in the U.S.A. and other countries. OpenStep is a trademark of NeXT Software, Inc. registered in the U.S.A. and other countries. All other trademarks are the property of their respective owners.