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     @constant kSecAttrAccessibleUntilReboot Not usable for keychain item. Can be used only
 334         for generating non-permanent SEP-based SecKey. Such key does not need any keybag loaded and
 335         is valid only until next reboot. Also known as class F protection.
 336 */
 337 extern const CFStringRef kSecAttrAccessibleAlwaysPrivate
 338 ;//%%%    __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 339 extern const CFStringRef kSecAttrAccessibleAlwaysThisDeviceOnlyPrivate
 340 ;//%%%    __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 341 extern const CFStringRef kSecAttrAccessibleUntilReboot
 342 API_AVAILABLE(macos(10.14.1), ios(12.1), tvos(12.1), watchos(5.1));
 343
 344 /*  View Hint Constants */
 345
 346 extern const CFStringRef kSecAttrViewHintPCSMasterKey;
 347 extern const CFStringRef kSecAttrViewHintPCSiCloudDrive;
 348 extern const CFStringRef kSecAttrViewHintPCSPhotos;
 349 extern const CFStringRef kSecAttrViewHintPCSCloudKit;
 350 extern const CFStringRef kSecAttrViewHintPCSEscrow;
 351 extern const CFStringRef kSecAttrViewHintPCSFDE;
 352 extern const CFStringRef kSecAttrViewHintPCSMailDrop;
 353 extern const CFStringRef kSecAttrViewHintPCSiCloudBackup;
 354 extern const CFStringRef kSecAttrViewHintPCSNotes;
 355 extern const CFStringRef kSecAttrViewHintPCSiMessage;
 356 extern const CFStringRef kSecAttrViewHintPCSFeldspar;
 357 extern const CFStringRef kSecAttrViewHintPCSSharing;
 358
 359 extern const CFStringRef kSecAttrViewHintAppleTV;
 360 extern const CFStringRef kSecAttrViewHintHomeKit;
 361 extern const CFStringRef kSecAttrViewHintContinuityUnlock;
 362 extern const CFStringRef kSecAttrViewHintAccessoryPairing;
 363 extern const CFStringRef kSecAttrViewHintNanoRegistry;
 364 extern const CFStringRef kSecAttrViewHintWatchMigration;
 365 extern const CFStringRef kSecAttrViewHintEngram;
 366 extern const CFStringRef kSecAttrViewHintManatee;
 367 extern const CFStringRef kSecAttrViewHintAutoUnlock;
 368 extern const CFStringRef kSecAttrViewHintHealth;
 369 extern const CFStringRef kSecAttrViewHintApplePay;
 370 extern const CFStringRef kSecAttrViewHintHome;
 371 extern const CFStringRef kSecAttrViewHintLimitedPeersAllowed;
 372
 373
 374 extern const CFStringRef kSecUseSystemKeychain
 375     __TVOS_AVAILABLE(9.2)
 376     __WATCHOS_AVAILABLE(3.0)
 377     __OSX_AVAILABLE(10.11.4)
 378     __IOS_AVAILABLE(9.3);
 379
 380 extern const CFStringRef kSecUseSyncBubbleKeychain
 381     __TVOS_AVAILABLE(9.2)
 382     __WATCHOS_AVAILABLE(3.0)
 383     __OSX_AVAILABLE(10.11.4)
 384     __IOS_AVAILABLE(9.3);
 385
 386 /*!
 387     @enum Other Constants (Private)
 388     @discussion Predefined constants used to set values in a dictionary.
 389     @constant kSecUseTombstones Specifies a dictionary key whose value is a
 390         CFBooleanRef if present this overrides the default behaviour for when
 391         we make tombstones.  The default being we create tombstones for
 392         synchronizable items unless we are explicitly deleting or updating a
 393         tombstone.  Setting this to false when calling SecItemDelete or
 394         SecItemUpdate will ensure no tombstones are created.  Setting it to
 395         true will ensure we create tombstones even when deleting or updating non
 396         synchronizable items.
 397     @constant kSecUseKeychain Specifies a dictionary key whose value is a
 398         keychain reference. You use this key to specify a value of type
 399         SecKeychainRef that indicates the keychain to which SecItemAdd
 400         will add the provided item(s).
 401     @constant kSecUseKeychainList Specifies a dictionary key whose value is
 402         either an array of keychains to search (CFArrayRef), or a single
 403         keychain (SecKeychainRef). If not provided, the user's default
 404         keychain list is searched. kSecUseKeychainList is ignored if an
 405         explicit kSecUseItemList is also provided.  This key can be used
 406         for the SecItemCopyMatching, SecItemUpdate and SecItemDelete calls.
 407     @constant kSecUseCredentialReference Specifies a CFDataRef containing
 408         AppleCredentialManager reference handle to be used when authorizing access
 409         to the item.
 410     @constant kSecUseCallerName Specifies a dictionary key whose value
 411         is a CFStringRef that represents a user-visible string describing
 412         the caller name for which the application is attempting to authenticate.
 413         The caller must have 'com.apple.private.LocalAuthentication.CallerName'
 414         entitlement set to YES to use this feature, otherwise it is ignored.
 415         @constant kSecUseTokenRawItems If set to true, token-based items (i.e. those
 416         which have non-empty kSecAttrTokenID are not going through client-side
 417         postprocessing, only raw form stored in the database is listed.  This
 418         flag is ignored in other operations than SecItemCopyMatching().
 419     @constant kSecUseCertificatesWithMatchIssuers If set to true,
 420         SecItemCopyMatching allows to return certificates when kSecMatchIssuers is specified.
 421 */
 422 extern const CFStringRef kSecUseTombstones
 423     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 424 extern const CFStringRef kSecUseCredentialReference
 425     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
 426 extern const CFStringRef kSecUseCallerName
 427     __OSX_AVAILABLE(10.11.4) __IOS_AVAILABLE(9.3) __TVOS_AVAILABLE(9.3) __WATCHOS_AVAILABLE(2.3);
 428 extern const CFStringRef kSecUseTokenRawItems
 429     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 430 extern const CFStringRef kSecUseCertificatesWithMatchIssuers
 431     __OSX_AVAILABLE(10.14) __IOS_UNAVAILABLE __TVOS_UNAVAILABLE __WATCHOS_UNAVAILABLE;
 432
 433 extern const CFStringRef kSOSInternalAccessGroup
 434     __OSX_AVAILABLE(10.9) __IOS_AVAILABLE(7.0) __TVOS_AVAILABLE(9.3) __WATCHOS_AVAILABLE(2.3);
 435
 436 /*!
 437  @enum kSecAttrTokenID Value Constants
 438  @discussion Predefined item attribute constant used to get or set values
 439  in a dictionary. The kSecAttrTokenID constant is the key and its value
 440  can be kSecAttrTokenIDSecureEnclave.
 441  @constant kSecAttrTokenIDKeyAppleStore Specifies well-known identifier of
 442  the token implemented using libaks (AppleKeyStore).  This token is identical to
 443  kSecAttrTokenIDSecureEnclave for devices which support Secure Enclave and
 444  silently falls back to in-kernel emulation for those devices which do not
 445  have Secure Enclave support.
 446  */
 447 extern const CFStringRef kSecAttrTokenIDAppleKeyStore
 448         __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(3.0);
 449
 450
 451 extern const CFStringRef kSecNetworkExtensionAccessGroupSuffix;
 452
 453 /*!
 454     @function SecItemCopyDisplayNames
 455     @abstract Returns an array containing unique display names for each of the
 456         certificates, keys, identities, or passwords in the provided items
 457         array.
 458     @param items An array containing items of type SecKeychainItemRef,
 459         SecKeyRef, SecCertificateRef, or SecIdentityRef. All items in the
 460         array should be of the same type.
 461     @param displayNames On return, an array of CFString references containing
 462         unique names for the supplied items. You are responsible for releasing
 463         this array reference by calling the CFRelease function.
 464     @result A result code. See "Security Error Codes" (SecBase.h).
 465     @discussion Use this function to obtain item names which are suitable for
 466         display in a menu or list view. The returned names are guaranteed to
 467         be unique across the set of provided items.
 468 */
 469 OSStatus SecItemCopyDisplayNames(CFArrayRef items, CFArrayRef *displayNames);
 470
 471 /*!
 472     @function SecItemDeleteAll
 473     @abstract Removes all items from the keychain.
 474     @result A result code. See "Security Error Codes" (SecBase.h).
 475 */
 476 OSStatus SecItemDeleteAll(void);
 477
 478 /*!
 479     @function _SecItemAddAndNotifyOnSync
 480     @abstract Adds an item to the keychain, and calls syncCallback when the item has synced
 481     @param attributes Attributes dictionary to be passed to SecItemAdd
 482     @param result Result reference to be passed to SecItemAdd
 483     @param syncCallback Block to be executed after the item has synced or failed to sync
 484     @result The result code returned from SecItemAdd
 485  */
 486 OSStatus _SecItemAddAndNotifyOnSync(CFDictionaryRef attributes, CFTypeRef * CF_RETURNS_RETAINED result, void (^syncCallback)(bool didSync, CFErrorRef error));
 487
 488 /*!
 489      @function SecItemSetCurrentItemAcrossAllDevices
 490      @abstract Sets 'new current item' to be the 'current' item in CloudKit for the given identifier.
 491  */
 492 void SecItemSetCurrentItemAcrossAllDevices(CFStringRef accessGroup,
 493                                            CFStringRef identifier,
 494                                            CFStringRef viewHint,
 495                                            CFDataRef newCurrentItemReference,
 496                                            CFDataRef newCurrentItemHash,
 497                                            CFDataRef oldCurrentItemReference,
 498                                            CFDataRef oldCurrentItemHash,
 499                                            void (^complete)(CFErrorRef error));
 500
 501 /*!
 502      @function SecItemFetchCurrentItemAcrossAllDevices
 503      @abstract Fetches the locally cached idea of which keychain item is 'current' across this iCloud account
 504                for the given access group and identifier.
 505  @param accessGroup The accessGroup of your process and the expected current item
 506  @param identifier Which 'current' item you're interested in. Freeform, but should match the ID given to
 507  SecItemSetCurrentItemAcrossAllDevices.
 508  @param viewHint The keychain view hint for your items.
 509  @param fetchCloudValue If false, will return the local machine's cached idea of which item is current. If true,
 510  performs a CloudKit operation to determine the most up-to-date version.
 511  @param complete Called to return values: a persistent ref to the current item, if such an item exists. Otherwise, error.
 512  */
 513 void SecItemFetchCurrentItemAcrossAllDevices(CFStringRef accessGroup,
 514                                              CFStringRef identifier,
 515                                              CFStringRef viewHint,
 516                                              bool fetchCloudValue,
 517                                              void (^complete)(CFDataRef persistentRef, CFErrorRef error));
 518
 519
 520 #if __OBJC__
 521 void _SecItemFetchDigests(NSString *itemClass, NSString *accessGroup, void (^complete)(NSArray *, NSError *));
 522 #endif
 523
 524 /*!
 525  @function SecItemDeleteAllWithAccessGroups
 526  @abstract Deletes all items for each class for the given access groups
 527  @param accessGroups An array of access groups for the items
 528  @result A result code. See "Security Error Codes" (SecBase.h).
 529  @discussion Provided for use by MobileInstallation to allow cleanup after uninstall
 530     Requires entitlement "com.apple.private.uninstall.deletion"
 531  */
 532 bool SecItemDeleteAllWithAccessGroups(CFArrayRef accessGroups, CFErrorRef *error);
 533
 534 /*
 535     Ensure the escrow keybag has been used to unlock the system keybag before
 536     calling either of these APIs.
 537     The password argument is optional, passing NULL implies no backup password
 538     was set.  We're assuming there will always be a backup keybag, except in
 539     the OTA case where the loaded OTA backup bag will be used.
 540  */
 541 CFDataRef _SecKeychainCopyBackup(CFDataRef backupKeybag, CFDataRef password);
 542 CFDataRef _SecKeychainCopyOTABackup(void);
 543 OSStatus _SecKeychainRestoreBackup(CFDataRef backup, CFDataRef backupKeybag,
 544     CFDataRef password);
 545 /*
 546     EMCS backups are similar to regular backups but we do not want to unlock the keybag
 547  */
 548 CFDataRef _SecKeychainCopyEMCSBackup(CFDataRef backupKeybag);
 549
 550 bool
 551 _SecKeychainWriteBackupToFileDescriptor(CFDataRef backupKeybag, CFDataRef password, int fd, CFErrorRef *error);
 552
 553 bool
 554 _SecKeychainRestoreBackupFromFileDescriptor(int fd, CFDataRef backupKeybag, CFDataRef password, CFErrorRef *error);
 555
 556 CFStringRef
 557 _SecKeychainCopyKeybagUUIDFromFileDescriptor(int fd, CFErrorRef *error);
 558
 559 OSStatus _SecKeychainBackupSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in, CFDictionaryRef *backup_out);
 560 OSStatus _SecKeychainRestoreSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in);
 561
 562 /* Called by clients to push sync circle and message changes to us.
 563    Requires caller to have the kSecEntitlementKeychainSyncUpdates entitlement. */
 564 CFArrayRef _SecKeychainSyncUpdateMessage(CFDictionaryRef updates, CFErrorRef *error);
 565
 566 #if !TARGET_OS_IPHONE
 567 CFDataRef _SecItemGetPersistentReference(CFTypeRef raw_item);
 568 #endif
 569
 570 /* Returns an OSStatus value for the given CFErrorRef, returns errSecInternal if the
 571    domain of the provided error is not recognized.  Passing NULL returns errSecSuccess (0). */
 572 OSStatus SecErrorGetOSStatus(CFErrorRef error);
 573
 574 bool _SecKeychainRollKeys(bool force, CFErrorRef *error);
 575
 576 CFDictionaryRef _SecSecuritydCopyWhoAmI(CFErrorRef *error);
 577 XPC_RETURNS_RETAINED xpc_endpoint_t _SecSecuritydCopyCKKSEndpoint(CFErrorRef *error);
 578 XPC_RETURNS_RETAINED xpc_endpoint_t _SecSecuritydCopySFKeychainEndpoint(CFErrorRef* error);
 579 XPC_RETURNS_RETAINED xpc_endpoint_t _SecSecuritydCopyKeychainControlEndpoint(CFErrorRef* error);
 580
 581 #if SEC_OS_IPHONE
 582 bool _SecSyncBubbleTransfer(CFArrayRef services, uid_t uid, CFErrorRef *error);
 583 #else /* SEC_OS_IPHONE */
 584 bool _SecSyncBubbleTransfer(CFArrayRef services, CFErrorRef *error);
 585 #endif /* SEC_OS_IPHONE */
 586
 587 bool _SecSystemKeychainTransfer(CFErrorRef *error);
 588 bool _SecSyncDeleteUserViews(uid_t uid, CFErrorRef *error);
 589
 590
 591
 592 OSStatus SecItemUpdateTokenItems(CFTypeRef tokenID, CFArrayRef tokenItemsAttributes);
 593
 594 #if SEC_OS_OSX
 595 CFTypeRef SecItemCreateFromAttributeDictionary_osx(CFDictionaryRef refAttributes);
 596 #endif
 597
 598 /*!
 599  * @function SecCopyLastError
 600  * @abstract return the last CFErrorRef for this thread
 601  * @param status the error code returned from the API call w/o CFErrorRef or 0
 602  * @result NULL or a retained CFError of the matching error code
 603  *
 604  * @discussion There are plenty of API calls in Security.framework that
 605  * doesn't return an CFError in case of an error, many of them actually have
 606  * a CFErrorRef internally, but throw it away at the last moment.
 607  * This might be your chance to get hold of it. The status code pass in is there
 608  * to avoid stale copies of CFErrorRef.
 609
 610  * Note, not all interfaces support returning a CFErrorRef on the thread local
 611  * storage. This is especially true when going though old CDSA style API.
 612  */
 613
 614 CFErrorRef
 615 SecCopyLastError(OSStatus status)
 616     __TVOS_AVAILABLE(10.0)
 617     __WATCHOS_AVAILABLE(3.0)
 618     __IOS_AVAILABLE(10.0);
 619
 620
 621 bool
 622 SecItemUpdateWithError(CFDictionaryRef inQuery,
 623                        CFDictionaryRef inAttributesToUpdate,
 624                        CFErrorRef *error)
 625     __TVOS_AVAILABLE(10.0)
 626     __WATCHOS_AVAILABLE(3.0)
 627     __IOS_AVAILABLE(10.0);
 628
 629 #if SEC_OS_OSX
 630 /*!
 631  @function SecItemParentCachePurge
 632  @abstract Clear the cache of parent certificates used in SecItemCopyParentCertificates_osx.
 633  */
 634 void SecItemParentCachePurge(void);
 635 #endif
 636
 637
 638 #if SEC_OS_OSX_INCLUDES
 639 /*!
 640  @function SecItemCopyParentCertificates_osx
 641  @abstract Retrieve an array of possible issuing certificates for a given certificate.
 642  @param certificate A reference to a certificate whose issuers are being sought.
 643  @param context Pass NULL in this parameter to indicate that the default certificate
 644  source(s) should be searched. The default is to search all available keychains.
 645  Values of context other than NULL are currently ignored.
 646  @result An array of zero or more certificates whose normalized subject matches the
 647  normalized issuer of the provided certificate. Note that no cryptographic validation
 648  of the signature is performed by this function; its purpose is only to provide a list
 649  of candidate certificates.
 650  */
 651 CFArrayRef SecItemCopyParentCertificates_osx(SecCertificateRef certificate, void *context)
 652 __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 653
 654 /*!
 655  @function SecItemCopyStoredCertificate
 656  @abstract Retrieve the first stored instance of a given certificate.
 657  @param certificate A reference to a certificate.
 658  @param context Pass NULL in this parameter to indicate that the default certificate
 659  source(s) should be searched. The default is to search all available keychains.
 660  Values of context other than NULL are currently ignored.
 661  @result Returns a certificate reference if the given certificate exists in a keychain,
 662  or NULL if the certificate cannot be found in any keychain. The caller is responsible
 663  for releasing the returned certificate reference when finished with it.
 664  */
 665 SecCertificateRef SecItemCopyStoredCertificate(SecCertificateRef certificate, void *context)
 666 __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 667 #endif /* SEC_OS_OSX */
 668
 669 __END_DECLS
 670
 671 #endif /* !_SECURITY_SECITEMPRIV_H_ */