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 /*
 135  * DER format support.
 136  * Obtain portable public and private DER-encoded key blobs from a key.
 137  */
 138 feeReturn feePubKeyCreateDERPubBlob(feePubKey pubKey,
 139         unsigned char **keyBlob,        // mallocd and RETURNED
 140         unsigned *keyBlobLen);          // RETURNED
 141
 142 feeReturn feePubKeyCreateDERPrivBlob(feePubKey pubKey,
 143         unsigned char **keyBlob,        // mallocd and RETURNED
 144         unsigned *keyBlobLen);          // RETURNED
 145
 146 /*
 147  * Init an empty feePubKey from a DER-encoded blob, public and private key versions.
 148  */
 149 feeReturn feePubKeyInitFromDERPubBlob(feePubKey pubKey,
 150         unsigned char *keyBlob,
 151         size_t keyBlobLen);
 152 feeReturn feePubKeyInitFromDERPrivBlob(feePubKey pubKey,
 153         unsigned char *keyBlob,
 154         size_t keyBlobLen);
 155
 156 /*
 157  * X509 (public) and PKCS8 (private) key formatting.
 158  */
 159 feeReturn feePubKeyCreateX509Blob(
 160         feePubKey pubKey,                       // public key
 161         unsigned char **keyBlob,        // mallocd and RETURNED
 162         unsigned *keyBlobLen);          // RETURNED
 163
 164 feeReturn feePubKeyCreatePKCS8Blob(
 165         feePubKey pubKey,                       // private key
 166         unsigned char **keyBlob,        // mallocd and RETURNED
 167         unsigned *keyBlobLen);          // RETURNED
 168
 169 feeReturn feePubKeyInitFromX509Blob(
 170         feePubKey pubKey,                       // public key
 171         unsigned char *keyBlob,
 172         size_t keyBlobLen);
 173
 174 feeReturn feePubKeyInitFromPKCS8Blob(
 175         feePubKey pubKey,                       // private key
 176         unsigned char *keyBlob,
 177         size_t keyBlobLen);
 178
 179 /*
 180  * The native OpenSSL ECDSA key format contains both the private and public
 181  * components in one blob. This throws a bit of a monkey wrench into the API
 182  * here, as we only have one encoder - which requires a private key - and one
 183  * decoder, which can result in the decoding of either a public or a private
 184  * key.
 185  */
 186 feeReturn feePubKeyCreateOpenSSLBlob(
 187         feePubKey pubKey,                       // private key
 188         unsigned char **keyBlob,        // mallocd and RETURNED
 189         unsigned *keyBlobLen);          // RETURNED
 190
 191 feeReturn feePubKeyInitFromOpenSSLBlob(
 192         feePubKey pubKey,                       // private or public key
 193         int pubOnly,
 194         unsigned char *keyBlob,
 195         size_t keyBlobLen);
 196
 197 /*
 198  * ANSI X9.62/Certicom key support.
 199  * Public key is 04 || x || y
 200  * Private key is privData per Certicom SEC1 C.4.
 201  */
 202 feeReturn feeCreateECDSAPubBlob(feePubKey pubKey,
 203         unsigned char **keyBlob,
 204         unsigned *keyBlobLen);
 205
 206 feeReturn feeCreateECDSAPrivBlob(feePubKey pubKey,
 207         unsigned char **keyBlob,
 208         unsigned *keyBlobLen);
 209
 210 /* Caller determines depth from other sources (e.g. AlgId.Params) */
 211 feeReturn feePubKeyInitFromECDSAPubBlob(feePubKey pubKey,
 212         const unsigned char *keyBlob,
 213         unsigned keyBlobLen,
 214         feeDepth depth);
 215
 216 feeReturn feePubKeyInitFromECDSAPrivBlob(feePubKey pubKey,
 217         const unsigned char *keyBlob,
 218         unsigned keyBlobLen,
 219         feeDepth depth);
 220
 221
 222 /***
 223  *** Miscellaneous feePubKey functions.
 224  ***/
 225
 226 /*
 227  * Given private-capable privKey, initialize pubKey to be its corresponding
 228  * public key.
 229  */
 230 feeReturn feePubKeyInitPubKeyFromPriv(feePubKey privKey,
 231         feePubKey pubKey);
 232
 233 /*
 234  * Returns non-zero if two keys are equivalent.
 235  */
 236 int feePubKeyIsEqual(feePubKey key1,
 237         feePubKey key2);
 238
 239 /*
 240  * Returns non-zero if key is private-capable (i.e., capable of signing
 241  * and decrypting).
 242  */
 243 int feePubKeyIsPrivate(feePubKey key);
 244
 245
 246 /*
 247  * Diffie-Hellman. Public key is specified either as a feePubKey or
 248  * a ANSI X9.62 format public key string (0x04 | x | y). In either case
 249  * the caller must ensure that the two keys are on the same curve.
 250  * Output data is falloc'd here; caller must free. Output data is
 251  * exactly the size of the curve's modulus in bytes.
 252  */
 253 feeReturn feePubKeyECDH(
 254         feePubKey privKey,
 255         /* one of the following two is non-NULL */
 256         feePubKey pubKey,
 257         const unsigned char *pubKeyStr,
 258         unsigned pubKeyStrLen,
 259         /* output fallocd and RETURNED here */
 260         unsigned char **output,
 261         unsigned *outputLen);
 262
 263 /*
 264  * Accessor routines.
 265  */
 266 const char *feePubKeyAlgorithmName(void);
 267
 268 unsigned feePubKeyBitsize(feePubKey pubKey);
 269
 270 #ifdef __cplusplus
 271 }
 272 #endif
 273
 274 #endif  /*_CK_FEEPUBLICKEY_H_*/