OSX/libsecurity_cryptkit/lib/README

   1                     Apple FEE Library Source, v. 1.0
   2                         Last Update: 26 Sep 2001
   3
   4
   5    NOTICE: USE OF THE MATERIALS ACCOMPANYING THIS NOTICE IS SUBJECT
   6    TO THE TERMS OF THE SIGNED "FAST ELLIPTIC ENCRYPTION (FEE) REFERENCE
   7    SOURCE CODE EVALUATION AGREEMENT" BETWEEN APPLE COMPUTER, INC. AND THE
   8    ORIGINAL LICENSEE THAT OBTAINED THESE MATERIALS FROM APPLE COMPUTER,
   9    INC.  ANY USE OF THESE MATERIALS NOT PERMITTED BY SUCH AGREEMENT WILL
  10    EXPOSE YOU TO LIABILITY.
  11
  12
  13 This directory contains the source code for Apple's Fast Elliptic
  14 Encryption (FEE) library. All code is written in ANSI C. A UNIX
  15 Makefile is provided.
  16
  17 Note that all source files in this directory are best viewed with an
  18 editor configured for 8-space tabs, a fixed pitch font, and a window
  19 of at least 80 characters in width.
  20
  21
  22 Public Header Files
  23 -------------------
  24
  25 These files contain the public API used by clients of the FEE library.
  26
  27    Crypt.h
  28    -------
  29       A top-level header which includes all of the other public headers.
  30       Typically a client application will only include this file.
  31
  32    feeTypes.h
  33    ----------
  34       Common #defines and typedefs used throughout the library.
  35
  36    feePublicKey.h
  37    --------------
  38       Functions for generating and manipulating FEE public and private keys,
  39       performing key exchange, and high-level digital signature operations.
  40
  41    feeDigitalSignature.h
  42    ---------------------
  43       Low-level primitives for performing ElGamal digital signature
  44       operations. Not normally used by clients; high-level functions
  45       for performing signature operations are provided in feePublicKey.h.
  46
  47    feeECDSA.h
  48    ----------
  49       Low-level primitives for performing ECDSA digital signature operations.
  50       Not normally used by clients; high-level functions for performing
  51       signature operations are provided in feePublicKey.h.
  52
  53    feeDES.h
  54    --------
  55       DES symmetric encryption and decryption functions.
  56
  57    feeHash.h
  58    ---------
  59       MD5 Hash functions.
  60
  61    ckSHA1.h
  62    ------
  63       SHA-1 hash functions.
  64
  65    feeRandom.h
  66    -----------
  67       Pseudo-random number generator.
  68
  69    feeFunctions.h
  70    --------------
  71       General-purpose C functions.
  72
  73    feeFEED.h
  74    ---------
  75       Asymmetric encryption functions using the FEE Direct Embedding,
  76       or FEED, algorithm.
  77
  78    feeFEEDExp.h
  79    ------------
  80       Asymmetric encryption functions using the Expanding FEED algorithm.
  81
  82    enc64.h
  83    -------
  84       Functions for performing encoding and decoding via base-64 IA5
  85       format, per RFC 1421.
  86
  87    feeCipherFile.h
  88    CipherFileTypes.h
  89    ------------------
  90       High-level CipherFile support. Provides encapsulation of ciphertext,
  91       digital signature, and public key strings in a portable format.
  92
  93    falloc.h
  94    --------
  95       Memory alloc/free routines. All memory mallocd by CryptKit and
  96       returned to called must be freed via ffree(), declared here.
  97
  98
  99 'C' Files
 100 ---------
 101
 102 In addition to the '.c' files associated with the abovementioned public
 103 headers (e.g., feePublicKey.c, feeCipherFile.c), the FEE library
 104 contains the following source files:
 105
 106    giantIntegers.[ch]
 107    --------------------
 108       Large-precision integer arithmetic package.
 109
 110    elliptic.[ch]
 111    -------------
 112       Elliptic Curve algebra, Apple "FEE" style.
 113
 114    ellipticProj.[ch]
 115    -----------------
 116       Elliptic Curve Algebra using projective coordinates.
 117
 118    curveParams.[ch], curveParamData.h
 119    ----------------------------------
 120       Elliptic curve parameters. Declarations of known curves.
 121
 122    byteRep.[ch]
 123    ------------
 124       Platform-independent implement implementation of portable
 125       representation of all aggregate data types used in FEE library.
 126
 127    ckutilities.[ch]
 128    --------------
 129       Miscellaneous C utilities.
 130
 131    feeCipherFileAtom.c
 132    CipherFileDES.c
 133    CipherFileFEED.c
 134    ----------------
 135       CipherFile support.
 136
 137    ckDES.c
 138    ckMD5.c
 139    ckSHA1_priv.c
 140    -----------
 141       Low-level primitives for DES, MD5, SHA-1 algorithms.
 142
 143
 144 Porting to other platforms
 145 --------------------------
 146
 147 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).
 148
 149 There are at least 3 files which need to be edited in order to port the
 150 FEE library to other platforms. One is platform.c. This file has two
 151 platform-specific functions:
 152
 153    void NSGiantRaise(const char *reason);
 154
 155       This function is called interally in the library in the unlikely
 156       event of a fatal runtime error. The current versions of this
 157       function use printf() to log the reason and call exit(1).
 158
 159 The file platform.h contains a definition for the endianness of the
 160 current platform. Either __BIG_ENDIAN__ or __LITTLE_ENDIAN__ must
 161 be #defined at compile time. If your compiler does not implicitly
 162 define one of these symbols, edit platform.h appropriately.
 163
 164 Another file which may be modified during a port is falloc.c. All
 165 memory allocation calls in the library are performed via fmalloc() and
 166 ffree() in falloc.c. The current implementation of falloc.c merely
 167 passes these calls on to the standard malloc() and free(). A port to
 168 another platform may require the use of different memory allocators.
 169
 170 The giantIntegers module, which implements large integer arithmetic,
 171 allows for specification of platform-dependent digit size. In addition,
 172 provisions are made for implementation of platform-dependent routines
 173 to perform low-level digit arithmetic (single and double precision add,
 174 subtract with carry, double precision multiply, multiply an array
 175 of digits by another digit). The current library contains assembly
 176 languange macros for the Intel and PPC platforms. The specification of
 177 the size of a giant digit, type giantDigit, is found in giantIntegers.h.
 178 The files which use low-level platform-dependent giant arithmentic
 179 include giantPortCommon.h, which select one of several possible header
 180 files. The header giantPortGeneric.h can be specified; this has
 181 no assembly language, but implements the necessary functions using
 182 the C "unsigned long long" type and static lines functions. The API for
 183 the low-level digit functions is the same in all three of the following
 184 files:
 185
 186    giantPortGeneric.h
 187    giantPort_i486.h
 188    giantPort_PPC.h
 189
 190 Currently, the implementation of the PPC-specific giant digit routines
 191 is in giantPort_PPC.c; the implementation of the Intels-specific giant
 192 routines is found in both giantPort_i486.h and giantPort_i486.s.
 193
 194 Building the library
 195 --------------------
 196
 197 This directory contains a UNIX Makefile. Just type 'make' in the current
 198 (writable) directory to build the library. The result is libFEE.a.
 199
 200
 201    Copyright (c) 1998 Apple Inc.  All rights reserved.
 202
 203 Apple and Macintosh are trademarks of Apple Computer, Inc., registered
 204 in the U.S.A. and other countries.  OpenStep is a trademark of NeXT
 205 Software, Inc. registered in the U.S.A. and other countries.  All other
 206 trademarks are the property of their respective owners.