Security/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    unsigned createRandomSeed();
 160
 161       This function obtains a 32-bit number with which FEE's
 162       pseudo-random number generator is seeded. The implementation
 163       of this function is highly platform-specific and also depends
 164       on the amount of security required from the RNG in a
 165       particular application. Common (and simple) implementations
 166       involve obtaining a high-precision system clock, process
 167       ID values. etc.
 168
 169       Note that this function is called during a call to feeRandAlloc()
 170       in feeRandom.c. Clients of the FEE library can also avoid this
 171       mechanism by instantiating the RNG via feeRandAllocWithSeed(),
 172       passing in an application-specific seed.
 173
 174 The file platform.h contains a definition for the endianness of the
 175 current platform. Either __BIG_ENDIAN__ or __LITTLE_ENDIAN__ must
 176 be #defined at compile time. If your compiler does not implicitly
 177 define one of these symbols, edit platform.h appropriately.
 178
 179 Another file which may be modified during a port is falloc.c. All
 180 memory allocation calls in the library are performed via fmalloc() and
 181 ffree() in falloc.c. The current implementation of falloc.c merely
 182 passes these calls on to the standard malloc() and free(). A port to
 183 another platform may require the use of different memory allocators.
 184
 185 The giantIntegers module, which implements large integer arithmetic,
 186 allows for specification of platform-dependent digit size. In addition,
 187 provisions are made for implementation of platform-dependent routines
 188 to perform low-level digit arithmetic (single and double precision add,
 189 subtract with carry, double precision multiply, multiply an array
 190 of digits by another digit). The current library contains assembly
 191 languange macros for the Intel and PPC platforms. The specification of
 192 the size of a giant digit, type giantDigit, is found in giantIntegers.h.
 193 The files which use low-level platform-dependent giant arithmentic
 194 include giantPortCommon.h, which select one of several possible header
 195 files. The header giantPortGeneric.h can be specified; this has
 196 no assembly language, but implements the necessary functions using
 197 the C "unsigned long long" type and static lines functions. The API for
 198 the low-level digit functions is the same in all three of the following
 199 files:
 200
 201    giantPortGeneric.h
 202    giantPort_i486.h
 203    giantPort_PPC.h
 204
 205 Currently, the implementation of the PPC-specific giant digit routines
 206 is in giantPort_PPC.c; the implementation of the Intels-specific giant
 207 routines is found in both giantPort_i486.h and giantPort_i486.s.
 208
 209 Building the library
 210 --------------------
 211
 212 This directory contains a UNIX Makefile. Just type 'make' in the current
 213 (writable) directory to build the library. The result is libFEE.a.
 214
 215
 216    Copyright (c) 1998 Apple Inc.  All rights reserved.
 217
 218 Apple and Macintosh are trademarks of Apple Computer, Inc., registered
 219 in the U.S.A. and other countries.  OpenStep is a trademark of NeXT
 220 Software, Inc. registered in the U.S.A. and other countries.  All other
 221 trademarks are the property of their respective owners.