Security/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 <Security/SecTask.h>
  37
  38 #if defined(__cplusplus)
  39 extern "C" {
  40 #endif
  41
  42         /*!
  43          @enum Class Value Constants (Private)
  44          @discussion Predefined item class constants used to get or set values in
  45          a dictionary. The kSecClass constant is the key and its value is one
  46          of the constants defined here.
  47          @constant kSecClassAppleSharePassword Specifies AppleShare password items.
  48          */
  49         extern const CFTypeRef kSecClassAppleSharePassword;
  50
  51         /*!
  52          @enum Attribute Key Constants (Private)
  53          @discussion Predefined item attribute keys used to get or set values in a
  54          dictionary. Not all attributes apply to each item class. The table
  55          below lists the currently defined attributes for each item class:
  56
  57          kSecClassGenericPassword item attributes:
  58          kSecAttrAccessGroup
  59          kSecAttrCreationDate
  60          kSecAttrModificationDate
  61          kSecAttrDescription
  62          kSecAttrComment
  63          kSecAttrCreator
  64          kSecAttrType
  65          kSecAttrScriptCode (private)
  66          kSecAttrLabel
  67          kSecAttrAlias (private)
  68          kSecAttrIsInvisible
  69          kSecAttrIsNegative
  70          kSecAttrHasCustomIcon (private)
  71          kSecAttrProtected (private)
  72          kSecAttrAccount
  73          kSecAttrService
  74          kSecAttrGeneric
  75
  76          kSecClassInternetPassword item attributes:
  77          kSecAttrAccessGroup
  78          kSecAttrCreationDate
  79          kSecAttrModificationDate
  80          kSecAttrDescription
  81          kSecAttrComment
  82          kSecAttrCreator
  83          kSecAttrType
  84          kSecAttrScriptCode (private)
  85          kSecAttrLabel
  86          kSecAttrAlias (private)
  87          kSecAttrIsInvisible
  88          kSecAttrIsNegative
  89          kSecAttrHasCustomIcon (private)
  90          kSecAttrProtected (private)
  91          kSecAttrAccount
  92          kSecAttrSecurityDomain
  93          kSecAttrServer
  94          kSecAttrProtocol
  95          kSecAttrAuthenticationType
  96          kSecAttrPort
  97          kSecAttrPath
  98
  99          kSecClassAppleSharePassword item attributes:
 100          kSecAttrAccessGroup
 101          kSecAttrCreationDate
 102          kSecAttrModificationDate
 103          kSecAttrDescription
 104          kSecAttrComment
 105          kSecAttrCreator
 106          kSecAttrType
 107          kSecAttrScriptCode (private)
 108          kSecAttrLabel
 109          kSecAttrAlias (private)
 110          kSecAttrIsInvisible
 111          kSecAttrIsNegative
 112          kSecAttrHasCustomIcon (private)
 113          kSecAttrProtected (private)
 114          kSecAttrAccount
 115          kSecAttrVolume
 116          kSecAttrAddress
 117          kSecAttrAFPServerSignature
 118
 119          kSecClassCertificate item attributes:
 120          kSecAttrAccessGroup
 121          kSecAttrCertificateType
 122          kSecAttrCertificateEncoding
 123          kSecAttrLabel
 124          kSecAttrAlias (private)
 125          kSecAttrSubject
 126          kSecAttrIssuer
 127          kSecAttrSerialNumber
 128          kSecAttrSubjectKeyID
 129          kSecAttrPublicKeyHash
 130
 131          kSecClassKey item attributes:
 132          kSecAttrAccessGroup
 133          kSecAttrKeyClass
 134          kSecAttrLabel
 135          kSecAttrAlias (private)
 136          kSecAttrApplicationLabel
 137          kSecAttrIsPermanent
 138          kSecAttrIsPrivate (private)
 139          kSecAttrIsModifiable (private)
 140          kSecAttrApplicationTag
 141          kSecAttrKeyCreator (private)
 142          kSecAttrKeyType
 143          kSecAttrKeySizeInBits
 144          kSecAttrEffectiveKeySize
 145          kSecAttrStartDate (private)
 146          kSecAttrEndDate (private)
 147          kSecAttrIsSensitive (private)
 148          kSecAttrWasAlwaysSensitive (private)
 149          kSecAttrIsExtractable (private)
 150          kSecAttrWasNeverExtractable (private)
 151          kSecAttrCanEncrypt
 152          kSecAttrCanDecrypt
 153          kSecAttrCanDerive
 154          kSecAttrCanSign
 155          kSecAttrCanVerify
 156          kSecAttrCanSignRecover (private)
 157          kSecAttrCanVerifyRecover (private)
 158          kSecAttrCanWrap
 159          kSecAttrCanUnwrap
 160
 161          kSecClassIdentity item attributes:
 162          Since an identity is the combination of a private key and a
 163          certificate, this class shares attributes of both kSecClassKey and
 164          kSecClassCertificate.
 165
 166          @constant kSecAttrScriptCode Specifies a dictionary key whose value is the
 167          item's script code attribute. You use this tag to set or get a value
 168          of type CFNumberRef that represents a script code for this item's
 169          strings. (Note: use of this attribute is deprecated; string attributes
 170          should always be stored in UTF-8 encoding. This is currently private
 171          for use by syncing; new code should not ever access this attribute.)
 172          @constant kSecAttrAlias Specifies a dictionary key whose value is the
 173          item's alias. You use this key to get or set a value of type CFDataRef
 174          which represents an alias. For certificate items, the alias is either
 175          a single email address, an array of email addresses, or the common
 176          name of the certificate if it does not contain any email address.
 177          (Items of class kSecClassCertificate have this attribute.)
 178          @constant kSecAttrHasCustomIcon Specifies a dictionary key whose value is the
 179          item's custom icon attribute. You use this tag to set or get a value
 180          of type CFBooleanRef that indicates whether the item should have an
 181          application-specific icon. (Note: use of this attribute is deprecated;
 182          custom item icons are not supported in Mac OS X. This is currently
 183          private for use by syncing; new code should not use this attribute.)
 184          @constant kSecAttrVolume Specifies a dictionary key whose value is the
 185          item's volume attribute. You use this key to set or get a CFStringRef
 186          value that represents an AppleShare volume name. (Items of class
 187          kSecClassAppleSharePassword have this attribute.)
 188          @constant kSecAttrAddress Specifies a dictionary key whose value is the
 189          item's address attribute. You use this key to set or get a CFStringRef
 190          value that contains the AppleTalk zone name, or the IP or domain name
 191          that represents the server address. (Items of class
 192          kSecClassAppleSharePassword have this attribute.)
 193          @constant kSecAttrAFPServerSignature Specifies a dictionary key whose value
 194          is the item's AFP server signature attribute. You use this key to set
 195          or get a CFDataRef value containing 16 bytes that represents the
 196          server's signature block. (Items of class kSecClassAppleSharePassword
 197          have this attribute.)
 198          @constant kSecAttrCRLType (read-only) Specifies a dictionary key whose
 199          value is the item's certificate revocation list type. You use this
 200          key to get a value of type CFNumberRef that denotes the CRL type (see
 201          the CSSM_CRL_TYPE enum in cssmtype.h). (Items of class
 202          kSecClassCertificate have this attribute.)
 203          @constant kSecAttrCRLEncoding (read-only) Specifies a dictionary key whose
 204          value is the item's certificate revocation list encoding.  You use
 205          this key to get a value of type CFNumberRef that denotes the CRL
 206          encoding (see the CSSM_CRL_ENCODING enum in cssmtype.h). (Items of
 207          class kSecClassCertificate have this attribute.)
 208          @constant kSecAttrKeyCreator Specifies a dictionary key whose value is a
 209          CFDataRef containing a CSSM_GUID structure representing the module ID of
 210          the CSP that owns this key.
 211          @constant kSecAttrIsPrivate Specifies a dictionary key whose value is a
 212          CFBooleanRef indicating whether the raw key material of the key in
 213          question is private.
 214          @constant kSecAttrIsModifiable Specifies a dictionary key whose value is a
 215          CFBooleanRef indicating whether any of the attributes of this key are
 216          modifiable.
 217          @constant kSecAttrStartDate Specifies a dictionary key whose value is a
 218          CFDateRef indicating the earliest date on which this key may be used.
 219          If kSecAttrStartDate is not present, the restriction does not apply.
 220          @constant kSecAttrEndDate Specifies a dictionary key whose value is a
 221          CFDateRef indicating the last date on which this key may be used.
 222          If kSecAttrEndDate is not present, the restriction does not apply.
 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 kSecAttrWasNeverExtractable Specifies a dictionary key whose value
 227          is a CFBooleanRef indicating that the key in question has never been
 228          marked as extractable.
 229          @constant kSecAttrCanSignRecover Specifies a dictionary key whose value is a
 230          CFBooleanRef indicating whether the key in question can be used to
 231          perform sign recovery.
 232          @constant kSecAttrCanVerifyRecover Specifies a dictionary key whose value is
 233          a CFBooleanRef indicating whether the key in question can be used to
 234          perform verify recovery.
 235          @constant kSecAttrTombstone Specifies a dictionary key whose value is
 236          a CFBooleanRef indicating that the item in question is a tombstone.
 237          @constant kSecCredentialReference Specifies a CFDataRef containing CoreAuthentication
 238          reference handle to be used when authorizing access to the item.
 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 kSecAttrWasAlwaysSensitive;
 254         extern CFTypeRef kSecAttrWasNeverExtractable;
 255         extern CFTypeRef kSecAttrCanSignRecover;
 256         extern CFTypeRef kSecAttrCanVerifyRecover;
 257         extern CFTypeRef kSecAttrTombstone;
 258         extern CFTypeRef kSecCredentialReference;
 259
 260         /*!
 261          @function SecItemCopyDisplayNames
 262          @abstract Returns an array containing unique display names for each of the
 263          certificates, keys, identities, or passwords in the provided items
 264          array.
 265          @param items An array containing items of type SecKeychainItemRef,
 266          SecKeyRef, SecCertificateRef, or SecIdentityRef. All items in the
 267          array should be of the same type.
 268          @param displayNames On return, an array of CFString references containing
 269          unique names for the supplied items. You are responsible for releasing
 270          this array reference by calling the CFRelease function.
 271          @result A result code. See "Security Error Codes" (SecBase.h).
 272          @discussion Use this function to obtain item names which are suitable for
 273          display in a menu or list view. The returned names are guaranteed to
 274          be unique across the set of provided items.
 275          */
 276         OSStatus SecItemCopyDisplayNames(CFArrayRef items, CFArrayRef *displayNames);
 277
 278         /*!
 279          @function SecItemDeleteAll
 280          @abstract Removes all items from the keychain and added root certificates
 281          from the trust store.
 282          @result A result code. See "Security Error Codes" (SecBase.h).
 283          */
 284         OSStatus SecItemDeleteAll(void);
 285
 286 /* Called by clients to push sync circle and message changes to us.
 287  Requires caller to have the kSecEntitlementKeychainSyncUpdates entitlement. */
 288 CFArrayRef _SecKeychainSyncUpdateKeyParameter(CFDictionaryRef updates, CFErrorRef *error);
 289 CFArrayRef _SecKeychainSyncUpdateCircle(CFDictionaryRef updates, CFErrorRef *error);
 290 CFArrayRef _SecKeychainSyncUpdateMessage(CFDictionaryRef updates, CFErrorRef *error);
 291
 292 CFDataRef _SecItemGetPersistentReference(CFTypeRef raw_item);
 293
 294 bool _SecKeychainBackupSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in, CFDictionaryRef *backup_out);
 295 bool _SecKeychainRestoreSyncable(CFDataRef keybag, CFDataRef password, CFDictionaryRef backup_in);
 296
 297 #if defined(__cplusplus)
 298 }
 299 #endif
 300
 301 #endif /* !_SECURITY_SECITEMPRIV_H_ */