Security-58286.60.28.tar.gz

[apple/security.git] / OSX / libsecurity_cryptkit / lib / README

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

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 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.