keychain/SecItemPriv.h

   1 /*
   2  * Copyright (c) 2006-2014 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 SecItemPriv
  26     SecItemPriv defines private constants and SPI functions for access to
  27     Security items (certificates, identities, keys, and keychain items.)
  28 */
  29
  30 #ifndef _SECURITY_SECITEMPRIV_H_
  31 #define _SECURITY_SECITEMPRIV_H_
  32
  33 #include <CoreFoundation/CFDictionary.h>
  34 #include <CoreFoundation/CFData.h>
  35 #include <CoreFoundation/CFError.h>
  36 #include <TargetConditionals.h>
  37 #include <Security/SecBase.h>
  38 #include <xpc/xpc.h>
  39
  40 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
  41 #include <Security/SecTask.h>
  42 #endif
  43
  44 __BEGIN_DECLS
  45
  46 /*!
  47     @enum Class Value Constants (Private)
  48     @discussion Predefined item class constants used to get or set values in
  49         a dictionary. The kSecClass constant is the key and its value is one
  50         of the constants defined here.
  51     @constant kSecClassAppleSharePassword Specifies AppleShare password items.
  52 */
  53 extern const CFStringRef kSecClassAppleSharePassword;
  54
  55
  56 /*!
  57     @enum Attribute Key Constants (Private)
  58     @discussion Predefined item attribute keys used to get or set values in a
  59         dictionary. Not all attributes apply to each item class. The table
  60         below lists the currently defined attributes for each item class:
  61
  62     kSecClassGenericPassword item attributes:
  63         kSecAttrAccessGroup
  64         kSecAttrCreationDate
  65         kSecAttrModificationDate
  66         kSecAttrDescription
  67         kSecAttrComment
  68         kSecAttrCreator
  69         kSecAttrType
  70         kSecAttrScriptCode (private)
  71         kSecAttrLabel
  72         kSecAttrAlias (private)
  73         kSecAttrIsInvisible
  74         kSecAttrIsNegative
  75         kSecAttrHasCustomIcon (private)
  76         kSecAttrProtected (private)
  77         kSecAttrAccount
  78         kSecAttrService
  79         kSecAttrGeneric
  80         kSecAttrSynchronizable
  81         kSecAttrSyncViewHint
  82
  83     kSecClassInternetPassword item attributes:
  84         kSecAttrAccessGroup
  85         kSecAttrCreationDate
  86         kSecAttrModificationDate
  87         kSecAttrDescription
  88         kSecAttrComment
  89         kSecAttrCreator
  90         kSecAttrType
  91         kSecAttrScriptCode (private)
  92         kSecAttrLabel
  93         kSecAttrAlias (private)
  94         kSecAttrIsInvisible
  95         kSecAttrIsNegative
  96         kSecAttrHasCustomIcon (private)
  97         kSecAttrProtected (private)
  98         kSecAttrAccount
  99         kSecAttrSecurityDomain
 100         kSecAttrServer
 101         kSecAttrProtocol
 102         kSecAttrAuthenticationType
 103         kSecAttrPort
 104         kSecAttrPath
 105         kSecAttrSynchronizable
 106         kSecAttrSyncViewHint
 107
 108     kSecClassAppleSharePassword item attributes:
 109         kSecAttrAccessGroup
 110         kSecAttrCreationDate
 111         kSecAttrModificationDate
 112         kSecAttrDescription
 113         kSecAttrComment
 114         kSecAttrCreator
 115         kSecAttrType
 116         kSecAttrScriptCode (private)
 117         kSecAttrLabel
 118         kSecAttrAlias (private)
 119         kSecAttrIsInvisible
 120         kSecAttrIsNegative
 121         kSecAttrHasCustomIcon (private)
 122         kSecAttrProtected (private)
 123         kSecAttrAccount
 124         kSecAttrVolume
 125         kSecAttrAddress
 126         kSecAttrAFPServerSignature
 127         kSecAttrSynchronizable
 128         kSecAttrSyncViewHint
 129
 130     kSecClassCertificate item attributes:
 131         kSecAttrAccessGroup
 132         kSecAttrCertificateType
 133         kSecAttrCertificateEncoding
 134         kSecAttrLabel
 135         kSecAttrAlias (private)
 136         kSecAttrSubject
 137         kSecAttrIssuer
 138         kSecAttrSerialNumber
 139         kSecAttrSubjectKeyID
 140         kSecAttrPublicKeyHash
 141         kSecAttrSynchronizable
 142         kSecAttrSyncViewHint
 143
 144     kSecClassKey item attributes:
 145         kSecAttrAccessGroup
 146         kSecAttrKeyClass
 147         kSecAttrLabel
 148         kSecAttrAlias (private)
 149         kSecAttrApplicationLabel
 150         kSecAttrIsPermanent
 151         kSecAttrIsPrivate (private)
 152         kSecAttrIsModifiable (private)
 153         kSecAttrApplicationTag
 154         kSecAttrKeyCreator (private)
 155         kSecAttrKeyType
 156         kSecAttrKeySizeInBits
 157         kSecAttrEffectiveKeySize
 158         kSecAttrStartDate (private)
 159         kSecAttrEndDate (private)
 160         kSecAttrIsSensitive (private)
 161         kSecAttrWasAlwaysSensitive (private)
 162         kSecAttrIsExtractable (private)
 163         kSecAttrWasNeverExtractable (private)
 164         kSecAttrCanEncrypt
 165         kSecAttrCanDecrypt
 166         kSecAttrCanDerive
 167         kSecAttrCanSign
 168         kSecAttrCanVerify
 169         kSecAttrCanSignRecover (private)
 170         kSecAttrCanVerifyRecover (private)
 171         kSecAttrCanWrap
 172         kSecAttrCanUnwrap
 173         kSecAttrSynchronizable
 174         kSecAttrSyncViewHint
 175
 176     kSecClassIdentity item attributes:
 177         Since an identity is the combination of a private key and a
 178         certificate, this class shares attributes of both kSecClassKey and
 179         kSecClassCertificate.
 180
 181     @constant kSecAttrScriptCode Specifies a dictionary key whose value is the
 182         item's script code attribute. You use this tag to set or get a value
 183         of type CFNumberRef that represents a script code for this item's
 184         strings. (Note: use of this attribute is deprecated; string attributes
 185         should always be stored in UTF-8 encoding. This is currently private
 186         for use by syncing; new code should not ever access this attribute.)
 187     @constant kSecAttrAlias Specifies a dictionary key whose value is the
 188         item's alias. You use this key to get or set a value of type CFDataRef
 189         which represents an alias. For certificate items, the alias is either
 190         a single email address, an array of email addresses, or the common
 191         name of the certificate if it does not contain any email address.
 192         (Items of class kSecClassCertificate have this attribute.)
 193     @constant kSecAttrHasCustomIcon Specifies a dictionary key whose value is the
 194         item's custom icon attribute. You use this tag to set or get a value
 195         of type CFBooleanRef that indicates whether the item should have an
 196         application-specific icon. (Note: use of this attribute is deprecated;
 197         custom item icons are not supported in Mac OS X. This is currently
 198         private for use by syncing; new code should not use this attribute.)
 199     @constant kSecAttrVolume Specifies a dictionary key whose value is the
 200         item's volume attribute. You use this key to set or get a CFStringRef
 201         value that represents an AppleShare volume name. (Items of class
 202         kSecClassAppleSharePassword have this attribute.)
 203     @constant kSecAttrAddress Specifies a dictionary key whose value is the
 204         item's address attribute. You use this key to set or get a CFStringRef
 205         value that contains the AppleTalk zone name, or the IP or domain name
 206         that represents the server address. (Items of class
 207         kSecClassAppleSharePassword have this attribute.)
 208     @constant kSecAttrAFPServerSignature Specifies a dictionary key whose value
 209         is the item's AFP server signature attribute. You use this key to set
 210         or get a CFDataRef value containing 16 bytes that represents the
 211         server's signature block. (Items of class kSecClassAppleSharePassword
 212         have this attribute.)
 213     @constant kSecAttrCRLType (read-only) Specifies a dictionary key whose
 214         value is the item's certificate revocation list type. You use this
 215         key to get a value of type CFNumberRef that denotes the CRL type (see
 216         the CSSM_CRL_TYPE enum in cssmtype.h). (Items of class
 217         kSecClassCertificate have this attribute.)
 218     @constant kSecAttrCRLEncoding (read-only) Specifies a dictionary key whose
 219         value is the item's certificate revocation list encoding.  You use
 220         this key to get a value of type CFNumberRef that denotes the CRL
 221         encoding (see the CSSM_CRL_ENCODING enum in cssmtype.h). (Items of
 222         class kSecClassCertificate have this attribute.)
 223     @constant kSecAttrKeyCreator Specifies a dictionary key whose value is a
 224         CFDataRef containing a CSSM_GUID structure representing the module ID of
 225         the CSP that owns this key.
 226     @constant kSecAttrIsPrivate Specifies a dictionary key whose value is a
 227         CFBooleanRef indicating whether the raw key material of the key in
 228         question is private.
 229     @constant kSecAttrIsModifiable Specifies a dictionary key whose value is a
 230         CFBooleanRef indicating whether any of the attributes of this key are
 231         modifiable.
 232     @constant kSecAttrStartDate Specifies a dictionary key whose value is a
 233         CFDateRef indicating the earliest date on which this key may be used.
 234         If kSecAttrStartDate is not present, the restriction does not apply.
 235     @constant kSecAttrEndDate Specifies a dictionary key whose value is a
 236         CFDateRef indicating the last date on which this key may be used.
 237         If kSecAttrEndDate is not present, the restriction does not apply.
 238     @constant kSecAttrIsSensitive Specifies a dictionary key whose value
 239         is a CFBooleanRef indicating whether the key in question must be wrapped
 240         with an algorithm other than CSSM_ALGID_NONE.
 241     @constant kSecAttrWasAlwaysSensitive Specifies a dictionary key whose value
 242         is a CFBooleanRef indicating that the key in question has always been
 243         marked as sensitive.
 244     @constant kSecAttrIsExtractable Specifies a dictionary key whose value
 245         is a CFBooleanRef indicating whether the key in question may be wrapped.
 246     @constant kSecAttrWasNeverExtractable Specifies a dictionary key whose value
 247         is a CFBooleanRef indicating that the key in question has never been
 248         marked as extractable.
 249     @constant kSecAttrCanSignRecover Specifies a dictionary key whole value is a
 250         CFBooleanRef indicating whether the key in question can be used to
 251         perform sign recovery.
 252     @constant kSecAttrCanVerifyRecover Specifies a dictionary key whole value is
 253         a CFBooleanRef indicating whether the key in question can be used to
 254         perform verify recovery.
 255     @constant kSecAttrTombstone Specifies a dictionary key whose value is
 256         a CFBooleanRef indicating that the item in question is a tombstone.
 257     @constant kSecAttrNoLegacy Specifies a dictionary key whose
 258         value is a CFBooleanRef indicating that the query must be run on the
 259         syncable backend even for non syncable items.
 260 */
 261 extern const CFStringRef kSecAttrScriptCode;
 262 extern const CFStringRef kSecAttrAlias;
 263 extern const CFStringRef kSecAttrHasCustomIcon;
 264 extern const CFStringRef kSecAttrVolume;
 265 extern const CFStringRef kSecAttrAddress;
 266 extern const CFStringRef kSecAttrAFPServerSignature;
 267 extern const CFStringRef kSecAttrCRLType;
 268 extern const CFStringRef kSecAttrCRLEncoding;
 269 extern const CFStringRef kSecAttrKeyCreator;
 270 extern const CFStringRef kSecAttrIsPrivate;
 271 extern const CFStringRef kSecAttrIsModifiable;
 272 extern const CFStringRef kSecAttrStartDate;
 273 extern const CFStringRef kSecAttrEndDate;
 274 extern const CFStringRef kSecAttrIsSensitive;
 275 extern const CFStringRef kSecAttrWasAlwaysSensitive;
 276 extern const CFStringRef kSecAttrIsExtractable;
 277 extern const CFStringRef kSecAttrWasNeverExtractable;
 278 extern const CFStringRef kSecAttrCanSignRecover;
 279 extern const CFStringRef kSecAttrCanVerifyRecover;
 280 extern const CFStringRef kSecAttrTombstone;
 281 extern const CFStringRef kSecAttrNoLegacy
 282     __OSX_AVAILABLE(10.11) __IOS_AVAILABLE(9.3) __TVOS_AVAILABLE(9.3) __WATCHOS_AVAILABLE(2.3);
 283 extern const CFStringRef kSecAttrSyncViewHint
 284     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 285 extern const CFStringRef kSecAttrMultiUser
 286     __OSX_AVAILABLE(10.11.5) __IOS_AVAILABLE(9.3) __TVOS_AVAILABLE(9.3) __WATCHOS_AVAILABLE(2.3);
 287
 288 /* This will force the syncing system to derive an item's plaintext synchronization id from its primary key.
 289  * This might leak primary key information, but will cause syncing devices to discover sync conflicts sooner.
 290  * Protected by the kSecEntitlementPrivateCKKSPlaintextFields entitlement.
 291  *
 292  * Will only be respected during a SecItemAdd.
 293  */
 294 extern const CFStringRef kSecAttrDeriveSyncIDFromItemAttributes
 295 __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 296 extern const CFStringRef kSecAttrPCSPlaintextServiceIdentifier
 297     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 298 extern const CFStringRef kSecAttrPCSPlaintextPublicKey
 299     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 300 extern const CFStringRef kSecAttrPCSPlaintextPublicIdentity
 301     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 302
 303 // ObjectID of item stored on the token.  Token-type specific BLOB.
 304 // For kSecAttrTokenIDSecureEnclave and kSecAttrTokenIDAppleKeyStore, ObjectID is libaks's blob representation of encoded key.
 305 extern const CFStringRef kSecAttrTokenOID
 306      __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 307 extern const CFStringRef kSecAttrUUID
 308     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 309 extern const CFStringRef kSecAttrSysBound
 310     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 311 extern const CFStringRef kSecAttrSHA1
 312 __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 313
 314 #define kSecSecAttrSysBoundNot                    0
 315 #define kSecSecAttrSysBoundPreserveDuringRestore  1
 316
 317
 318 extern const CFStringRef kSecAttrKeyTypeECSECPrimeRandomPKA
 319      __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 320 extern const CFStringRef kSecAttrKeyTypeSecureEnclaveAttestation
 321      __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 322
 323 // Should not be used, use kSecAttrTokenOID instead.
 324 extern const CFStringRef kSecAttrSecureEnclaveKeyBlob
 325      __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 326
 327 /*!
 328     @enum kSecAttrAccessible Value Constants (Private)
 329     @constant kSecAttrAccessibleAlwaysPrivate Private alias for kSecAttrAccessibleAlways,
 330         which is going to be deprecated for 3rd party use.
 331     @constant kSecAttrAccessibleAlwaysThisDeviceOnlyPrivate for kSecAttrAccessibleAlwaysThisDeviceOnly,
 332         which is going to be deprecated for 3rd party use.
 333 */
 334 extern const CFStringRef kSecAttrAccessibleAlwaysPrivate
 335 ;//%%%    __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 336 extern const CFStringRef kSecAttrAccessibleAlwaysThisDeviceOnlyPrivate
 337 ;//%%%    __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 338
 339 /*  View Hint Constants */
 340
 341 extern const CFStringRef kSecAttrViewHintPCSMasterKey;
 342 extern const CFStringRef kSecAttrViewHintPCSiCloudDrive;
 343 extern const CFStringRef kSecAttrViewHintPCSPhotos;
 344 extern const CFStringRef kSecAttrViewHintPCSCloudKit;
 345 extern const CFStringRef kSecAttrViewHintPCSEscrow;
 346 extern const CFStringRef kSecAttrViewHintPCSFDE;
 347 extern const CFStringRef kSecAttrViewHintPCSMailDrop;
 348 extern const CFStringRef kSecAttrViewHintPCSiCloudBackup;
 349 extern const CFStringRef kSecAttrViewHintPCSNotes;
 350 extern const CFStringRef kSecAttrViewHintPCSiMessage;
 351 #if SEC_OS_IPHONE
 352 extern const CFStringRef kSecAttrViewHintPCSFeldspar;
 353 #endif /* SEC_OS_IPHONE */
 354 extern const CFStringRef kSecAttrViewHintPCSSharing;
 355
 356 extern const CFStringRef kSecAttrViewHintAppleTV;
 357 extern const CFStringRef kSecAttrViewHintHomeKit;
 358 extern const CFStringRef kSecAttrViewHintThumper;
 359 extern const CFStringRef kSecAttrViewHintContinuityUnlock;
 360 extern const CFStringRef kSecAttrViewHintAccessoryPairing;
 361 extern const CFStringRef kSecAttrViewHintNanoRegistry;
 362 extern const CFStringRef kSecAttrViewHintWatchMigration;
 363 extern const CFStringRef kSecAttrViewHintEngram;
 364 extern const CFStringRef kSecAttrViewHintManatee;
 365 extern const CFStringRef kSecAttrViewHintAutoUnlock;
 366 extern const CFStringRef kSecAttrViewHintHealth;
 367 extern const CFStringRef kSecAttrViewHintApplePay;
 368
 369
 370 #if SEC_OS_IPHONE
 371 extern const CFStringRef kSecUseSystemKeychain
 372     __TVOS_AVAILABLE(9.2)
 373     __WATCHOS_AVAILABLE(3.0)
 374     __OSX_AVAILABLE(10.11.4)
 375     __IOS_AVAILABLE(9.3);
 376
 377 extern const CFStringRef kSecUseSyncBubbleKeychain
 378     __TVOS_AVAILABLE(9.2)
 379     __WATCHOS_AVAILABLE(3.0)
 380     __OSX_AVAILABLE(10.11.4)
 381     __IOS_AVAILABLE(9.3);
 382 #endif /* SEC_OS_IPHONE */
 383
 384 /*!
 385     @enum Other Constants (Private)
 386     @discussion Predefined constants used to set values in a dictionary.
 387     @constant kSecUseTombstones Specifies a dictionary key whose value is a
 388         CFBooleanRef if present this overrides the default behaviour for when
 389         we make tombstones.  The default being we create tombstones for
 390         synchronizable items unless we are explicitly deleting or updating a
 391         tombstone.  Setting this to false when calling SecItemDelete or
 392         SecItemUpdate will ensure no tombstones are created.  Setting it to
 393         true will ensure we create tombstones even when deleting or updating non
 394         synchronizable items.
 395     @constant kSecUseKeychain Specifies a dictionary key whose value is a
 396         keychain reference. You use this key to specify a value of type
 397         SecKeychainRef that indicates the keychain to which SecItemAdd
 398         will add the provided item(s).
 399     @constant kSecUseKeychainList Specifies a dictionary key whose value is
 400         either an array of keychains to search (CFArrayRef), or a single
 401         keychain (SecKeychainRef). If not provided, the user's default
 402         keychain list is searched. kSecUseKeychainList is ignored if an
 403         explicit kSecUseItemList is also provided.  This key can be used
 404         for the SecItemCopyMatching, SecItemUpdate and SecItemDelete calls.
 405     @constant kSecUseCredentialReference Specifies a CFDataRef containing
 406         AppleCredentialManager reference handle to be used when authorizing access
 407         to the item.
 408     @constant kSecUseCallerName Specifies a dictionary key whose value
 409         is a CFStringRef that represents a user-visible string describing
 410         the caller name for which the application is attempting to authenticate.
 411         The caller must have 'com.apple.private.LocalAuthentication.CallerName'
 412         entitlement set to YES to use this feature, otherwise it is ignored.
 413         @constant kSecUseTokenRawItems If set to true, token-based items (i.e. those
 414         which have non-empty kSecAttrTokenID are not going through client-side
 415         postprocessing, only raw form stored in the database is listed.  This
 416         flag is ignored in other operations than SecItemCopyMatching().
 417 */
 418 extern const CFStringRef kSecUseTombstones
 419     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 420 extern const CFStringRef kSecUseCredentialReference
 421     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
 422 extern const CFStringRef kSecUseCallerName
 423     __OSX_AVAILABLE(10.11.4) __IOS_AVAILABLE(9.3) __TVOS_AVAILABLE(9.3) __WATCHOS_AVAILABLE(2.3);
 424 extern const CFStringRef kSecUseTokenRawItems
 425     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 426
 427 extern const CFStringRef kSOSInternalAccessGroup
 428     __OSX_AVAILABLE(10.9) __IOS_AVAILABLE(7.0) __TVOS_AVAILABLE(9.3) __WATCHOS_AVAILABLE(2.3);
 429
 430 /*!
 431  @enum kSecAttrTokenID Value Constants
 432  @discussion Predefined item attribute constant used to get or set values
 433  in a dictionary. The kSecAttrTokenID constant is the key and its value
 434  can be kSecAttrTokenIDSecureEnclave.
 435  @constant kSecAttrTokenIDKeyAppleStore Specifies well-known identifier of
 436  the token implemented using libaks (AppleKeyStore).  This token is identical to
 437  kSecAttrTokenIDSecureEnclave for devices which support Secure Enclave and
 438  silently falls back to in-kernel emulation for those devices which do not
 439  have Secure Enclave support.
 440  */
 441 extern const CFStringRef kSecAttrTokenIDAppleKeyStore
 442         __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(3.0);
 443
 444
 445 extern const CFStringRef kSecNetworkExtensionAccessGroupSuffix;
 446
 447 /*!
 448     @function SecItemCopyDisplayNames
 449     @abstract Returns an array containing unique display names for each of the
 450         certificates, keys, identities, or passwords in the provided items
 451         array.
 452     @param items An array containing items of type SecKeychainItemRef,
 453         SecKeyRef, SecCertificateRef, or SecIdentityRef. All items in the
 454         array should be of the same type.
 455     @param displayNames On return, an array of CFString references containing
 456         unique names for the supplied items. You are responsible for releasing
 457         this array reference by calling the CFRelease function.
 458     @result A result code. See "Security Error Codes" (SecBase.h).
 459     @discussion Use this function to obtain item names which are suitable for
 460         display in a menu or list view. The returned names are guaranteed to
 461         be unique across the set of provided items.
 462 */
 463 OSStatus SecItemCopyDisplayNames(CFArrayRef items, CFArrayRef *displayNames);
 464
 465 /*!
 466     @function SecItemDeleteAll
 467     @abstract Removes all items from the keychain.
 468     @result A result code. See "Security Error Codes" (SecBase.h).
 469 */
 470 OSStatus SecItemDeleteAll(void);
 471
 472 /*!
 473     @function _SecItemAddAndNotifyOnSync
 474     @abstract Adds an item to the keychain, and calls syncCallback when the item has synced
 475     @param attributes Attributes dictionary to be passed to SecItemAdd
 476     @param result Result reference to be passed to SecItemAdd
 477     @param syncCallback Block to be executed after the item has synced or failed to sync
 478     @result The result code returned from SecItemAdd
 479  */
 480 OSStatus _SecItemAddAndNotifyOnSync(CFDictionaryRef attributes, CFTypeRef * CF_RETURNS_RETAINED result, void (^syncCallback)(bool didSync, CFErrorRef error));
 481
 482 /*!
 483      @function SecItemSetCurrentItemAcrossAllDevices
 484      @abstract Sets 'new current item' to be the 'current' item in CloudKit for the given identifier.
 485  */
 486 void SecItemSetCurrentItemAcrossAllDevices(CFStringRef accessGroup,
 487                                            CFStringRef identifier,
 488                                            CFStringRef viewHint,
 489                                            CFDataRef newCurrentItemReference,
 490                                            CFDataRef newCurrentItemHash,
 491                                            CFDataRef oldCurrentItemReference,
 492                                            CFDataRef oldCurrentItemHash,
 493                                            void (^complete)(CFErrorRef error));
 494
 495 /*!
 496      @function SecItemFetchCurrentItemAcrossAllDevices
 497      @abstract Fetches the locally cached idea of which keychain item is 'current' across this iCloud account
 498                for the given access group and identifier.
 499  @param accessGroup The accessGroup of your process and the expected current item
 500  @param identifier Which 'current' item you're interested in. Freeform, but should match the ID given to
 501  SecItemSetCurrentItemAcrossAllDevices.
 502  @param viewHint The keychain view hint for your items.
 503  @param fetchCloudValue If false, will return the local machine's cached idea of which item is current. If true,
 504  performs a CloudKit operation to determine the most up-to-date version.
 505  @param complete Called to return values: a persistent ref to the current item, if such an item exists. Otherwise, error.
 506  */
 507 void SecItemFetchCurrentItemAcrossAllDevices(CFStringRef accessGroup,
 508                                              CFStringRef identifier,
 509                                              CFStringRef viewHint,
 510                                              bool fetchCloudValue,
 511                                              void (^complete)(CFDataRef persistentRef, CFErrorRef error));
 512
 513
 514 #if __OBJC__
 515 void _SecItemFetchDigests(NSString *itemClass, NSString *accessGroup, void (^complete)(NSArray *, NSError *));
 516 #endif
 517
 518 #if SEC_OS_IPHONE
 519 /*!
 520  @function SecItemDeleteAllWithAccessGroups
 521  @abstract Deletes all items for each class for the given access groups
 522  @param accessGroups An array of access groups for the items
 523  @result A result code. See "Security Error Codes" (SecBase.h).
 524  @discussion Provided for use by MobileInstallation to allow cleanup after uninstall
 525     Requires entitlement "com.apple.private.uninstall.deletion"
 526  */
 527 bool SecItemDeleteAllWithAccessGroups(CFArrayRef accessGroups, CFErrorRef *error);
 528 #endif /* SEC_OS_IPHONE */
 529
 530 /*
 531     Ensure the escrow keybag has been used to unlock the system keybag before
 532     calling either of these APIs.
 533     The password argument is optional, passing NULL implies no backup password
 534     was set.  We're assuming there will always be a backup keybag, except in
 535     the OTA case where the loaded OTA backup bag will be used.
 536  */
 537 CFDataRef _SecKeychainCopyBackup(CFDataRef backupKeybag, CFDataRef password);
 538 CFDataRef _SecKeychainCopyOTABackup(void);
 539 OSStatus _SecKeychainRestoreBackup(CFDataRef backup, CFDataRef backupKeybag,
 540     CFDataRef password);
 541
 542 #if SEC_OS_IPHONE
 543 bool
 544 _SecKeychainWriteBackupToFileDescriptor(CFDataRef backupKeybag, CFDataRef password, int fd, CFErrorRef *error);
 545
 546 bool
 547 _SecKeychainRestoreBackupFromFileDescriptor(int fd, CFDataRef backupKeybag, CFDataRef password, CFErrorRef *error);
 548
 549 CFStringRef
 550 _SecKeychainCopyKeybagUUIDFromFileDescriptor(int fd, CFErrorRef *error);
 551 #endif /* SEC_OS_IPHONE */
 552
 553 OSStatus _SecKeychainBackupSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in, CFDictionaryRef *backup_out);
 554 OSStatus _SecKeychainRestoreSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in);
 555
 556 /* Called by clients to push sync circle and message changes to us.
 557    Requires caller to have the kSecEntitlementKeychainSyncUpdates entitlement. */
 558 CFArrayRef _SecKeychainSyncUpdateMessage(CFDictionaryRef updates, CFErrorRef *error);
 559
 560 #if !TARGET_OS_IPHONE
 561 CFDataRef _SecItemGetPersistentReference(CFTypeRef raw_item);
 562 #endif
 563
 564 /* Returns an OSStatus value for the given CFErrorRef, returns errSecInternal if the
 565    domain of the provided error is not recognized.  Passing NULL returns errSecSuccess (0). */
 566 OSStatus SecErrorGetOSStatus(CFErrorRef error);
 567
 568 bool _SecKeychainRollKeys(bool force, CFErrorRef *error);
 569
 570 CFDictionaryRef _SecSecuritydCopyWhoAmI(CFErrorRef *error);
 571 XPC_RETURNS_RETAINED xpc_endpoint_t _SecSecuritydCopyCKKSEndpoint(CFErrorRef *error);
 572 XPC_RETURNS_RETAINED xpc_endpoint_t _SecSecuritydCopySOSStatusEndpoint(CFErrorRef *error);
 573
 574 #if SEC_OS_IPHONE
 575 bool _SecSyncBubbleTransfer(CFArrayRef services, uid_t uid, CFErrorRef *error);
 576 #else /* SEC_OS_IPHONE */
 577 bool _SecSyncBubbleTransfer(CFArrayRef services, CFErrorRef *error);
 578 #endif /* SEC_OS_IPHONE */
 579
 580 bool _SecSystemKeychainTransfer(CFErrorRef *error);
 581 #if SEC_OS_IPHONE
 582 bool _SecSyncDeleteUserViews(uid_t uid, CFErrorRef *error);
 583 #endif /* SEC_OS_IPHONE */
 584
 585
 586
 587 OSStatus SecItemUpdateTokenItems(CFTypeRef tokenID, CFArrayRef tokenItemsAttributes);
 588
 589 #if SEC_OS_OSX
 590 CFTypeRef SecItemCreateFromAttributeDictionary_osx(CFDictionaryRef refAttributes);
 591 #endif
 592
 593 #if SEC_OS_IPHONE
 594 /*!
 595  * @function SecCopyLastError
 596  * @abstract return the last CFErrorRef for this thread
 597  * @param status the error code returned from the API call w/o CFErrorRef or 0
 598  * @result NULL or a retained CFError of the matching error code
 599  *
 600  * @discussion There are plenty of API calls in Security.framework that
 601  * doesn't return an CFError in case of an error, many of them actually have
 602  * a CFErrorRef internally, but throw it away at the last moment.
 603  * This might be your chance to get hold of it. The status code pass in is there
 604  * to avoid stale copies of CFErrorRef.
 605
 606  * Note, not all interfaces support returning a CFErrorRef on the thread local
 607  * storage. This is especially true when going though old CDSA style API.
 608  */
 609
 610 CFErrorRef
 611 SecCopyLastError(OSStatus status)
 612     __TVOS_AVAILABLE(10.0)
 613     __WATCHOS_AVAILABLE(3.0)
 614     __IOS_AVAILABLE(10.0);
 615
 616
 617 bool
 618 SecItemUpdateWithError(CFDictionaryRef inQuery,
 619                        CFDictionaryRef inAttributesToUpdate,
 620                        CFErrorRef *error)
 621     __TVOS_AVAILABLE(10.0)
 622     __WATCHOS_AVAILABLE(3.0)
 623     __IOS_AVAILABLE(10.0);
 624 #endif // SEC_OS_IPHONE
 625
 626 #if SEC_OS_OSX
 627 /*!
 628  @function SecItemParentCachePurge
 629  @abstract Clear the cache of parent certificates used in SecItemCopyParentCertificates_osx.
 630  */
 631 void SecItemParentCachePurge();
 632 #endif
 633
 634
 635 #if SEC_OS_OSX_INCLUDES
 636 /*!
 637  @function SecItemCopyParentCertificates_osx
 638  @abstract Retrieve an array of possible issuing certificates for a given certificate.
 639  @param certificate A reference to a certificate whose issuers are being sought.
 640  @param context Pass NULL in this parameter to indicate that the default certificate
 641  source(s) should be searched. The default is to search all available keychains.
 642  Values of context other than NULL are currently ignored.
 643  @result An array of zero or more certificates whose normalized subject matches the
 644  normalized issuer of the provided certificate. Note that no cryptographic validation
 645  of the signature is performed by this function; its purpose is only to provide a list
 646  of candidate certificates.
 647  */
 648 CFArrayRef SecItemCopyParentCertificates_osx(SecCertificateRef certificate, void *context)
 649 __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 650
 651 /*!
 652  @function SecItemCopyStoredCertificate
 653  @abstract Retrieve the first stored instance of a given certificate.
 654  @param certificate A reference to a certificate.
 655  @param context Pass NULL in this parameter to indicate that the default certificate
 656  source(s) should be searched. The default is to search all available keychains.
 657  Values of context other than NULL are currently ignored.
 658  @result Returns a certificate reference if the given certificate exists in a keychain,
 659  or NULL if the certificate cannot be found in any keychain. The caller is responsible
 660  for releasing the returned certificate reference when finished with it.
 661  */
 662 SecCertificateRef SecItemCopyStoredCertificate(SecCertificateRef certificate, void *context)
 663 __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 664 #endif /* SEC_OS_OSX */
 665
 666 __END_DECLS
 667
 668 #endif /* !_SECURITY_SECITEMPRIV_H_ */