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