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
  39 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
  40 #include <Security/SecTask.h>
  41 #endif
  42
  43 __BEGIN_DECLS
  44
  45 /*!
  46     @enum Class Value Constants (Private)
  47     @discussion Predefined item class constants used to get or set values in
  48         a dictionary. The kSecClass constant is the key and its value is one
  49         of the constants defined here.
  50     @constant kSecClassAppleSharePassword Specifies AppleShare password items.
  51 */
  52 extern const CFStringRef kSecClassAppleSharePassword;
  53
  54
  55 /*!
  56     @enum Attribute Key Constants (Private)
  57     @discussion Predefined item attribute keys used to get or set values in a
  58         dictionary. Not all attributes apply to each item class. The table
  59         below lists the currently defined attributes for each item class:
  60
  61     kSecClassGenericPassword item attributes:
  62         kSecAttrAccessGroup
  63         kSecAttrCreationDate
  64         kSecAttrModificationDate
  65         kSecAttrDescription
  66         kSecAttrComment
  67         kSecAttrCreator
  68         kSecAttrType
  69         kSecAttrScriptCode (private)
  70         kSecAttrLabel
  71         kSecAttrAlias (private)
  72         kSecAttrIsInvisible
  73         kSecAttrIsNegative
  74         kSecAttrHasCustomIcon (private)
  75         kSecAttrProtected (private)
  76         kSecAttrAccount
  77         kSecAttrService
  78         kSecAttrGeneric
  79         kSecAttrSynchronizable
  80         kSecAttrSyncViewHint
  81
  82     kSecClassInternetPassword item attributes:
  83         kSecAttrAccessGroup
  84         kSecAttrCreationDate
  85         kSecAttrModificationDate
  86         kSecAttrDescription
  87         kSecAttrComment
  88         kSecAttrCreator
  89         kSecAttrType
  90         kSecAttrScriptCode (private)
  91         kSecAttrLabel
  92         kSecAttrAlias (private)
  93         kSecAttrIsInvisible
  94         kSecAttrIsNegative
  95         kSecAttrHasCustomIcon (private)
  96         kSecAttrProtected (private)
  97         kSecAttrAccount
  98         kSecAttrSecurityDomain
  99         kSecAttrServer
 100         kSecAttrProtocol
 101         kSecAttrAuthenticationType
 102         kSecAttrPort
 103         kSecAttrPath
 104         kSecAttrSynchronizable
 105         kSecAttrSyncViewHint
 106
 107     kSecClassAppleSharePassword item attributes:
 108         kSecAttrAccessGroup
 109         kSecAttrCreationDate
 110         kSecAttrModificationDate
 111         kSecAttrDescription
 112         kSecAttrComment
 113         kSecAttrCreator
 114         kSecAttrType
 115         kSecAttrScriptCode (private)
 116         kSecAttrLabel
 117         kSecAttrAlias (private)
 118         kSecAttrIsInvisible
 119         kSecAttrIsNegative
 120         kSecAttrHasCustomIcon (private)
 121         kSecAttrProtected (private)
 122         kSecAttrAccount
 123         kSecAttrVolume
 124         kSecAttrAddress
 125         kSecAttrAFPServerSignature
 126         kSecAttrSynchronizable
 127         kSecAttrSyncViewHint
 128
 129     kSecClassCertificate item attributes:
 130         kSecAttrAccessGroup
 131         kSecAttrCertificateType
 132         kSecAttrCertificateEncoding
 133         kSecAttrLabel
 134         kSecAttrAlias (private)
 135         kSecAttrSubject
 136         kSecAttrIssuer
 137         kSecAttrSerialNumber
 138         kSecAttrSubjectKeyID
 139         kSecAttrPublicKeyHash
 140         kSecAttrSynchronizable
 141         kSecAttrSyncViewHint
 142
 143     kSecClassKey item attributes:
 144         kSecAttrAccessGroup
 145         kSecAttrKeyClass
 146         kSecAttrLabel
 147         kSecAttrAlias (private)
 148         kSecAttrApplicationLabel
 149         kSecAttrIsPermanent
 150         kSecAttrIsPrivate (private)
 151         kSecAttrIsModifiable (private)
 152         kSecAttrApplicationTag
 153         kSecAttrKeyCreator (private)
 154         kSecAttrKeyType
 155         kSecAttrKeySizeInBits
 156         kSecAttrEffectiveKeySize
 157         kSecAttrStartDate (private)
 158         kSecAttrEndDate (private)
 159         kSecAttrIsSensitive (private)
 160         kSecAttrWasAlwaysSensitive (private)
 161         kSecAttrIsExtractable (private)
 162         kSecAttrWasNeverExtractable (private)
 163         kSecAttrCanEncrypt
 164         kSecAttrCanDecrypt
 165         kSecAttrCanDerive
 166         kSecAttrCanSign
 167         kSecAttrCanVerify
 168         kSecAttrCanSignRecover (private)
 169         kSecAttrCanVerifyRecover (private)
 170         kSecAttrCanWrap
 171         kSecAttrCanUnwrap
 172         kSecAttrSynchronizable
 173         kSecAttrSyncViewHint
 174
 175     kSecClassIdentity item attributes:
 176         Since an identity is the combination of a private key and a
 177         certificate, this class shares attributes of both kSecClassKey and
 178         kSecClassCertificate.
 179
 180     @constant kSecAttrScriptCode Specifies a dictionary key whose value is the
 181         item's script code attribute. You use this tag to set or get a value
 182         of type CFNumberRef that represents a script code for this item's
 183         strings. (Note: use of this attribute is deprecated; string attributes
 184         should always be stored in UTF-8 encoding. This is currently private
 185         for use by syncing; new code should not ever access this attribute.)
 186     @constant kSecAttrAlias Specifies a dictionary key whose value is the
 187         item's alias. You use this key to get or set a value of type CFDataRef
 188         which represents an alias. For certificate items, the alias is either
 189         a single email address, an array of email addresses, or the common
 190         name of the certificate if it does not contain any email address.
 191         (Items of class kSecClassCertificate have this attribute.)
 192     @constant kSecAttrHasCustomIcon Specifies a dictionary key whose value is the
 193         item's custom icon attribute. You use this tag to set or get a value
 194         of type CFBooleanRef that indicates whether the item should have an
 195         application-specific icon. (Note: use of this attribute is deprecated;
 196         custom item icons are not supported in Mac OS X. This is currently
 197         private for use by syncing; new code should not use this attribute.)
 198     @constant kSecAttrVolume Specifies a dictionary key whose value is the
 199         item's volume attribute. You use this key to set or get a CFStringRef
 200         value that represents an AppleShare volume name. (Items of class
 201         kSecClassAppleSharePassword have this attribute.)
 202     @constant kSecAttrAddress Specifies a dictionary key whose value is the
 203         item's address attribute. You use this key to set or get a CFStringRef
 204         value that contains the AppleTalk zone name, or the IP or domain name
 205         that represents the server address. (Items of class
 206         kSecClassAppleSharePassword have this attribute.)
 207     @constant kSecAttrAFPServerSignature Specifies a dictionary key whose value
 208         is the item's AFP server signature attribute. You use this key to set
 209         or get a CFDataRef value containing 16 bytes that represents the
 210         server's signature block. (Items of class kSecClassAppleSharePassword
 211         have this attribute.)
 212     @constant kSecAttrCRLType (read-only) Specifies a dictionary key whose
 213         value is the item's certificate revocation list type. You use this
 214         key to get a value of type CFNumberRef that denotes the CRL type (see
 215         the CSSM_CRL_TYPE enum in cssmtype.h). (Items of class
 216         kSecClassCertificate have this attribute.)
 217     @constant kSecAttrCRLEncoding (read-only) Specifies a dictionary key whose
 218         value is the item's certificate revocation list encoding.  You use
 219         this key to get a value of type CFNumberRef that denotes the CRL
 220         encoding (see the CSSM_CRL_ENCODING enum in cssmtype.h). (Items of
 221         class kSecClassCertificate have this attribute.)
 222     @constant kSecAttrKeyCreator Specifies a dictionary key whose value is a
 223         CFDataRef containing a CSSM_GUID structure representing the module ID of
 224         the CSP that owns this key.
 225     @constant kSecAttrIsPrivate Specifies a dictionary key whose value is a
 226         CFBooleanRef indicating whether the raw key material of the key in
 227         question is private.
 228     @constant kSecAttrIsModifiable Specifies a dictionary key whose value is a
 229         CFBooleanRef indicating whether any of the attributes of this key are
 230         modifiable.
 231     @constant kSecAttrStartDate Specifies a dictionary key whose value is a
 232         CFDateRef indicating the earliest date on which this key may be used.
 233         If kSecAttrStartDate is not present, the restriction does not apply.
 234     @constant kSecAttrEndDate Specifies a dictionary key whose value is a
 235         CFDateRef indicating the last date on which this key may be used.
 236         If kSecAttrEndDate is not present, the restriction does not apply.
 237     @constant kSecAttrIsSensitive Specifies a dictionary key whose value
 238         is a CFBooleanRef indicating whether the key in question must be wrapped
 239         with an algorithm other than CSSM_ALGID_NONE.
 240     @constant kSecAttrWasAlwaysSensitive Specifies a dictionary key whose value
 241         is a CFBooleanRef indicating that the key in question has always been
 242         marked as sensitive.
 243     @constant kSecAttrIsExtractable Specifies a dictionary key whose value
 244         is a CFBooleanRef indicating whether the key in question may be wrapped.
 245     @constant kSecAttrWasNeverExtractable Specifies a dictionary key whose value
 246         is a CFBooleanRef indicating that the key in question has never been
 247         marked as extractable.
 248     @constant kSecAttrCanSignRecover Specifies a dictionary key whole value is a
 249         CFBooleanRef indicating whether the key in question can be used to
 250         perform sign recovery.
 251     @constant kSecAttrCanVerifyRecover Specifies a dictionary key whole value is
 252         a CFBooleanRef indicating whether the key in question can be used to
 253         perform verify recovery.
 254     @constant kSecAttrTombstone Specifies a dictionary key whose value is
 255         a CFBooleanRef indicating that the item in question is a tombstone.
 256     @constant kSecAttrNoLegacy Specifies a dictionary key whose
 257         value is a CFBooleanRef indicating that the query must be run on the
 258         syncable backend even for non syncable items.
 259 */
 260 extern const CFStringRef kSecAttrScriptCode;
 261 extern const CFStringRef kSecAttrAlias;
 262 extern const CFStringRef kSecAttrHasCustomIcon;
 263 extern const CFStringRef kSecAttrVolume;
 264 extern const CFStringRef kSecAttrAddress;
 265 extern const CFStringRef kSecAttrAFPServerSignature;
 266 extern const CFStringRef kSecAttrCRLType;
 267 extern const CFStringRef kSecAttrCRLEncoding;
 268 extern const CFStringRef kSecAttrKeyCreator;
 269 extern const CFStringRef kSecAttrIsPrivate;
 270 extern const CFStringRef kSecAttrIsModifiable;
 271 extern const CFStringRef kSecAttrStartDate;
 272 extern const CFStringRef kSecAttrEndDate;
 273 extern const CFStringRef kSecAttrIsSensitive;
 274 extern const CFStringRef kSecAttrWasAlwaysSensitive;
 275 extern const CFStringRef kSecAttrIsExtractable;
 276 extern const CFStringRef kSecAttrWasNeverExtractable;
 277 extern const CFStringRef kSecAttrCanSignRecover;
 278 extern const CFStringRef kSecAttrCanVerifyRecover;
 279 extern const CFStringRef kSecAttrTombstone;
 280 extern const CFStringRef kSecAttrNoLegacy
 281     __OSX_AVAILABLE(10.11) __IOS_AVAILABLE(9.3) __TVOS_AVAILABLE(9.3) __WATCHOS_AVAILABLE(2.3);
 282 extern const CFStringRef kSecAttrSyncViewHint
 283     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 284 extern const CFStringRef kSecAttrMultiUser
 285     __OSX_AVAILABLE(10.11.5) __IOS_AVAILABLE(9.3) __TVOS_AVAILABLE(9.3) __WATCHOS_AVAILABLE(2.3);
 286 extern const CFStringRef kSecAttrTokenOID
 287      __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 288
 289
 290 /*!
 291     @enum kSecAttrAccessible Value Constants (Private)
 292     @constant kSecAttrAccessibleAlwaysPrivate Private alias for kSecAttrAccessibleAlways,
 293         which is going to be deprecated for 3rd party use.
 294     @constant kSecAttrAccessibleAlwaysThisDeviceOnlyPrivate for kSecAttrAccessibleAlwaysThisDeviceOnly,
 295         which is going to be deprecated for 3rd party use.
 296 */
 297 extern const CFStringRef kSecAttrAccessibleAlwaysPrivate
 298 ;//%%%    __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 299 extern const CFStringRef kSecAttrAccessibleAlwaysThisDeviceOnlyPrivate
 300 ;//%%%    __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 301
 302 /*  View Hint Constants */
 303
 304 extern const CFStringRef kSecAttrViewHintPCSMasterKey;
 305 extern const CFStringRef kSecAttrViewHintPCSiCloudDrive;
 306 extern const CFStringRef kSecAttrViewHintPCSPhotos;
 307 extern const CFStringRef kSecAttrViewHintPCSCloudKit;
 308 extern const CFStringRef kSecAttrViewHintPCSEscrow;
 309 extern const CFStringRef kSecAttrViewHintPCSFDE;
 310 extern const CFStringRef kSecAttrViewHintPCSMailDrop;
 311 extern const CFStringRef kSecAttrViewHintPCSiCloudBackup;
 312 extern const CFStringRef kSecAttrViewHintPCSNotes;
 313 extern const CFStringRef kSecAttrViewHintPCSiMessage;
 314 #if SEC_OS_IPHONE
 315 extern const CFStringRef kSecAttrViewHintFeldspar;
 316 #endif /* SEC_OS_IPHONE */
 317 extern const CFStringRef kSecAttrViewHintPCSSharing;
 318
 319 extern const CFStringRef kSecAttrViewHintAppleTV;
 320 extern const CFStringRef kSecAttrViewHintHomeKit;
 321 extern const CFStringRef kSecAttrViewHintThumper;
 322 extern const CFStringRef kSecAttrViewHintContinuityUnlock;
 323 extern const CFStringRef kSecAttrViewHintAccessoryPairing;
 324
 325 #if SEC_OS_IPHONE
 326 extern const CFStringRef kSecUseSystemKeychain
 327     __TVOS_AVAILABLE(9.2)
 328     __WATCHOS_AVAILABLE(3.0)
 329     __OSX_AVAILABLE(10.11.4)
 330     __IOS_AVAILABLE(9.3);
 331
 332 extern const CFStringRef kSecUseSyncBubbleKeychain
 333     __TVOS_AVAILABLE(9.2)
 334     __WATCHOS_AVAILABLE(3.0)
 335     __OSX_AVAILABLE(10.11.4)
 336     __IOS_AVAILABLE(9.3);
 337 #endif /* SEC_OS_IPHONE */
 338
 339 /*!
 340     @enum Other Constants (Private)
 341     @discussion Predefined constants used to set values in a dictionary.
 342     @constant kSecUseTombstones Specifies a dictionary key whose value is a
 343         CFBooleanRef if present this overrides the default behaviour for when
 344         we make tombstones.  The default being we create tombstones for
 345         synchronizable items unless we are explicitly deleting or updating a
 346         tombstone.  Setting this to false when calling SecItemDelete or
 347         SecItemUpdate will ensure no tombstones are created.  Setting it to
 348         true will ensure we create tombstones even when deleting or updating non
 349         synchronizable items.
 350     @constant kSecUseKeychain Specifies a dictionary key whose value is a
 351         keychain reference. You use this key to specify a value of type
 352         SecKeychainRef that indicates the keychain to which SecItemAdd
 353         will add the provided item(s).
 354     @constant kSecUseKeychainList Specifies a dictionary key whose value is
 355         either an array of keychains to search (CFArrayRef), or a single
 356         keychain (SecKeychainRef). If not provided, the user's default
 357         keychain list is searched. kSecUseKeychainList is ignored if an
 358         explicit kSecUseItemList is also provided.  This key can be used
 359         for the SecItemCopyMatching, SecItemUpdate and SecItemDelete calls.
 360     @constant kSecUseCredentialReference Specifies a CFDataRef containing
 361         AppleCredentialManager reference handle to be used when authorizing access
 362         to the item.
 363     @constant kSecUseCallerName Specifies a dictionary key whose value
 364         is a CFStringRef that represents a user-visible string describing
 365         the caller name for which the application is attempting to authenticate.
 366         The caller must have 'com.apple.private.LocalAuthentication.CallerName'
 367         entitlement set to YES to use this feature, otherwise it is ignored.
 368 */
 369 extern const CFStringRef kSecUseTombstones
 370     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 371 extern const CFStringRef kSecUseCredentialReference
 372     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
 373 extern const CFStringRef kSecUseCallerName
 374     __OSX_AVAILABLE(10.11.4) __IOS_AVAILABLE(9.3) __TVOS_AVAILABLE(9.3) __WATCHOS_AVAILABLE(2.3);
 375
 376 /*!
 377     @function SecItemCopyDisplayNames
 378     @abstract Returns an array containing unique display names for each of the
 379         certificates, keys, identities, or passwords in the provided items
 380         array.
 381     @param items An array containing items of type SecKeychainItemRef,
 382         SecKeyRef, SecCertificateRef, or SecIdentityRef. All items in the
 383         array should be of the same type.
 384     @param displayNames On return, an array of CFString references containing
 385         unique names for the supplied items. You are responsible for releasing
 386         this array reference by calling the CFRelease function.
 387     @result A result code. See "Security Error Codes" (SecBase.h).
 388     @discussion Use this function to obtain item names which are suitable for
 389         display in a menu or list view. The returned names are guaranteed to
 390         be unique across the set of provided items.
 391 */
 392 OSStatus SecItemCopyDisplayNames(CFArrayRef items, CFArrayRef *displayNames);
 393
 394 /*!
 395     @function SecItemDeleteAll
 396     @abstract Removes all items from the keychain and added root certificates
 397         from the trust store.
 398     @result A result code. See "Security Error Codes" (SecBase.h).
 399 */
 400 OSStatus SecItemDeleteAll(void);
 401
 402 #if SEC_OS_IPHONE
 403 /*!
 404  @function SecItemDeleteAllWithAccessGroups
 405  @abstract Deletes all items for each class for the given access groups
 406  @param accessGroups An array of access groups for the items
 407  @result A result code. See "Security Error Codes" (SecBase.h).
 408  @discussion Provided for use by MobileInstallation to allow cleanup after uninstall
 409     Requires entitlement "com.apple.private.uninstall.deletion"
 410  */
 411 bool SecItemDeleteAllWithAccessGroups(CFArrayRef accessGroups, CFErrorRef *error);
 412 #endif /* SEC_OS_IPHONE */
 413
 414 /*
 415     Ensure the escrow keybag has been used to unlock the system keybag before
 416     calling either of these APIs.
 417     The password argument is optional, passing NULL implies no backup password
 418     was set.  We're assuming there will always be a backup keybag, except in
 419     the OTA case where the loaded OTA backup bag will be used.
 420  */
 421 CFDataRef _SecKeychainCopyBackup(CFDataRef backupKeybag, CFDataRef password);
 422 CFDataRef _SecKeychainCopyOTABackup(void);
 423 OSStatus _SecKeychainRestoreBackup(CFDataRef backup, CFDataRef backupKeybag,
 424     CFDataRef password);
 425
 426 #if SEC_OS_IPHONE
 427 bool
 428 _SecKeychainWriteBackupToFileDescriptor(CFDataRef backupKeybag, CFDataRef password, int fd, CFErrorRef *error);
 429
 430 bool
 431 _SecKeychainRestoreBackupFromFileDescriptor(int fd, CFDataRef backupKeybag, CFDataRef password, CFErrorRef *error);
 432
 433 CFStringRef
 434 _SecKeychainCopyKeybagUUIDFromFileDescriptor(int fd, CFErrorRef *error);
 435 #endif /* SEC_OS_IPHONE */
 436
 437 OSStatus _SecKeychainBackupSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in, CFDictionaryRef *backup_out);
 438 OSStatus _SecKeychainRestoreSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in);
 439
 440 /* Called by clients to push sync circle and message changes to us.
 441    Requires caller to have the kSecEntitlementKeychainSyncUpdates entitlement. */
 442 CFArrayRef _SecKeychainSyncUpdateMessage(CFDictionaryRef updates, CFErrorRef *error);
 443
 444 #if !TARGET_OS_IPHONE
 445 CFDataRef _SecItemGetPersistentReference(CFTypeRef raw_item);
 446 #endif
 447
 448 /* Returns an OSStatus value for the given CFErrorRef, returns errSecInternal if the
 449    domain of the provided error is not recognized.  Passing NULL returns errSecSuccess (0). */
 450 OSStatus SecErrorGetOSStatus(CFErrorRef error);
 451
 452 bool _SecKeychainRollKeys(bool force, CFErrorRef *error);
 453
 454 CFDictionaryRef _SecSecuritydCopyWhoAmI(CFErrorRef *error);
 455
 456 #if SEC_OS_IPHONE
 457 bool _SecSyncBubbleTransfer(CFArrayRef services, uid_t uid, CFErrorRef *error);
 458 #else /* SEC_OS_IPHONE */
 459 bool _SecSyncBubbleTransfer(CFArrayRef services, CFErrorRef *error);
 460 #endif /* SEC_OS_IPHONE */
 461
 462 bool _SecSystemKeychainTransfer(CFErrorRef *error);
 463 #if SEC_OS_IPHONE
 464 bool _SecSyncDeleteUserViews(uid_t uid, CFErrorRef *error);
 465 #endif /* SEC_OS_IPHONE */
 466
 467 OSStatus SecItemUpdateTokenItems(CFTypeRef tokenID, CFArrayRef tokenItemsAttributes);
 468
 469 #if SEC_OS_OSX
 470 CFTypeRef SecItemCreateFromAttributeDictionary_osx(CFDictionaryRef refAttributes);
 471 #endif
 472
 473 #if SEC_OS_IPHONE
 474 /*!
 475  * @function SecCopyLastError
 476  * @abstract return the last CFErrorRef for this thread
 477  * @param status the error code returned from the API call w/o CFErrorRef or 0
 478  * @result NULL or a retained CFError of the matching error code
 479  *
 480  * @discussion There are plenty of API calls in Security.framework that
 481  * doesn't return an CFError in case of an error, many of them actually have
 482  * a CFErrorRef internally, but throw it away at the last moment.
 483  * This might be your chance to get hold of it. The status code pass in is there
 484  * to avoid stale copies of CFErrorRef.
 485
 486  * Note, not all interfaces support returning a CFErrorRef on the thread local
 487  * storage. This is especially true when going though old CDSA style API.
 488  */
 489
 490 CFErrorRef
 491 SecCopyLastError(OSStatus status)
 492     __TVOS_AVAILABLE(10.0)
 493     __WATCHOS_AVAILABLE(3.0)
 494     __IOS_AVAILABLE(10.0);
 495
 496
 497 bool
 498 SecItemUpdateWithError(CFDictionaryRef inQuery,
 499                        CFDictionaryRef inAttributesToUpdate,
 500                        CFErrorRef *error)
 501     __TVOS_AVAILABLE(10.0)
 502     __WATCHOS_AVAILABLE(3.0)
 503     __IOS_AVAILABLE(10.0);
 504 #endif // SEC_OS_IPHONE
 505
 506 #if SEC_OS_OSX
 507 /*!
 508  @function SecItemParentCachePurge
 509  @abstract Clear the cache of parent certificates used in SecItemCopyParentCertificates.
 510  */
 511 void SecItemParentCachePurge();
 512 #endif
 513
 514
 515 #if SEC_OS_OSX_INCLUDES
 516 /*!
 517  @function SecItemCopyParentCertificates
 518  @abstract Retrieve an array of possible issuing certificates for a given certificate.
 519  @param certificate A reference to a certificate whose issuers are being sought.
 520  @param context Pass NULL in this parameter to indicate that the default certificate
 521  source(s) should be searched. The default is to search all available keychains.
 522  Values of context other than NULL are currently ignored.
 523  @result An array of zero or more certificates whose normalized subject matches the
 524  normalized issuer of the provided certificate. Note that no cryptographic validation
 525  of the signature is performed by this function; its purpose is only to provide a list
 526  of candidate certificates.
 527  */
 528 CFArrayRef SecItemCopyParentCertificates(SecCertificateRef certificate, void *context)
 529 __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 530
 531 /*!
 532  @function SecItemCopyStoredCertificate
 533  @abstract Retrieve the first stored instance of a given certificate.
 534  @param certificate A reference to a certificate.
 535  @param context Pass NULL in this parameter to indicate that the default certificate
 536  source(s) should be searched. The default is to search all available keychains.
 537  Values of context other than NULL are currently ignored.
 538  @result Returns a certificate reference if the given certificate exists in a keychain,
 539  or NULL if the certificate cannot be found in any keychain. The caller is responsible
 540  for releasing the returned certificate reference when finished with it.
 541  */
 542 SecCertificateRef SecItemCopyStoredCertificate(SecCertificateRef certificate, void *context)
 543 __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 544 #endif /* SEC_OS_OSX */
 545
 546 __END_DECLS
 547
 548 #endif /* !_SECURITY_SECITEMPRIV_H_ */