OSX/sec/Security/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
  38 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
  39 #include <Security/SecTask.h>
  40 #endif
  41
  42 __BEGIN_DECLS
  43
  44 /*!
  45     @enum Class Value Constants (Private)
  46     @discussion Predefined item class constants used to get or set values in
  47         a dictionary. The kSecClass constant is the key and its value is one
  48         of the constants defined here.
  49     @constant kSecClassAppleSharePassword Specifies AppleShare password items.
  50 */
  51 extern const CFStringRef kSecClassAppleSharePassword;
  52
  53
  54 /*!
  55     @enum Attribute Key Constants (Private)
  56     @discussion Predefined item attribute keys used to get or set values in a
  57         dictionary. Not all attributes apply to each item class. The table
  58         below lists the currently defined attributes for each item class:
  59
  60     kSecClassGenericPassword item attributes:
  61         kSecAttrAccessGroup
  62         kSecAttrCreationDate
  63         kSecAttrModificationDate
  64         kSecAttrDescription
  65         kSecAttrComment
  66         kSecAttrCreator
  67         kSecAttrType
  68         kSecAttrScriptCode (private)
  69         kSecAttrLabel
  70         kSecAttrAlias (private)
  71         kSecAttrIsInvisible
  72         kSecAttrIsNegative
  73         kSecAttrHasCustomIcon (private)
  74         kSecAttrProtected (private)
  75         kSecAttrAccount
  76         kSecAttrService
  77         kSecAttrGeneric
  78         kSecAttrSynchronizable
  79         kSecAttrSyncViewHint
  80
  81     kSecClassInternetPassword item attributes:
  82         kSecAttrAccessGroup
  83         kSecAttrCreationDate
  84         kSecAttrModificationDate
  85         kSecAttrDescription
  86         kSecAttrComment
  87         kSecAttrCreator
  88         kSecAttrType
  89         kSecAttrScriptCode (private)
  90         kSecAttrLabel
  91         kSecAttrAlias (private)
  92         kSecAttrIsInvisible
  93         kSecAttrIsNegative
  94         kSecAttrHasCustomIcon (private)
  95         kSecAttrProtected (private)
  96         kSecAttrAccount
  97         kSecAttrSecurityDomain
  98         kSecAttrServer
  99         kSecAttrProtocol
 100         kSecAttrAuthenticationType
 101         kSecAttrPort
 102         kSecAttrPath
 103         kSecAttrSynchronizable
 104         kSecAttrSyncViewHint
 105
 106     kSecClassAppleSharePassword item attributes:
 107         kSecAttrAccessGroup
 108         kSecAttrCreationDate
 109         kSecAttrModificationDate
 110         kSecAttrDescription
 111         kSecAttrComment
 112         kSecAttrCreator
 113         kSecAttrType
 114         kSecAttrScriptCode (private)
 115         kSecAttrLabel
 116         kSecAttrAlias (private)
 117         kSecAttrIsInvisible
 118         kSecAttrIsNegative
 119         kSecAttrHasCustomIcon (private)
 120         kSecAttrProtected (private)
 121         kSecAttrAccount
 122         kSecAttrVolume
 123         kSecAttrAddress
 124         kSecAttrAFPServerSignature
 125         kSecAttrSynchronizable
 126         kSecAttrSyncViewHint
 127
 128     kSecClassCertificate item attributes:
 129         kSecAttrAccessGroup
 130         kSecAttrCertificateType
 131         kSecAttrCertificateEncoding
 132         kSecAttrLabel
 133         kSecAttrAlias (private)
 134         kSecAttrSubject
 135         kSecAttrIssuer
 136         kSecAttrSerialNumber
 137         kSecAttrSubjectKeyID
 138         kSecAttrPublicKeyHash
 139         kSecAttrSynchronizable
 140         kSecAttrSyncViewHint
 141
 142     kSecClassKey item attributes:
 143         kSecAttrAccessGroup
 144         kSecAttrKeyClass
 145         kSecAttrLabel
 146         kSecAttrAlias (private)
 147         kSecAttrApplicationLabel
 148         kSecAttrIsPermanent
 149         kSecAttrIsPrivate (private)
 150         kSecAttrIsModifiable (private)
 151         kSecAttrApplicationTag
 152         kSecAttrKeyCreator (private)
 153         kSecAttrKeyType
 154         kSecAttrKeySizeInBits
 155         kSecAttrEffectiveKeySize
 156         kSecAttrStartDate (private)
 157         kSecAttrEndDate (private)
 158         kSecAttrIsSensitive (private)
 159         kSecAttrWasAlwaysSensitive (private)
 160         kSecAttrIsExtractable (private)
 161         kSecAttrWasNeverExtractable (private)
 162         kSecAttrCanEncrypt
 163         kSecAttrCanDecrypt
 164         kSecAttrCanDerive
 165         kSecAttrCanSign
 166         kSecAttrCanVerify
 167         kSecAttrCanSignRecover (private)
 168         kSecAttrCanVerifyRecover (private)
 169         kSecAttrCanWrap
 170         kSecAttrCanUnwrap
 171         kSecAttrSynchronizable
 172         kSecAttrSyncViewHint
 173
 174     kSecClassIdentity item attributes:
 175         Since an identity is the combination of a private key and a
 176         certificate, this class shares attributes of both kSecClassKey and
 177         kSecClassCertificate.
 178
 179     @constant kSecAttrScriptCode Specifies a dictionary key whose value is the
 180         item's script code attribute. You use this tag to set or get a value
 181         of type CFNumberRef that represents a script code for this item's
 182         strings. (Note: use of this attribute is deprecated; string attributes
 183         should always be stored in UTF-8 encoding. This is currently private
 184         for use by syncing; new code should not ever access this attribute.)
 185     @constant kSecAttrAlias Specifies a dictionary key whose value is the
 186         item's alias. You use this key to get or set a value of type CFDataRef
 187         which represents an alias. For certificate items, the alias is either
 188         a single email address, an array of email addresses, or the common
 189         name of the certificate if it does not contain any email address.
 190         (Items of class kSecClassCertificate have this attribute.)
 191     @constant kSecAttrHasCustomIcon Specifies a dictionary key whose value is the
 192         item's custom icon attribute. You use this tag to set or get a value
 193         of type CFBooleanRef that indicates whether the item should have an
 194         application-specific icon. (Note: use of this attribute is deprecated;
 195         custom item icons are not supported in Mac OS X. This is currently
 196         private for use by syncing; new code should not use this attribute.)
 197     @constant kSecAttrVolume Specifies a dictionary key whose value is the
 198         item's volume attribute. You use this key to set or get a CFStringRef
 199         value that represents an AppleShare volume name. (Items of class
 200         kSecClassAppleSharePassword have this attribute.)
 201     @constant kSecAttrAddress Specifies a dictionary key whose value is the
 202         item's address attribute. You use this key to set or get a CFStringRef
 203         value that contains the AppleTalk zone name, or the IP or domain name
 204         that represents the server address. (Items of class
 205         kSecClassAppleSharePassword have this attribute.)
 206     @constant kSecAttrAFPServerSignature Specifies a dictionary key whose value
 207         is the item's AFP server signature attribute. You use this key to set
 208         or get a CFDataRef value containing 16 bytes that represents the
 209         server's signature block. (Items of class kSecClassAppleSharePassword
 210         have this attribute.)
 211     @constant kSecAttrCRLType (read-only) Specifies a dictionary key whose
 212         value is the item's certificate revocation list type. You use this
 213         key to get a value of type CFNumberRef that denotes the CRL type (see
 214         the CSSM_CRL_TYPE enum in cssmtype.h). (Items of class
 215         kSecClassCertificate have this attribute.)
 216     @constant kSecAttrCRLEncoding (read-only) Specifies a dictionary key whose
 217         value is the item's certificate revocation list encoding.  You use
 218         this key to get a value of type CFNumberRef that denotes the CRL
 219         encoding (see the CSSM_CRL_ENCODING enum in cssmtype.h). (Items of
 220         class kSecClassCertificate have this attribute.)
 221     @constant kSecAttrKeyCreator Specifies a dictionary key whose value is a
 222         CFDataRef containing a CSSM_GUID structure representing the module ID of
 223         the CSP that owns this key.
 224     @constant kSecAttrIsPrivate Specifies a dictionary key whose value is a
 225         CFBooleanRef indicating whether the raw key material of the key in
 226         question is private.
 227     @constant kSecAttrIsModifiable Specifies a dictionary key whose value is a
 228         CFBooleanRef indicating whether any of the attributes of this key are
 229         modifiable.
 230     @constant kSecAttrStartDate Specifies a dictionary key whose value is a
 231         CFDateRef indicating the earliest date on which this key may be used.
 232         If kSecAttrStartDate is not present, the restriction does not apply.
 233     @constant kSecAttrEndDate Specifies a dictionary key whose value is a
 234         CFDateRef indicating the last date on which this key may be used.
 235         If kSecAttrEndDate is not present, the restriction does not apply.
 236     @constant kSecAttrIsSensitive Specifies a dictionary key whose value
 237         is a CFBooleanRef indicating whether the key in question must be wrapped
 238         with an algorithm other than CSSM_ALGID_NONE.
 239     @constant kSecAttrWasAlwaysSensitive Specifies a dictionary key whose value
 240         is a CFBooleanRef indicating that the key in question has always been
 241         marked as sensitive.
 242     @constant kSecAttrIsExtractable Specifies a dictionary key whose value
 243         is a CFBooleanRef indicating whether the key in question may be wrapped.
 244     @constant kSecAttrWasNeverExtractable Specifies a dictionary key whose value
 245         is a CFBooleanRef indicating that the key in question has never been
 246         marked as extractable.
 247     @constant kSecAttrCanSignRecover Specifies a dictionary key whole value is a
 248         CFBooleanRef indicating whether the key in question can be used to
 249         perform sign recovery.
 250     @constant kSecAttrCanVerifyRecover Specifies a dictionary key whole value is
 251         a CFBooleanRef indicating whether the key in question can be used to
 252         perform verify recovery.
 253     @constant kSecAttrTombstone Specifies a dictionary key whose value is
 254         a CFBooleanRef indicating that the item in question is a tombstone.
 255     @constant kSecAttrNoLegacy Specifies a dictionary key whose
 256         value is a CFBooleanRef indicating that the query must be run on the
 257         syncable backend even for non syncable items.
 258 */
 259 extern const CFStringRef kSecAttrScriptCode;
 260 extern const CFStringRef kSecAttrAlias;
 261 extern const CFStringRef kSecAttrHasCustomIcon;
 262 extern const CFStringRef kSecAttrVolume;
 263 extern const CFStringRef kSecAttrAddress;
 264 extern const CFStringRef kSecAttrAFPServerSignature;
 265 extern const CFStringRef kSecAttrCRLType;
 266 extern const CFStringRef kSecAttrCRLEncoding;
 267 extern const CFStringRef kSecAttrKeyCreator;
 268 extern const CFStringRef kSecAttrIsPrivate;
 269 extern const CFStringRef kSecAttrIsModifiable;
 270 extern const CFStringRef kSecAttrStartDate;
 271 extern const CFStringRef kSecAttrEndDate;
 272 extern const CFStringRef kSecAttrIsSensitive;
 273 extern const CFStringRef kSecAttrWasAlwaysSensitive;
 274 extern const CFStringRef kSecAttrIsExtractable;
 275 extern const CFStringRef kSecAttrWasNeverExtractable;
 276 extern const CFStringRef kSecAttrCanSignRecover;
 277 extern const CFStringRef kSecAttrCanVerifyRecover;
 278 extern const CFStringRef kSecAttrTombstone;
 279 extern const CFStringRef kSecAttrNoLegacy
 280     __OSX_AVAILABLE(10.11) __IOS_AVAILABLE(9.3) __TVOS_AVAILABLE(9.3) __WATCHOS_AVAILABLE(2.3);
 281 extern const CFStringRef kSecAttrSyncViewHint
 282     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 283 extern const CFStringRef kSecAttrTokenID
 284     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 285
 286 extern const CFStringRef kSecAttrMultiUser
 287     __OSX_AVAILABLE(10.11.5) __IOS_AVAILABLE(9.3) __TVOS_AVAILABLE(9.3) __WATCHOS_AVAILABLE(2.3);
 288
 289 /*  View Hint Constants */
 290
 291 extern const CFStringRef kSecAttrViewHintPCSMasterKey;
 292 extern const CFStringRef kSecAttrViewHintPCSiCloudDrive;
 293 extern const CFStringRef kSecAttrViewHintPCSPhotos;
 294 extern const CFStringRef kSecAttrViewHintPCSCloudKit;
 295 extern const CFStringRef kSecAttrViewHintPCSEscrow;
 296 extern const CFStringRef kSecAttrViewHintPCSFDE;
 297 extern const CFStringRef kSecAttrViewHintPCSMailDrop;
 298 extern const CFStringRef kSecAttrViewHintPCSiCloudBackup;
 299 extern const CFStringRef kSecAttrViewHintPCSNotes;
 300 extern const CFStringRef kSecAttrViewHintPCSiMessage;
 301 extern const CFStringRef kSecAttrViewHintFeldspar;
 302
 303 extern const CFStringRef kSecAttrViewHintAppleTV;
 304 extern const CFStringRef kSecAttrViewHintHomeKit;
 305 extern const CFStringRef kSecAttrViewHintThumper;
 306
 307 /*
 308  *
 309  */
 310
 311 extern const CFStringRef kSecUseSystemKeychain
 312     __TVOS_AVAILABLE(9.2)
 313     __WATCHOS_AVAILABLE(3.0)
 314     __OSX_AVAILABLE(10.11.4)
 315     __IOS_AVAILABLE(9.3);
 316
 317 extern const CFStringRef kSecUseSyncBubbleKeychain
 318     __TVOS_AVAILABLE(9.2)
 319     __WATCHOS_AVAILABLE(3.0)
 320     __OSX_AVAILABLE(10.11.4)
 321     __IOS_AVAILABLE(9.3);
 322
 323
 324 /*!
 325     @enum Other Constants (Private)
 326     @discussion Predefined constants used to set values in a dictionary.
 327     @constant kSecUseTombstones Specifies a dictionary key whose value is a
 328         CFBooleanRef if present this overrides the default behaviour for when
 329         we make tombstones.  The default being we create tombstones for
 330         synchronizable items unless we are explicitly deleting or updating a
 331         tombstone.  Setting this to false when calling SecItemDelete or
 332         SecItemUpdate will ensure no tombstones are created.  Setting it to
 333         true will ensure we create tombstones even when deleting or updating non
 334         synchronizable items.
 335     @constant kSecUseKeychain Specifies a dictionary key whose value is a
 336         keychain reference. You use this key to specify a value of type
 337         SecKeychainRef that indicates the keychain to which SecItemAdd
 338         will add the provided item(s).
 339     @constant kSecUseKeychainList Specifies a dictionary key whose value is
 340         either an array of keychains to search (CFArrayRef), or a single
 341         keychain (SecKeychainRef). If not provided, the user's default
 342         keychain list is searched. kSecUseKeychainList is ignored if an
 343         explicit kSecUseItemList is also provided.  This key can be used
 344         for the SecItemCopyMatching, SecItemUpdate and SecItemDelete calls.
 345     @constant kSecUseCredentialReference Specifies a CFDataRef containing
 346         AppleCredentialManager reference handle to be used when authorizing access
 347         to the item.
 348     @constant kSecUseCallerName Specifies a dictionary key whose value
 349         is a CFStringRef that represents a user-visible string describing
 350         the caller name for which the application is attempting to authenticate.
 351         The caller must have 'com.apple.private.LocalAuthentication.CallerName'
 352         entitlement set to YES to use this feature, otherwise it is ignored.
 353 */
 354 extern const CFStringRef kSecUseTombstones
 355     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 356 extern const CFStringRef kSecUseCredentialReference
 357     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
 358 extern const CFStringRef kSecUseCallerName
 359     __OSX_AVAILABLE(10.11.4) __IOS_AVAILABLE(9.3) __TVOS_AVAILABLE(9.3) __WATCHOS_AVAILABLE(2.3);
 360
 361 /*!
 362     @function SecItemCopyDisplayNames
 363     @abstract Returns an array containing unique display names for each of the
 364         certificates, keys, identities, or passwords in the provided items
 365         array.
 366     @param items An array containing items of type SecKeychainItemRef,
 367         SecKeyRef, SecCertificateRef, or SecIdentityRef. All items in the
 368         array should be of the same type.
 369     @param displayNames On return, an array of CFString references containing
 370         unique names for the supplied items. You are responsible for releasing
 371         this array reference by calling the CFRelease function.
 372     @result A result code. See "Security Error Codes" (SecBase.h).
 373     @discussion Use this function to obtain item names which are suitable for
 374         display in a menu or list view. The returned names are guaranteed to
 375         be unique across the set of provided items.
 376 */
 377 OSStatus SecItemCopyDisplayNames(CFArrayRef items, CFArrayRef *displayNames);
 378
 379 /*!
 380     @function SecItemDeleteAll
 381     @abstract Removes all items from the keychain and added root certificates
 382         from the trust store.
 383     @result A result code. See "Security Error Codes" (SecBase.h).
 384 */
 385 OSStatus SecItemDeleteAll(void);
 386
 387 /*
 388     Ensure the escrow keybag has been used to unlock the system keybag before
 389     calling either of these APIs.
 390     The password argument is optional, passing NULL implies no backup password
 391     was set.  We're assuming there will always be a backup keybag, except in
 392     the OTA case where the loaded OTA backup bag will be used.
 393  */
 394 CFDataRef _SecKeychainCopyBackup(CFDataRef backupKeybag, CFDataRef password);
 395 CFDataRef _SecKeychainCopyOTABackup(void);
 396 OSStatus _SecKeychainRestoreBackup(CFDataRef backup, CFDataRef backupKeybag,
 397     CFDataRef password);
 398
 399
 400 bool
 401 _SecKeychainWriteBackupToFileDescriptor(CFDataRef backupKeybag, CFDataRef password, int fd, CFErrorRef *error);
 402
 403 bool
 404 _SecKeychainRestoreBackupFromFileDescriptor(int fd, CFDataRef backupKeybag, CFDataRef password, CFErrorRef *error);
 405
 406
 407
 408 OSStatus _SecKeychainBackupSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in, CFDictionaryRef *backup_out);
 409 OSStatus _SecKeychainRestoreSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in);
 410
 411 /* Called by clients to push sync circle and message changes to us.
 412    Requires caller to have the kSecEntitlementKeychainSyncUpdates entitlement. */
 413 CFArrayRef _SecKeychainSyncUpdateMessage(CFDictionaryRef updates, CFErrorRef *error);
 414
 415 #if !TARGET_OS_IPHONE
 416 CFDataRef _SecItemGetPersistentReference(CFTypeRef raw_item);
 417 #endif
 418
 419 /* Returns an OSStatus value for the given CFErrorRef, returns errSecInternal if the
 420  domain of the provided error is not recognized.  Passing NULL returns errSecSuccess (0). */
 421 OSStatus SecErrorGetOSStatus(CFErrorRef error);
 422
 423 bool _SecKeychainRollKeys(bool force, CFErrorRef *error);
 424
 425 CFDictionaryRef _SecSecuritydCopyWhoAmI(CFErrorRef *error);
 426 bool _SecSyncBubbleTransfer(CFArrayRef services, uid_t uid, CFErrorRef *error);
 427 bool _SecSystemKeychainTransfer(CFErrorRef *error);
 428 bool _SecSyncDeleteUserViews(uid_t uid, CFErrorRef *error);
 429
 430 __END_DECLS
 431
 432 #endif /* !_SECURITY_SECITEMPRIV_H_ */