libsecurity_keychain/lib/SecItemPriv.h

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