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/CFData.h>
  40
  41 #if defined(__cplusplus)
  42 extern "C" {
  43 #endif
  44
  45 typedef struct __SecDERKey {
  46         uint8_t             *oid;
  47         CFIndex             oidLength;
  48
  49         uint8_t             *parameters;
  50         CFIndex             parametersLength;
  51
  52     /* Contents of BIT STRING in DER Encoding */
  53         uint8_t             *key;
  54         CFIndex             keyLength;
  55 } SecDERKey;
  56
  57
  58 typedef uint32_t SecKeyEncoding;
  59 enum {
  60     /* Typically only used for symmetric keys. */
  61     kSecKeyEncodingRaw = 0,
  62
  63     /* RSA keys are DER-encoded according to PKCS1. */
  64     kSecKeyEncodingPkcs1 = 1,
  65
  66     /* RSA keys are DER-encoded according to PKCS1 with Apple Extensions. */
  67     kSecKeyEncodingApplePkcs1 = 2,
  68
  69     /* RSA public key in SecRSAPublicKeyParams format.  keyData is a pointer
  70        to a SecRSAPublicKeyParams and keyDataLength is
  71        sizeof(SecRSAPublicKeyParams). */
  72     kSecKeyEncodingRSAPublicParams = 3,
  73
  74     /* RSA public key in SecRSAPublicKeyParams format.  keyData is a pointer
  75        to a SecRSAPublicKeyParams and keyDataLength is
  76        sizeof(SecRSAPublicKeyParams). */
  77     kSecDERKeyEncoding = 4,
  78
  79     /* Internal "encodings to send other data" */
  80     kSecGenerateKey = 5,
  81     kSecExtractPublicFromPrivate = 6,
  82
  83     /* Encoding came from SecKeyCopyPublicBytes for a public key,
  84        or internally from a private key */
  85     kSecKeyEncodingBytes = 7,
  86 };
  87
  88 typedef OSStatus (*SecKeyInitMethod)(SecKeyRef, const uint8_t *, CFIndex,
  89     SecKeyEncoding);
  90 typedef void  (*SecKeyDestroyMethod)(SecKeyRef);
  91 typedef OSStatus (*SecKeyRawSignMethod)(SecKeyRef key, SecPadding padding,
  92         const uint8_t *dataToSign, size_t dataToSignLen,
  93         uint8_t *sig, size_t *sigLen);
  94 typedef OSStatus (*SecKeyRawVerifyMethod)(
  95     SecKeyRef key, SecPadding padding, const uint8_t *signedData,
  96     size_t signedDataLen, const uint8_t *sig, size_t sigLen);
  97 typedef OSStatus (*SecKeyEncryptMethod)(SecKeyRef key, SecPadding padding,
  98     const uint8_t *plainText, size_t plainTextLen,
  99         uint8_t *cipherText, size_t *cipherTextLen);
 100 typedef OSStatus (*SecKeyDecryptMethod)(SecKeyRef key, SecPadding padding,
 101     const uint8_t *cipherText, size_t cipherTextLen,
 102     uint8_t *plainText, size_t *plainTextLen);
 103 typedef OSStatus (*SecKeyComputeMethod)(SecKeyRef key,
 104     const uint8_t *pub_key, size_t pub_key_len,
 105     uint8_t *computed_key, size_t *computed_key_len);
 106 typedef size_t (*SecKeyBlockSizeMethod)(SecKeyRef key);
 107 typedef CFDictionaryRef (*SecKeyCopyDictionaryMethod)(SecKeyRef key);
 108 typedef CFIndex (*SecKeyGetAlgorithmIDMethod)(SecKeyRef key);
 109 typedef OSStatus (*SecKeyCopyPublicBytesMethod)(SecKeyRef key, CFDataRef *serailziation);
 110
 111
 112 #define kSecKeyDescriptorVersion  (2)
 113
 114 typedef struct __SecKeyDescriptor {
 115     /* Version of this SecKeyDescriptor.  Must be kSecKeyDescriptorVersion. */
 116     uint32_t version;
 117
 118     /* Name of this key class for use by SecKeyShow(). */
 119     const char *name;
 120
 121     /* If nonzero, SecKeyCreate will allocate this many bytes for the key
 122        field in the SecKeyRef it creates.  If zero key is NULL and the
 123        implementor can choose to dynamically allocate it in the init
 124        function and free it in the destroy function.  */
 125     uint32_t extraBytes;
 126
 127     /* Called by SecKeyCreate(). */
 128     SecKeyInitMethod init;
 129     /* Called by destructor (final CFRelease() or gc if using). */
 130     SecKeyDestroyMethod destroy;
 131     /* Called by SecKeyRawSign(). */
 132     SecKeyRawSignMethod rawSign;
 133     /* Called by SecKeyRawVerify(). */
 134     SecKeyRawVerifyMethod rawVerify;
 135     /* Called by SecKeyEncrypt(). */
 136     SecKeyEncryptMethod encrypt;
 137     /* Called by SecKeyDecrypt(). */
 138     SecKeyDecryptMethod decrypt;
 139     /* Reserved for future use. */
 140     SecKeyComputeMethod compute;
 141     /* Called by SecKeyGetBlockSize(). */
 142     SecKeyBlockSizeMethod blockSize;
 143     /* Called by SecKeyCopyAttributeDictionary(), which is private. */
 144     SecKeyCopyDictionaryMethod copyDictionary;
 145 #if kSecKeyDescriptorVersion > 0
 146     /* Called by SecKeyCopyAttributeDictionary(), which is private. */
 147     SecKeyGetAlgorithmIDMethod getAlgorithmID;
 148 #endif
 149 #if kSecKeyDescriptorVersion > 1
 150     SecKeyCopyPublicBytesMethod copyPublic;
 151 #endif
 152 } SecKeyDescriptor;
 153
 154 struct __SecKey {
 155     CFRuntimeBase               _base;
 156
 157     const SecKeyDescriptor *key_class;
 158
 159     /* The actual key handled by class. */
 160     void *key;
 161 };
 162
 163 /*!
 164     @function SecKeyCreate
 165     @abstract Given a private key and data to sign, generate a digital signature.
 166     @param allocator allocator to use when allocating this key instance.
 167     @param key_class pointer to a SecKeyDescriptor.
 168     @param keyData The second argument to the init() function in the key_class.
 169     @param keyDataLength The third argument to the init() function in the key_class.
 170     @param encoding The fourth argument to the init() function in the key_class.
 171     @result A newly allocated SecKeyRef.
 172  */
 173 SecKeyRef SecKeyCreate(CFAllocatorRef allocator,
 174     const SecKeyDescriptor *key_class, const uint8_t *keyData,
 175         CFIndex keyDataLength, SecKeyEncoding encoding);
 176
 177 /* Create a public key from an oid, params and keyData all in DER format. */
 178 SecKeyRef SecKeyCreatePublicFromDER(CFAllocatorRef allocator,
 179     const SecAsn1Oid *oid1, const SecAsn1Item *params,
 180     const SecAsn1Item *keyData);
 181
 182 /* Return an attribute dictionary used to store this item in a keychain. */
 183 CFDictionaryRef SecKeyCopyAttributeDictionary(SecKeyRef key);
 184
 185 /* Return a key from an attribute dictionary that was used to store this item
 186    in a keychain. */
 187 SecKeyRef SecKeyCreateFromAttributeDictionary(CFDictionaryRef refAttributes);
 188
 189 OSStatus SecKeyDigestAndVerify(
 190     SecKeyRef           key,            /* Public key */
 191         const SecAsn1AlgId  *algId,         /* algorithm oid/params */
 192         const uint8_t       *dataToDigest,      /* signature over this data */
 193         size_t              dataToDigestLen,/* length of dataToDigest */
 194         const uint8_t       *sig,                       /* signature to verify */
 195         size_t              sigLen);            /* length of sig */
 196
 197 OSStatus SecKeyDigestAndSign(
 198     SecKeyRef           key,            /* Private key */
 199         const SecAsn1AlgId  *algId,         /* algorithm oid/params */
 200         const uint8_t       *dataToDigest,      /* signature over this data */
 201         size_t              dataToDigestLen,/* length of dataToDigest */
 202         uint8_t             *sig,                       /* signature, RETURNED */
 203         size_t              *sigLen);           /* IN/OUT */
 204
 205 OSStatus SecKeyVerifyDigest(
 206     SecKeyRef           key,            /* Private key */
 207     const SecAsn1AlgId  *algId,         /* algorithm oid/params */
 208     const uint8_t       *digestData,    /* signature over this digest */
 209     size_t              digestDataLen,/* length of dataToDigest */
 210     const uint8_t       *sig,                   /* signature to verify */
 211     size_t              sigLen);        /* length of sig */
 212
 213 OSStatus SecKeySignDigest(
 214     SecKeyRef           key,            /* Private key */
 215     const SecAsn1AlgId  *algId,         /* algorithm oid/params */
 216     const uint8_t       *digestData,    /* signature over this digest */
 217     size_t              digestDataLen,/* length of digestData */
 218     uint8_t             *sig,                   /* signature, RETURNED */
 219     size_t              *sigLen);               /* IN/OUT */
 220
 221 OSStatus SecKeyCopyPublicBytes(SecKeyRef key, CFDataRef* serializedPublic);
 222 SecKeyRef SecKeyCreateFromPublicBytes(CFAllocatorRef allocator, CFIndex algorithmID, const uint8_t *keyData, CFIndex keyDataLength);
 223 SecKeyRef SecKeyCreateFromPublicData(CFAllocatorRef allocator, CFIndex algorithmID, CFDataRef serialized);
 224
 225
 226 CFDictionaryRef SecKeyGeneratePrivateAttributeDictionary(SecKeyRef key,
 227                                                          CFTypeRef keyType,
 228                                                          CFDataRef privateBlob);
 229 CFDictionaryRef SecKeyGeneratePublicAttributeDictionary(SecKeyRef key, CFTypeRef keyType);
 230
 231 enum {
 232     kSecNullAlgorithmID = 0,
 233     kSecRSAAlgorithmID = 1,
 234     kSecDSAAlgorithmID = 2,   /* unsupported, just here for reference. */
 235     kSecECDSAAlgorithmID = 3,
 236 };
 237
 238 CFIndex SecKeyGetAlgorithmID(SecKeyRef key);
 239
 240 typedef enum {
 241     kSecKeyKeySizeInBits        = 0,
 242     kSecKeySignatureSize        = 1,
 243     kSecKeyEncryptedDataSize    = 2,
 244     // More might belong here, but we aren't settled on how
 245     // to take into account padding and/or digest types.
 246 } SecKeySize;
 247
 248 /*!
 249  @function SecKeyGetSize
 250  @abstract Returns a size in bytes.
 251  @param key The key for which the block length is requested.
 252  @param whichSize The size that you want evaluated.
 253  @result The block length of the key in bytes.
 254  @discussion If for example key is an RSA key the value returned by
 255  this function is the size of the modulus.
 256  */
 257 size_t SecKeyGetSize(SecKeyRef key, SecKeySize whichSize)
 258 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0);
 259
 260
 261
 262 #if defined(__cplusplus)
 263 }
 264 #endif
 265
 266 #endif /* !_SECURITY_SECKEYPRIV_H_ */