OSX/libsecurity_cryptkit/lib/feePublicKey.h

   1 /* Copyright (c) 1998,2011-2012,2014 Apple 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, INC. AND THE
   6  * ORIGINAL LICENSEE THAT OBTAINED THESE MATERIALS FROM APPLE,
   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 at Apple
  16  *      Added blob support.
  17  * 17 Jul 97 at Apple
  18  *      Added ECDSA signature routines.
  19  * 20 Aug 96 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
  37 extern "C" {
  38 #endif
  39
  40 /*
  41  * Obatin a newly allocated feePubKey.
  42  */
  43 feePubKey feePubKeyAlloc(void);
  44
  45 void 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  */
  56 feeReturn feePubKeyInitFromPrivDataDepth(feePubKey pubKey,
  57         const unsigned char *privData,
  58         unsigned privDataLen,
  59         feeDepth depth,
  60         char hashPrivData);
  61
  62 feeReturn 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  */
  78 feeReturn 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  */
 102 feeReturn feePubKeyCreatePubBlob(feePubKey pubKey,
 103         unsigned char **keyBlob,        // mallocd and RETURNED
 104         unsigned *keyBlobLen);          // RETURNED
 105
 106 feeReturn 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  */
 113 feeReturn feePubKeyInitFromPubBlob(feePubKey pubKey,
 114         unsigned char *keyBlob,
 115         unsigned keyBlobLen);
 116 feeReturn 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  */
 123 feeReturn feePubKeyCreateKeyString(feePubKey pubKey,
 124         char **pubKeyString,            /* fmalloc'd & RETURNED */
 125         unsigned *pubKeyStringLen);     /* RETURNED */
 126
 127 /*
 128  * Init feePubKey from a public key string.
 129  */
 130 feeReturn 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  */
 140 feeReturn feePubKeyCreateDERPubBlob(feePubKey pubKey,
 141         unsigned char **keyBlob,        // mallocd and RETURNED
 142         unsigned *keyBlobLen);          // RETURNED
 143
 144 feeReturn 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  */
 151 feeReturn feePubKeyInitFromDERPubBlob(feePubKey pubKey,
 152         unsigned char *keyBlob,
 153         size_t keyBlobLen);
 154 feeReturn feePubKeyInitFromDERPrivBlob(feePubKey pubKey,
 155         unsigned char *keyBlob,
 156         size_t keyBlobLen);
 157
 158 /*
 159  * X509 (public) and PKCS8 (private) key formatting.
 160  */
 161 feeReturn feePubKeyCreateX509Blob(
 162         feePubKey pubKey,                       // public key
 163         unsigned char **keyBlob,        // mallocd and RETURNED
 164         unsigned *keyBlobLen);          // RETURNED
 165
 166 feeReturn feePubKeyCreatePKCS8Blob(
 167         feePubKey pubKey,                       // private key
 168         unsigned char **keyBlob,        // mallocd and RETURNED
 169         unsigned *keyBlobLen);          // RETURNED
 170
 171 feeReturn feePubKeyInitFromX509Blob(
 172         feePubKey pubKey,                       // public key
 173         unsigned char *keyBlob,
 174         size_t keyBlobLen);
 175
 176 feeReturn 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  */
 188 feeReturn feePubKeyCreateOpenSSLBlob(
 189         feePubKey pubKey,                       // private key
 190         unsigned char **keyBlob,        // mallocd and RETURNED
 191         unsigned *keyBlobLen);          // RETURNED
 192
 193 feeReturn 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  */
 206 feeReturn feeCreateECDSAPubBlob(feePubKey pubKey,
 207         unsigned char **keyBlob,
 208         unsigned *keyBlobLen);
 209
 210 feeReturn feeCreateECDSAPrivBlob(feePubKey pubKey,
 211         unsigned char **keyBlob,
 212         unsigned *keyBlobLen);
 213
 214 /* Caller determines depth from other sources (e.g. AlgId.Params) */
 215 feeReturn feePubKeyInitFromECDSAPubBlob(feePubKey pubKey,
 216         const unsigned char *keyBlob,
 217         unsigned keyBlobLen,
 218         feeDepth depth);
 219
 220 feeReturn 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  */
 234 feeReturn feePubKeyInitPubKeyFromPriv(feePubKey privKey,
 235         feePubKey pubKey);
 236
 237 /*
 238  * Returns non-zero if two keys are equivalent.
 239  */
 240 int 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  */
 247 int 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  */
 256 feeReturn 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  */
 271 feeReturn 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  */
 280 feeReturn 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  */
 294 feeReturn 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  */
 303 feeReturn 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  */
 320 feeReturn 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  */
 333 const char *feePubKeyAlgorithmName(void);
 334
 335 unsigned feePubKeyBitsize(feePubKey pubKey);
 336
 337 #ifdef __cplusplus
 338 }
 339 #endif
 340
 341 #endif  /*_CK_FEEPUBLICKEY_H_*/