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
  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_STARTING(__MAC_10_11, __IPHONE_NA);
 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 /*  View Hint Constants */
 287
 288 extern const CFStringRef kSecAttrViewHintPCSMasterKey;
 289 extern const CFStringRef kSecAttrViewHintPCSiCloudDrive;
 290 extern const CFStringRef kSecAttrViewHintPCSPhotos;
 291 extern const CFStringRef kSecAttrViewHintPCSCloudKit;
 292 extern const CFStringRef kSecAttrViewHintPCSEscrow;
 293 extern const CFStringRef kSecAttrViewHintPCSFDE;
 294 extern const CFStringRef kSecAttrViewHintPCSMailDrop;
 295 extern const CFStringRef kSecAttrViewHintPCSiCloudBackup;
 296 extern const CFStringRef kSecAttrViewHintPCSNotes;
 297 extern const CFStringRef kSecAttrViewHintPCSiMessage;
 298
 299 extern const CFStringRef kSecAttrViewHintAppleTV;
 300 extern const CFStringRef kSecAttrViewHintHomeKit;
 301 extern const CFStringRef kSecAttrViewHintThumper;
 302
 303 /*!
 304     @enum Other Constants (Private)
 305     @discussion Predefined constants used to set values in a dictionary.
 306     @constant kSecUseTombstones Specifies a dictionary key whose value is a
 307         CFBooleanRef if present this overrides the default behaviour for when
 308         we make tombstones.  The default being we create tombstones for
 309         synchronizable items unless we are explicitly deleting or updating a
 310         tombstone.  Setting this to false when calling SecItemDelete or
 311         SecItemUpdate will ensure no tombstones are created.  Setting it to
 312         true will ensure we create tombstones even when deleting or updating non
 313         synchronizable items.
 314     @constant kSecUseKeychain Specifies a dictionary key whose value is a
 315         keychain reference. You use this key to specify a value of type
 316         SecKeychainRef that indicates the keychain to which SecItemAdd
 317         will add the provided item(s).
 318     @constant kSecUseKeychainList Specifies a dictionary key whose value is
 319         either an array of keychains to search (CFArrayRef), or a single
 320         keychain (SecKeychainRef). If not provided, the user's default
 321         keychain list is searched. kSecUseKeychainList is ignored if an
 322         explicit kSecUseItemList is also provided.  This key can be used
 323         for the SecItemCopyMatching, SecItemUpdate and SecItemDelete calls.
 324     @constant kSecUseCredentialReference Specifies a CFDataRef containing
 325         AppleCredentialManager reference handle to be used when authorizing access
 326         to the item.
 327 */
 328 extern const CFStringRef kSecUseTombstones
 329     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 330 extern const CFStringRef kSecUseCredentialReference
 331     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
 332 #if defined(MULTIPLE_KEYCHAINS)
 333 extern const CFStringRef kSecUseKeychain;
 334 extern const CFStringRef kSecUseKeychainList;
 335 #endif /* !defined(MULTIPLE_KEYCHAINS) */
 336
 337
 338 /*!
 339     @function SecItemCopyDisplayNames
 340     @abstract Returns an array containing unique display names for each of the
 341         certificates, keys, identities, or passwords in the provided items
 342         array.
 343     @param items An array containing items of type SecKeychainItemRef,
 344         SecKeyRef, SecCertificateRef, or SecIdentityRef. All items in the
 345         array should be of the same type.
 346     @param displayNames On return, an array of CFString references containing
 347         unique names for the supplied items. You are responsible for releasing
 348         this array reference by calling the CFRelease function.
 349     @result A result code. See "Security Error Codes" (SecBase.h).
 350     @discussion Use this function to obtain item names which are suitable for
 351         display in a menu or list view. The returned names are guaranteed to
 352         be unique across the set of provided items.
 353 */
 354 OSStatus SecItemCopyDisplayNames(CFArrayRef items, CFArrayRef *displayNames);
 355
 356 /*!
 357     @function SecItemDeleteAll
 358     @abstract Removes all items from the keychain and added root certificates
 359         from the trust store.
 360     @result A result code. See "Security Error Codes" (SecBase.h).
 361 */
 362 OSStatus SecItemDeleteAll(void);
 363
 364 /*
 365     Ensure the escrow keybag has been used to unlock the system keybag before
 366     calling either of these APIs.
 367     The password argument is optional, passing NULL implies no backup password
 368     was set.  We're assuming there will always be a backup keybag, except in
 369     the OTA case where the loaded OTA backup bag will be used.
 370  */
 371 CFDataRef _SecKeychainCopyBackup(CFDataRef backupKeybag, CFDataRef password);
 372 CFDataRef _SecKeychainCopyOTABackup(void);
 373 OSStatus _SecKeychainRestoreBackup(CFDataRef backup, CFDataRef backupKeybag,
 374     CFDataRef password);
 375
 376 OSStatus _SecKeychainBackupSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in, CFDictionaryRef *backup_out);
 377 OSStatus _SecKeychainRestoreSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in);
 378
 379 /* Called by clients to push sync circle and message changes to us.
 380    Requires caller to have the kSecEntitlementKeychainSyncUpdates entitlement. */
 381 CFArrayRef _SecKeychainSyncUpdateMessage(CFDictionaryRef updates, CFErrorRef *error);
 382
 383 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
 384 CFDataRef _SecItemGetPersistentReference(CFTypeRef raw_item);
 385 #endif
 386
 387 /* Returns an OSStatus value for the given CFErrorRef, returns errSecInternal if the
 388    domain of the provided error is not recognized.  Passing NULL returns errSecSuccess (0). */
 389 OSStatus SecErrorGetOSStatus(CFErrorRef error);
 390
 391 bool _SecKeychainRollKeys(bool force, CFErrorRef *error);
 392
 393 __END_DECLS
 394
 395 #endif /* !_SECURITY_SECITEMPRIV_H_ */