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