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