OSX/libsecurity_keychain/lib/SecKeyPriv.h

   1 /*
   2  * Copyright (c) 2002-2009,2011-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  * SecKeyPriv.h - SPIs to SecKeyRef objects.
  24  */
  25
  26 /*!
  27         @header SecKeyPriv
  28         The functions provided in SecKeyPriv.h implement and manage a particular
  29     type of keychain item that represents a key.  A key can be stored in a
  30     keychain, but a key can also be a transient object.
  31
  32         You can use a key as a keychain item in most functions.
  33 */
  34
  35 #ifndef _SECURITY_SECKEYPRIV_H_
  36 #define _SECURITY_SECKEYPRIV_H_
  37
  38 #include <Security/SecKey.h>
  39 #include <Security/x509defs.h>
  40 #include <Security/SecAsn1Types.h>
  41 #include <AvailabilityMacros.h>
  42
  43 #if defined(__cplusplus)
  44 extern "C" {
  45 #endif
  46
  47 typedef struct SecRSAPublicKeyParams {
  48     uint8_t             *modulus;                       /* modulus */
  49     CFIndex             modulusLength;
  50     uint8_t             *exponent;                      /* public exponent */
  51     CFIndex             exponentLength;
  52 } SecRSAPublicKeyParams;
  53
  54 typedef uint32_t SecKeyEncoding;
  55 enum {
  56     /* Typically only used for symmetric keys. */
  57     kSecKeyEncodingRaw = 0,
  58
  59     /* RSA keys are DER-encoded according to PKCS1. */
  60     kSecKeyEncodingPkcs1 = 1,
  61
  62     /* RSA keys are DER-encoded according to PKCS1 with Apple Extensions. */
  63     kSecKeyEncodingApplePkcs1 = 2,
  64
  65     /* RSA public key in SecRSAPublicKeyParams format.  keyData is a pointer
  66        to a SecRSAPublicKeyParams and keyDataLength is
  67        sizeof(SecRSAPublicKeyParams). */
  68     kSecKeyEncodingRSAPublicParams = 3,
  69 };
  70
  71 typedef OSStatus (*SecKeyInitMethod)(SecKeyRef, const uint8_t *, CFIndex,
  72     SecKeyEncoding);
  73 typedef void *(*SecKeyCopyMethod)(SecKeyRef);
  74 typedef void  (*SecKeyDestroyMethod)(SecKeyRef);
  75 typedef void  (*SecKeyDeleteMethod)(SecKeyRef);
  76 typedef void  (*SecKeyShowMethod)(SecKeyRef);
  77 typedef OSStatus (*SecKeyRawSignMethod)(SecKeyRef key, SecPadding padding,
  78         const uint8_t *dataToSign, size_t dataToSignLen,
  79         uint8_t *sig, size_t *sigLen);
  80 typedef OSStatus (*SecKeyRawVerifyMethod)(
  81     SecKeyRef key, SecPadding padding, const uint8_t *signedData,
  82     size_t signedDataLen, const uint8_t *sig, size_t sigLen);
  83 typedef OSStatus (*SecKeyEncryptMethod)(SecKeyRef key, SecPadding padding,
  84     const uint8_t *plainText, size_t plainTextLen,
  85         uint8_t *cipherText, size_t *cipherTextLen);
  86 typedef OSStatus (*SecKeyDecryptMethod)(SecKeyRef key, SecPadding padding,
  87     const uint8_t *cipherText, size_t cipherTextLen,
  88     uint8_t *plainText, size_t *plainTextLen);
  89 typedef size_t (*SecKeyBlockSizeMethod)(SecKeyRef key);
  90 typedef CFDictionaryRef (*SecKeyCopyDictionaryMethod)(SecKeyRef key);
  91
  92 typedef struct {
  93     const char *name;
  94     SecKeyInitMethod init;
  95     SecKeyCopyMethod copy;
  96     SecKeyDestroyMethod destroy;
  97     SecKeyDeleteMethod remove;
  98     SecKeyShowMethod show;
  99     SecKeyRawSignMethod rawSign;
 100     SecKeyRawVerifyMethod rawVerify;
 101     SecKeyEncryptMethod encrypt;
 102     SecKeyDecryptMethod decrypt;
 103     SecKeyBlockSizeMethod blockSize;
 104     SecKeyCopyDictionaryMethod copyDictionary;
 105     /* If known, the number of bytes to allocate for the key field in the SecKey struct. */
 106     int extraBytes;
 107 } SecKeyDescriptor;
 108
 109 CFTypeID SecKeyGetCFClassTypeID(void);
 110
 111 /*!
 112         @function SecKeyGetAlgorithmID
 113         @abstract Returns a pointer to a CSSM_X509_ALGORITHM_IDENTIFIER structure for the given key.
 114     @param key A key reference.
 115     @param algid On return, a pointer to a CSSM_X509_ALGORITHM_IDENTIFIER structure.
 116         @result A result code.  See "Security Error Codes" (SecBase.h).
 117         @discussion Deprecated in OS X 10.8 and later. Continued use is strongly discouraged,
 118     since there is a naming conflict with a similar function (also deprecated) on iOS that
 119     had different arguments and a different return value. Use SecKeyGetAlgorithmId instead.
 120 */
 121 OSStatus SecKeyGetAlgorithmID(SecKeyRef key, const CSSM_X509_ALGORITHM_IDENTIFIER **algid)
 122         DEPRECATED_IN_MAC_OS_X_VERSION_10_8_AND_LATER;
 123
 124 enum {
 125     kSecNullAlgorithmID = 0,
 126     kSecRSAAlgorithmID = 1,
 127     kSecDSAAlgorithmID = 2,   /* unsupported, just here for reference. */
 128     kSecECDSAAlgorithmID = 3,
 129 };
 130
 131 /*!
 132         @function SecKeyGetAlgorithmId
 133         @abstract Returns an enumerated constant value which identifies the algorithm for the given key.
 134         @param key A key reference.
 135         @result An algorithm identifier.
 136 */
 137 CFIndex SecKeyGetAlgorithmId(SecKeyRef key)
 138         __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_9_0);
 139
 140 /*!
 141         @function SecKeyGetStrengthInBits
 142         @abstract Returns key strength in bits for the given key.
 143     @param key A key reference.
 144     @param algid A pointer to a CSSM_X509_ALGORITHM_IDENTIFIER structure, as returned from a call to SecKeyGetAlgorithmID.
 145     @param strength On return, the key strength in bits.
 146         @result A result code.  See "Security Error Codes" (SecBase.h).
 147 */
 148 OSStatus SecKeyGetStrengthInBits(SecKeyRef key, const CSSM_X509_ALGORITHM_IDENTIFIER *algid, unsigned int *strength);
 149
 150 /*!
 151         @function SecKeyImportPair
 152         @abstract Takes an asymmetric key pair and stores it in the keychain specified by the keychain parameter.
 153         @param keychainRef A reference to the keychain in which to store the private and public key items. Specify NULL for the default keychain.
 154     @param publicCssmKey A CSSM_KEY which is valid for the CSP returned by SecKeychainGetCSPHandle(). This may be a normal key or reference key.
 155     @param privateCssmKey A CSSM_KEY which is valid for the CSP returned by SecKeychainGetCSPHandle(). This may be a normal key or reference key.
 156     @param initialAccess A SecAccess object that determines the initial access rights to the private key. The public key is given an any/any acl by default.
 157     @param publicKey Optional output pointer to the keychain item reference of the imported public key. The caller must call CFRelease on this value if it is returned.
 158     @param privateKey Optional output pointer to the keychain item reference of the imported private key. The caller must call CFRelease on this value if it is returned.
 159         @result A result code.  See "Security Error Codes" (SecBase.h).
 160     @deprecated in 10.5 and later. Use the SecKeychainItemImport function instead; see <Security/SecImportExport.h>
 161 */
 162 OSStatus SecKeyImportPair(
 163         SecKeychainRef keychainRef,
 164                 const CSSM_KEY *publicCssmKey,
 165                 const CSSM_KEY *privateCssmKey,
 166         SecAccessRef initialAccess,
 167         SecKeyRef* publicKey,
 168         SecKeyRef* privateKey)
 169                 DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER;
 170
 171 /*!
 172     @function SecKeyCreate
 173     @abstract Create a key reference from the supplied key data.
 174     @param allocator CFAllocator to allocate the key data. Pass NULL to use the default allocator.
 175     @param keyClass A descriptor for the particular class of key that is being created.
 176     @param keyData Data from which to create the key. Specify the format of this data in the encoding parameter.
 177     @param keyDataLength Length of the data pointed to by keyData.
 178     @param encoding A value of type SecKeyEncoding which describes the format of keyData.
 179     @result A key reference.
 180     @discussion Warning: this function is NOT intended for use outside the Security stack in its current state. <rdar://3201885>
 181         IMPORTANT: on Mac OS X 10.5 and earlier, the SecKeyCreate function had a different parameter list.
 182         The current parameter list matches the iPhone OS implementation. Existing clients of this function
 183         on Mac OS X (and there should not be any outside the Security stack, per the warning above) must
 184         migrate to the replacement function, SecKeyCreateWithCSSMKey.
 185 */
 186 SecKeyRef SecKeyCreate(CFAllocatorRef allocator,
 187     const SecKeyDescriptor *keyClass, const uint8_t *keyData,
 188         CFIndex keyDataLength, SecKeyEncoding encoding);
 189
 190 /*!
 191     @function SecKeyCreateWithCSSMKey
 192     @abstract Generate a temporary floating key reference for a CSSM_KEY.
 193     @param key A pointer to a CSSM_KEY structure.
 194     @param keyRef On return, a key reference.
 195     @result A result code. See "Security Error Codes" (SecBase.h).
 196     @discussion Warning: this function is NOT intended for use outside the Security stack in its current state. <rdar://3201885>
 197 */
 198 OSStatus SecKeyCreateWithCSSMKey(const CSSM_KEY *key, SecKeyRef* keyRef);
 199
 200
 201 /*!
 202         @function SecKeyRawSign
 203         @abstract Given a private key and data to sign, generate a digital signature.
 204         @param key Private key with which to sign.
 205         @param padding See Padding Types above, typically kSecPaddingPKCS1SHA1.
 206         @param dataToSign The data to be signed, typically the digest of the actual data.
 207         @param dataToSignLen Length of dataToSign in bytes.
 208         @param sig Pointer to buffer in which the signature will be returned.
 209         @param sigLen IN/OUT maximum length of sig buffer on input, actualy length of sig on output.
 210         @result A result code. See "Security Error Codes" (SecBase.h).
 211         @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding
 212          will be performed prior to signing. If this argument is kSecPaddingNone,
 213          the incoming data will be signed "as is".
 214
 215          When PKCS1 padding is performed, the maximum length of data that can
 216          be signed is the value returned by SecKeyGetBlockSize() - 11.
 217
 218          NOTE: The behavior this function with kSecPaddingNone is undefined if the
 219          first byte of dataToSign is zero; there is no way to verify leading zeroes
 220          as they are discarded during the calculation.
 221
 222          If you want to generate a proper PKCS1 style signature with DER encoding of
 223          the digest type - and the dataToSign is a SHA1 digest - use kSecPaddingPKCS1SHA1.
 224 */
 225 OSStatus SecKeyRawSign(
 226                 SecKeyRef           key,
 227                 SecPadding          padding,
 228                 const uint8_t       *dataToSign,
 229                 size_t              dataToSignLen,
 230                 uint8_t             *sig,
 231                 size_t              *sigLen);
 232
 233
 234 /*!
 235         @function SecKeyRawVerify
 236         @abstract Given a public key, data which has been signed, and a signature, verify the signature.
 237         @param key Public key with which to verify the signature.
 238         @param padding See Padding Types above, typically kSecPaddingPKCS1SHA1.
 239         @param signedData The data over which sig is being verified, typically the digest of the actual data.
 240         @param signedDataLen Length of signedData in bytes.
 241         @param sig Pointer to the signature to verify.
 242         @param sigLen Length of sig in  bytes.
 243         @result A result code. See "Security Error Codes" (SecBase.h).
 244         @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding
 245          will be checked during verification. If this argument is kSecPaddingNone,
 246          the incoming data will be compared directly to sig.
 247
 248          If you are verifying a proper PKCS1-style signature, with DER encoding of the digest
 249          type - and the signedData is a SHA1 digest - use kSecPaddingPKCS1SHA1.
 250 */
 251 OSStatus SecKeyRawVerify(
 252                  SecKeyRef           key,
 253                  SecPadding          padding,
 254                  const uint8_t       *signedData,
 255                  size_t              signedDataLen,
 256                  const uint8_t       *sig,
 257                  size_t              sigLen);
 258
 259
 260 /*!
 261         @function SecKeyEncrypt
 262         @abstract Encrypt a block of plaintext.
 263         @param key Public key with which to encrypt the data.
 264         @param padding See Padding Types above, typically kSecPaddingPKCS1.
 265         @param plainText The data to encrypt.
 266         @param plainTextLen Length of plainText in bytes, this must be less
 267          or equal to the value returned by SecKeyGetBlockSize().
 268         @param cipherText Pointer to the output buffer.
 269         @param cipherTextLen On input, specifies how much space is available at
 270          cipherText; on return, it is the actual number of cipherText bytes written.
 271         @result A result code. See "Security Error Codes" (SecBase.h).
 272         @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding
 273          will be performed prior to encryption. If this argument is kSecPaddingNone,
 274          the incoming data will be encrypted "as is".
 275
 276          When PKCS1 padding is performed, the maximum length of data that can
 277          be encrypted is the value returned by SecKeyGetBlockSize() - 11.
 278
 279          When memory usage is a critical issue, note that the input buffer
 280          (plainText) can be the same as the output buffer (cipherText).
 281 */
 282 OSStatus SecKeyEncrypt(
 283            SecKeyRef           key,
 284            SecPadding          padding,
 285            const uint8_t       *plainText,
 286            size_t              plainTextLen,
 287            uint8_t             *cipherText,
 288            size_t              *cipherTextLen);
 289
 290
 291 /*!
 292         @function SecKeyDecrypt
 293         @abstract Decrypt a block of ciphertext.
 294         @param key Private key with which to decrypt the data.
 295         @param padding See SecPadding types above; typically kSecPaddingPKCS1.
 296         @param cipherText The data to decrypt.
 297         @param cipherTextLen Length of cipherText in bytes; this must be less
 298          or equal to the value returned by SecKeyGetBlockSize().
 299         @param plainText Pointer to the output buffer.
 300         @param plainTextLen On input, specifies how much space is available at
 301          plainText; on return, it is the actual number of plainText bytes written.
 302         @result A result code. See "Security Error Codes" (SecBase.h).
 303         @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding
 304          will be removed after decryption. If this argument is kSecPaddingNone,
 305          the decrypted data will be returned "as is".
 306
 307          When memory usage is a critical issue, note that the input buffer
 308          (plainText) can be the same as the output buffer (cipherText).
 309 */
 310 OSStatus SecKeyDecrypt(
 311            SecKeyRef           key,             /* Private key */
 312            SecPadding          padding,                 /* kSecPaddingNone, kSecPaddingPKCS1, kSecPaddingOAEP */
 313            const uint8_t       *cipherText,
 314            size_t              cipherTextLen,   /* length of cipherText */
 315            uint8_t             *plainText,
 316            size_t              *plainTextLen);  /* IN/OUT */
 317
 318 OSStatus SecKeyVerifyDigest(
 319            SecKeyRef           key,            /* Private key */
 320            const SecAsn1AlgId  *algId,         /* algorithm oid/params */
 321            const uint8_t       *digestData,        /* signature over this digest */
 322            size_t              digestDataLen,  /* length of dataToDigest */
 323            const uint8_t       *sig,           /* signature to verify */
 324            size_t              sigLen);        /* length of sig */
 325
 326 OSStatus SecKeySignDigest(
 327            SecKeyRef           key,            /* Private key */
 328            const SecAsn1AlgId  *algId,         /* algorithm oid/params */
 329            const uint8_t       *digestData,    /* signature over this digest */
 330            size_t              digestDataLen,  /* length of digestData */
 331            uint8_t             *sig,           /* signature, RETURNED */
 332            size_t              *sigLen);       /* IN/OUT */
 333
 334
 335 /* These are the named curves we support. These values come from RFC 4492
 336  section 5.1.1, with the exception of SSL_Curve_None which means
 337  "ECDSA not negotiated". */
 338 typedef enum
 339 {
 340         kSecECCurveNone = -1,
 341         kSecECCurveSecp256r1 = 23,
 342         kSecECCurveSecp384r1 = 24,
 343         kSecECCurveSecp521r1 = 25
 344 } SecECNamedCurve;
 345
 346 /* Return a named curve enum for ecPrivateKey. */
 347 SecECNamedCurve SecECKeyGetNamedCurve(SecKeyRef ecPrivateKey);
 348 CFDataRef SecECKeyCopyPublicBits(SecKeyRef key);
 349
 350 /* Given an RSA public key in encoded form return a SecKeyRef representing
 351    that key. Supported encodings are kSecKeyEncodingPkcs1. */
 352 SecKeyRef SecKeyCreateRSAPublicKey(CFAllocatorRef allocator,
 353                                    const uint8_t *keyData, CFIndex keyDataLength,
 354                                    SecKeyEncoding encoding);
 355
 356 CFDataRef SecKeyCopyModulus(SecKeyRef rsaPublicKey);
 357 CFDataRef SecKeyCopyExponent(SecKeyRef rsaPublicKey);
 358
 359 /*!
 360  @function SecKeyCopyPublicBytes
 361  @abstract Gets the bits of a public key
 362  @param key Key to retrieve the bits.
 363  @param publicBytes An out parameter to receive the public key bits
 364  @result Errors if any when retrieving the public key bits..
 365  */
 366 OSStatus SecKeyCopyPublicBytes(SecKeyRef key, CFDataRef* publicBytes);
 367
 368 /*!
 369         @function SecKeyCreatePublicFromPrivate
 370         @abstract Create a public SecKeyRef from a private SecKeyRef
 371         @param privateKey The private SecKeyRef for which you want the public key
 372         @result A public SecKeyRef, or NULL if the conversion failed
 373         @discussion This is a "best attempt" function, hence the SPI nature. If the public
 374     key bits are not in memory, it attempts to load from the keychain. If the public
 375     key was not tracked on the keychain, it will fail.
 376 */
 377 SecKeyRef SecKeyCreatePublicFromPrivate(SecKeyRef privateKey);
 378
 379 /*!
 380         @function SecKeyCreateFromPublicData
 381 */
 382 SecKeyRef SecKeyCreateFromPublicData(CFAllocatorRef allocator, CFIndex algorithmID, CFDataRef publicBytes);
 383
 384 OSStatus SecKeyRawVerifyOSX(
 385                  SecKeyRef           key,
 386                  SecPadding          padding,
 387                  const uint8_t       *signedData,
 388                  size_t              signedDataLen,
 389                  const uint8_t       *sig,
 390                  size_t              sigLen);
 391
 392 #if defined(__cplusplus)
 393 }
 394 #endif
 395
 396 #endif /* !_SECURITY_SECKEYPRIV_H_ */
 397