OSX/sec/Security/SecKeyPriv.h

   1 /*
   2  * Copyright (c) 2006-2010,2012-2015 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*!
  25         @header SecKeyPriv
  26         The functions provided in SecKeyPriv.h implement and manage a particular
  27     type of keychain item that represents a key.  A key can be stored in a
  28     keychain, but a key can also be a transient object.
  29
  30         You can use a key as a keychain item in most functions.
  31 */
  32
  33 #ifndef _SECURITY_SECKEYPRIV_H_
  34 #define _SECURITY_SECKEYPRIV_H_
  35
  36 #include <Security/SecKey.h>
  37 #include <Security/SecAsn1Types.h>
  38 #include <CoreFoundation/CFRuntime.h>
  39 #include <CoreFoundation/CoreFoundation.h>
  40
  41 __BEGIN_DECLS
  42
  43 typedef struct __SecDERKey {
  44         uint8_t             *oid;
  45         CFIndex             oidLength;
  46
  47         uint8_t             *parameters;
  48         CFIndex             parametersLength;
  49
  50     /* Contents of BIT STRING in DER Encoding */
  51         uint8_t             *key;
  52         CFIndex             keyLength;
  53 } SecDERKey;
  54
  55
  56 typedef uint32_t SecKeyEncoding;
  57 enum {
  58     /* Typically only used for symmetric keys. */
  59     kSecKeyEncodingRaw = 0,
  60
  61     /* RSA keys are DER-encoded according to PKCS1. */
  62     kSecKeyEncodingPkcs1 = 1,
  63
  64     /* RSA keys are DER-encoded according to PKCS1 with Apple Extensions. */
  65     kSecKeyEncodingApplePkcs1 = 2,
  66
  67     /* RSA public key in SecRSAPublicKeyParams format.  keyData is a pointer
  68        to a SecRSAPublicKeyParams and keyDataLength is
  69        sizeof(SecRSAPublicKeyParams). */
  70     kSecKeyEncodingRSAPublicParams = 3,
  71
  72     /* RSA public key in SecRSAPublicKeyParams format.  keyData is a pointer
  73        to a SecRSAPublicKeyParams and keyDataLength is
  74        sizeof(SecRSAPublicKeyParams). */
  75     kSecDERKeyEncoding = 4,
  76
  77     /* Internal "encodings to send other data" */
  78     kSecGenerateKey = 5,
  79     kSecExtractPublicFromPrivate = 6,
  80
  81     /* Encoding came from SecKeyCopyPublicBytes for a public key,
  82        or internally from a private key */
  83     kSecKeyEncodingBytes = 7,
  84
  85     /* Handing in a private key from corecrypto directly. */
  86     kSecKeyCoreCrypto = 8,
  87
  88 };
  89
  90 typedef uint32_t SecKeyWrapType;
  91 enum {
  92     /* wrap key in RFC3394 (AESWrap) */
  93     kSecKeyWrapRFC3394 = 0,
  94
  95     /* wrap key in PGP style (support EC keys only right now) */
  96     kSecKeyWrapPublicKeyPGP = 1,
  97
  98 };
  99
 100 typedef OSStatus (*SecKeyInitMethod)(SecKeyRef, const uint8_t *, CFIndex,
 101     SecKeyEncoding);
 102 typedef void  (*SecKeyDestroyMethod)(SecKeyRef);
 103 typedef OSStatus (*SecKeyRawSignMethod)(SecKeyRef key, SecPadding padding,
 104         const uint8_t *dataToSign, size_t dataToSignLen,
 105         uint8_t *sig, size_t *sigLen);
 106 typedef OSStatus (*SecKeyRawVerifyMethod)(
 107     SecKeyRef key, SecPadding padding, const uint8_t *signedData,
 108     size_t signedDataLen, const uint8_t *sig, size_t sigLen);
 109 typedef OSStatus (*SecKeyEncryptMethod)(SecKeyRef key, SecPadding padding,
 110     const uint8_t *plainText, size_t plainTextLen,
 111         uint8_t *cipherText, size_t *cipherTextLen);
 112 typedef OSStatus (*SecKeyDecryptMethod)(SecKeyRef key, SecPadding padding,
 113     const uint8_t *cipherText, size_t cipherTextLen,
 114     uint8_t *plainText, size_t *plainTextLen);
 115 typedef OSStatus (*SecKeyComputeMethod)(SecKeyRef key,
 116     const uint8_t *pub_key, size_t pub_key_len,
 117     uint8_t *computed_key, size_t *computed_key_len);
 118 typedef size_t (*SecKeyBlockSizeMethod)(SecKeyRef key);
 119 typedef CFDictionaryRef (*SecKeyCopyDictionaryMethod)(SecKeyRef key);
 120 typedef CFIndex (*SecKeyGetAlgorithmIDMethod)(SecKeyRef key);
 121 typedef OSStatus (*SecKeyCopyPublicBytesMethod)(SecKeyRef key, CFDataRef *serialization);
 122 typedef CFDataRef (*SecKeyCopyWrapKeyMethod)(SecKeyRef key, SecKeyWrapType type, CFDataRef unwrappedKey, CFDictionaryRef parameters, CFDictionaryRef *outParam, CFErrorRef *error);
 123 typedef CFDataRef (*SecKeyCopyUnwrapKeyMethod)(SecKeyRef key, SecKeyWrapType type, CFDataRef wrappedKey, CFDictionaryRef parameters, CFDictionaryRef *outParam, CFErrorRef *error);
 124 typedef CFStringRef (*SecKeyDescribeMethod)(SecKeyRef key);
 125
 126 #define kSecKeyDescriptorVersion  (3)
 127
 128 typedef struct __SecKeyDescriptor {
 129     /* Version of this SecKeyDescriptor.  Must be kSecKeyDescriptorVersion. */
 130     uint32_t version;
 131
 132     /* Name of this key class for use by SecKeyShow(). */
 133     const char *name;
 134
 135     /* If nonzero, SecKeyCreate will allocate this many bytes for the key
 136        field in the SecKeyRef it creates.  If zero key is NULL and the
 137        implementor can choose to dynamically allocate it in the init
 138        function and free it in the destroy function.  */
 139     uint32_t extraBytes;
 140
 141     /* Called by SecKeyCreate(). */
 142     SecKeyInitMethod init;
 143     /* Called by destructor (final CFRelease() or gc if using). */
 144     SecKeyDestroyMethod destroy;
 145     /* Called by SecKeyRawSign(). */
 146     SecKeyRawSignMethod rawSign;
 147     /* Called by SecKeyRawVerify(). */
 148     SecKeyRawVerifyMethod rawVerify;
 149     /* Called by SecKeyEncrypt(). */
 150     SecKeyEncryptMethod encrypt;
 151     /* Called by SecKeyDecrypt(). */
 152     SecKeyDecryptMethod decrypt;
 153     /* Reserved for future use. */
 154     SecKeyComputeMethod compute;
 155     /* Called by SecKeyGetBlockSize(). */
 156     SecKeyBlockSizeMethod blockSize;
 157     /* Called by SecKeyCopyAttributeDictionary(), which is private. */
 158     SecKeyCopyDictionaryMethod copyDictionary;
 159     /* Called by SecKeyDescribeMethod(). */
 160     SecKeyDescribeMethod describe;
 161 #if kSecKeyDescriptorVersion > 0
 162     /* Called by SecKeyCopyAttributeDictionary(), which is private. */
 163     SecKeyGetAlgorithmIDMethod getAlgorithmID;
 164 #endif
 165 #if kSecKeyDescriptorVersion > 1
 166     SecKeyCopyPublicBytesMethod copyPublic;
 167 #endif
 168 #if kSecKeyDescriptorVersion > 2
 169     SecKeyCopyWrapKeyMethod copyWrapKey;
 170     SecKeyCopyUnwrapKeyMethod copyUnwrapKey;
 171 #endif
 172 } SecKeyDescriptor;
 173
 174 struct __SecKey {
 175     CFRuntimeBase               _base;
 176
 177     const SecKeyDescriptor *key_class;
 178
 179     /* The actual key handled by class. */
 180     void *key;
 181 };
 182
 183 /*!
 184     @function SecKeyCreate
 185     @abstract Given a private key and data to sign, generate a digital signature.
 186     @param allocator allocator to use when allocating this key instance.
 187     @param key_class pointer to a SecKeyDescriptor.
 188     @param keyData The second argument to the init() function in the key_class.
 189     @param keyDataLength The third argument to the init() function in the key_class.
 190     @param encoding The fourth argument to the init() function in the key_class.
 191     @result A newly allocated SecKeyRef.
 192  */
 193 SecKeyRef SecKeyCreate(CFAllocatorRef allocator,
 194     const SecKeyDescriptor *key_class, const uint8_t *keyData,
 195         CFIndex keyDataLength, SecKeyEncoding encoding);
 196
 197 /* Create a public key from an oid, params and keyData all in DER format. */
 198 SecKeyRef SecKeyCreatePublicFromDER(CFAllocatorRef allocator,
 199     const SecAsn1Oid *oid1, const SecAsn1Item *params,
 200     const SecAsn1Item *keyData);
 201
 202 /* Create a public key from a CFData containing a SubjectPublicKeyInfo in DER format. */
 203 SecKeyRef SecKeyCreateFromSubjectPublicKeyInfoData(CFAllocatorRef allocator,
 204     CFDataRef subjectPublicKeyInfoData);
 205
 206 /* Create public key from private key */
 207 SecKeyRef SecKeyCreatePublicFromPrivate(SecKeyRef privateKey);
 208
 209 /* Get Private Key (if present) by publicKey. */
 210 SecKeyRef SecKeyCopyMatchingPrivateKey(SecKeyRef publicKey, CFErrorRef *error);
 211 OSStatus SecKeyGetMatchingPrivateKeyStatus(SecKeyRef publicKey, CFErrorRef *error);
 212
 213 CFDataRef SecKeyCreatePersistentRefToMatchingPrivateKey(SecKeyRef publicKey, CFErrorRef *error);
 214
 215 /* Return an attribute dictionary used to find a private key by public key hash */
 216 CFDictionaryRef CreatePrivateKeyMatchingQuery(SecKeyRef publicKey, bool returnPersistentRef);
 217
 218 /* Return an attribute dictionary used to store this item in a keychain. */
 219 CFDictionaryRef SecKeyCopyAttributeDictionary(SecKeyRef key);
 220
 221 /* Return a key from an attribute dictionary that was used to store this item
 222    in a keychain. */
 223 SecKeyRef SecKeyCreateFromAttributeDictionary(CFDictionaryRef refAttributes);
 224
 225 OSStatus SecKeyDigestAndVerify(
 226     SecKeyRef           key,            /* Public key */
 227         const SecAsn1AlgId  *algId,         /* algorithm oid/params */
 228         const uint8_t       *dataToDigest,      /* signature over this data */
 229         size_t              dataToDigestLen,/* length of dataToDigest */
 230         const uint8_t       *sig,                       /* signature to verify */
 231         size_t              sigLen);            /* length of sig */
 232
 233 OSStatus SecKeyDigestAndSign(
 234     SecKeyRef           key,            /* Private key */
 235         const SecAsn1AlgId  *algId,         /* algorithm oid/params */
 236         const uint8_t       *dataToDigest,      /* signature over this data */
 237         size_t              dataToDigestLen,/* length of dataToDigest */
 238         uint8_t             *sig,                       /* signature, RETURNED */
 239         size_t              *sigLen);           /* IN/OUT */
 240
 241 OSStatus SecKeyVerifyDigest(
 242     SecKeyRef           key,            /* Private key */
 243     const SecAsn1AlgId  *algId,         /* algorithm oid/params */
 244     const uint8_t       *digestData,    /* signature over this digest */
 245     size_t              digestDataLen,/* length of dataToDigest */
 246     const uint8_t       *sig,                   /* signature to verify */
 247     size_t              sigLen);        /* length of sig */
 248
 249 OSStatus SecKeySignDigest(
 250     SecKeyRef           key,            /* Private key */
 251     const SecAsn1AlgId  *algId,         /* algorithm oid/params */
 252     const uint8_t       *digestData,    /* signature over this digest */
 253     size_t              digestDataLen,/* length of digestData */
 254     uint8_t             *sig,                   /* signature, RETURNED */
 255     size_t              *sigLen);               /* IN/OUT */
 256
 257 OSStatus SecKeyCopyPublicBytes(SecKeyRef key, CFDataRef* serializedPublic);
 258 SecKeyRef SecKeyCreateFromPublicBytes(CFAllocatorRef allocator, CFIndex algorithmID, const uint8_t *keyData, CFIndex keyDataLength);
 259 SecKeyRef SecKeyCreateFromPublicData(CFAllocatorRef allocator, CFIndex algorithmID, CFDataRef serialized);
 260 CFDataRef SecKeyCopyPublicKeyHash(SecKeyRef key);
 261
 262 CF_RETURNS_RETAINED
 263 CFDictionaryRef SecKeyGeneratePrivateAttributeDictionary(SecKeyRef key,
 264                                                          CFTypeRef keyType,
 265                                                          CFDataRef privateBlob);
 266 CF_RETURNS_RETAINED
 267 CFDictionaryRef SecKeyGeneratePublicAttributeDictionary(SecKeyRef key, CFTypeRef keyType);
 268
 269 enum {
 270     kSecNullAlgorithmID = 0,
 271     kSecRSAAlgorithmID = 1,
 272     kSecDSAAlgorithmID = 2,   /* unsupported, just here for reference. */
 273     kSecECDSAAlgorithmID = 3,
 274 };
 275
 276 /*!
 277         @function SecKeyGetAlgorithmID
 278         @abstract Returns an enumerated constant value which identifies the algorithm for the given key.
 279         @param key A key reference.
 280         @result An algorithm identifier.
 281         @discussion Deprecated in iOS 9.0. Note that SecKeyGetAlgorithmID also exists on OS X
 282         with different arguments for CDSA-based SecKeyRefs, and returns different values.
 283         For compatibility, your code should migrate to use SecKeyGetAlgorithmId instead.
 284 */
 285 CFIndex SecKeyGetAlgorithmID(SecKeyRef key)
 286         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_8, __IPHONE_5_0, __IPHONE_9_0);
 287
 288 /*!
 289         @function SecKeyGetAlgorithmId
 290         @abstract Returns an enumerated constant value which identifies the algorithm for the given key.
 291         @param key A key reference.
 292         @result An algorithm identifier.
 293 */
 294 CFIndex SecKeyGetAlgorithmId(SecKeyRef key)
 295         __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_9_0);
 296
 297
 298 typedef enum {
 299     kSecKeyKeySizeInBits        = 0,
 300     kSecKeySignatureSize        = 1,
 301     kSecKeyEncryptedDataSize    = 2,
 302     // More might belong here, but we aren't settled on how
 303     // to take into account padding and/or digest types.
 304 } SecKeySize;
 305
 306 /*!
 307  @function SecKeyGetSize
 308  @abstract Returns a size in bytes.
 309  @param key The key for which the block length is requested.
 310  @param whichSize The size that you want evaluated.
 311  @result The block length of the key in bytes.
 312  @discussion If for example key is an RSA key the value returned by
 313  this function is the size of the modulus.
 314  */
 315 size_t SecKeyGetSize(SecKeyRef key, SecKeySize whichSize)
 316 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0);
 317
 318
 319 /*!
 320  @function SecKeyLookupPersistentRef
 321  @abstract Looks up a SecKeyRef via persistent ref.
 322  @param persistentRef The persistent ref data for looking up.
 323  @param lookedUpData retained SecKeyRef for the found object.
 324  @result Errors when using SecItemFind for the persistent ref.
 325  */
 326 OSStatus SecKeyFindWithPersistentRef(CFDataRef persistentRef, SecKeyRef* lookedUpData)
 327 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 328
 329 /*!
 330  @function SecKeyCopyPersistentRef
 331  @abstract Gets a persistent reference for a key.
 332  @param key Key to make a persistent ref for.
 333  @param persistentRef Allocated data representing the persistent ref.
 334  @result Errors when using SecItemFind for the persistent ref.
 335  */
 336 OSStatus SecKeyCopyPersistentRef(SecKeyRef key, CFDataRef* persistentRef)
 337 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 338
 339
 340 /*
 341  *
 342  */
 343
 344 extern const CFStringRef _kSecKeyWrapPGPSymAlg; /* CFNumber */
 345 extern const CFStringRef _kSecKeyWrapPGPFingerprint; /* CFDataRef, at least 20 bytes */
 346 extern const CFStringRef _kSecKeyWrapPGPWrapAlg; /* kSecKeyWrapRFC6637WrapNNN, or any of the other PGP wrap algs */
 347 extern const CFStringRef _kSecKeyWrapRFC6637Flags;
 348 extern const CFStringRef _kSecKeyWrapRFC6637WrapDigestSHA256KekAES128;
 349 extern const CFStringRef _kSecKeyWrapRFC6637WrapDigestSHA512KekAES256;
 350
 351 enum { kSecKeyWrapPGPFingerprintMinSize = 20 };
 352 /*!
 353  @function _SecKeyCopyWrapKey
 354  @abstract Wrap a key
 355  */
 356
 357 CFDataRef
 358 _SecKeyCopyWrapKey(SecKeyRef key, SecKeyWrapType type, CFDataRef unwrappedKey, CFDictionaryRef parameters, CFDictionaryRef *outParam, CFErrorRef *error)
 359 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
 360
 361 /*!
 362  @function _SecKeyWrapKey
 363  @abstract Unwrap a key
 364  */
 365
 366 CFDataRef
 367 _SecKeyCopyUnwrapKey(SecKeyRef key, SecKeyWrapType type, CFDataRef wrappedKey, CFDictionaryRef parameters, CFDictionaryRef *outParam, CFErrorRef *error)
 368 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
 369
 370
 371 __END_DECLS
 372
 373 #endif /* !_SECURITY_SECKEYPRIV_H_ */