sec/Security/SecKeyPriv.h

   1 /*
   2  * Copyright (c) 2006-2010 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 OSStatus (*SecKeyInitMethod)(SecKeyRef, const uint8_t *, CFIndex,
  91     SecKeyEncoding);
  92 typedef void  (*SecKeyDestroyMethod)(SecKeyRef);
  93 typedef OSStatus (*SecKeyRawSignMethod)(SecKeyRef key, SecPadding padding,
  94         const uint8_t *dataToSign, size_t dataToSignLen,
  95         uint8_t *sig, size_t *sigLen);
  96 typedef OSStatus (*SecKeyRawVerifyMethod)(
  97     SecKeyRef key, SecPadding padding, const uint8_t *signedData,
  98     size_t signedDataLen, const uint8_t *sig, size_t sigLen);
  99 typedef OSStatus (*SecKeyEncryptMethod)(SecKeyRef key, SecPadding padding,
 100     const uint8_t *plainText, size_t plainTextLen,
 101         uint8_t *cipherText, size_t *cipherTextLen);
 102 typedef OSStatus (*SecKeyDecryptMethod)(SecKeyRef key, SecPadding padding,
 103     const uint8_t *cipherText, size_t cipherTextLen,
 104     uint8_t *plainText, size_t *plainTextLen);
 105 typedef OSStatus (*SecKeyComputeMethod)(SecKeyRef key,
 106     const uint8_t *pub_key, size_t pub_key_len,
 107     uint8_t *computed_key, size_t *computed_key_len);
 108 typedef size_t (*SecKeyBlockSizeMethod)(SecKeyRef key);
 109 typedef CFDictionaryRef (*SecKeyCopyDictionaryMethod)(SecKeyRef key);
 110 typedef CFIndex (*SecKeyGetAlgorithmIDMethod)(SecKeyRef key);
 111 typedef OSStatus (*SecKeyCopyPublicBytesMethod)(SecKeyRef key, CFDataRef *serailziation);
 112 typedef CFStringRef (*SecKeyDescribeMethod)(SecKeyRef key);
 113
 114 #define kSecKeyDescriptorVersion  (2)
 115
 116 typedef struct __SecKeyDescriptor {
 117     /* Version of this SecKeyDescriptor.  Must be kSecKeyDescriptorVersion. */
 118     uint32_t version;
 119
 120     /* Name of this key class for use by SecKeyShow(). */
 121     const char *name;
 122
 123     /* If nonzero, SecKeyCreate will allocate this many bytes for the key
 124        field in the SecKeyRef it creates.  If zero key is NULL and the
 125        implementor can choose to dynamically allocate it in the init
 126        function and free it in the destroy function.  */
 127     uint32_t extraBytes;
 128
 129     /* Called by SecKeyCreate(). */
 130     SecKeyInitMethod init;
 131     /* Called by destructor (final CFRelease() or gc if using). */
 132     SecKeyDestroyMethod destroy;
 133     /* Called by SecKeyRawSign(). */
 134     SecKeyRawSignMethod rawSign;
 135     /* Called by SecKeyRawVerify(). */
 136     SecKeyRawVerifyMethod rawVerify;
 137     /* Called by SecKeyEncrypt(). */
 138     SecKeyEncryptMethod encrypt;
 139     /* Called by SecKeyDecrypt(). */
 140     SecKeyDecryptMethod decrypt;
 141     /* Reserved for future use. */
 142     SecKeyComputeMethod compute;
 143     /* Called by SecKeyGetBlockSize(). */
 144     SecKeyBlockSizeMethod blockSize;
 145     /* Called by SecKeyCopyAttributeDictionary(), which is private. */
 146     SecKeyCopyDictionaryMethod copyDictionary;
 147     /* Called by SecKeyDescribeMethod(). */
 148     SecKeyDescribeMethod describe;
 149 #if kSecKeyDescriptorVersion > 0
 150     /* Called by SecKeyCopyAttributeDictionary(), which is private. */
 151     SecKeyGetAlgorithmIDMethod getAlgorithmID;
 152 #endif
 153 #if kSecKeyDescriptorVersion > 1
 154     SecKeyCopyPublicBytesMethod copyPublic;
 155 #endif
 156 } SecKeyDescriptor;
 157
 158 struct __SecKey {
 159     CFRuntimeBase               _base;
 160
 161     const SecKeyDescriptor *key_class;
 162
 163     /* The actual key handled by class. */
 164     void *key;
 165 };
 166
 167 /*!
 168     @function SecKeyCreate
 169     @abstract Given a private key and data to sign, generate a digital signature.
 170     @param allocator allocator to use when allocating this key instance.
 171     @param key_class pointer to a SecKeyDescriptor.
 172     @param keyData The second argument to the init() function in the key_class.
 173     @param keyDataLength The third argument to the init() function in the key_class.
 174     @param encoding The fourth argument to the init() function in the key_class.
 175     @result A newly allocated SecKeyRef.
 176  */
 177 SecKeyRef SecKeyCreate(CFAllocatorRef allocator,
 178     const SecKeyDescriptor *key_class, const uint8_t *keyData,
 179         CFIndex keyDataLength, SecKeyEncoding encoding);
 180
 181 /* Create a public key from an oid, params and keyData all in DER format. */
 182 SecKeyRef SecKeyCreatePublicFromDER(CFAllocatorRef allocator,
 183     const SecAsn1Oid *oid1, const SecAsn1Item *params,
 184     const SecAsn1Item *keyData);
 185
 186 /* Create public key from private key */
 187 SecKeyRef SecKeyCreatePublicFromPrivate(SecKeyRef privateKey);
 188 SecKeyRef SecKeyCopyMatchingPrivateKey(SecKeyRef publicKey, CFErrorRef *error);
 189 CFDataRef SecKeyCreatePersistentRefToMatchingPrivateKey(SecKeyRef publicKey, CFErrorRef *error);
 190
 191 /* Return an attribute dictionary used to store this item in a keychain. */
 192 CFDictionaryRef SecKeyCopyAttributeDictionary(SecKeyRef key);
 193
 194 /* Return a key from an attribute dictionary that was used to store this item
 195    in a keychain. */
 196 SecKeyRef SecKeyCreateFromAttributeDictionary(CFDictionaryRef refAttributes);
 197
 198 OSStatus SecKeyDigestAndVerify(
 199     SecKeyRef           key,            /* Public key */
 200         const SecAsn1AlgId  *algId,         /* algorithm oid/params */
 201         const uint8_t       *dataToDigest,      /* signature over this data */
 202         size_t              dataToDigestLen,/* length of dataToDigest */
 203         const uint8_t       *sig,                       /* signature to verify */
 204         size_t              sigLen);            /* length of sig */
 205
 206 OSStatus SecKeyDigestAndSign(
 207     SecKeyRef           key,            /* Private key */
 208         const SecAsn1AlgId  *algId,         /* algorithm oid/params */
 209         const uint8_t       *dataToDigest,      /* signature over this data */
 210         size_t              dataToDigestLen,/* length of dataToDigest */
 211         uint8_t             *sig,                       /* signature, RETURNED */
 212         size_t              *sigLen);           /* IN/OUT */
 213
 214 OSStatus SecKeyVerifyDigest(
 215     SecKeyRef           key,            /* Private key */
 216     const SecAsn1AlgId  *algId,         /* algorithm oid/params */
 217     const uint8_t       *digestData,    /* signature over this digest */
 218     size_t              digestDataLen,/* length of dataToDigest */
 219     const uint8_t       *sig,                   /* signature to verify */
 220     size_t              sigLen);        /* length of sig */
 221
 222 OSStatus SecKeySignDigest(
 223     SecKeyRef           key,            /* Private key */
 224     const SecAsn1AlgId  *algId,         /* algorithm oid/params */
 225     const uint8_t       *digestData,    /* signature over this digest */
 226     size_t              digestDataLen,/* length of digestData */
 227     uint8_t             *sig,                   /* signature, RETURNED */
 228     size_t              *sigLen);               /* IN/OUT */
 229
 230 OSStatus SecKeyCopyPublicBytes(SecKeyRef key, CFDataRef* serializedPublic);
 231 SecKeyRef SecKeyCreateFromPublicBytes(CFAllocatorRef allocator, CFIndex algorithmID, const uint8_t *keyData, CFIndex keyDataLength);
 232 SecKeyRef SecKeyCreateFromPublicData(CFAllocatorRef allocator, CFIndex algorithmID, CFDataRef serialized);
 233
 234 CF_RETURNS_RETAINED
 235 CFDictionaryRef SecKeyGeneratePrivateAttributeDictionary(SecKeyRef key,
 236                                                          CFTypeRef keyType,
 237                                                          CFDataRef privateBlob);
 238 CF_RETURNS_RETAINED
 239 CFDictionaryRef SecKeyGeneratePublicAttributeDictionary(SecKeyRef key, CFTypeRef keyType);
 240
 241 enum {
 242     kSecNullAlgorithmID = 0,
 243     kSecRSAAlgorithmID = 1,
 244     kSecDSAAlgorithmID = 2,   /* unsupported, just here for reference. */
 245     kSecECDSAAlgorithmID = 3,
 246 };
 247
 248 CFIndex SecKeyGetAlgorithmID(SecKeyRef key);
 249
 250 typedef enum {
 251     kSecKeyKeySizeInBits        = 0,
 252     kSecKeySignatureSize        = 1,
 253     kSecKeyEncryptedDataSize    = 2,
 254     // More might belong here, but we aren't settled on how
 255     // to take into account padding and/or digest types.
 256 } SecKeySize;
 257
 258 /*!
 259  @function SecKeyGetSize
 260  @abstract Returns a size in bytes.
 261  @param key The key for which the block length is requested.
 262  @param whichSize The size that you want evaluated.
 263  @result The block length of the key in bytes.
 264  @discussion If for example key is an RSA key the value returned by
 265  this function is the size of the modulus.
 266  */
 267 size_t SecKeyGetSize(SecKeyRef key, SecKeySize whichSize)
 268 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0);
 269
 270
 271 /*!
 272  @function SecKeyLookupPersistentRef
 273  @abstract Looks up a SecKeyRef via persistent ref.
 274  @param persistentRef The persistent ref data for looking up.
 275  @param lookedUpData retained SecKeyRef for the found object.
 276  @result Errors when using SecItemFind for the persistent ref.
 277  */
 278 OSStatus SecKeyFindWithPersistentRef(CFDataRef persistentRef, SecKeyRef* lookedUpData)
 279 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 280
 281 /*!
 282  @function SecKeyCopyPersistentRef
 283  @abstract Gets a persistent reference for a key.
 284  @param key Key to make a persistent ref for.
 285  @param persistentRef Allocated data representing the persistent ref.
 286  @result Errors when using SecItemFind for the persistent ref.
 287  */
 288 OSStatus SecKeyCopyPersistentRef(SecKeyRef key, CFDataRef* persistentRef)
 289 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 290
 291
 292
 293 __END_DECLS
 294
 295 #endif /* !_SECURITY_SECKEYPRIV_H_ */