OSX/libsecurity_keychain/lib/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 extern const CFStringRef kSecAttrViewHintPCSSharing;
 315
 316 extern const CFStringRef kSecAttrViewHintAppleTV;
 317 extern const CFStringRef kSecAttrViewHintHomeKit;
 318 extern const CFStringRef kSecAttrViewHintThumper;
 319 extern const CFStringRef kSecAttrViewHintContinuityUnlock;
 320 extern const CFStringRef kSecAttrViewHintAccessoryPairing;
 321
 322 /*!
 323     @enum Other Constants (Private)
 324     @discussion Predefined constants used to set values in a dictionary.
 325     @constant kSecUseTombstones Specifies a dictionary key whose value is a
 326         CFBooleanRef if present this overrides the default behaviour for when
 327         we make tombstones.  The default being we create tombstones for
 328         synchronizable items unless we are explicitly deleting or updating a
 329         tombstone.  Setting this to false when calling SecItemDelete or
 330         SecItemUpdate will ensure no tombstones are created.  Setting it to
 331         true will ensure we create tombstones even when deleting or updating non
 332         synchronizable items.
 333     @constant kSecUseKeychain Specifies a dictionary key whose value is a
 334         keychain reference. You use this key to specify a value of type
 335         SecKeychainRef that indicates the keychain to which SecItemAdd
 336         will add the provided item(s).
 337     @constant kSecUseKeychainList Specifies a dictionary key whose value is
 338         either an array of keychains to search (CFArrayRef), or a single
 339         keychain (SecKeychainRef). If not provided, the user's default
 340         keychain list is searched. kSecUseKeychainList is ignored if an
 341         explicit kSecUseItemList is also provided.  This key can be used
 342         for the SecItemCopyMatching, SecItemUpdate and SecItemDelete calls.
 343     @constant kSecUseCredentialReference Specifies a CFDataRef containing
 344         AppleCredentialManager reference handle to be used when authorizing access
 345         to the item.
 346     @constant kSecUseCallerName Specifies a dictionary key whose value
 347         is a CFStringRef that represents a user-visible string describing
 348         the caller name for which the application is attempting to authenticate.
 349         The caller must have 'com.apple.private.LocalAuthentication.CallerName'
 350         entitlement set to YES to use this feature, otherwise it is ignored.
 351 */
 352 extern const CFStringRef kSecUseTombstones
 353     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 354 extern const CFStringRef kSecUseCredentialReference
 355     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
 356 extern const CFStringRef kSecUseCallerName
 357     __OSX_AVAILABLE(10.11.4) __IOS_AVAILABLE(9.3) __TVOS_AVAILABLE(9.3) __WATCHOS_AVAILABLE(2.3);
 358
 359 /*!
 360     @function SecItemCopyDisplayNames
 361     @abstract Returns an array containing unique display names for each of the
 362         certificates, keys, identities, or passwords in the provided items
 363         array.
 364     @param items An array containing items of type SecKeychainItemRef,
 365         SecKeyRef, SecCertificateRef, or SecIdentityRef. All items in the
 366         array should be of the same type.
 367     @param displayNames On return, an array of CFString references containing
 368         unique names for the supplied items. You are responsible for releasing
 369         this array reference by calling the CFRelease function.
 370     @result A result code. See "Security Error Codes" (SecBase.h).
 371     @discussion Use this function to obtain item names which are suitable for
 372         display in a menu or list view. The returned names are guaranteed to
 373         be unique across the set of provided items.
 374 */
 375 OSStatus SecItemCopyDisplayNames(CFArrayRef items, CFArrayRef *displayNames);
 376
 377 /*!
 378     @function SecItemDeleteAll
 379     @abstract Removes all items from the keychain and added root certificates
 380         from the trust store.
 381     @result A result code. See "Security Error Codes" (SecBase.h).
 382 */
 383 OSStatus SecItemDeleteAll(void);
 384
 385
 386 /*!
 387  @function SecItemParentCachePurge
 388  @abstract Clear the cache of parent certificates used in SecItemCopyParentCertificates.
 389  */
 390 void SecItemParentCachePurge();
 391
 392 /*!
 393     @function SecItemCopyParentCertificates
 394     @abstract Retrieve an array of possible issuing certificates for a given certificate.
 395     @param certificate A reference to a certificate whose issuers are being sought.
 396     @param context Pass NULL in this parameter to indicate that the default certificate
 397     source(s) should be searched. The default is to search all available keychains.
 398     Values of context other than NULL are currently ignored.
 399     @result An array of zero or more certificates whose normalized subject matches the
 400     normalized issuer of the provided certificate. Note that no cryptographic validation
 401     of the signature is performed by this function; its purpose is only to provide a list
 402     of candidate certificates.
 403 */
 404 CFArrayRef SecItemCopyParentCertificates(SecCertificateRef certificate, void *context)
 405     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 406
 407 /*!
 408     @function SecItemCopyStoredCertificate
 409     @abstract Retrieve the first stored instance of a given certificate.
 410     @param certificate A reference to a certificate.
 411     @param context Pass NULL in this parameter to indicate that the default certificate
 412     source(s) should be searched. The default is to search all available keychains.
 413     Values of context other than NULL are currently ignored.
 414     @result Returns a certificate reference if the given certificate exists in a keychain,
 415     or NULL if the certificate cannot be found in any keychain. The caller is responsible
 416     for releasing the returned certificate reference when finished with it.
 417 */
 418 SecCertificateRef SecItemCopyStoredCertificate(SecCertificateRef certificate, void *context)
 419     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 420
 421 /*
 422     Ensure the escrow keybag has been used to unlock the system keybag before
 423     calling either of these APIs.
 424     The password argument is optional, passing NULL implies no backup password
 425     was set.  We're assuming there will always be a backup keybag, except in
 426     the OTA case where the loaded OTA backup bag will be used.
 427  */
 428 CFDataRef _SecKeychainCopyBackup(CFDataRef backupKeybag, CFDataRef password);
 429 CFDataRef _SecKeychainCopyOTABackup(void);
 430 OSStatus _SecKeychainRestoreBackup(CFDataRef backup, CFDataRef backupKeybag,
 431     CFDataRef password);
 432
 433 OSStatus _SecKeychainBackupSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in, CFDictionaryRef *backup_out);
 434 OSStatus _SecKeychainRestoreSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in);
 435
 436 /* Called by clients to push sync circle and message changes to us.
 437    Requires caller to have the kSecEntitlementKeychainSyncUpdates entitlement. */
 438 CFArrayRef _SecKeychainSyncUpdateMessage(CFDictionaryRef updates, CFErrorRef *error);
 439
 440 #if !TARGET_OS_IPHONE
 441 CFDataRef _SecItemGetPersistentReference(CFTypeRef raw_item);
 442 #endif
 443
 444 /* Returns an OSStatus value for the given CFErrorRef, returns errSecInternal if the
 445    domain of the provided error is not recognized.  Passing NULL returns errSecSuccess (0). */
 446 OSStatus SecErrorGetOSStatus(CFErrorRef error);
 447
 448 bool _SecKeychainRollKeys(bool force, CFErrorRef *error);
 449
 450 CFDictionaryRef _SecSecuritydCopyWhoAmI(CFErrorRef *error);
 451 bool _SecSyncBubbleTransfer(CFArrayRef services, CFErrorRef *error);
 452 bool _SecSystemKeychainTransfer(CFErrorRef *error);
 453
 454 OSStatus SecItemUpdateTokenItems(CFTypeRef tokenID, CFArrayRef tokenItemsAttributes);
 455
 456 __END_DECLS
 457
 458 #endif /* !_SECURITY_SECITEMPRIV_H_ */