sec/Security/SecItemPriv.h

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