1/* Copyright (c) 1998 Apple Computer, Inc.  All rights reserved.
2 *
3 * NOTICE: USE OF THE MATERIALS ACCOMPANYING THIS NOTICE IS SUBJECT
4 * TO THE TERMS OF THE SIGNED "FAST ELLIPTIC ENCRYPTION (FEE) REFERENCE
5 * SOURCE CODE EVALUATION AGREEMENT" BETWEEN APPLE COMPUTER, INC. AND THE
6 * ORIGINAL LICENSEE THAT OBTAINED THESE MATERIALS FROM APPLE COMPUTER,
7 * INC.  ANY USE OF THESE MATERIALS NOT PERMITTED BY SUCH AGREEMENT WILL
8 * EXPOSE YOU TO LIABILITY.
9 ***************************************************************************
10 *
11 * feePublicKey.h
12 *
13 * Revision History
14 * ----------------
15 * 23 Mar 98	Doug Mitchell at Apple
16 *	Added blob support.
17 * 17 Jul 97	Doug Mitchell at Apple
18 *	Added ECDSA signature routines.
19 * 20 Aug 96	Doug Mitchell at NeXT
20 *	Created.
21 */
22
23#ifndef	_CK_FEEPUBLICKEY_H_
24#define _CK_FEEPUBLICKEY_H_
25
26#include "ckconfig.h"
27
28#include <sys/types.h>		/* size_t */
29
30#if	!defined(__MACH__)
31#include <feeTypes.h>
32#else
33#include <security_cryptkit/feeTypes.h>
34#endif
35
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40/*
41 * Obatin a newly allocated feePubKey.
42 */
43feePubKey feePubKeyAlloc(void);
44
45void feePubKeyFree(feePubKey pubKey);
46
47/*
48 * Init feePubKey from private "password" data. Incoming password data will
49 * be processed with digests before use if hashPrivData is true, otherwise
50 * it'll be used as is. In the 'as is' case, the privData must be at least
51 * as large as the key being created.
52 *
53 * Currently two versions - one in which the size of the key is specified as
54 * a feeDepth; one for key size in bits and optional primeType and curveType.
55 */
56feeReturn feePubKeyInitFromPrivDataDepth(feePubKey pubKey,
57	const unsigned char *privData,
58	unsigned privDataLen,
59	feeDepth depth,
60	char hashPrivData);
61
62feeReturn feePubKeyInitFromPrivDataKeyBits(feePubKey pubKey,
63	const unsigned char *privData,
64	unsigned privDataLen,
65	unsigned keyBits,			/* key size in bits */
66	feePrimeType primeType,		/* FPT_Fefault means "best one" */
67	feeCurveType curveType,		/* FCT_Default means "best one" */
68	char hashPrivData);
69
70/*
71 * Init feePubKey from private "password" and from data curve parameters
72 * matching existing oldKey. Incoming password data will
73 * be processed with digests before use if hashPrivData is true, otherwise
74 * it'll be used as is. In the 'as is' case, the privData must be at least
75 * as large as the key being created.
76
77 */
78feeReturn feePubKeyInitFromKey(feePubKey pubKey,
79	const unsigned char *privData,
80	unsigned privDataLen,
81	feePubKey oldKey,
82	char hashPrivData);
83
84/***
85 *** Exportable key blob support.
86 ***
87 *** Currently there are three different ways of representing a feePubKey in
88 *** an exportable format.
89 ***
90 *** Raw blob:  basic native blob format.
91 *** DER blob:  DER-encoded. Currently not available in ANSI C version of
92 ***            CryptKit library without additional porting; the OS X version of
93 ***            Apple implements this functionality via SNACC-generated C++ classes.
94 *** KeyString: NULL-terminated ASCII C string, suitable for application such as
95 ***            distributing one's public key via email. Only public keys (not
96 ***            private) can be exported and imported via KeyStrings.
97 ***/
98
99/*
100 * Obtain portable public and private key blobs from a key.
101 */
102feeReturn feePubKeyCreatePubBlob(feePubKey pubKey,
103	unsigned char **keyBlob,	// mallocd and RETURNED
104	unsigned *keyBlobLen);		// RETURNED
105
106feeReturn feePubKeyCreatePrivBlob(feePubKey pubKey,
107	unsigned char **keyBlob,	// mallocd and RETURNED
108	unsigned *keyBlobLen);		// RETURNED
109
110/*
111 * Init an empty feePubKey from a blob, public and private key versions.
112 */
113feeReturn feePubKeyInitFromPubBlob(feePubKey pubKey,
114	unsigned char *keyBlob,
115	unsigned keyBlobLen);
116feeReturn feePubKeyInitFromPrivBlob(feePubKey pubKey,
117	unsigned char *keyBlob,
118	unsigned keyBlobLen);
119
120/*
121 * Create a public key in the form of a null-terminated C string.
122 */
123feeReturn feePubKeyCreateKeyString(feePubKey pubKey,
124	char **pubKeyString,		/* fmalloc'd & RETURNED */
125	unsigned *pubKeyStringLen);	/* RETURNED */
126
127/*
128 * Init feePubKey from a public key string.
129 */
130feeReturn feePubKeyInitFromKeyString(feePubKey pubKey,
131	const char *keyStr,
132	unsigned keyStrLen);
133
134#if CRYPTKIT_DER_ENABLE
135
136/*
137 * DER format support.
138 * Obtain portable public and private DER-encoded key blobs from a key.
139 */
140feeReturn feePubKeyCreateDERPubBlob(feePubKey pubKey,
141	unsigned char **keyBlob,	// mallocd and RETURNED
142	unsigned *keyBlobLen);		// RETURNED
143
144feeReturn feePubKeyCreateDERPrivBlob(feePubKey pubKey,
145	unsigned char **keyBlob,	// mallocd and RETURNED
146	unsigned *keyBlobLen);		// RETURNED
147
148/*
149 * Init an empty feePubKey from a DER-encoded blob, public and private key versions.
150 */
151feeReturn feePubKeyInitFromDERPubBlob(feePubKey pubKey,
152	unsigned char *keyBlob,
153	size_t keyBlobLen);
154feeReturn feePubKeyInitFromDERPrivBlob(feePubKey pubKey,
155	unsigned char *keyBlob,
156	size_t keyBlobLen);
157
158/*
159 * X509 (public) and PKCS8 (private) key formatting.
160 */
161feeReturn feePubKeyCreateX509Blob(
162	feePubKey pubKey,			// public key
163	unsigned char **keyBlob,	// mallocd and RETURNED
164	unsigned *keyBlobLen);		// RETURNED
165
166feeReturn feePubKeyCreatePKCS8Blob(
167	feePubKey pubKey,			// private key
168	unsigned char **keyBlob,	// mallocd and RETURNED
169	unsigned *keyBlobLen);		// RETURNED
170
171feeReturn feePubKeyInitFromX509Blob(
172	feePubKey pubKey,			// public key
173	unsigned char *keyBlob,
174	size_t keyBlobLen);
175
176feeReturn feePubKeyInitFromPKCS8Blob(
177	feePubKey pubKey,			// private key
178	unsigned char *keyBlob,
179	size_t keyBlobLen);
180
181/*
182 * The native OpenSSL ECDSA key format contains both the private and public
183 * components in one blob. This throws a bit of a monkey wrench into the API
184 * here, as we only have one encoder - which requires a private key - and one
185 * decoder, which can result in the decoding of either a public or a private
186 * key.
187 */
188feeReturn feePubKeyCreateOpenSSLBlob(
189	feePubKey pubKey,			// private key
190	unsigned char **keyBlob,	// mallocd and RETURNED
191	unsigned *keyBlobLen);		// RETURNED
192
193feeReturn feePubKeyInitFromOpenSSLBlob(
194	feePubKey pubKey,			// private or public key
195	int pubOnly,
196	unsigned char *keyBlob,
197	size_t keyBlobLen);
198
199#endif	/* CRYPTKIT_DER_ENABLE */
200
201/*
202 * ANSI X9.62/Certicom key support.
203 * Public key is 04 || x || y
204 * Private key is privData per Certicom SEC1 C.4.
205 */
206feeReturn feeCreateECDSAPubBlob(feePubKey pubKey,
207	unsigned char **keyBlob,
208	unsigned *keyBlobLen);
209
210feeReturn feeCreateECDSAPrivBlob(feePubKey pubKey,
211	unsigned char **keyBlob,
212	unsigned *keyBlobLen);
213
214/* Caller determines depth from other sources (e.g. AlgId.Params) */
215feeReturn feePubKeyInitFromECDSAPubBlob(feePubKey pubKey,
216	const unsigned char *keyBlob,
217	unsigned keyBlobLen,
218	feeDepth depth);
219
220feeReturn feePubKeyInitFromECDSAPrivBlob(feePubKey pubKey,
221	const unsigned char *keyBlob,
222	unsigned keyBlobLen,
223	feeDepth depth);
224
225
226/***
227 *** Miscellaneous feePubKey functions.
228 ***/
229
230/*
231 * Given private-capable privKey, initialize pubKey to be its corresponding
232 * public key.
233 */
234feeReturn feePubKeyInitPubKeyFromPriv(feePubKey privKey,
235	feePubKey pubKey);
236
237/*
238 * Returns non-zero if two keys are equivalent.
239 */
240int feePubKeyIsEqual(feePubKey key1,
241	feePubKey key2);
242
243/*
244 * Returns non-zero if key is private-capable (i.e., capable of signing
245 * and decrypting).
246 */
247int feePubKeyIsPrivate(feePubKey key);
248
249#if	CRYPTKIT_KEY_EXCHANGE
250
251/*
252 * Generate a pad, for use with symmetric encryption, derived from two keys.
253 * 'myKey' must be created with private data (via feePubKeyInitFromPrivData()
254 * or feePubKeyInitFromKey().
255 */
256feeReturn feePubKeyCreatePad(feePubKey myKey,
257	feePubKey theirKey,
258	unsigned char **padData,	/* fmalloc'd & RETURNED */
259	unsigned *padDataLen);		/* RETURNED padData length in bytes */
260
261#endif	/* CRYPTKIT_KEY_EXCHANGE */
262
263#if	CRYPTKIT_HIGH_LEVEL_SIG
264
265/*
266 * The following two routines are implemented using primitives in the
267 * feeHash and feeDigitalSignature objects.
268 *
269 * Generate digital signature, ElGamal style.
270 */
271feeReturn feePubKeyCreateSignature(feePubKey pubKey,
272	const unsigned char *data,
273	unsigned dataLen,
274	unsigned char **signature,	/* fmalloc'd and RETURNED */
275	unsigned *signatureLen);	/* RETURNED */
276
277/*
278 * Verify digital signature, ElGamal style.
279 */
280feeReturn feePubKeyVerifySignature(feePubKey pubKey,
281	const unsigned char *data,
282	unsigned dataLen,
283	const unsigned char *signature,
284	unsigned signatureLen);
285
286#if CRYPTKIT_ECDSA_ENABLE
287
288/*
289 * The following two routines are implemented using primitives in the
290 * feeHash and feeECDSA objects.
291 *
292 * Generate digital signature, ECDSA style.
293 */
294feeReturn feePubKeyCreateECDSASignature(feePubKey pubKey,
295	const unsigned char *data,
296	unsigned dataLen,
297	unsigned char **signature,		/* fmalloc'd and RETURNED */
298	unsigned *signatureLen);		/* RETURNED */
299
300/*
301 * Verify digital signature, ECDSA style.
302 */
303feeReturn feePubKeyVerifyECDSASignature(feePubKey pubKey,
304	const unsigned char *data,
305	unsigned dataLen,
306	const unsigned char *signature,
307	unsigned signatureLen);
308
309#endif	/* CRYPTKIT_ECDSA_ENABLE */
310
311#endif	/* CRYPTKIT_HIGH_LEVEL_SIG */
312
313/*
314 * Diffie-Hellman. Public key is specified either as a feePubKey or
315 * a ANSI X9.62 format public key string (0x04 | x | y). In either case
316 * the caller must ensure that the two keys are on the same curve.
317 * Output data is falloc'd here; caller must free. Output data is
318 * exactly the size of the curve's modulus in bytes.
319 */
320feeReturn feePubKeyECDH(
321	feePubKey privKey,
322	/* one of the following two is non-NULL */
323	feePubKey pubKey,
324	const unsigned char *pubKeyStr,
325	unsigned pubKeyStrLen,
326	/* output fallocd and RETURNED here */
327	unsigned char **output,
328	unsigned *outputLen);
329
330/*
331 * Accessor routines.
332 */
333const char *feePubKeyAlgorithmName(void);
334
335unsigned feePubKeyBitsize(feePubKey pubKey);
336
337#ifdef __cplusplus
338}
339#endif
340
341#endif	/*_CK_FEEPUBLICKEY_H_*/
342