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
13This directory contains the source code for Apple's Fast Elliptic
14Encryption (FEE) library. All code is written in ANSI C. A UNIX
15Makefile is provided.
16
17Note that all source files in this directory are best viewed with an
18editor configured for 8-space tabs, a fixed pitch font, and a window
19of at least 80 characters in width.
20
21
22Public Header Files
23-------------------
24
25These 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
102In addition to the '.c' files associated with the abovementioned public
103headers (e.g., feePublicKey.c, feeCipherFile.c), the FEE library
104contains 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
144Porting to other platforms
145--------------------------
146
147The 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
149There are at least 3 files which need to be edited in order to port the
150FEE library to other platforms. One is platform.c. This file has two
151platform-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
174The file platform.h contains a definition for the endianness of the
175current platform. Either __BIG_ENDIAN__ or __LITTLE_ENDIAN__ must
176be #defined at compile time. If your compiler does not implicitly
177define one of these symbols, edit platform.h appropriately.
178
179Another file which may be modified during a port is falloc.c. All
180memory allocation calls in the library are performed via fmalloc() and
181ffree() in falloc.c. The current implementation of falloc.c merely
182passes these calls on to the standard malloc() and free(). A port to
183another platform may require the use of different memory allocators.
184
185The giantIntegers module, which implements large integer arithmetic,
186allows for specification of platform-dependent digit size. In addition,
187provisions are made for implementation of platform-dependent routines
188to perform low-level digit arithmetic (single and double precision add,
189subtract with carry, double precision multiply, multiply an array
190of digits by another digit). The current library contains assembly
191languange macros for the Intel and PPC platforms. The specification of
192the size of a giant digit, type giantDigit, is found in giantIntegers.h.
193The files which use low-level platform-dependent giant arithmentic
194include giantPortCommon.h, which select one of several possible header
195files. The header giantPortGeneric.h can be specified; this has
196no assembly language, but implements the necessary functions using
197the C "unsigned long long" type and static lines functions. The API for
198the low-level digit functions is the same in all three of the following
199files:
200
201 giantPortGeneric.h
202 giantPort_i486.h
203 giantPort_PPC.h
204
205Currently, the implementation of the PPC-specific giant digit routines
206is in giantPort_PPC.c; the implementation of the Intels-specific giant
207routines is found in both giantPort_i486.h and giantPort_i486.s.
208
209Building the library
210--------------------
211
212This 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
218Apple and Macintosh are trademarks of Apple Computer, Inc., registered
219in the U.S.A. and other countries. OpenStep is a trademark of NeXT
220Software, Inc. registered in the U.S.A. and other countries. All other
221trademarks are the property of their respective owners.
222
TOP_README
1 Apple FEE Library Source, v. 1.0
2 Last Update: 28 Jan 1998
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
12This directory contains two subdirecories. One, CryptKit, contains the
13source code for the Apple Fast Elliptic Encryption (FEE) library. The
14other directory, Examples, contains a number of programs which illustrate
15the use of the FEE library. All code is written in ANSI C; UNIX Makefiles
16are provided for each directory. See the README files in the respective
17directories for information on the contents of specific files, porting
18issues, and so forth.
19
20Note that all source files in these directories are best viewed with an
21editor configured for 8-space tabs, a fixed pitch font, and a window
22of at least 80 characters in width.
23
24
25 Copyright (c) 1998 Apple Inc. All rights reserved.
26
27Apple and Macintosh are trademarks of Apple Computer, Inc., registered
28in the U.S.A. and other countries. OpenStep is a trademark of NeXT
29Software, Inc. registered in the U.S.A. and other countries. All other
30trademarks are the property of their respective owners.
31