keychain/headers/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_OSX
  41 #include <Security/SecTask.h>
  42 #endif
  43
  44 #if __OBJC__
  45 #import <Foundation/Foundation.h>
  46 #endif
  47
  48 __BEGIN_DECLS
  49
  50 /*!
  51     @enum Class Value Constants (Private)
  52     @discussion Predefined item class constants used to get or set values in
  53         a dictionary. The kSecClass constant is the key and its value is one
  54         of the constants defined here.
  55     @constant kSecClassAppleSharePassword Specifies AppleShare password items.
  56 */
  57 extern const CFStringRef kSecClassAppleSharePassword;
  58
  59
  60 /*!
  61     @enum Attribute Key Constants (Private)
  62     @discussion Predefined item attribute keys used to get or set values in a
  63         dictionary. Not all attributes apply to each item class. The table
  64         below lists the currently defined attributes for each item class:
  65
  66     kSecClassGenericPassword item attributes:
  67         kSecAttrAccessGroup
  68         kSecAttrCreationDate
  69         kSecAttrModificationDate
  70         kSecAttrDescription
  71         kSecAttrComment
  72         kSecAttrCreator
  73         kSecAttrType
  74         kSecAttrScriptCode (private)
  75         kSecAttrLabel
  76         kSecAttrAlias (private)
  77         kSecAttrIsInvisible
  78         kSecAttrIsNegative
  79         kSecAttrHasCustomIcon (private)
  80         kSecAttrProtected (private)
  81         kSecAttrAccount
  82         kSecAttrService
  83         kSecAttrGeneric
  84         kSecAttrSynchronizable
  85         kSecAttrSyncViewHint
  86
  87     kSecClassInternetPassword item attributes:
  88         kSecAttrAccessGroup
  89         kSecAttrCreationDate
  90         kSecAttrModificationDate
  91         kSecAttrDescription
  92         kSecAttrComment
  93         kSecAttrCreator
  94         kSecAttrType
  95         kSecAttrScriptCode (private)
  96         kSecAttrLabel
  97         kSecAttrAlias (private)
  98         kSecAttrIsInvisible
  99         kSecAttrIsNegative
 100         kSecAttrHasCustomIcon (private)
 101         kSecAttrProtected (private)
 102         kSecAttrAccount
 103         kSecAttrSecurityDomain
 104         kSecAttrServer
 105         kSecAttrProtocol
 106         kSecAttrAuthenticationType
 107         kSecAttrPort
 108         kSecAttrPath
 109         kSecAttrSynchronizable
 110         kSecAttrSyncViewHint
 111
 112     kSecClassAppleSharePassword item attributes:
 113         kSecAttrAccessGroup
 114         kSecAttrCreationDate
 115         kSecAttrModificationDate
 116         kSecAttrDescription
 117         kSecAttrComment
 118         kSecAttrCreator
 119         kSecAttrType
 120         kSecAttrScriptCode (private)
 121         kSecAttrLabel
 122         kSecAttrAlias (private)
 123         kSecAttrIsInvisible
 124         kSecAttrIsNegative
 125         kSecAttrHasCustomIcon (private)
 126         kSecAttrProtected (private)
 127         kSecAttrAccount
 128         kSecAttrVolume
 129         kSecAttrAddress
 130         kSecAttrAFPServerSignature
 131         kSecAttrSynchronizable
 132         kSecAttrSyncViewHint
 133
 134     kSecClassCertificate item attributes:
 135         kSecAttrAccessGroup
 136         kSecAttrCertificateType
 137         kSecAttrCertificateEncoding
 138         kSecAttrLabel
 139         kSecAttrAlias (private)
 140         kSecAttrSubject
 141         kSecAttrIssuer
 142         kSecAttrSerialNumber
 143         kSecAttrSubjectKeyID
 144         kSecAttrPublicKeyHash
 145         kSecAttrSynchronizable
 146         kSecAttrSyncViewHint
 147
 148     kSecClassKey item attributes:
 149         kSecAttrAccessGroup
 150         kSecAttrKeyClass
 151         kSecAttrLabel
 152         kSecAttrAlias (private)
 153         kSecAttrApplicationLabel
 154         kSecAttrIsPermanent
 155         kSecAttrIsPrivate (private)
 156         kSecAttrIsModifiable (private)
 157         kSecAttrApplicationTag
 158         kSecAttrKeyCreator (private)
 159         kSecAttrKeyType
 160         kSecAttrKeySizeInBits
 161         kSecAttrEffectiveKeySize
 162         kSecAttrStartDate (private)
 163         kSecAttrEndDate (private)
 164         kSecAttrIsSensitive (private)
 165         kSecAttrWasAlwaysSensitive (private)
 166         kSecAttrIsExtractable (private)
 167         kSecAttrWasNeverExtractable (private)
 168         kSecAttrCanEncrypt
 169         kSecAttrCanDecrypt
 170         kSecAttrCanDerive
 171         kSecAttrCanSign
 172         kSecAttrCanVerify
 173         kSecAttrCanSignRecover (private)
 174         kSecAttrCanVerifyRecover (private)
 175         kSecAttrCanWrap
 176         kSecAttrCanUnwrap
 177         kSecAttrSynchronizable
 178         kSecAttrSyncViewHint
 179
 180     kSecClassIdentity item attributes:
 181         Since an identity is the combination of a private key and a
 182         certificate, this class shares attributes of both kSecClassKey and
 183         kSecClassCertificate.
 184
 185     @constant kSecAttrScriptCode Specifies a dictionary key whose value is the
 186         item's script code attribute. You use this tag to set or get a value
 187         of type CFNumberRef that represents a script code for this item's
 188         strings. (Note: use of this attribute is deprecated; string attributes
 189         should always be stored in UTF-8 encoding. This is currently private
 190         for use by syncing; new code should not ever access this attribute.)
 191     @constant kSecAttrAlias Specifies a dictionary key whose value is the
 192         item's alias. You use this key to get or set a value of type CFDataRef
 193         which represents an alias. For certificate items, the alias is either
 194         a single email address, an array of email addresses, or the common
 195         name of the certificate if it does not contain any email address.
 196         (Items of class kSecClassCertificate have this attribute.)
 197     @constant kSecAttrHasCustomIcon Specifies a dictionary key whose value is the
 198         item's custom icon attribute. You use this tag to set or get a value
 199         of type CFBooleanRef that indicates whether the item should have an
 200         application-specific icon. (Note: use of this attribute is deprecated;
 201         custom item icons are not supported in Mac OS X. This is currently
 202         private for use by syncing; new code should not use this attribute.)
 203     @constant kSecAttrVolume Specifies a dictionary key whose value is the
 204         item's volume attribute. You use this key to set or get a CFStringRef
 205         value that represents an AppleShare volume name. (Items of class
 206         kSecClassAppleSharePassword have this attribute.)
 207     @constant kSecAttrAddress Specifies a dictionary key whose value is the
 208         item's address attribute. You use this key to set or get a CFStringRef
 209         value that contains the AppleTalk zone name, or the IP or domain name
 210         that represents the server address. (Items of class
 211         kSecClassAppleSharePassword have this attribute.)
 212     @constant kSecAttrAFPServerSignature Specifies a dictionary key whose value
 213         is the item's AFP server signature attribute. You use this key to set
 214         or get a CFDataRef value containing 16 bytes that represents the
 215         server's signature block. (Items of class kSecClassAppleSharePassword
 216         have this attribute.)
 217     @constant kSecAttrCRLType (read-only) Specifies a dictionary key whose
 218         value is the item's certificate revocation list type. You use this
 219         key to get a value of type CFNumberRef that denotes the CRL type (see
 220         the CSSM_CRL_TYPE enum in cssmtype.h). (Items of class
 221         kSecClassCertificate have this attribute.)
 222     @constant kSecAttrCRLEncoding (read-only) Specifies a dictionary key whose
 223         value is the item's certificate revocation list encoding.  You use
 224         this key to get a value of type CFNumberRef that denotes the CRL
 225         encoding (see the CSSM_CRL_ENCODING enum in cssmtype.h). (Items of
 226         class kSecClassCertificate have this attribute.)
 227     @constant kSecAttrKeyCreator Specifies a dictionary key whose value is a
 228         CFDataRef containing a CSSM_GUID structure representing the module ID of
 229         the CSP that owns this key.
 230     @constant kSecAttrIsPrivate Specifies a dictionary key whose value is a
 231         CFBooleanRef indicating whether the raw key material of the key in
 232         question is private.
 233     @constant kSecAttrIsModifiable Specifies a dictionary key whose value is a
 234         CFBooleanRef indicating whether any of the attributes of this key are
 235         modifiable.
 236     @constant kSecAttrStartDate Specifies a dictionary key whose value is a
 237         CFDateRef indicating the earliest date on which this key may be used.
 238         If kSecAttrStartDate is not present, the restriction does not apply.
 239     @constant kSecAttrEndDate Specifies a dictionary key whose value is a
 240         CFDateRef indicating the last date on which this key may be used.
 241         If kSecAttrEndDate is not present, the restriction does not apply.
 242     @constant kSecAttrIsSensitive Specifies a dictionary key whose value
 243         is a CFBooleanRef indicating whether the key in question must be wrapped
 244         with an algorithm other than CSSM_ALGID_NONE.
 245     @constant kSecAttrWasAlwaysSensitive Specifies a dictionary key whose value
 246         is a CFBooleanRef indicating that the key in question has always been
 247         marked as sensitive.
 248     @constant kSecAttrIsExtractable Specifies a dictionary key whose value
 249         is a CFBooleanRef indicating whether the key in question may be wrapped.
 250     @constant kSecAttrWasNeverExtractable Specifies a dictionary key whose value
 251         is a CFBooleanRef indicating that the key in question has never been
 252         marked as extractable.
 253     @constant kSecAttrCanSignRecover Specifies a dictionary key whole value is a
 254         CFBooleanRef indicating whether the key in question can be used to
 255         perform sign recovery.
 256     @constant kSecAttrCanVerifyRecover Specifies a dictionary key whole value is
 257         a CFBooleanRef indicating whether the key in question can be used to
 258         perform verify recovery.
 259     @constant kSecAttrTombstone Specifies a dictionary key whose value is
 260         a CFBooleanRef indicating that the item in question is a tombstone.
 261     @constant kSecAttrNoLegacy Specifies a dictionary key whose
 262         value is a CFBooleanRef indicating that the query must be run on the
 263         syncable backend even for non syncable items. This attribute is deprecated
 264         in favor of the kSecUseDataProtectionKeychain API attribute.
 265 */
 266 extern const CFStringRef kSecAttrScriptCode;
 267 extern const CFStringRef kSecAttrAlias;
 268 extern const CFStringRef kSecAttrHasCustomIcon;
 269 extern const CFStringRef kSecAttrVolume;
 270 extern const CFStringRef kSecAttrAddress;
 271 extern const CFStringRef kSecAttrAFPServerSignature;
 272 extern const CFStringRef kSecAttrCRLType;
 273 extern const CFStringRef kSecAttrCRLEncoding;
 274 extern const CFStringRef kSecAttrKeyCreator;
 275 extern const CFStringRef kSecAttrIsPrivate;
 276 extern const CFStringRef kSecAttrIsModifiable;
 277 extern const CFStringRef kSecAttrStartDate;
 278 extern const CFStringRef kSecAttrEndDate;
 279 extern const CFStringRef kSecAttrIsSensitive;
 280 extern const CFStringRef kSecAttrWasAlwaysSensitive;
 281 extern const CFStringRef kSecAttrIsExtractable;
 282 extern const CFStringRef kSecAttrWasNeverExtractable;
 283 extern const CFStringRef kSecAttrCanSignRecover;
 284 extern const CFStringRef kSecAttrCanVerifyRecover;
 285 extern const CFStringRef kSecAttrTombstone;
 286 extern const CFStringRef kSecAttrNoLegacy
 287     __API_DEPRECATED_WITH_REPLACEMENT("kSecUseDataProtectionKeychain", macos(10.11, 10.15), ios(9.3, 13.0), tvos(9.3, 13.0), watchos(2.3, 6.0));
 288 extern const CFStringRef kSecAttrSyncViewHint
 289     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 290 extern const CFStringRef kSecAttrMultiUser
 291     __OSX_AVAILABLE(10.11.5) __IOS_AVAILABLE(9.3) __TVOS_AVAILABLE(9.3) __WATCHOS_AVAILABLE(2.3);
 292
 293 /* This will force the syncing system to derive an item's plaintext synchronization id from its primary key.
 294  * This might leak primary key information, but will cause syncing devices to discover sync conflicts sooner.
 295  * Protected by the kSecEntitlementPrivateCKKSPlaintextFields entitlement.
 296  *
 297  * Will only be respected during a SecItemAdd.
 298  */
 299 extern const CFStringRef kSecAttrDeriveSyncIDFromItemAttributes
 300 __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 301 extern const CFStringRef kSecAttrPCSPlaintextServiceIdentifier
 302     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 303 extern const CFStringRef kSecAttrPCSPlaintextPublicKey
 304     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 305 extern const CFStringRef kSecAttrPCSPlaintextPublicIdentity
 306     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 307
 308 extern const CFStringRef kSecDataInetExtraNotes
 309 __OSX_AVAILABLE(10.16) __IOS_AVAILABLE(14.0) __TVOS_AVAILABLE(14.0) __WATCHOS_AVAILABLE(7.0);
 310 extern const CFStringRef kSecDataInetExtraHistory
 311 __OSX_AVAILABLE(10.16) __IOS_AVAILABLE(14.0) __TVOS_AVAILABLE(14.0) __WATCHOS_AVAILABLE(7.0);
 312 extern const CFStringRef kSecDataInetExtraClientDefined0
 313 __OSX_AVAILABLE(10.16) __IOS_AVAILABLE(14.0) __TVOS_AVAILABLE(14.0) __WATCHOS_AVAILABLE(7.0);
 314 extern const CFStringRef kSecDataInetExtraClientDefined1
 315 __OSX_AVAILABLE(10.16) __IOS_AVAILABLE(14.0) __TVOS_AVAILABLE(14.0) __WATCHOS_AVAILABLE(7.0);
 316 extern const CFStringRef kSecDataInetExtraClientDefined2
 317 __OSX_AVAILABLE(10.16) __IOS_AVAILABLE(14.0) __TVOS_AVAILABLE(14.0) __WATCHOS_AVAILABLE(7.0);
 318 extern const CFStringRef kSecDataInetExtraClientDefined3
 319 __OSX_AVAILABLE(10.16) __IOS_AVAILABLE(14.0) __TVOS_AVAILABLE(14.0) __WATCHOS_AVAILABLE(7.0);
 320
 321 // ObjectID of item stored on the token.  Token-type specific BLOB.
 322 // For kSecAttrTokenIDSecureEnclave and kSecAttrTokenIDAppleKeyStore, ObjectID is libaks's blob representation of encoded key.
 323 extern const CFStringRef kSecAttrTokenOID
 324      __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 325 extern const CFStringRef kSecAttrUUID
 326     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 327 extern const CFStringRef kSecAttrSysBound
 328     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 329 extern const CFStringRef kSecAttrSHA1
 330 __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 331
 332 #define kSecSecAttrSysBoundNot                    0
 333 #define kSecSecAttrSysBoundPreserveDuringRestore  1
 334
 335
 336 extern const CFStringRef kSecAttrKeyTypeECSECPrimeRandomPKA
 337      __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 338 extern const CFStringRef kSecAttrKeyTypeSecureEnclaveAttestation
 339      __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 340
 341 // Should not be used, use kSecAttrTokenOID instead.
 342 extern const CFStringRef kSecAttrSecureEnclaveKeyBlob
 343      __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 344
 345 /*!
 346     @enum kSecAttrAccessible Value Constants (Private)
 347     @constant kSecAttrAccessibleAlwaysPrivate Private alias for kSecAttrAccessibleAlways,
 348         which is going to be deprecated for 3rd party use.
 349     @constant kSecAttrAccessibleAlwaysThisDeviceOnlyPrivate for kSecAttrAccessibleAlwaysThisDeviceOnly,
 350         which is going to be deprecated for 3rd party use.
 351     @constant kSecAttrAccessibleUntilReboot Not usable for keychain item. Can be used only
 352         for generating non-permanent SEP-based SecKey. Such key does not need any keybag loaded and
 353         is valid only until next reboot. Also known as class F protection.
 354 */
 355 extern const CFStringRef kSecAttrAccessibleAlwaysPrivate
 356 ;//%%%    __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 357 extern const CFStringRef kSecAttrAccessibleAlwaysThisDeviceOnlyPrivate
 358 ;//%%%    __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 359 extern const CFStringRef kSecAttrAccessibleUntilReboot
 360 API_AVAILABLE(macos(10.14.1), ios(12.1), tvos(12.1), watchos(5.1));
 361
 362 /*  View Hint Constants */
 363
 364 extern const CFStringRef kSecAttrViewHintPCSMasterKey;
 365 extern const CFStringRef kSecAttrViewHintPCSiCloudDrive;
 366 extern const CFStringRef kSecAttrViewHintPCSPhotos;
 367 extern const CFStringRef kSecAttrViewHintPCSCloudKit;
 368 extern const CFStringRef kSecAttrViewHintPCSEscrow;
 369 extern const CFStringRef kSecAttrViewHintPCSFDE;
 370 extern const CFStringRef kSecAttrViewHintPCSMailDrop;
 371 extern const CFStringRef kSecAttrViewHintPCSiCloudBackup;
 372 extern const CFStringRef kSecAttrViewHintPCSNotes;
 373 extern const CFStringRef kSecAttrViewHintPCSiMessage;
 374 extern const CFStringRef kSecAttrViewHintPCSFeldspar;
 375 extern const CFStringRef kSecAttrViewHintPCSSharing;
 376
 377 extern const CFStringRef kSecAttrViewHintAppleTV;
 378 extern const CFStringRef kSecAttrViewHintHomeKit;
 379 extern const CFStringRef kSecAttrViewHintContinuityUnlock;
 380 extern const CFStringRef kSecAttrViewHintAccessoryPairing;
 381 extern const CFStringRef kSecAttrViewHintNanoRegistry;
 382 extern const CFStringRef kSecAttrViewHintWatchMigration;
 383 extern const CFStringRef kSecAttrViewHintEngram;
 384 extern const CFStringRef kSecAttrViewHintManatee;
 385 extern const CFStringRef kSecAttrViewHintAutoUnlock;
 386 extern const CFStringRef kSecAttrViewHintHealth;
 387 extern const CFStringRef kSecAttrViewHintApplePay;
 388 extern const CFStringRef kSecAttrViewHintHome;
 389 extern const CFStringRef kSecAttrViewHintLimitedPeersAllowed;
 390
 391
 392 extern const CFStringRef kSecUseSystemKeychain
 393     __TVOS_AVAILABLE(9.2)
 394     __WATCHOS_AVAILABLE(3.0)
 395     __OSX_AVAILABLE(10.11.4)
 396     __IOS_AVAILABLE(9.3);
 397
 398 extern const CFStringRef kSecUseSyncBubbleKeychain
 399     __TVOS_AVAILABLE(9.2)
 400     __WATCHOS_AVAILABLE(3.0)
 401     __OSX_AVAILABLE(10.11.4)
 402     __IOS_AVAILABLE(9.3);
 403
 404 /*!
 405     @enum Other Constants (Private)
 406     @discussion Predefined constants used to set values in a dictionary.
 407     @constant kSecUseTombstones Specifies a dictionary key whose value is a
 408         CFBooleanRef if present this overrides the default behaviour for when
 409         we make tombstones.  The default being we create tombstones for
 410         synchronizable items unless we are explicitly deleting or updating a
 411         tombstone.  Setting this to false when calling SecItemDelete or
 412         SecItemUpdate will ensure no tombstones are created.  Setting it to
 413         true will ensure we create tombstones even when deleting or updating non
 414         synchronizable items.
 415     @constant kSecUseKeychain Specifies a dictionary key whose value is a
 416         keychain reference. You use this key to specify a value of type
 417         SecKeychainRef that indicates the keychain to which SecItemAdd
 418         will add the provided item(s).
 419     @constant kSecUseKeychainList Specifies a dictionary key whose value is
 420         either an array of keychains to search (CFArrayRef), or a single
 421         keychain (SecKeychainRef). If not provided, the user's default
 422         keychain list is searched. kSecUseKeychainList is ignored if an
 423         explicit kSecUseItemList is also provided.  This key can be used
 424         for the SecItemCopyMatching, SecItemUpdate and SecItemDelete calls.
 425     @constant kSecUseCredentialReference Specifies a CFDataRef containing
 426         AppleCredentialManager reference handle to be used when authorizing access
 427         to the item.
 428     @constant kSecUseCallerName Specifies a dictionary key whose value
 429         is a CFStringRef that represents a user-visible string describing
 430         the caller name for which the application is attempting to authenticate.
 431         The caller must have 'com.apple.private.LocalAuthentication.CallerName'
 432         entitlement set to YES to use this feature, otherwise it is ignored.
 433         @constant kSecUseTokenRawItems If set to true, token-based items (i.e. those
 434         which have non-empty kSecAttrTokenID are not going through client-side
 435         postprocessing, only raw form stored in the database is listed.  This
 436         flag is ignored in other operations than SecItemCopyMatching().
 437     @constant kSecUseCertificatesWithMatchIssuers If set to true,
 438         SecItemCopyMatching allows to return certificates when kSecMatchIssuers is specified.
 439 */
 440 extern const CFStringRef kSecUseTombstones
 441     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 442 extern const CFStringRef kSecUseCredentialReference
 443     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
 444 extern const CFStringRef kSecUseCallerName
 445     __OSX_AVAILABLE(10.11.4) __IOS_AVAILABLE(9.3) __TVOS_AVAILABLE(9.3) __WATCHOS_AVAILABLE(2.3);
 446 extern const CFStringRef kSecUseTokenRawItems
 447     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 448 extern const CFStringRef kSecUseCertificatesWithMatchIssuers
 449     __OSX_AVAILABLE(10.14) API_UNAVAILABLE(ios, tvos, watchos, bridgeos, macCatalyst);
 450
 451 extern const CFStringRef kSOSInternalAccessGroup
 452     __OSX_AVAILABLE(10.9) __IOS_AVAILABLE(7.0) __TVOS_AVAILABLE(9.3) __WATCHOS_AVAILABLE(2.3);
 453
 454 /*!
 455  @enum kSecAttrTokenID Value Constants
 456  @discussion Predefined item attribute constant used to get or set values
 457  in a dictionary. The kSecAttrTokenID constant is the key and its value
 458  can be kSecAttrTokenIDSecureEnclave.
 459  @constant kSecAttrTokenIDKeyAppleStore Specifies well-known identifier of
 460  the token implemented using libaks (AppleKeyStore).  This token is identical to
 461  kSecAttrTokenIDSecureEnclave for devices which support Secure Enclave and
 462  silently falls back to in-kernel emulation for those devices which do not
 463  have Secure Enclave support.
 464  */
 465 extern const CFStringRef kSecAttrTokenIDAppleKeyStore
 466         __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(3.0);
 467
 468
 469 extern const CFStringRef kSecNetworkExtensionAccessGroupSuffix;
 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 #if __OBJC__
 520 /*!
 521     @function SecItemVerifyBackupIntegrity
 522     @abstract Verifies the presence and integrity of all key material required
 523         to restore a backup of the keychain.
 524     @discussion This function performs a synchronous call to securityd, be prepared to wait for it to scan the keychain.
 525     @param lightweight Only verify the item keys wrapped by backup keys instead
 526         of the default rigorous pass. This mode can be run in any
 527         security class.
 528     @param completion Called to indicate results: a dictionary containing information about the the infrastructure
 529         and of the backup state of keychain items. Error is set when at least one failure occurred.
 530  */
 531 void SecItemVerifyBackupIntegrity(BOOL lightweight,
 532                                   void(^completion)(NSDictionary* resultsPerKeyclass, NSError* error));
 533 void _SecItemFetchDigests(NSString *itemClass, NSString *accessGroup, void (^complete)(NSArray *, NSError *));
 534 void _SecKeychainDeleteMultiUser(NSString *musrUUID, void (^complete)(bool, NSError *));
 535 #endif
 536
 537 /*!
 538  @function SecItemDeleteAllWithAccessGroups
 539  @abstract Deletes all items for each class for the given access groups
 540  @param accessGroups An array of access groups for the items
 541  @result A result code. See "Security Error Codes" (SecBase.h).
 542  @discussion Provided for use by MobileInstallation to allow cleanup after uninstall
 543     Requires entitlement "com.apple.private.uninstall.deletion"
 544  */
 545 bool SecItemDeleteAllWithAccessGroups(CFArrayRef accessGroups, CFErrorRef *error);
 546
 547 /*
 548     Ensure the escrow keybag has been used to unlock the system keybag before
 549     calling either of these APIs.
 550     The password argument is optional, passing NULL implies no backup password
 551     was set.  We're assuming there will always be a backup keybag, except in
 552     the OTA case where the loaded OTA backup bag will be used.
 553  */
 554 CFDataRef _SecKeychainCopyBackup(CFDataRef backupKeybag, CFDataRef password);
 555 CFDataRef _SecKeychainCopyOTABackup(void);
 556 OSStatus _SecKeychainRestoreBackup(CFDataRef backup, CFDataRef backupKeybag,
 557     CFDataRef password);
 558 /*
 559     EMCS backups are similar to regular backups but we do not want to unlock the keybag
 560  */
 561 CFDataRef _SecKeychainCopyEMCSBackup(CFDataRef backupKeybag);
 562
 563 bool
 564 _SecKeychainWriteBackupToFileDescriptor(CFDataRef backupKeybag, CFDataRef password, int fd, CFErrorRef *error);
 565
 566 bool
 567 _SecKeychainRestoreBackupFromFileDescriptor(int fd, CFDataRef backupKeybag, CFDataRef password, CFErrorRef *error);
 568
 569 CFStringRef
 570 _SecKeychainCopyKeybagUUIDFromFileDescriptor(int fd, CFErrorRef *error);
 571
 572 OSStatus _SecKeychainBackupSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in, CFDictionaryRef *backup_out);
 573 OSStatus _SecKeychainRestoreSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in);
 574
 575 /* Called by clients to push sync circle and message changes to us.
 576    Requires caller to have the kSecEntitlementKeychainSyncUpdates entitlement. */
 577 CFArrayRef _SecKeychainSyncUpdateMessage(CFDictionaryRef updates, CFErrorRef *error);
 578
 579 #if !TARGET_OS_IPHONE
 580 CFDataRef _SecItemGetPersistentReference(CFTypeRef raw_item);
 581 #endif
 582
 583 /* Returns an OSStatus value for the given CFErrorRef, returns errSecInternal if the
 584    domain of the provided error is not recognized.  Passing NULL returns errSecSuccess (0). */
 585 OSStatus SecErrorGetOSStatus(CFErrorRef error);
 586
 587 bool _SecKeychainRollKeys(bool force, CFErrorRef *error);
 588
 589 CFDictionaryRef _SecSecuritydCopyWhoAmI(CFErrorRef *error);
 590 XPC_RETURNS_RETAINED xpc_endpoint_t _SecSecuritydCopyCKKSEndpoint(CFErrorRef *error);
 591 XPC_RETURNS_RETAINED xpc_endpoint_t _SecSecuritydCopySFKeychainEndpoint(CFErrorRef* error);
 592 XPC_RETURNS_RETAINED xpc_endpoint_t _SecSecuritydCopyKeychainControlEndpoint(CFErrorRef* error);
 593
 594 bool _SecSyncBubbleTransfer(CFArrayRef services, uid_t uid, CFErrorRef *error);
 595
 596 bool _SecSystemKeychainTransfer(CFErrorRef *error);
 597 bool _SecSyncDeleteUserViews(uid_t uid, CFErrorRef *error);
 598
 599
 600 OSStatus SecItemUpdateTokenItemsForAccessGroups(CFTypeRef tokenID, CFArrayRef accessGroups, CFArrayRef tokenItemsAttributes);
 601
 602 #if SEC_OS_OSX
 603 CFTypeRef SecItemCreateFromAttributeDictionary_osx(CFDictionaryRef refAttributes);
 604 #endif
 605
 606 /*!
 607  * @function SecCopyLastError
 608  * @abstract return the last CFErrorRef for this thread
 609  * @param status the error code returned from the API call w/o CFErrorRef or 0
 610  * @result NULL or a retained CFError of the matching error code
 611  *
 612  * @discussion There are plenty of API calls in Security.framework that
 613  * doesn't return an CFError in case of an error, many of them actually have
 614  * a CFErrorRef internally, but throw it away at the last moment.
 615  * This might be your chance to get hold of it. The status code pass in is there
 616  * to avoid stale copies of CFErrorRef.
 617
 618  * Note, not all interfaces support returning a CFErrorRef on the thread local
 619  * storage. This is especially true when going though old CDSA style API.
 620  */
 621
 622 CFErrorRef
 623 SecCopyLastError(OSStatus status)
 624     __TVOS_AVAILABLE(10.0)
 625     __WATCHOS_AVAILABLE(3.0)
 626     __IOS_AVAILABLE(10.0);
 627
 628
 629 bool
 630 SecItemUpdateWithError(CFDictionaryRef inQuery,
 631                        CFDictionaryRef inAttributesToUpdate,
 632                        CFErrorRef *error)
 633     __TVOS_AVAILABLE(10.0)
 634     __WATCHOS_AVAILABLE(3.0)
 635     __IOS_AVAILABLE(10.0);
 636
 637 #if SEC_OS_OSX
 638 /*!
 639  @function SecItemParentCachePurge
 640  @abstract Clear the cache of parent certificates used in SecItemCopyParentCertificates_osx.
 641  */
 642 void SecItemParentCachePurge(void);
 643 #endif
 644
 645
 646 #if SEC_OS_OSX_INCLUDES
 647 /*!
 648  @function SecItemCopyParentCertificates_osx
 649  @abstract Retrieve an array of possible issuing certificates for a given certificate.
 650  @param certificate A reference to a certificate whose issuers are being sought.
 651  @param context Pass NULL in this parameter to indicate that the default certificate
 652  source(s) should be searched. The default is to search all available keychains.
 653  Values of context other than NULL are currently ignored.
 654  @result An array of zero or more certificates whose normalized subject matches the
 655  normalized issuer of the provided certificate. Note that no cryptographic validation
 656  of the signature is performed by this function; its purpose is only to provide a list
 657  of candidate certificates.
 658  */
 659 CFArrayRef SecItemCopyParentCertificates_osx(SecCertificateRef certificate, void *context)
 660 __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 661
 662 /*!
 663  @function SecItemCopyStoredCertificate
 664  @abstract Retrieve the first stored instance of a given certificate.
 665  @param certificate A reference to a certificate.
 666  @param context Pass NULL in this parameter to indicate that the default certificate
 667  source(s) should be searched. The default is to search all available keychains.
 668  Values of context other than NULL are currently ignored.
 669  @result Returns a certificate reference if the given certificate exists in a keychain,
 670  or NULL if the certificate cannot be found in any keychain. The caller is responsible
 671  for releasing the returned certificate reference when finished with it.
 672  */
 673 SecCertificateRef SecItemCopyStoredCertificate(SecCertificateRef certificate, void *context)
 674 __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 675 #endif /* SEC_OS_OSX */
 676
 677 /*!
 678  @enum kSecAttrTokenID Value Constants
 679  @discussion Predefined item attribute constant used to get or set values
 680  in a dictionary. The kSecAttrTokenID constant is the key and its value
 681  can be kSecAttrTokenIDSecureEnclave or kSecAttrTokenIDSecureElement.
 682  @constant kSecAttrTokenIDSecureElement Specifies well-known identifier of the
 683  token implemented using device's Secure Element. The only keychain items
 684  supported by the Secure Element token are 256-bit elliptic curve keys
 685  (kSecAttrKeyTypeECSecPrimeRandom). Keys must be generated on the secure element using
 686  SecKeyCreateRandomKey call with kSecAttrTokenID set to
 687  kSecAttrTokenIDSecureElement in the parameters dictionary, it is not
 688  possible to import pregenerated keys to kSecAttrTokenIDSecureElement token.
 689  */
 690 extern const CFStringRef kSecAttrTokenIDSecureElement
 691 SPI_AVAILABLE(ios(10.13));
 692
 693 /*!
 694  @function SecItemDeleteKeychainItemsForAppClip
 695  @abstract Remove all keychain items of specified App Clip's application identifier
 696  @discussion At uninstallation time an App Clip should not leave behind any data. This function deletes any keychain items it might have had.
 697  @param applicationIdentifier Name of the App Clip application identifier which is getting uninstalled.
 698  @result Returns errSecSuccess if zero or more items were successfully deleted, otherwise errSecInternal
 699  */
 700 OSStatus
 701 SecItemDeleteKeychainItemsForAppClip(CFStringRef applicationIdentifier)
 702 SPI_AVAILABLE(ios(10.14));
 703
 704 __END_DECLS
 705
 706 #endif /* !_SECURITY_SECITEMPRIV_H_ */