keychain/SecItemPriv.h

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