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 #include <CoreFoundation/CFRuntime.h>
  43
  44 #if defined(__cplusplus)
  45 extern "C" {
  46 #endif
  47
  48 typedef struct SecRSAPublicKeyParams {
  49     uint8_t             *modulus;                       /* modulus */
  50     CFIndex             modulusLength;
  51     uint8_t             *exponent;                      /* public exponent */
  52     CFIndex             exponentLength;
  53 } SecRSAPublicKeyParams;
  54
  55 typedef uint32_t SecKeyEncoding;
  56 enum {
  57     /* Typically only used for symmetric keys. */
  58     kSecKeyEncodingRaw = 0,
  59
  60     /* RSA keys are DER-encoded according to PKCS1. */
  61     kSecKeyEncodingPkcs1 = 1,
  62
  63     /* RSA keys are DER-encoded according to PKCS1 with Apple Extensions. */
  64     kSecKeyEncodingApplePkcs1 = 2,
  65
  66     /* RSA public key in SecRSAPublicKeyParams format.  keyData is a pointer
  67        to a SecRSAPublicKeyParams and keyDataLength is
  68        sizeof(SecRSAPublicKeyParams). */
  69     kSecKeyEncodingRSAPublicParams = 3,
  70
  71     /* RSA public key in SecRSAPublicKeyParams format.  keyData is a pointer
  72        to a SecRSAPublicKeyParams and keyDataLength is
  73        sizeof(SecRSAPublicKeyParams). */
  74     kSecDERKeyEncoding = 4,
  75
  76     /* Internal "encodings to send other data" */
  77     kSecGenerateKey = 5,
  78     kSecExtractPublicFromPrivate = 6,
  79
  80     /* Encoding came from SecKeyCopyPublicBytes for a public key,
  81        or internally from a private key */
  82     kSecKeyEncodingBytes = 7,
  83
  84     /* Handing in a private key from corecrypto directly. */
  85     kSecKeyCoreCrypto = 8,
  86 };
  87
  88 typedef uint32_t SecKeyWrapType;
  89 enum {
  90     /* wrap key in RFC3394 (AESWrap) */
  91     kSecKeyWrapRFC3394 = 0,
  92
  93     /* wrap key in PGP style (support EC keys only right now) */
  94     kSecKeyWrapPublicKeyPGP = 1,
  95
  96 };
  97
  98 typedef CF_ENUM(CFIndex, SecKeyOperationMode) {
  99     kSecKeyOperationModePerform = 0,
 100     kSecKeyOperationModeCheckIfSupported = 1,
 101 };
 102
 103 typedef OSStatus (*SecKeyInitMethod)(SecKeyRef, const uint8_t *, CFIndex,
 104     SecKeyEncoding);
 105 typedef void  (*SecKeyDestroyMethod)(SecKeyRef);
 106 typedef OSStatus (*SecKeyRawSignMethod)(SecKeyRef key, SecPadding padding,
 107         const uint8_t *dataToSign, size_t dataToSignLen,
 108         uint8_t *sig, size_t *sigLen);
 109 typedef OSStatus (*SecKeyRawVerifyMethod)(
 110     SecKeyRef key, SecPadding padding, const uint8_t *signedData,
 111     size_t signedDataLen, const uint8_t *sig, size_t sigLen);
 112 typedef OSStatus (*SecKeyEncryptMethod)(SecKeyRef key, SecPadding padding,
 113     const uint8_t *plainText, size_t plainTextLen,
 114         uint8_t *cipherText, size_t *cipherTextLen);
 115 typedef OSStatus (*SecKeyDecryptMethod)(SecKeyRef key, SecPadding padding,
 116     const uint8_t *cipherText, size_t cipherTextLen,
 117     uint8_t *plainText, size_t *plainTextLen);
 118 typedef OSStatus (*SecKeyComputeMethod)(SecKeyRef key,
 119     const uint8_t *pub_key, size_t pub_key_len,
 120     uint8_t *computed_key, size_t *computed_key_len);
 121 typedef size_t (*SecKeyBlockSizeMethod)(SecKeyRef key);
 122 typedef CFDictionaryRef (*SecKeyCopyDictionaryMethod)(SecKeyRef key);
 123 typedef CFIndex (*SecKeyGetAlgorithmIDMethod)(SecKeyRef key);
 124 typedef OSStatus (*SecKeyCopyPublicBytesMethod)(SecKeyRef key, CFDataRef *serialization);
 125 typedef CFDataRef (*SecKeyCopyWrapKeyMethod)(SecKeyRef key, SecKeyWrapType type, CFDataRef unwrappedKey, CFDictionaryRef parameters, CFDictionaryRef *outParam, CFErrorRef *error);
 126 typedef CFDataRef (*SecKeyCopyUnwrapKeyMethod)(SecKeyRef key, SecKeyWrapType type, CFDataRef wrappedKey, CFDictionaryRef parameters, CFDictionaryRef *outParam, CFErrorRef *error);
 127 typedef CFStringRef (*SecKeyDescribeMethod)(SecKeyRef key);
 128
 129 typedef CFDataRef (*SecKeyCopyExternalRepresentationMethod)(SecKeyRef key, CFErrorRef *error);
 130 typedef SecKeyRef (*SecKeyCopyPublicKeyMethod)(SecKeyRef key);
 131 typedef Boolean (*SecKeyIsEqualMethod)(SecKeyRef key1, SecKeyRef key2);
 132 /*!
 133  @abstract Performs cryptographic operation with the key.
 134  @param key Key to perform the operation on.
 135  @param operation Type of operation to be performed.
 136  @param algorithm Algorithm identifier for the operation.  Determines format of input and output data.
 137  @param allAlgorithms Array of algorithms which were traversed until we got to this operation.  The last member of this array is always the same as @c algorithm parameter.
 138  @param mode Mode in which the operation is performed.  Two available modes are checking only if the operation can be performed or actually performing the operation.
 139  @param in1 First input parameter for the operation, meaningful only in ModePerform.
 140  @param in2 Second input parameter for the operation, meaningful only in ModePerform.
 141  @param error Error details when NULL is returned.
 142  @return NULL if some failure occured. kCFNull if operation/algorithm/key combination is not supported, otherwise the result of the operation or kCFBooleanTrue in ModeCheckIfSupported.
 143  */
 144 typedef CFTypeRef(*SecKeyCopyOperationResultMethod)(SecKeyRef key, SecKeyOperationType operation, SecKeyAlgorithm algorithm, CFArrayRef allAlgorithms, SecKeyOperationMode mode, CFTypeRef in1, CFTypeRef in2, CFErrorRef *error);
 145
 146 #define kSecKeyDescriptorVersion  (4)
 147
 148 typedef struct __SecKeyDescriptor {
 149     /* Version of this SecKeyDescriptor.  Must be kSecKeyDescriptorVersion. */
 150     uint32_t version;
 151
 152     /* Name of this key class for use by SecKeyShow(). */
 153     const char *name;
 154
 155     /* If nonzero, SecKeyCreate will allocate this many bytes for the key
 156        field in the SecKeyRef it creates.  If zero key is NULL and the
 157        implementor can choose to dynamically allocate it in the init
 158        function and free it in the destroy function.  */
 159     uint32_t extraBytes;
 160
 161     /* Called by SecKeyCreate(). */
 162     SecKeyInitMethod init;
 163     /* Called by destructor (final CFRelease() or gc if using). */
 164     SecKeyDestroyMethod destroy;
 165     /* Called by SecKeyRawSign(). */
 166     SecKeyRawSignMethod rawSign;
 167     /* Called by SecKeyRawVerify(). */
 168     SecKeyRawVerifyMethod rawVerify;
 169     /* Called by SecKeyEncrypt(). */
 170     SecKeyEncryptMethod encrypt;
 171     /* Called by SecKeyDecrypt(). */
 172     SecKeyDecryptMethod decrypt;
 173     /* Reserved for future use. */
 174     SecKeyComputeMethod compute;
 175     /* Called by SecKeyGetBlockSize(). */
 176     SecKeyBlockSizeMethod blockSize;
 177     /* Called by SecKeyCopyAttributeDictionary(), which is private. */
 178     SecKeyCopyDictionaryMethod copyDictionary;
 179     /* Called by SecKeyDescribeMethod(). */
 180     SecKeyDescribeMethod describe;
 181 #if kSecKeyDescriptorVersion > 0
 182     /* Called by SecKeyCopyAttributeDictionary(), which is private. */
 183     SecKeyGetAlgorithmIDMethod getAlgorithmID;
 184 #endif
 185 #if kSecKeyDescriptorVersion > 1
 186     SecKeyCopyPublicBytesMethod copyPublic;
 187 #endif
 188 #if kSecKeyDescriptorVersion > 2
 189     SecKeyCopyWrapKeyMethod copyWrapKey;
 190     SecKeyCopyUnwrapKeyMethod copyUnwrapKey;
 191 #endif
 192 #if kSecKeyDescriptorVersion > 3
 193     SecKeyCopyExternalRepresentationMethod copyExternalRepresentation;
 194     SecKeyCopyPublicKeyMethod copyPublicKey;
 195     SecKeyCopyOperationResultMethod copyOperationResult;
 196     SecKeyIsEqualMethod isEqual;
 197 #endif
 198 } SecKeyDescriptor;
 199
 200 /*!
 201         @function SecKeyGetAlgorithmID
 202         @abstract Returns a pointer to a CSSM_X509_ALGORITHM_IDENTIFIER structure for the given key.
 203     @param key A key reference.
 204     @param algid On return, a pointer to a CSSM_X509_ALGORITHM_IDENTIFIER structure.
 205         @result A result code.  See "Security Error Codes" (SecBase.h).
 206         @discussion Deprecated in OS X 10.8 and later. Continued use is strongly discouraged,
 207     since there is a naming conflict with a similar function (also deprecated) on iOS that
 208     had different arguments and a different return value. Use SecKeyGetAlgorithmId instead.
 209 */
 210 OSStatus SecKeyGetAlgorithmID(SecKeyRef key, const CSSM_X509_ALGORITHM_IDENTIFIER **algid)
 211         DEPRECATED_IN_MAC_OS_X_VERSION_10_8_AND_LATER;
 212
 213 enum {
 214     kSecNullAlgorithmID = 0,
 215     kSecRSAAlgorithmID = 1,
 216     kSecDSAAlgorithmID = 2,   /* unsupported, just here for reference. */
 217     kSecECDSAAlgorithmID = 3,
 218 };
 219
 220 /*!
 221         @function SecKeyGetAlgorithmId
 222         @abstract Returns an enumerated constant value which identifies the algorithm for the given key.
 223         @param key A key reference.
 224         @result An algorithm identifier.
 225 */
 226 CFIndex SecKeyGetAlgorithmId(SecKeyRef key)
 227         __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_9_0);
 228
 229 /*!
 230         @function SecKeyGetStrengthInBits
 231         @abstract Returns key strength in bits for the given key.
 232     @param key A key reference.
 233     @param algid A pointer to a CSSM_X509_ALGORITHM_IDENTIFIER structure, as returned from a call to SecKeyGetAlgorithmID.
 234     @param strength On return, the key strength in bits.
 235         @result A result code.  See "Security Error Codes" (SecBase.h).
 236 */
 237 OSStatus SecKeyGetStrengthInBits(SecKeyRef key, const CSSM_X509_ALGORITHM_IDENTIFIER *algid, unsigned int *strength);
 238
 239 /*!
 240         @function SecKeyImportPair
 241         @abstract Takes an asymmetric key pair and stores it in the keychain specified by the keychain parameter.
 242         @param keychainRef A reference to the keychain in which to store the private and public key items. Specify NULL for the default keychain.
 243     @param publicCssmKey A CSSM_KEY which is valid for the CSP returned by SecKeychainGetCSPHandle(). This may be a normal key or reference key.
 244     @param privateCssmKey A CSSM_KEY which is valid for the CSP returned by SecKeychainGetCSPHandle(). This may be a normal key or reference key.
 245     @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.
 246     @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.
 247     @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.
 248         @result A result code.  See "Security Error Codes" (SecBase.h).
 249     @deprecated in 10.5 and later. Use the SecKeychainItemImport function instead; see <Security/SecImportExport.h>
 250 */
 251 OSStatus SecKeyImportPair(
 252         SecKeychainRef keychainRef,
 253                 const CSSM_KEY *publicCssmKey,
 254                 const CSSM_KEY *privateCssmKey,
 255         SecAccessRef initialAccess,
 256         SecKeyRef* publicKey,
 257         SecKeyRef* privateKey)
 258                 DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER;
 259
 260 /*!
 261     @function SecKeyCreate
 262     @abstract Create a key reference from the supplied key data.
 263     @param allocator CFAllocator to allocate the key data. Pass NULL to use the default allocator.
 264     @param keyClass A descriptor for the particular class of key that is being created.
 265     @param keyData Data from which to create the key. Specify the format of this data in the encoding parameter.
 266     @param keyDataLength Length of the data pointed to by keyData.
 267     @param encoding A value of type SecKeyEncoding which describes the format of keyData.
 268     @result A key reference.
 269     @discussion Warning: this function is NOT intended for use outside the Security stack in its current state. <rdar://3201885>
 270         IMPORTANT: on Mac OS X 10.5 and earlier, the SecKeyCreate function had a different parameter list.
 271         The current parameter list matches the iPhone OS implementation. Existing clients of this function
 272         on Mac OS X (and there should not be any outside the Security stack, per the warning above) must
 273         migrate to the replacement function, SecKeyCreateWithCSSMKey.
 274 */
 275 SecKeyRef SecKeyCreate(CFAllocatorRef allocator,
 276     const SecKeyDescriptor *keyClass, const uint8_t *keyData,
 277         CFIndex keyDataLength, SecKeyEncoding encoding);
 278
 279 /*!
 280     @function SecKeyCreateWithCSSMKey
 281     @abstract Generate a temporary floating key reference for a CSSM_KEY.
 282     @param key A pointer to a CSSM_KEY structure.
 283     @param keyRef On return, a key reference.
 284     @result A result code. See "Security Error Codes" (SecBase.h).
 285     @discussion Warning: this function is NOT intended for use outside the Security stack in its current state. <rdar://3201885>
 286 */
 287 OSStatus SecKeyCreateWithCSSMKey(const CSSM_KEY *key, SecKeyRef* keyRef);
 288
 289
 290 /*!
 291         @function SecKeyRawSign
 292         @abstract Given a private key and data to sign, generate a digital signature.
 293         @param key Private key with which to sign.
 294         @param padding See Padding Types above, typically kSecPaddingPKCS1SHA1.
 295         @param dataToSign The data to be signed, typically the digest of the actual data.
 296         @param dataToSignLen Length of dataToSign in bytes.
 297         @param sig Pointer to buffer in which the signature will be returned.
 298         @param sigLen IN/OUT maximum length of sig buffer on input, actualy length of sig on output.
 299         @result A result code. See "Security Error Codes" (SecBase.h).
 300         @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding
 301          will be performed prior to signing. If this argument is kSecPaddingNone,
 302          the incoming data will be signed "as is".
 303
 304          When PKCS1 padding is performed, the maximum length of data that can
 305          be signed is the value returned by SecKeyGetBlockSize() - 11.
 306
 307          NOTE: The behavior this function with kSecPaddingNone is undefined if the
 308          first byte of dataToSign is zero; there is no way to verify leading zeroes
 309          as they are discarded during the calculation.
 310
 311          If you want to generate a proper PKCS1 style signature with DER encoding of
 312          the digest type - and the dataToSign is a SHA1 digest - use kSecPaddingPKCS1SHA1.
 313 */
 314 OSStatus SecKeyRawSign(
 315                 SecKeyRef           key,
 316                 SecPadding          padding,
 317                 const uint8_t       *dataToSign,
 318                 size_t              dataToSignLen,
 319                 uint8_t             *sig,
 320                 size_t              *sigLen);
 321
 322
 323 /*!
 324         @function SecKeyRawVerify
 325         @abstract Given a public key, data which has been signed, and a signature, verify the signature.
 326         @param key Public key with which to verify the signature.
 327         @param padding See Padding Types above, typically kSecPaddingPKCS1SHA1.
 328         @param signedData The data over which sig is being verified, typically the digest of the actual data.
 329         @param signedDataLen Length of signedData in bytes.
 330         @param sig Pointer to the signature to verify.
 331         @param sigLen Length of sig in  bytes.
 332         @result A result code. See "Security Error Codes" (SecBase.h).
 333         @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding
 334          will be checked during verification. If this argument is kSecPaddingNone,
 335          the incoming data will be compared directly to sig.
 336
 337          If you are verifying a proper PKCS1-style signature, with DER encoding of the digest
 338          type - and the signedData is a SHA1 digest - use kSecPaddingPKCS1SHA1.
 339 */
 340 OSStatus SecKeyRawVerify(
 341                  SecKeyRef           key,
 342                  SecPadding          padding,
 343                  const uint8_t       *signedData,
 344                  size_t              signedDataLen,
 345                  const uint8_t       *sig,
 346                  size_t              sigLen);
 347
 348
 349 /*!
 350         @function SecKeyEncrypt
 351         @abstract Encrypt a block of plaintext.
 352         @param key Public key with which to encrypt the data.
 353         @param padding See Padding Types above, typically kSecPaddingPKCS1.
 354         @param plainText The data to encrypt.
 355         @param plainTextLen Length of plainText in bytes, this must be less
 356          or equal to the value returned by SecKeyGetBlockSize().
 357         @param cipherText Pointer to the output buffer.
 358         @param cipherTextLen On input, specifies how much space is available at
 359          cipherText; on return, it is the actual number of cipherText bytes written.
 360         @result A result code. See "Security Error Codes" (SecBase.h).
 361         @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding
 362          will be performed prior to encryption. If this argument is kSecPaddingNone,
 363          the incoming data will be encrypted "as is".
 364
 365          When PKCS1 padding is performed, the maximum length of data that can
 366          be encrypted is the value returned by SecKeyGetBlockSize() - 11.
 367
 368          When memory usage is a critical issue, note that the input buffer
 369          (plainText) can be the same as the output buffer (cipherText).
 370 */
 371 OSStatus SecKeyEncrypt(
 372            SecKeyRef           key,
 373            SecPadding          padding,
 374            const uint8_t       *plainText,
 375            size_t              plainTextLen,
 376            uint8_t             *cipherText,
 377            size_t              *cipherTextLen);
 378
 379
 380 /*!
 381         @function SecKeyDecrypt
 382         @abstract Decrypt a block of ciphertext.
 383         @param key Private key with which to decrypt the data.
 384         @param padding See SecPadding types above; typically kSecPaddingPKCS1.
 385         @param cipherText The data to decrypt.
 386         @param cipherTextLen Length of cipherText in bytes; this must be less
 387          or equal to the value returned by SecKeyGetBlockSize().
 388         @param plainText Pointer to the output buffer.
 389         @param plainTextLen On input, specifies how much space is available at
 390          plainText; on return, it is the actual number of plainText bytes written.
 391         @result A result code. See "Security Error Codes" (SecBase.h).
 392         @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding
 393          will be removed after decryption. If this argument is kSecPaddingNone,
 394          the decrypted data will be returned "as is".
 395
 396          When memory usage is a critical issue, note that the input buffer
 397          (plainText) can be the same as the output buffer (cipherText).
 398 */
 399 OSStatus SecKeyDecrypt(
 400            SecKeyRef           key,             /* Private key */
 401            SecPadding          padding,                 /* kSecPaddingNone, kSecPaddingPKCS1, kSecPaddingOAEP */
 402            const uint8_t       *cipherText,
 403            size_t              cipherTextLen,   /* length of cipherText */
 404            uint8_t             *plainText,
 405            size_t              *plainTextLen);  /* IN/OUT */
 406
 407 OSStatus SecKeyVerifyDigest(
 408            SecKeyRef           key,            /* Private key */
 409            const SecAsn1AlgId  *algId,         /* algorithm oid/params */
 410            const uint8_t       *digestData,        /* signature over this digest */
 411            size_t              digestDataLen,  /* length of dataToDigest */
 412            const uint8_t       *sig,           /* signature to verify */
 413            size_t              sigLen);        /* length of sig */
 414
 415 OSStatus SecKeySignDigest(
 416            SecKeyRef           key,            /* Private key */
 417            const SecAsn1AlgId  *algId,         /* algorithm oid/params */
 418            const uint8_t       *digestData,    /* signature over this digest */
 419            size_t              digestDataLen,  /* length of digestData */
 420            uint8_t             *sig,           /* signature, RETURNED */
 421            size_t              *sigLen);       /* IN/OUT */
 422
 423
 424 /* These are the named curves we support. These values come from RFC 4492
 425  section 5.1.1, with the exception of SSL_Curve_None which means
 426  "ECDSA not negotiated". */
 427 typedef enum
 428 {
 429         kSecECCurveNone = -1,
 430         kSecECCurveSecp256r1 = 23,
 431         kSecECCurveSecp384r1 = 24,
 432         kSecECCurveSecp521r1 = 25
 433 } SecECNamedCurve;
 434
 435 /* Return a named curve enum for ecPrivateKey. */
 436 SecECNamedCurve SecECKeyGetNamedCurve(SecKeyRef ecPrivateKey);
 437 CFDataRef SecECKeyCopyPublicBits(SecKeyRef key);
 438
 439 /* Given an RSA public key in encoded form return a SecKeyRef representing
 440    that key. Supported encodings are kSecKeyEncodingPkcs1. */
 441 SecKeyRef SecKeyCreateRSAPublicKey(CFAllocatorRef allocator,
 442                                    const uint8_t *keyData, CFIndex keyDataLength,
 443                                    SecKeyEncoding encoding);
 444
 445 CFDataRef SecKeyCopyModulus(SecKeyRef rsaPublicKey);
 446 CFDataRef SecKeyCopyExponent(SecKeyRef rsaPublicKey);
 447
 448 /*!
 449  @function SecKeyCopyPublicBytes
 450  @abstract Gets the bits of a public key
 451  @param key Key to retrieve the bits.
 452  @param publicBytes An out parameter to receive the public key bits
 453  @result Errors if any when retrieving the public key bits..
 454  */
 455 OSStatus SecKeyCopyPublicBytes(SecKeyRef key, CFDataRef* publicBytes);
 456
 457 /*!
 458         @function SecKeyCreatePublicFromPrivate
 459         @abstract Create a public SecKeyRef from a private SecKeyRef
 460         @param privateKey The private SecKeyRef for which you want the public key
 461         @result A public SecKeyRef, or NULL if the conversion failed
 462         @discussion This is a "best attempt" function, hence the SPI nature. If the public
 463     key bits are not in memory, it attempts to load from the keychain. If the public
 464     key was not tracked on the keychain, it will fail.
 465 */
 466 SecKeyRef SecKeyCreatePublicFromPrivate(SecKeyRef privateKey);
 467
 468 /*!
 469         @function SecKeyCreateFromPublicData
 470 */
 471 SecKeyRef SecKeyCreateFromPublicData(CFAllocatorRef allocator, CFIndex algorithmID, CFDataRef publicBytes);
 472
 473 OSStatus SecKeyRawVerifyOSX(
 474                  SecKeyRef           key,
 475                  SecPadding          padding,
 476                  const uint8_t       *signedData,
 477                  size_t              signedDataLen,
 478                  const uint8_t       *sig,
 479                  size_t              sigLen);
 480
 481 /*!
 482  @enum SecKeyAttestationKeyType
 483  @abstract Defines types of builtin attestation keys.
 484 */
 485 typedef CF_ENUM(uint32_t, SecKeyAttestationKeyType)
 486 {
 487         kSecKeyAttestationKeyTypeSIK = 0,
 488         kSecKeyAttestationKeyTypeGID
 489 } __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 490
 491 /*!
 492  @function SecKeyCopyAttestationKey
 493  @abstract Returns a copy of a builtin attestation key.
 494
 495  @param keyType Type of the requested builtin key.
 496  @param error An optional pointer to a CFErrorRef. This value is set if an error occurred.
 497
 498  @result On success a SecKeyRef containing the requested key is returned, on failure it returns NULL.
 499 */
 500 SecKeyRef SecKeyCopyAttestationKey(SecKeyAttestationKeyType keyType, CFErrorRef *error)
 501 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 502
 503 /*!
 504  @function SecKeyCreateAttestation
 505  @abstract Attests a key with another key.
 506
 507  @param key The attesting key.
 508  @param keyToAttest The key which is to be attested.
 509  @param error An optional pointer to a CFErrorRef. This value is set if an error occurred.
 510
 511  @result On success a CFDataRef containing the attestation data is returned, on failure it returns NULL.
 512
 513  @discussion Key attestation only works for CTK SEP keys, i.e. keys created with kSecAttrTokenID=kSecAttrTokenIDSecureEnclave.
 514 */
 515 CFDataRef SecKeyCreateAttestation(SecKeyRef key, SecKeyRef keyToAttest, CFErrorRef *error)
 516 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 517
 518 /*!
 519  @function SecKeySetParameter
 520  @abstract Sets unspecified key parameter for the backend.
 521
 522  @param key Key to set the parameter to.
 523  @param name Identifies parameter to be set.
 524  @param value New value for the parameter.
 525  @param error Error which gathers more information when something went wrong.
 526
 527  @discussion Serves as channel between SecKey client and backend for passing additional sideband data send from SecKey caller
 528  to SecKey implementation backend (currently only CTK-based token backend is supported).  Parameter names and types are
 529  a contract between SecKey user (application) and backend and are not interpreted by SecKey layer in any way.
 530  */
 531 Boolean SecKeySetParameter(SecKeyRef key, CFStringRef name, CFPropertyListRef value, CFErrorRef *error)
 532 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 533
 534 /*!
 535  Algorithms for converting between bigendian and core-crypto ccunit data representation.
 536  */
 537 extern const SecKeyAlgorithm kSecKeyAlgorithmRSASignatureRawCCUnit;
 538 extern const SecKeyAlgorithm kSecKeyAlgorithmRSAEncryptionRawCCUnit;
 539
 540 /*!
 541  Internal algorithm for RSA-MD5.  We do not want to export MD5 in new API, but we need it
 542  for implementing legacy interfaces.
 543  */
 544 extern const SecKeyAlgorithm kSecKeyAlgorithmRSASignatureDigestPKCS1v15MD5;
 545 extern const SecKeyAlgorithm kSecKeyAlgorithmRSASignatureMessagePKCS1v15MD5;
 546
 547 /*!
 548  Algorithms for interoperability with libaks smartcard support.
 549  */
 550 extern const SecKeyAlgorithm kSecKeyAlgorithmECIESEncryptionAKSSmartCard;
 551
 552 #if defined(__cplusplus)
 553 }
 554 #endif
 555
 556 #endif /* !_SECURITY_SECKEYPRIV_H_ */
 557