sec/Security/SecItemPriv.h

   1 /*
   2  * Copyright (c) 2006-2013 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/CFData.h>
  34 #include <CoreFoundation/CFError.h>
  35
  36 __BEGIN_DECLS
  37
  38 /*!
  39     @enum Class Value Constants (Private)
  40     @discussion Predefined item class constants used to get or set values in
  41         a dictionary. The kSecClass constant is the key and its value is one
  42         of the constants defined here.
  43     @constant kSecClassAppleSharePassword Specifies AppleShare password items.
  44 */
  45 extern CFTypeRef kSecClassAppleSharePassword;
  46
  47
  48 /*!
  49     @enum Attribute Key Constants (Private)
  50     @discussion Predefined item attribute keys used to get or set values in a
  51         dictionary. Not all attributes apply to each item class. The table
  52         below lists the currently defined attributes for each item class:
  53
  54     kSecClassGenericPassword item attributes:
  55         kSecAttrAccessGroup
  56         kSecAttrCreationDate
  57         kSecAttrModificationDate
  58         kSecAttrDescription
  59         kSecAttrComment
  60         kSecAttrCreator
  61         kSecAttrType
  62         kSecAttrScriptCode (private)
  63         kSecAttrLabel
  64         kSecAttrAlias (private)
  65         kSecAttrIsInvisible
  66         kSecAttrIsNegative
  67         kSecAttrHasCustomIcon (private)
  68         kSecAttrProtected (private)
  69         kSecAttrAccount
  70         kSecAttrService
  71         kSecAttrGeneric
  72
  73     kSecClassInternetPassword item attributes:
  74         kSecAttrAccessGroup
  75         kSecAttrCreationDate
  76         kSecAttrModificationDate
  77         kSecAttrDescription
  78         kSecAttrComment
  79         kSecAttrCreator
  80         kSecAttrType
  81         kSecAttrScriptCode (private)
  82         kSecAttrLabel
  83         kSecAttrAlias (private)
  84         kSecAttrIsInvisible
  85         kSecAttrIsNegative
  86         kSecAttrHasCustomIcon (private)
  87         kSecAttrProtected (private)
  88         kSecAttrAccount
  89         kSecAttrSecurityDomain
  90         kSecAttrServer
  91         kSecAttrProtocol
  92         kSecAttrAuthenticationType
  93         kSecAttrPort
  94         kSecAttrPath
  95
  96     kSecClassAppleSharePassword item attributes:
  97         kSecAttrAccessGroup
  98         kSecAttrCreationDate
  99         kSecAttrModificationDate
 100         kSecAttrDescription
 101         kSecAttrComment
 102         kSecAttrCreator
 103         kSecAttrType
 104         kSecAttrScriptCode (private)
 105         kSecAttrLabel
 106         kSecAttrAlias (private)
 107         kSecAttrIsInvisible
 108         kSecAttrIsNegative
 109         kSecAttrHasCustomIcon (private)
 110         kSecAttrProtected (private)
 111         kSecAttrAccount
 112         kSecAttrVolume
 113         kSecAttrAddress
 114         kSecAttrAFPServerSignature
 115
 116     kSecClassCertificate item attributes:
 117         kSecAttrAccessGroup
 118         kSecAttrCertificateType
 119         kSecAttrCertificateEncoding
 120         kSecAttrLabel
 121         kSecAttrAlias (private)
 122         kSecAttrSubject
 123         kSecAttrIssuer
 124         kSecAttrSerialNumber
 125         kSecAttrSubjectKeyID
 126         kSecAttrPublicKeyHash
 127
 128     kSecClassKey item attributes:
 129         kSecAttrAccessGroup
 130         kSecAttrKeyClass
 131         kSecAttrLabel
 132         kSecAttrAlias (private)
 133         kSecAttrApplicationLabel
 134         kSecAttrIsPermanent
 135         kSecAttrIsPrivate (private)
 136         kSecAttrIsModifiable (private)
 137         kSecAttrApplicationTag
 138         kSecAttrKeyCreator (private)
 139         kSecAttrKeyType
 140         kSecAttrKeySizeInBits
 141         kSecAttrEffectiveKeySize
 142         kSecAttrStartDate (private)
 143         kSecAttrEndDate (private)
 144         kSecAttrIsSensitive (private)
 145         kSecAttrWasAlwaysSensitive (private)
 146         kSecAttrIsExtractable (private)
 147         kSecAttrWasNeverExtractable (private)
 148         kSecAttrCanEncrypt
 149         kSecAttrCanDecrypt
 150         kSecAttrCanDerive
 151         kSecAttrCanSign
 152         kSecAttrCanVerify
 153         kSecAttrCanSignRecover (private)
 154         kSecAttrCanVerifyRecover (private)
 155         kSecAttrCanWrap
 156         kSecAttrCanUnwrap
 157
 158     kSecClassIdentity item attributes:
 159         Since an identity is the combination of a private key and a
 160         certificate, this class shares attributes of both kSecClassKey and
 161         kSecClassCertificate.
 162
 163     @constant kSecAttrScriptCode Specifies a dictionary key whose value is the
 164         item's script code attribute. You use this tag to set or get a value
 165         of type CFNumberRef that represents a script code for this item's
 166         strings. (Note: use of this attribute is deprecated; string attributes
 167         should always be stored in UTF-8 encoding. This is currently private
 168         for use by syncing; new code should not ever access this attribute.)
 169     @constant kSecAttrAlias Specifies a dictionary key whose value is the
 170         item's alias. You use this key to get or set a value of type CFDataRef
 171         which represents an alias. For certificate items, the alias is either
 172         a single email address, an array of email addresses, or the common
 173         name of the certificate if it does not contain any email address.
 174         (Items of class kSecClassCertificate have this attribute.)
 175     @constant kSecAttrHasCustomIcon Specifies a dictionary key whose value is the
 176         item's custom icon attribute. You use this tag to set or get a value
 177         of type CFBooleanRef that indicates whether the item should have an
 178         application-specific icon. (Note: use of this attribute is deprecated;
 179         custom item icons are not supported in Mac OS X. This is currently
 180         private for use by syncing; new code should not use this attribute.)
 181     @constant kSecAttrVolume Specifies a dictionary key whose value is the
 182         item's volume attribute. You use this key to set or get a CFStringRef
 183         value that represents an AppleShare volume name. (Items of class
 184         kSecClassAppleSharePassword have this attribute.)
 185     @constant kSecAttrAddress Specifies a dictionary key whose value is the
 186         item's address attribute. You use this key to set or get a CFStringRef
 187         value that contains the AppleTalk zone name, or the IP or domain name
 188         that represents the server address. (Items of class
 189         kSecClassAppleSharePassword have this attribute.)
 190     @constant kSecAttrAFPServerSignature Specifies a dictionary key whose value
 191         is the item's AFP server signature attribute. You use this key to set
 192         or get a CFDataRef value containing 16 bytes that represents the
 193         server's signature block. (Items of class kSecClassAppleSharePassword
 194         have this attribute.)
 195     @constant kSecAttrCRLType (read-only) Specifies a dictionary key whose
 196         value is the item's certificate revocation list type. You use this
 197         key to get a value of type CFNumberRef that denotes the CRL type (see
 198         the CSSM_CRL_TYPE enum in cssmtype.h). (Items of class
 199         kSecClassCertificate have this attribute.)
 200     @constant kSecAttrCRLEncoding (read-only) Specifies a dictionary key whose
 201         value is the item's certificate revocation list encoding.  You use
 202         this key to get a value of type CFNumberRef that denotes the CRL
 203         encoding (see the CSSM_CRL_ENCODING enum in cssmtype.h). (Items of
 204         class kSecClassCertificate have this attribute.)
 205     @constant kSecAttrKeyCreator Specifies a dictionary key whose value is a
 206         CFDataRef containing a CSSM_GUID structure representing the module ID of
 207         the CSP that owns this key.
 208     @constant kSecAttrIsPrivate Specifies a dictionary key whose value is a
 209         CFBooleanRef indicating whether the raw key material of the key in
 210         question is private.
 211     @constant kSecAttrIsModifiable Specifies a dictionary key whose value is a
 212         CFBooleanRef indicating whether any of the attributes of this key are
 213         modifiable.
 214     @constant kSecAttrStartDate Specifies a dictionary key whose value is a
 215         CFDateRef indicating the earliest date on which this key may be used.
 216         If kSecAttrStartDate is not present, the restriction does not apply.
 217     @constant kSecAttrEndDate Specifies a dictionary key whose value is a
 218         CFDateRef indicating the last date on which this key may be used.
 219         If kSecAttrEndDate is not present, the restriction does not apply.
 220     @constant kSecAttrIsSensitive Specifies a dictionary key whose value
 221         is a CFBooleanRef indicating whether the key in question must be wrapped
 222         with an algorithm other than CSSM_ALGID_NONE.
 223     @constant kSecAttrWasAlwaysSensitive Specifies a dictionary key whose value
 224         is a CFBooleanRef indicating that the key in question has always been
 225         marked as sensitive.
 226     @constant kSecAttrIsExtractable Specifies a dictionary key whose value
 227         is a CFBooleanRef indicating whether the key in question may be wrapped.
 228     @constant kSecAttrWasNeverExtractable Specifies a dictionary key whose value
 229         is a CFBooleanRef indicating that the key in question has never been
 230         marked as extractable.
 231     @constant kSecAttrCanSignRecover Specifies a dictionary key whole value is a
 232         CFBooleanRef indicating whether the key in question can be used to
 233         perform sign recovery.
 234     @constant kSecAttrCanVerifyRecover Specifies a dictionary key whole value is
 235         a CFBooleanRef indicating whether the key in question can be used to
 236         perform verify recovery.
 237     @constant kSecAttrTombstone Specifies a dictionary key whose value is
 238         a CFBooleanRef indicating that the item in question is a tombstone.
 239 */
 240 extern CFTypeRef kSecAttrScriptCode;
 241 extern CFTypeRef kSecAttrAlias;
 242 extern CFTypeRef kSecAttrHasCustomIcon;
 243 extern CFTypeRef kSecAttrVolume;
 244 extern CFTypeRef kSecAttrAddress;
 245 extern CFTypeRef kSecAttrAFPServerSignature;
 246 extern CFTypeRef kSecAttrCRLType;
 247 extern CFTypeRef kSecAttrCRLEncoding;
 248 extern CFTypeRef kSecAttrKeyCreator;
 249 extern CFTypeRef kSecAttrIsPrivate;
 250 extern CFTypeRef kSecAttrIsModifiable;
 251 extern CFTypeRef kSecAttrStartDate;
 252 extern CFTypeRef kSecAttrEndDate;
 253 extern CFTypeRef kSecAttrIsSensitive;
 254 extern CFTypeRef kSecAttrWasAlwaysSensitive;
 255 extern CFTypeRef kSecAttrIsExtractable;
 256 extern CFTypeRef kSecAttrWasNeverExtractable;
 257 extern CFTypeRef kSecAttrCanSignRecover;
 258 extern CFTypeRef kSecAttrCanVerifyRecover;
 259 extern CFTypeRef kSecAttrTombstone;
 260
 261 /*!
 262     @enum Other Constants (Private)
 263     @discussion Predefined constants used to set values in a dictionary.
 264     @constant kSecUseTombstones Specifies a dictionary key whose value is a
 265         CFBooleanRef if present this overrides the default behaviour for when
 266         we make tombstones.  The default being we create tombstones for
 267         synchronizable items unless we are explicitly deleting or updating a
 268         tombstone.  Setting this to false when calling SecItemDelete or
 269         SecItemUpdate will ensure no tombstones are created.  Setting it to
 270         true will ensure we create tombstones even when deleting or updating non
 271         synchronizable items.
 272     @constant kSecUseKeychain Specifies a dictionary key whose value is a
 273         keychain reference. You use this key to specify a value of type
 274         SecKeychainRef that indicates the keychain to which SecItemAdd
 275         will add the provided item(s).
 276     @constant kSecUseKeychainList Specifies a dictionary key whose value is
 277         either an array of keychains to search (CFArrayRef), or a single
 278         keychain (SecKeychainRef). If not provided, the user's default
 279         keychain list is searched. kSecUseKeychainList is ignored if an
 280         explicit kSecUseItemList is also provided.  This key can be used
 281         for the SecItemCopyMatching, SecItemUpdate and SecItemDelete calls.
 282 */
 283 extern CFTypeRef kSecUseTombstones
 284     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 285 #if defined(MULTIPLE_KEYCHAINS)
 286 extern CFTypeRef kSecUseKeychain;
 287 extern CFTypeRef kSecUseKeychainList;
 288 #endif /* !defined(MULTIPLE_KEYCHAINS) */
 289
 290
 291 /*!
 292     @function SecItemCopyDisplayNames
 293     @abstract Returns an array containing unique display names for each of the
 294         certificates, keys, identities, or passwords in the provided items
 295         array.
 296     @param items An array containing items of type SecKeychainItemRef,
 297         SecKeyRef, SecCertificateRef, or SecIdentityRef. All items in the
 298         array should be of the same type.
 299     @param displayNames On return, an array of CFString references containing
 300         unique names for the supplied items. You are responsible for releasing
 301         this array reference by calling the CFRelease function.
 302     @result A result code. See "Security Error Codes" (SecBase.h).
 303     @discussion Use this function to obtain item names which are suitable for
 304         display in a menu or list view. The returned names are guaranteed to
 305         be unique across the set of provided items.
 306 */
 307 OSStatus SecItemCopyDisplayNames(CFArrayRef items, CFArrayRef *displayNames);
 308
 309 /*!
 310     @function SecItemDeleteAll
 311     @abstract Removes all items from the keychain and added root certificates
 312         from the trust store.
 313     @result A result code. See "Security Error Codes" (SecBase.h).
 314 */
 315 OSStatus SecItemDeleteAll(void);
 316
 317 /*
 318     Ensure the escrow keybag has been used to unlock the system keybag before
 319     calling either of these APIs.
 320     The password argument is optional, passing NULL implies no backup password
 321     was set.  We're assuming there will always be a backup keybag, except in
 322     the OTA case where the loaded OTA backup bag will be used.
 323  */
 324 CFDataRef _SecKeychainCopyBackup(CFDataRef backupKeybag, CFDataRef password);
 325 CFDataRef _SecKeychainCopyOTABackup(void);
 326 OSStatus _SecKeychainRestoreBackup(CFDataRef backup, CFDataRef backupKeybag,
 327     CFDataRef password);
 328
 329 OSStatus _SecKeychainBackupSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in, CFDictionaryRef *backup_out);
 330 OSStatus _SecKeychainRestoreSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in);
 331
 332 /* Called by clients to push sync circle and message changes to us.
 333    Requires caller to have the kSecEntitlementKeychainSyncUpdates entitlement. */
 334 bool _SecKeychainSyncUpdate(CFDictionaryRef updates, CFErrorRef *error);
 335
 336 /* Returns an OSStatus value for the given CFErrorRef, returns errSecInternal if the domain of the providied error is not recognized.  Passing NULL returns errSecSuccess (0). */
 337 OSStatus SecErrorGetOSStatus(CFErrorRef error);
 338
 339 __END_DECLS
 340
 341 #endif /* !_SECURITY_SECITEMPRIV_H_ */