2 * Copyright (c) 2006-2014 Apple Inc. All Rights Reserved.
4 * @APPLE_LICENSE_HEADER_START@
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
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.
21 * @APPLE_LICENSE_HEADER_END@
26 SecItem defines CoreFoundation-based constants and functions for
27 access to Security items (certificates, keys, identities, and
31 #ifndef _SECURITY_SECITEM_H_
32 #define _SECURITY_SECITEM_H_
34 #include <CoreFoundation/CFNumber.h>
35 #include <CoreFoundation/CFArray.h>
36 #include <CoreFoundation/CFDictionary.h>
38 #if defined(__cplusplus)
43 @enum Class Key Constant
44 @discussion Predefined key constant used to get or set item class values in
45 a dictionary. Its value is one of the constants defined in the Value
46 Constants for kSecClass.
47 @constant kSecClass Specifies a dictionary key whose value is the item's
48 class code. You use this key to get or set a value of type CFTypeRef
49 that contains the item class code.
51 extern const CFTypeRef kSecClass
52 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
55 @enum Class Value Constants
56 @discussion Predefined item class constants used to get or set values in
57 a dictionary. The kSecClass constant is the key and its value is one
58 of the constants defined here. Note: on Mac OS X 10.6, only items
59 of class kSecClassInternetPassword are supported.
60 @constant kSecClassInternetPassword Specifies Internet password items.
61 @constant kSecClassGenericPassword Specifies generic password items.
62 @constant kSecClassCertificate Specifies certificate items.
63 @constant kSecClassKey Specifies key items.
64 @constant kSecClassIdentity Specifies identity items.
66 extern const CFTypeRef kSecClassInternetPassword
67 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
68 extern const CFTypeRef kSecClassGenericPassword
69 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
70 extern const CFTypeRef kSecClassCertificate
71 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
72 extern const CFTypeRef kSecClassKey
73 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
74 extern const CFTypeRef kSecClassIdentity
75 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
78 @enum Attribute Key Constants
79 @discussion Predefined item attribute keys used to get or set values in a
80 dictionary. Not all attributes apply to each item class. The table
81 below lists the currently defined attributes for each item class:
83 kSecClassGenericPassword item attributes:
84 kSecAttrAccess (OS X only)
86 kSecAttrAccessGroup (iOS; also OS X if kSecAttrSynchronizable specified)
87 kSecAttrAccessible (iOS; also OS X if kSecAttrSynchronizable specified)
89 kSecAttrModificationDate
101 kSecClassInternetPassword item attributes:
102 kSecAttrAccess (OS X only)
103 kSecAttrAccessGroup (iOS; also OS X if kSecAttrSynchronizable specified)
104 kSecAttrAccessible (iOS; also OS X if kSecAttrSynchronizable specified)
106 kSecAttrModificationDate
115 kSecAttrSecurityDomain
118 kSecAttrAuthenticationType
122 kSecClassCertificate item attributes:
123 kSecAttrCertificateType
124 kSecAttrCertificateEncoding
130 kSecAttrPublicKeyHash
132 kSecClassKey item attributes:
133 kSecAttrAccess (OS X only)
134 kSecAttrAccessGroup (iOS only)
135 kSecAttrAccessible (iOS only)
138 kSecAttrApplicationLabel
140 kSecAttrApplicationTag
145 kSecAttrKeySizeInBits
146 kSecAttrEffectiveKeySize
155 Note that the attributes kSecAttrCan* describe attributes of the
156 key itself at relatively high level. Some of these attributes are
157 mathematical -- for example, a DSA key cannot encrypt. Others are
158 key-level policy issues -- for example, it is good cryptographic
159 hygiene to use an RSA key either for encryption or signing but not
160 both. Compare these to the certificate-level policy values in
163 kSecClassIdentity item attributes:
164 Since an identity is the combination of a private key and a
165 certificate, this class shares attributes of both kSecClassKey and
166 kSecClassCertificate.
168 @constant kSecAttrAccessible Specifies a dictionary key whose value
169 indicates when your application needs access to an item's data. You
170 should choose the most restrictive option that meets your application's
171 needs to allow the system to protect that item in the best way possible.
172 See the "kSecAttrAccessible Value Constants" section for a list of
173 values which can be specified.
174 IMPORTANT: This attribute is currently not supported for OS X keychain
175 items, unless the kSecAttrSynchronizable attribute is also present. If
176 both attributes are specified on either OS X or iOS, the value for the
177 kSecAttrAccessible key may only be one whose name does not end with
178 "ThisDeviceOnly", as those cannot sync to another device.
180 @constant kSecAttrAccessControl Specifies a dictionary key whose value
181 is SecAccessControl instance which contains access control conditions
183 IMPORTANT: This attribute is mutually exclusive with kSecAttrAccess
186 @constant kSecAttrAccess Specifies a dictionary key whose value
187 is a SecAccessRef describing the access control settings for this item.
188 This key is available on OS X only.
190 @constant kSecAttrAccessGroup Specifies a dictionary key whose value is
191 a CFStringRef indicating which access group a item is in. The access
192 groups that a particular application has membership in are determined by
193 two entitlements for that application. The application-identifier
194 entitlement contains the application's single access group, unless
195 there is a keychain-access-groups entitlement present. The latter
196 has as its value a list of access groups; the first item in this list
197 is the default access group. Unless a specific access group is provided
198 as the value of kSecAttrAccessGroup when SecItemAdd is called, new items
199 are created in the application's default access group. Specifying this
200 attribute in SecItemCopyMatching, SecItemUpdate, or SecItemDelete calls
201 limits the search to the specified access group (of which the calling
202 application must be a member to obtain matching results.) To share
203 keychain items between multiple applications, each application must have
204 a common group listed in its keychain-access-groups entitlement, and each
205 must specify this shared access group name as the value for the
206 kSecAttrAccessGroup key in the dictionary passed to SecItem functions.
208 @constant kSecAttrSynchronizable Specifies a dictionary key whose value is
209 a CFBooleanRef indicating whether the item in question can be synchronized.
210 To add a new item which can be synced to other devices, or to obtain
211 synchronizable results from a query, supply this key with a value of
212 kCFBooleanTrue. If the key is not supplied, or has a value of
213 kCFBooleanFalse, then no synchronizable items will be added or returned.
214 A predefined value, kSecAttrSynchronizableAny, may be provided instead of
215 kCFBooleanTrue if both synchronizable and non-synchronizable results are
218 IMPORTANT: Specifying the kSecAttrSynchronizable key has several caveats:
220 - Updating or deleting items using the kSecAttrSynchronizable key will
221 affect all copies of the item, not just the one on your local device.
222 Be sure that it makes sense to use the same password on all devices
223 before deciding to make a password synchronizable.
224 - Only password items can currently be synchronized. Keychain syncing
225 is not supported for certificates or cryptographic keys.
226 - Items stored or obtained using the kSecAttrSynchronizable key cannot
227 specify SecAccessRef-based access control with kSecAttrAccess. If a
228 password is intended to be shared between multiple applications, the
229 kSecAttrAccessGroup key must be specified, and each application
230 using this password must have a 'keychain-access-groups' entitlement
231 with the specified access group value.
232 - Items stored or obtained using the kSecAttrSynchronizable key may
233 not also specify a kSecAttrAccessible value which is incompatible
234 with syncing (namely, those whose names end with "ThisDeviceOnly".)
235 - Items stored or obtained using the kSecAttrSynchronizable key cannot
236 be specified by reference. You must pass kSecReturnAttributes and/or
237 kSecReturnData to retrieve results; kSecReturnRef is currently not
238 supported for synchronizable items.
239 - Persistent references to synchronizable items should be avoided;
240 while they may work locally, they cannot be moved between devices,
241 and may not resolve if the item is modified on some other device.
242 - When specifying a query that uses the kSecAttrSynchronizable key,
243 search keys are limited to the item's class and attributes.
244 The only search constant which may be used is kSecMatchLimit; other
245 constants using the kSecMatch prefix are not supported at this time.
247 @constant kSecAttrSynchronizableAny Specifies that both synchronizable and
248 non-synchronizable results should be returned from this query. This may be
249 used as a value for the kSecAttrSynchronizable dictionary key in a call to
250 SecItemCopyMatching, SecItemUpdate, or SecItemDelete.
252 @constant kSecAttrCreationDate (read-only) Specifies a dictionary key whose
253 value is the item's creation date. You use this key to get a value
254 of type CFDateRef that represents the date the item was created.
255 @constant kSecAttrModificationDate (read-only) Specifies a dictionary key
256 whose value is the item's modification date. You use this key to get
257 a value of type CFDateRef that represents the last time the item was
259 @constant kSecAttrDescription Specifies a dictionary key whose value is
260 the item's description attribute. You use this key to set or get a
261 value of type CFStringRef that represents a user-visible string
262 describing this particular kind of item (e.g., "disk image password").
263 @constant kSecAttrComment Specifies a dictionary key whose value is the
264 item's comment attribute. You use this key to set or get a value of
265 type CFStringRef containing the user-editable comment for this item.
266 @constant kSecAttrCreator Specifies a dictionary key whose value is the
267 item's creator attribute. You use this key to set or get a value of
268 type CFNumberRef that represents the item's creator. This number is
269 the unsigned integer representation of a four-character code (e.g.,
271 @constant kSecAttrType Specifies a dictionary key whose value is the item's
272 type attribute. You use this key to set or get a value of type
273 CFNumberRef that represents the item's type. This number is the
274 unsigned integer representation of a four-character code (e.g.,
276 @constant kSecAttrLabel Specifies a dictionary key whose value is the
277 item's label attribute. You use this key to set or get a value of
278 type CFStringRef containing the user-visible label for this item.
279 @constant kSecAttrIsInvisible Specifies a dictionary key whose value is the
280 item's invisible attribute. You use this key to set or get a value
281 of type CFBooleanRef that indicates whether the item is invisible
282 (i.e., should not be displayed.)
283 @constant kSecAttrIsNegative Specifies a dictionary key whose value is the
284 item's negative attribute. You use this key to set or get a value of
285 type CFBooleanRef that indicates whether there is a valid password
286 associated with this keychain item. This is useful if your application
287 doesn't want a password for some particular service to be stored in
288 the keychain, but prefers that it always be entered by the user.
289 @constant kSecAttrAccount Specifies a dictionary key whose value is the
290 item's account attribute. You use this key to set or get a CFStringRef
291 that contains an account name. (Items of class
292 kSecClassGenericPassword, kSecClassInternetPassword have this
294 @constant kSecAttrService Specifies a dictionary key whose value is the
295 item's service attribute. You use this key to set or get a CFStringRef
296 that represents the service associated with this item. (Items of class
297 kSecClassGenericPassword have this attribute.)
298 @constant kSecAttrGeneric Specifies a dictionary key whose value is the
299 item's generic attribute. You use this key to set or get a value of
300 CFDataRef that contains a user-defined attribute. (Items of class
301 kSecClassGenericPassword have this attribute.)
302 @constant kSecAttrSecurityDomain Specifies a dictionary key whose value
303 is the item's security domain attribute. You use this key to set or
304 get a CFStringRef value that represents the Internet security domain.
305 (Items of class kSecClassInternetPassword have this attribute.)
306 @constant kSecAttrServer Specifies a dictionary key whose value is the
307 item's server attribute. You use this key to set or get a value of
308 type CFStringRef that contains the server's domain name or IP address.
309 (Items of class kSecClassInternetPassword have this attribute.)
310 @constant kSecAttrProtocol Specifies a dictionary key whose value is the
311 item's protocol attribute. You use this key to set or get a value of
312 type CFNumberRef that denotes the protocol for this item (see the
313 SecProtocolType enum in SecKeychainItem.h). (Items of class
314 kSecClassInternetPassword have this attribute.)
315 @constant kSecAttrAuthenticationType Specifies a dictionary key whose value
316 is the item's authentication type attribute. You use this key to set
317 or get a value of type CFNumberRef that denotes the authentication
318 scheme for this item (see the kSecAttrAuthenticationType value
320 @constant kSecAttrPort Specifies a dictionary key whose value is the item's
321 port attribute. You use this key to set or get a CFNumberRef value
322 that represents an Internet port number. (Items of class
323 kSecClassInternetPassword have this attribute.)
324 @constant kSecAttrPath Specifies a dictionary key whose value is the item's
325 path attribute, typically this is the path component of the URL. You use
326 this key to set or get a CFStringRef value that represents a path. (Items
327 of class kSecClassInternetPassword have this attribute.)
328 @constant kSecAttrSubject (read-only) Specifies a dictionary key whose
329 value is the item's subject. You use this key to get a value of type
330 CFDataRef that contains the X.500 subject name of a certificate.
331 (Items of class kSecClassCertificate have this attribute.)
332 @constant kSecAttrIssuer (read-only) Specifies a dictionary key whose value
333 is the item's issuer. You use this key to get a value of type
334 CFDataRef that contains the X.500 issuer name of a certificate. (Items
335 of class kSecClassCertificate have this attribute.)
336 @constant kSecAttrSerialNumber (read-only) Specifies a dictionary key whose
337 value is the item's serial number. You use this key to get a value
338 of type CFDataRef that contains the serial number data of a
339 certificate. (Items of class kSecClassCertificate have this
341 @constant kSecAttrSubjectKeyID (read-only) Specifies a dictionary key whose
342 value is the item's subject key ID. You use this key to get a value
343 of type CFDataRef that contains the subject key ID of a certificate.
344 (Items of class kSecClassCertificate have this attribute.)
345 @constant kSecAttrPublicKeyHash (read-only) Specifies a dictionary key
346 whose value is the item's public key hash. You use this key to get a
347 value of type CFDataRef that contains the hash of a certificate's
348 public key. (Items of class kSecClassCertificate have this attribute.)
349 @constant kSecAttrCertificateType (read-only) Specifies a dictionary key
350 whose value is the item's certificate type. You use this key to get
351 a value of type CFNumberRef that denotes the certificate type (see the
352 CSSM_CERT_TYPE enum in cssmtype.h). (Items of class
353 kSecClassCertificate have this attribute.)
354 @constant kSecAttrCertificateEncoding (read-only) Specifies a dictionary
355 key whose value is the item's certificate encoding. You use this key
356 to get a value of type CFNumberRef that denotes the certificate
357 encoding (see the CSSM_CERT_ENCODING enum in cssmtype.h). (Items of
358 class kSecClassCertificate have this attribute.)
359 @constant kSecAttrKeyClass (read only) Specifies a dictionary key whose
360 value is one of kSecAttrKeyClassPublic, kSecAttrKeyClassPrivate or
361 kSecAttrKeyClassSymmetric.
362 @constant kSecAttrApplicationLabel Specifies a dictionary key whose value
363 is the key's application label attribute. This is different from the
364 kSecAttrLabel (which is intended to be human-readable). This attribute
365 is used to look up a key programmatically; in particular, for keys of
366 class kSecAttrKeyClassPublic and kSecAttrKeyClassPrivate, the value of
367 this attribute is the hash of the public key. This item is a type of CFDataRef.
368 Legacy keys may contain a UUID in this field as a CFStringRef.
369 @constant kSecAttrIsPermanent Specifies a dictionary key whose value is a
370 CFBooleanRef indicating whether the key in question will be stored
372 @constant kSecAttrIsSensitive Specifies a dictionary key whose value is a
373 CFBooleanRef indicating that the key in question can only be exported
374 in a wrapped (encrypted) format.
375 @constant kSecAttrIsExtractable Specifies a dictionary key whose value is a
376 CFBooleanRef indicating whether the key in question can be exported from
377 its keychain container.
378 @constant kSecAttrApplicationTag Specifies a dictionary key whose value is a
379 CFDataRef containing private tag data.
380 @constant kSecAttrKeyType Specifies a dictionary key whose value is a
381 CFNumberRef indicating the algorithm associated with this key (see the
382 CSSM_ALGORITHMS enum in cssmtype.h).
383 @constant kSecAttrPRF Specifies a dictionary key whose value is the PRF
384 (pseudo-random function) for this key (see "kSecAttrPRF Value Constants".)
385 @constant kSecAttrSalt Specifies a dictionary key whose value is a
386 CFData containing the salt to use for this key.
387 @constant kSecAttrRounds Specifies a dictionary key whose value is the
388 number of rounds for the pseudo-random function specified by kSecAttrPRF.
389 @constant kSecAttrKeySizeInBits Specifies a dictionary key whose value
390 is a CFNumberRef indicating the number of bits in this key.
391 @constant kSecAttrEffectiveKeySize Specifies a dictionary key whose value
392 is a CFNumberRef indicating the effective number of bits in this key.
393 For example, a DES key has a kSecAttrKeySizeInBits of 64, but a
394 kSecAttrEffectiveKeySize of 56 bits.
395 @constant kSecAttrCanEncrypt Specifies a dictionary key whole value is a
396 CFBooleanRef indicating whether the key in question can be used to
398 @constant kSecAttrCanDecrypt Specifies a dictionary key whole value is a
399 CFBooleanRef indicating whether the key in question can be used to
401 @constant kSecAttrCanDerive Specifies a dictionary key whole value is a
402 CFBooleanRef indicating whether the key in question can be used to
404 @constant kSecAttrCanSign Specifies a dictionary key whole value is a
405 CFBooleanRef indicating whether the key in question can be used to
406 create a digital signature.
407 @constant kSecAttrCanVerify Specifies a dictionary key whole value is a
408 CFBooleanRef indicating whether the key in question can be used to
409 verify a digital signature.
410 @constant kSecAttrCanWrap Specifies a dictionary key whole value is a
411 CFBooleanRef indicating whether the key in question can be used to
413 @constant kSecAttrCanUnwrap Specifies a dictionary key whole value is a
414 CFBooleanRef indicating whether the key in question can be used to
417 extern const CFTypeRef kSecAttrAccessible
418 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
419 extern const CFTypeRef kSecAttrAccess
420 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
421 extern CFTypeRef kSecAttrAccessControl
422 __OSX_AVAILABLE_STARTING(__MAC_10_10
, __IPHONE_8_0
);
423 extern const CFTypeRef kSecAttrAccessGroup
424 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_3_0
);
425 extern const CFTypeRef kSecAttrSynchronizable
426 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_7_0
);
427 extern const CFTypeRef kSecAttrSynchronizableAny
428 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_7_0
);
429 extern const CFTypeRef kSecAttrCreationDate
430 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
431 extern const CFTypeRef kSecAttrModificationDate
432 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
433 extern const CFTypeRef kSecAttrDescription
434 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
435 extern const CFTypeRef kSecAttrComment
436 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
437 extern const CFTypeRef kSecAttrCreator
438 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
439 extern const CFTypeRef kSecAttrType
440 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
441 extern const CFTypeRef kSecAttrLabel
442 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
443 extern const CFTypeRef kSecAttrIsInvisible
444 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
445 extern const CFTypeRef kSecAttrIsNegative
446 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
447 extern const CFTypeRef kSecAttrAccount
448 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
449 extern const CFTypeRef kSecAttrService
450 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
451 extern const CFTypeRef kSecAttrGeneric
452 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
453 extern const CFTypeRef kSecAttrSecurityDomain
454 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
455 extern const CFTypeRef kSecAttrServer
456 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
457 extern const CFTypeRef kSecAttrProtocol
458 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
459 extern const CFTypeRef kSecAttrAuthenticationType
460 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
461 extern const CFTypeRef kSecAttrPort
462 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
463 extern const CFTypeRef kSecAttrPath
464 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
465 extern const CFTypeRef kSecAttrSubject
466 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
467 extern const CFTypeRef kSecAttrIssuer
468 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
469 extern const CFTypeRef kSecAttrSerialNumber
470 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
471 extern const CFTypeRef kSecAttrSubjectKeyID
472 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
473 extern const CFTypeRef kSecAttrPublicKeyHash
474 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
475 extern const CFTypeRef kSecAttrCertificateType
476 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
477 extern const CFTypeRef kSecAttrCertificateEncoding
478 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
479 extern const CFTypeRef kSecAttrKeyClass
480 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
481 extern const CFTypeRef kSecAttrApplicationLabel
482 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
483 extern const CFTypeRef kSecAttrIsPermanent
484 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
485 extern const CFTypeRef kSecAttrIsSensitive
486 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
487 extern const CFTypeRef kSecAttrIsExtractable
488 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
489 extern const CFTypeRef kSecAttrApplicationTag
490 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
491 extern const CFTypeRef kSecAttrKeyType
492 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
493 extern const CFTypeRef kSecAttrPRF
494 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
495 extern const CFTypeRef kSecAttrSalt
496 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
497 extern const CFTypeRef kSecAttrRounds
498 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
499 extern const CFTypeRef kSecAttrKeySizeInBits
500 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
501 extern const CFTypeRef kSecAttrEffectiveKeySize
502 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
503 extern const CFTypeRef kSecAttrCanEncrypt
504 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
505 extern const CFTypeRef kSecAttrCanDecrypt
506 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
507 extern const CFTypeRef kSecAttrCanDerive
508 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
509 extern const CFTypeRef kSecAttrCanSign
510 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
511 extern const CFTypeRef kSecAttrCanVerify
512 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
513 extern const CFTypeRef kSecAttrCanWrap
514 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
515 extern const CFTypeRef kSecAttrCanUnwrap
516 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
519 @enum kSecAttrAccessible Value Constants
520 @discussion Predefined item attribute constants used to get or set values
521 in a dictionary. The kSecAttrAccessible constant is the key and its
522 value is one of the constants defined here.
523 When asking SecItemCopyMatching to return the item's data, the error
524 errSecInteractionNotAllowed will be returned if the item's data is not
525 available until a device unlock occurs.
526 @constant kSecAttrAccessibleWhenUnlocked Item data can only be accessed
527 while the device is unlocked. This is recommended for items that only
528 need be accesible while the application is in the foreground. Items
529 with this attribute will migrate to a new device when using encrypted
531 @constant kSecAttrAccessibleAfterFirstUnlock Item data can only be
532 accessed once the device has been unlocked after a restart. This is
533 recommended for items that need to be accesible by background
534 applications. Items with this attribute will migrate to a new device
535 when using encrypted backups.
536 @constant kSecAttrAccessibleAlways Item data can always be accessed
537 regardless of the lock state of the device. This is not recommended
538 for anything except system use. Items with this attribute will migrate
539 to a new device when using encrypted backups.
540 @constant kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly Item data can
541 only be accessed while the device is unlocked. This is recommended for
542 items that only need to be accessible while the application is in the
543 foreground and requires a passcode to be set on the device. Items with
544 this attribute will never migrate to a new device, so after a backup
545 is restored to a new device, these items will be missing. This
546 attribute will not be available on devices without a passcode. Disabling
547 the device passcode will cause all previously protected items to
549 @constant kSecAttrAccessibleWhenUnlockedThisDeviceOnly Item data can only
550 be accessed while the device is unlocked. This is recommended for items
551 that only need be accesible while the application is in the foreground.
552 Items with this attribute will never migrate to a new device, so after
553 a backup is restored to a new device, these items will be missing.
554 @constant kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly Item data can
555 only be accessed once the device has been unlocked after a restart.
556 This is recommended for items that need to be accessible by background
557 applications. Items with this attribute will never migrate to a new
558 device, so after a backup is restored to a new device these items will
560 @constant kSecAttrAccessibleAlwaysThisDeviceOnly Item data can always
561 be accessed regardless of the lock state of the device. This option
562 is not recommended for anything except system use. Items with this
563 attribute will never migrate to a new device, so after a backup is
564 restored to a new device, these items will be missing.
566 extern const CFTypeRef kSecAttrAccessibleWhenUnlocked
567 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
568 extern const CFTypeRef kSecAttrAccessibleAfterFirstUnlock
569 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
570 extern const CFTypeRef kSecAttrAccessibleAlways
571 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
572 extern CFTypeRef kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly
573 __OSX_AVAILABLE_STARTING(__MAC_10_10
, __IPHONE_8_0
);
574 extern const CFTypeRef kSecAttrAccessibleWhenUnlockedThisDeviceOnly
575 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
576 extern const CFTypeRef kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
577 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
578 extern const CFTypeRef kSecAttrAccessibleAlwaysThisDeviceOnly
579 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
582 @enum kSecAttrProtocol Value Constants
583 @discussion Predefined item attribute constants used to get or set values
584 in a dictionary. The kSecAttrProtocol constant is the key and its
585 value is one of the constants defined here.
586 @constant kSecAttrProtocolFTP
587 @constant kSecAttrProtocolFTPAccount
588 @constant kSecAttrProtocolHTTP
589 @constant kSecAttrProtocolIRC
590 @constant kSecAttrProtocolNNTP
591 @constant kSecAttrProtocolPOP3
592 @constant kSecAttrProtocolSMTP
593 @constant kSecAttrProtocolSOCKS
594 @constant kSecAttrProtocolIMAP
595 @constant kSecAttrProtocolLDAP
596 @constant kSecAttrProtocolAppleTalk
597 @constant kSecAttrProtocolAFP
598 @constant kSecAttrProtocolTelnet
599 @constant kSecAttrProtocolSSH
600 @constant kSecAttrProtocolFTPS
601 @constant kSecAttrProtocolHTTPS
602 @constant kSecAttrProtocolHTTPProxy
603 @constant kSecAttrProtocolHTTPSProxy
604 @constant kSecAttrProtocolFTPProxy
605 @constant kSecAttrProtocolSMB
606 @constant kSecAttrProtocolRTSP
607 @constant kSecAttrProtocolRTSPProxy
608 @constant kSecAttrProtocolDAAP
609 @constant kSecAttrProtocolEPPC
610 @constant kSecAttrProtocolIPP
611 @constant kSecAttrProtocolNNTPS
612 @constant kSecAttrProtocolLDAPS
613 @constant kSecAttrProtocolTelnetS
614 @constant kSecAttrProtocolIMAPS
615 @constant kSecAttrProtocolIRCS
616 @constant kSecAttrProtocolPOP3S
618 extern const CFTypeRef kSecAttrProtocolFTP
619 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
620 extern const CFTypeRef kSecAttrProtocolFTPAccount
621 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
622 extern const CFTypeRef kSecAttrProtocolHTTP
623 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
624 extern const CFTypeRef kSecAttrProtocolIRC
625 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
626 extern const CFTypeRef kSecAttrProtocolNNTP
627 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
628 extern const CFTypeRef kSecAttrProtocolPOP3
629 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
630 extern const CFTypeRef kSecAttrProtocolSMTP
631 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
632 extern const CFTypeRef kSecAttrProtocolSOCKS
633 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
634 extern const CFTypeRef kSecAttrProtocolIMAP
635 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
636 extern const CFTypeRef kSecAttrProtocolLDAP
637 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
638 extern const CFTypeRef kSecAttrProtocolAppleTalk
639 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
640 extern const CFTypeRef kSecAttrProtocolAFP
641 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
642 extern const CFTypeRef kSecAttrProtocolTelnet
643 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
644 extern const CFTypeRef kSecAttrProtocolSSH
645 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
646 extern const CFTypeRef kSecAttrProtocolFTPS
647 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
648 extern const CFTypeRef kSecAttrProtocolHTTPS
649 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
650 extern const CFTypeRef kSecAttrProtocolHTTPProxy
651 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
652 extern const CFTypeRef kSecAttrProtocolHTTPSProxy
653 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
654 extern const CFTypeRef kSecAttrProtocolFTPProxy
655 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
656 extern const CFTypeRef kSecAttrProtocolSMB
657 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
658 extern const CFTypeRef kSecAttrProtocolRTSP
659 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
660 extern const CFTypeRef kSecAttrProtocolRTSPProxy
661 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
662 extern const CFTypeRef kSecAttrProtocolDAAP
663 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
664 extern const CFTypeRef kSecAttrProtocolEPPC
665 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
666 extern const CFTypeRef kSecAttrProtocolIPP
667 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
668 extern const CFTypeRef kSecAttrProtocolNNTPS
669 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
670 extern const CFTypeRef kSecAttrProtocolLDAPS
671 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
672 extern const CFTypeRef kSecAttrProtocolTelnetS
673 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
674 extern const CFTypeRef kSecAttrProtocolIMAPS
675 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
676 extern const CFTypeRef kSecAttrProtocolIRCS
677 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
678 extern const CFTypeRef kSecAttrProtocolPOP3S
679 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
682 @enum kSecAttrAuthenticationType Value Constants
683 @discussion Predefined item attribute constants used to get or set values
684 in a dictionary. The kSecAttrAuthenticationType constant is the key
685 and its value is one of the constants defined here.
686 @constant kSecAttrAuthenticationTypeNTLM
687 @constant kSecAttrAuthenticationTypeMSN
688 @constant kSecAttrAuthenticationTypeDPA
689 @constant kSecAttrAuthenticationTypeRPA
690 @constant kSecAttrAuthenticationTypeHTTPBasic
691 @constant kSecAttrAuthenticationTypeHTTPDigest
692 @constant kSecAttrAuthenticationTypeHTMLForm
693 @constant kSecAttrAuthenticationTypeDefault
695 extern const CFTypeRef kSecAttrAuthenticationTypeNTLM
696 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
697 extern const CFTypeRef kSecAttrAuthenticationTypeMSN
698 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
699 extern const CFTypeRef kSecAttrAuthenticationTypeDPA
700 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
701 extern const CFTypeRef kSecAttrAuthenticationTypeRPA
702 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
703 extern const CFTypeRef kSecAttrAuthenticationTypeHTTPBasic
704 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
705 extern const CFTypeRef kSecAttrAuthenticationTypeHTTPDigest
706 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
707 extern const CFTypeRef kSecAttrAuthenticationTypeHTMLForm
708 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
709 extern const CFTypeRef kSecAttrAuthenticationTypeDefault
710 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
713 @enum kSecAttrKeyClass Value Constants
714 @discussion Predefined item attribute constants used to get or set values
715 in a dictionary. The kSecAttrKeyClass constant is the key
716 and its value is one of the constants defined here.
717 @constant kSecAttrKeyClassPublic
718 @constant kSecAttrKeyClassPrivate
719 @constant kSecAttrKeyClassSymmetric
721 extern const CFTypeRef kSecAttrKeyClassPublic
722 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
723 extern const CFTypeRef kSecAttrKeyClassPrivate
724 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
725 extern const CFTypeRef kSecAttrKeyClassSymmetric
726 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
729 @enum kSecAttrKeyType Value Constants
730 @discussion Predefined item attribute constants used to get or set values
731 in a dictionary. The kSecAttrKeyType constant is the key
732 and its value is one of the constants defined here.
733 @constant kSecAttrKeyTypeRSA
734 @constant kSecAttrKeyTypeDSA
735 @constant kSecAttrKeyTypeAES
736 @constant kSecAttrKeyType3DES
737 @constant kSecAttrKeyTypeRC4
738 @constant kSecAttrKeyTypeRC2
739 @constant kSecAttrKeyTypeCAST
740 @constant kSecAttrKeyTypeECDSA (deprecated; use kSecAttrKeyTypeEC instead.)
741 @constant kSecAttrKeyTypeEC
743 extern const CFTypeRef kSecAttrKeyTypeRSA
744 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
745 extern const CFTypeRef kSecAttrKeyTypeDSA
746 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
747 extern const CFTypeRef kSecAttrKeyTypeAES
748 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
749 extern const CFTypeRef kSecAttrKeyTypeDES
750 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
751 extern const CFTypeRef kSecAttrKeyType3DES
752 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
753 extern const CFTypeRef kSecAttrKeyTypeRC4
754 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
755 extern const CFTypeRef kSecAttrKeyTypeRC2
756 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
757 extern const CFTypeRef kSecAttrKeyTypeCAST
758 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
759 extern const CFTypeRef kSecAttrKeyTypeECDSA
760 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
761 extern const CFTypeRef kSecAttrKeyTypeEC
762 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
765 @enum kSecAttrPRF Value Constants
766 @discussion Predefined item attribute constants used to specify the PRF
767 to use with SecKeyDeriveFromPassword.
768 @constant kSecAttrPRFHmacAlgSHA1
769 @constant kSecAttrPRFHmacAlgSHA224
770 @constant kSecAttrPRFHmacAlgSHA256
771 @constant kSecAttrPRFHmacAlgSHA384
772 @constant kSecAttrPRFHmacAlgSHA512
774 extern const CFTypeRef kSecAttrPRFHmacAlgSHA1
775 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
776 extern const CFTypeRef kSecAttrPRFHmacAlgSHA224
777 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
778 extern const CFTypeRef kSecAttrPRFHmacAlgSHA256
779 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
780 extern const CFTypeRef kSecAttrPRFHmacAlgSHA384
781 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
782 extern const CFTypeRef kSecAttrPRFHmacAlgSHA512
783 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
786 @enum Search Constants
787 @discussion Predefined search constants used to set values in a query
788 dictionary. You can specify a combination of search attributes and
789 item attributes when looking for matching items with the
790 SecItemCopyMatching function.
791 @constant kSecMatchPolicy Specifies a dictionary key whose value is a
792 SecPolicyRef. If provided, returned certificates or identities must
793 verify with this policy.
794 @constant kSecMatchItemList Specifies a dictionary key whose value is a
795 CFArray of SecKeychainItemRef items. If provided, returned items will be
796 limited to the subset which are contained in this list.
797 @constant kSecMatchSearchList Specifies a dictionary key whose value is a
798 CFArray of SecKeychainRef items. If provided, the search will be limited
799 to the keychains contained in this list.
800 @constant kSecMatchIssuers Specifies a dictionary key whose value is a
801 CFArray of X.500 names (of type CFDataRef). If provided, returned
802 certificates or identities will be limited to those whose
803 certificate chain contains one of the issuers provided in this list.
804 @constant kSecMatchEmailAddressIfPresent Specifies a dictionary key whose
805 value is a CFStringRef containing an RFC822 email address. If
806 provided, returned certificates or identities will be limited to those
807 that contain the address, or do not contain any email address.
808 @constant kSecMatchSubjectContains Specifies a dictionary key whose value
809 is a CFStringRef. If provided, returned certificates or identities
810 will be limited to those containing this string in the subject.
811 @constant kSecMatchSubjectStartsWith Specifies a dictionary key whose value
812 is a CFStringRef. If provided, returned certificates or identities
813 will be limited to those with subject names that start with this string.
814 @constant kSecMatchSubjectEndsWith Specifies a dictionary key whose value
815 is a CFStringRef. If provided, returned certificates or identities
816 will be limited to those with subject names that end with this string.
817 @constant kSecMatchSubjectWholeString Specifies a dictionary key whose
818 value is a CFStringRef. If provided, returned certificates or identities
819 will be limited to those matching this string exactly in the subject.
820 @constant kSecMatchCaseInsensitive Specifies a dictionary key whose value
821 is a CFBooleanRef. If this value is kCFBooleanFalse, or is not
822 provided, then case-sensitive string matching is performed.
823 @constant kSecMatchDiacriticInsensitive Specifies a dictionary key whose
824 value is a CFBooleanRef. If this value is kCFBooleanFalse, or is not
825 provided, then diacritic-sensitive string matching is performed.
826 @constant kSecMatchWidthInsensitive Specifies a dictionary key whose
827 value is a CFBooleanRef. If this value is kCFBooleanFalse, or is not
828 provided, then string matching is width-sensitive (e.g. 'a' != 0xFF41).
829 @constant kSecMatchTrustedOnly Specifies a dictionary key whose value is
830 a CFBooleanRef. If provided with a value of kCFBooleanTrue, only
831 certificates which can be verified back to a trusted anchor will be
832 returned. If this value is kCFBooleanFalse, or is not provided, then
833 both trusted and untrusted certificates may be returned.
834 @constant kSecMatchValidOnDate Specifies a dictionary key whose value is
835 of type CFDateRef. If provided, returned keys, certificates or
836 identities will be limited to those which are valid for the given date.
837 Pass a value of kCFNull to indicate the current date.
838 @constant kSecMatchLimit Specifies a dictionary key whose value is a
839 CFNumberRef. If provided, this value specifies the maximum number of
840 results to return. If not provided, results are limited to the first
841 item found. Predefined values are provided for a single item
842 (kSecMatchLimitOne) and all matching items (kSecMatchLimitAll).
843 @constant kSecMatchLimitOne Specifies that results are limited to the first
844 item found; used as a value for the kSecMatchLimit dictionary key.
845 @constant kSecMatchLimitAll Specifies that an unlimited number of results
846 may be returned; used as a value for the kSecMatchLimit dictionary
849 extern const CFTypeRef kSecMatchPolicy
850 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
851 extern const CFTypeRef kSecMatchItemList
852 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
853 extern const CFTypeRef kSecMatchSearchList
854 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
855 extern const CFTypeRef kSecMatchIssuers
856 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
857 extern const CFTypeRef kSecMatchEmailAddressIfPresent
858 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
859 extern const CFTypeRef kSecMatchSubjectContains
860 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
861 extern const CFTypeRef kSecMatchSubjectStartsWith
862 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
863 extern const CFTypeRef kSecMatchSubjectEndsWith
864 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
865 extern const CFTypeRef kSecMatchSubjectWholeString
866 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
867 extern const CFTypeRef kSecMatchCaseInsensitive
868 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
869 extern const CFTypeRef kSecMatchDiacriticInsensitive
870 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
871 extern const CFTypeRef kSecMatchWidthInsensitive
872 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
873 extern const CFTypeRef kSecMatchTrustedOnly
874 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
875 extern const CFTypeRef kSecMatchValidOnDate
876 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
877 extern const CFTypeRef kSecMatchLimit
878 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
879 extern const CFTypeRef kSecMatchLimitOne
880 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
881 extern const CFTypeRef kSecMatchLimitAll
882 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
886 @enum Return Type Key Constants
887 @discussion Predefined return type keys used to set values in a dictionary.
888 You use these keys to specify the type of results which should be
889 returned by the SecItemCopyMatching or SecItemAdd function. You can
890 specify zero or more of these return types. If more than one of these
891 result types is specified, the result is returned as a CFDictionaryRef
892 whose keys are the result types and values are the requested data.
893 @constant kSecReturnData Specifies a dictionary key whose value is of type
894 CFBooleanRef. A value of kCFBooleanTrue indicates that the data of
895 an item (CFDataRef) should be returned. For keys and password
896 items, data is secret (encrypted) and may require the user to enter
897 a password for access.
898 @constant kSecReturnAttributes Specifies a dictionary key whose value is
899 of type CFBooleanRef. A value of kCFBooleanTrue indicates that the
900 (non-encrypted) attributes of an item (in a CFDictionaryRef) should be
902 @constant kSecReturnRef Specifies a dictionary key whose value is a
903 CFBooleanRef. A value of kCFBooleanTrue indicates that a reference
904 should be returned. Depending on the item class requested, the
905 returned reference(s) may be of type SecKeychainItemRef, SecKeyRef,
906 SecCertificateRef, or SecIdentityRef.
907 @constant kSecReturnPersistentRef Specifies a dictionary key whose value
908 is of type CFBooleanRef. A value of kCFBooleanTrue indicates that a
909 persistent reference to an item (CFDataRef) should be returned.
911 extern const CFTypeRef kSecReturnData
912 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
913 extern const CFTypeRef kSecReturnAttributes
914 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
915 extern const CFTypeRef kSecReturnRef
916 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
917 extern const CFTypeRef kSecReturnPersistentRef
918 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
922 @enum Value Type Key Constants
923 @discussion Predefined value type keys used to pass values in a dictionary.
924 You can specify zero or more of these types depending on the function
925 you are calling. For SecItemCopyMatching or SecItemAdd these are
926 used as keys in the results dictionary.
927 @constant kSecValueData Specifies a dictionary key whose value is of type
928 CFDataRef. For keys and password items, data is secret (encrypted)
929 and may require the user to enter a password for access.
930 @constant kSecValueRef Specifies a dictionary key whose value, depending
931 on the item class requested, is of type SecKeychainItemRef, SecKeyRef,
932 SecCertificateRef, or SecIdentityRef.
933 @constant kSecValuePersistentRef Specifies a dictionary key whose value
934 is of type CFDataRef. The bytes in this CFDataRef can be stored by
935 the caller and used on a subsequent invocation of the application (or
936 even a different application) to retrieve the item referenced by it.
938 extern const CFTypeRef kSecValueData
939 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
940 extern const CFTypeRef kSecValueRef
941 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
942 extern const CFTypeRef kSecValuePersistentRef
943 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
947 @enum Other Constants
948 @discussion Predefined constants used to set values in a dictionary.
949 @constant kSecUseItemList Specifies a dictionary key whose value is a
950 CFArray of items. If provided, this array is treated as the set of
951 all possible items to search, or add if the API being called is
952 SecItemAdd. The items in this array may be of type SecKeyRef,
953 SecCertificateRef, SecIdentityRef, or CFDataRef (for a persistent
954 item reference.) The items in the array must all be of the same
955 type. When this attribute is provided, no keychains are searched.
956 @constant kSecUseKeychain Specifies a dictionary key whose value is a
957 keychain reference. You use this key to specify a value of type
958 SecKeychainRef to which SecItemAdd will add the provided item(s).
960 extern const CFTypeRef kSecUseItemList
961 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
962 extern const CFTypeRef kSecUseKeychain
963 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
966 @function SecItemCopyMatching
967 @abstract Returns one or more items which match a search query.
968 @param query A dictionary containing an item class specification and
969 optional attributes for controlling the search. See the "Keychain
970 Search Attributes" section for a description of currently defined
972 @param result On return, a CFTypeRef reference to the found item(s). The
973 exact type of the result is based on the search attributes supplied
974 in the query, as discussed below.
975 @result A result code. See "Security Error Codes" (SecBase.h).
976 @discussion Attributes defining a search are specified by adding key/value
977 pairs to the query dictionary.
979 A typical query consists of:
981 * a kSecClass key, whose value is a constant from the Class
982 Constants section that specifies the class of item(s) to be searched
983 * one or more keys from the "Attribute Key Constants" section, whose value
984 is the attribute data to be matched
985 * one or more keys from the "Search Constants" section, whose value is
986 used to further refine the search
987 * a key from the "Return Type Key Constants" section, specifying the type of
990 Result types are specified as follows:
992 * To obtain the data of a matching item (CFDataRef), specify
993 kSecReturnData with a value of kCFBooleanTrue.
994 * To obtain the attributes of a matching item (CFDictionaryRef), specify
995 kSecReturnAttributes with a value of kCFBooleanTrue.
996 * To obtain a reference to a matching item (SecKeychainItemRef,
997 SecKeyRef, SecCertificateRef, or SecIdentityRef), specify kSecReturnRef
998 with a value of kCFBooleanTrue.
999 * To obtain a persistent reference to a matching item (CFDataRef),
1000 specify kSecReturnPersistentRef with a value of kCFBooleanTrue. Note
1001 that unlike normal references, a persistent reference may be stored
1002 on disk or passed between processes.
1003 * If more than one of these result types is specified, the result is
1004 returned as a CFDictionaryRef containing all the requested data.
1006 By default, this function returns only the first match found. To obtain
1007 more than one matching item at a time, specify kSecMatchLimit with a value
1008 greater than 1. The result will be a CFArrayRef containing up to that
1009 number of matching items; the items' types are described above.
1011 To filter a provided list of items down to those matching the query,
1012 specify a kSecMatchItemList whose value is a CFArray of SecKeychainItemRef,
1013 SecKeyRef, SecCertificateRef, or SecIdentityRef items. The objects in the
1014 provided array must be of the same type.
1016 To convert from persistent item references to normal item references,
1017 specify a kSecMatchItemList whose value is a CFArray containing one or
1018 more CFDataRef elements (the persistent reference), and a kSecReturnRef
1019 whose value is kCFBooleanTrue. The objects in the provided array must be
1022 OSStatus
SecItemCopyMatching(CFDictionaryRef query
, CFTypeRef
*result
)
1023 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
1026 @function SecItemAdd
1027 @abstract Add one or more items to a keychain.
1028 @param attributes A dictionary containing an item class specification and
1029 optional entries specifying the item's attribute values. See the
1030 "Attribute Key Constants" section for a description of currently defined
1032 @param result On return, a CFTypeRef reference to the newly added item(s).
1033 The exact type of the result is based on the values supplied
1034 in attributes, as discussed below. Pass NULL if this result is not
1036 @result A result code. See "Security Error Codes" (SecBase.h).
1037 @discussion Attributes defining an item are specified by adding key/value
1038 pairs to the attributes dictionary. To add multiple items to a keychain
1039 at once use the kSecUseItemList key with an array of items as its value.
1040 This is currently only supported for non password items. To add an item
1041 to a particular keychain, supply kSecUseKeychain with a SecKeychainRef as
1044 Result types are specified as follows:
1046 * To obtain the data of the added item (CFDataRef), specify
1047 kSecReturnData with a value of kCFBooleanTrue.
1048 * To obtain all the attributes of the added item (CFDictionaryRef),
1049 specify kSecReturnAttributes with a value of kCFBooleanTrue.
1050 * To obtain a reference to the added item (SecKeychainItemRef, SecKeyRef,
1051 SecCertificateRef, or SecIdentityRef), specify kSecReturnRef with a
1052 value of kCFBooleanTrue. This is the default behavior if a result
1053 type is not explicitly specified.
1054 * To obtain a persistent reference to the added item (CFDataRef), specify
1055 kSecReturnPersistentRef with a value of kCFBooleanTrue. Note that
1056 unlike normal references, a persistent reference may be stored on disk
1057 or passed between processes.
1058 * If more than one of these result types is specified, the result is
1059 returned as a CFDictionaryRef containing all the requested data.
1061 OSStatus
SecItemAdd(CFDictionaryRef attributes
, CFTypeRef
*result
)
1062 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
1065 @function SecItemUpdate
1066 @abstract Modify zero or more items which match a search query.
1067 @param query A dictionary containing an item class specification and
1068 optional attributes for controlling the search. See the "Attribute
1069 Constants" and "Search Constants" sections for a description of
1070 currently defined search attributes.
1071 @param attributesToUpdate A dictionary containing one or more attributes
1072 whose values should be set to the ones specified. Only real keychain
1073 attributes are permitted in this dictionary (no "meta" attributes are
1074 allowed.) See the "Attribute Key Constants" section for a description of
1075 currently defined value attributes.
1076 @result A result code. See "Security Error Codes" (SecBase.h).
1077 @discussion Attributes defining a search are specified by adding key/value
1078 pairs to the query dictionary.
1080 OSStatus
SecItemUpdate(CFDictionaryRef query
, CFDictionaryRef attributesToUpdate
)
1081 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
1084 @function SecItemDelete
1085 @abstract Delete zero or more items which match a search query.
1086 @param query A dictionary containing an item class specification and
1087 optional attributes for controlling the search. See the "Attribute
1088 Constants" and "Search Constants" sections for a description of
1089 currently defined search attributes.
1090 @result A result code. See "Security Error Codes" (SecBase.h).
1091 @discussion Attributes defining a search are specified by adding key/value
1092 pairs to the query dictionary.
1094 By default, this function deletes all items matching the specified query.
1095 You can change this behavior by specifying one of the follow keys:
1097 * To delete an item identified by a transient reference, specify
1098 kSecMatchItemList with a reference returned by using the kSecReturnRef
1099 key in a previous call to SecItemCopyMatching or SecItemAdd.
1100 * To delete an item identified by a persistent reference, specify
1101 kSecMatchItemList with a persistent reference returned by using the
1102 kSecReturnPersistentRef key to SecItemCopyMatching or SecItemAdd.
1103 * If more than one of these result keys is specified, the behavior is
1106 OSStatus
SecItemDelete(CFDictionaryRef query
)
1107 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
1109 #if defined(__cplusplus)
1113 #endif /* !_SECURITY_SECITEM_H_ */
projects / apple / security.git / blob