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