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 <Security/SecBase.h>
35 #include <CoreFoundation/CFArray.h>
36 #include <CoreFoundation/CFDictionary.h>
40 CF_ASSUME_NONNULL_BEGIN
41 CF_IMPLICIT_BRIDGING_ENABLED
44 @enum Class Key Constant
45 @discussion Predefined key constant used to get or set item class values in
46 a dictionary. Its value is one of the constants defined in the Value
47 Constants for kSecClass.
48 @constant kSecClass Specifies a dictionary key whose value is the item's
49 class code. You use this key to get or set a value of type CFTypeRef
50 that contains the item class code.
52 extern const CFStringRef kSecClass
53 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
56 @enum Class Value Constants
57 @discussion Predefined item class constants used to get or set values in
58 a dictionary. The kSecClass constant is the key and its value is one
59 of the constants defined here.
60 @constant kSecClassGenericPassword Specifies generic password items.
61 @constant kSecClassInternetPassword Specifies Internet password items.
62 @constant kSecClassCertificate Specifies certificate items.
63 @constant kSecClassKey Specifies key items.
64 @constant kSecClassIdentity Specifies identity items.
66 extern const CFStringRef kSecClassGenericPassword
67 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
68 extern const CFStringRef kSecClassInternetPassword
69 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
70 extern const CFStringRef kSecClassCertificate
71 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
72 extern const CFStringRef kSecClassKey
73 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
74 extern const CFStringRef kSecClassIdentity
75 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
79 @enum Attribute Key Constants
80 @discussion Predefined item attribute keys used to get or set values in a
81 dictionary. Not all attributes apply to each item class. The table
82 below lists the currently defined attributes for each item class:
84 kSecClassGenericPassword item attributes:
89 kSecAttrModificationDate
100 kSecAttrSynchronizable
102 kSecClassInternetPassword item attributes:
104 kSecAttrAccessControl
107 kSecAttrModificationDate
116 kSecAttrSecurityDomain
119 kSecAttrAuthenticationType
122 kSecAttrSynchronizable
124 kSecClassCertificate item attributes:
126 kSecAttrAccessControl
128 kSecAttrCertificateType
129 kSecAttrCertificateEncoding
135 kSecAttrPublicKeyHash
136 kSecAttrSynchronizable
138 kSecClassKey item attributes:
140 kSecAttrAccessControl
144 kSecAttrApplicationLabel
146 kSecAttrApplicationTag
148 kSecAttrKeySizeInBits
149 kSecAttrEffectiveKeySize
157 kSecAttrSynchronizable
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.
164 @constant kSecAttrAccessible Specifies a dictionary key whose value
165 indicates when your application needs access to an item's data. You
166 should choose the most restrictive option that meets your application's
167 needs to allow the system to protect that item in the best way possible.
168 See the "kSecAttrAccessible Value Constants" section for a list of
169 values which can be specified.
170 IMPORTANT: This attribute is currently not supported for OS X keychain
171 items, unless the kSecAttrSynchronizable attribute is also present. If
172 both attributes are specified on either OS X or iOS, the value for the
173 kSecAttrAccessible key may only be one whose name does not end with
174 "ThisDeviceOnly", as those cannot sync to another device.
176 @constant kSecAttrAccessControl Specifies a dictionary key whose value
177 is SecAccessControl instance which contains access control conditions
180 @constant kSecAttrAccessGroup Specifies a dictionary key whose value is
181 a CFStringRef indicating which access group a item is in. The access
182 groups that a particular application has membership in are determined by
183 two entitlements for that application. The application-identifier
184 entitlement contains the application's single access group, unless
185 there is a keychain-access-groups entitlement present. The latter
186 has as its value a list of access groups; the first item in this list
187 is the default access group. Unless a specific access group is provided
188 as the value of kSecAttrAccessGroup when SecItemAdd is called, new items
189 are created in the application's default access group. Specifying this
190 attribute in SecItemCopyMatching, SecItemUpdate, or SecItemDelete calls
191 limits the search to the specified access group (of which the calling
192 application must be a member to obtain matching results.) To share
193 keychain items between multiple applications, each application must have
194 a common group listed in its keychain-access-groups entitlement, and each
195 must specify this shared access group name as the value for the
196 kSecAttrAccessGroup key in the dictionary passed to SecItem functions.
198 @constant kSecAttrSynchronizable Specifies a dictionary key whose value is
199 a CFBooleanRef indicating whether the item in question can be synchronized.
200 To add a new item which can be synced to other devices, or to obtain
201 synchronizable results from a query, supply this key with a value of
202 kCFBooleanTrue. If the key is not supplied, or has a value of
203 kCFBooleanFalse, then no synchronizable items will be added or returned.
204 A predefined value, kSecAttrSynchronizableAny, may be provided instead of
205 kCFBooleanTrue if both synchronizable and non-synchronizable results are
208 IMPORTANT: Specifying the kSecAttrSynchronizable key has several caveats:
210 - Updating or deleting items using the kSecAttrSynchronizable key will
211 affect all copies of the item, not just the one on your local device.
212 Be sure that it makes sense to use the same password on all devices
213 before deciding to make a password synchronizable.
214 - Only password items can currently be synchronized. Keychain syncing
215 is not supported for certificates or cryptographic keys.
216 - Items stored or obtained using the kSecAttrSynchronizable key cannot
217 specify SecAccessRef-based access control with kSecAttrAccess. If a
218 password is intended to be shared between multiple applications, the
219 kSecAttrAccessGroup key must be specified, and each application
220 using this password must have a 'keychain-access-groups' entitlement
221 with the specified access group value.
222 - Items stored or obtained using the kSecAttrSynchronizable key may
223 not also specify a kSecAttrAccessible value which is incompatible
224 with syncing (namely, those whose names end with "ThisDeviceOnly".)
225 - Items stored or obtained using the kSecAttrSynchronizable key cannot
226 be specified by reference. You must pass kSecReturnAttributes and/or
227 kSecReturnData to retrieve results; kSecReturnRef is currently not
228 supported for synchronizable items.
229 - Persistent references to synchronizable items should be avoided;
230 while they may work locally, they cannot be moved between devices,
231 and may not resolve if the item is modified on some other device.
232 - When specifying a query that uses the kSecAttrSynchronizable key,
233 search keys are limited to the item's class and attributes.
234 The only search constant which may be used is kSecMatchLimit; other
235 constants using the kSecMatch prefix are not supported at this time.
237 @constant kSecAttrCreationDate (read-only) Specifies a dictionary key whose
238 value is the item's creation date. You use this key to get a value
239 of type CFDateRef that represents the date the item was created.
240 @constant kSecAttrModificationDate (read-only) Specifies a dictionary key
241 whose value is the item's modification date. You use this key to get
242 a value of type CFDateRef that represents the last time the item was
244 @constant kSecAttrDescription Specifies a dictionary key whose value is
245 the item's description attribute. You use this key to set or get a
246 value of type CFStringRef that represents a user-visible string
247 describing this particular kind of item (e.g., "disk image password").
248 @constant kSecAttrComment Specifies a dictionary key whose value is the
249 item's comment attribute. You use this key to set or get a value of
250 type CFStringRef containing the user-editable comment for this item.
251 @constant kSecAttrCreator Specifies a dictionary key whose value is the
252 item's creator attribute. You use this key to set or get a value of
253 type CFNumberRef that represents the item's creator. This number is
254 the unsigned integer representation of a four-character code (e.g.,
256 @constant kSecAttrType Specifies a dictionary key whose value is the item's
257 type attribute. You use this key to set or get a value of type
258 CFNumberRef that represents the item's type. This number is the
259 unsigned integer representation of a four-character code (e.g.,
261 @constant kSecAttrLabel Specifies a dictionary key whose value is the
262 item's label attribute. You use this key to set or get a value of
263 type CFStringRef containing the user-visible label for this item.
264 @constant kSecAttrIsInvisible Specifies a dictionary key whose value is the
265 item's invisible attribute. You use this key to set or get a value
266 of type CFBooleanRef that indicates whether the item is invisible
267 (i.e., should not be displayed.)
268 @constant kSecAttrIsNegative Specifies a dictionary key whose value is the
269 item's negative attribute. You use this key to set or get a value of
270 type CFBooleanRef that indicates whether there is a valid password
271 associated with this keychain item. This is useful if your application
272 doesn't want a password for some particular service to be stored in
273 the keychain, but prefers that it always be entered by the user.
274 @constant kSecAttrAccount Specifies a dictionary key whose value is the
275 item's account attribute. You use this key to set or get a CFStringRef
276 that contains an account name. (Items of class
277 kSecClassGenericPassword, kSecClassInternetPassword have this
279 @constant kSecAttrService Specifies a dictionary key whose value is the
280 item's service attribute. You use this key to set or get a CFStringRef
281 that represents the service associated with this item. (Items of class
282 kSecClassGenericPassword have this attribute.)
283 @constant kSecAttrGeneric Specifies a dictionary key whose value is the
284 item's generic attribute. You use this key to set or get a value of
285 CFDataRef that contains a user-defined attribute. (Items of class
286 kSecClassGenericPassword have this attribute.)
287 @constant kSecAttrSecurityDomain Specifies a dictionary key whose value
288 is the item's security domain attribute. You use this key to set or
289 get a CFStringRef value that represents the Internet security domain.
290 (Items of class kSecClassInternetPassword have this attribute.)
291 @constant kSecAttrServer Specifies a dictionary key whose value is the
292 item's server attribute. You use this key to set or get a value of
293 type CFStringRef that contains the server's domain name or IP address.
294 (Items of class kSecClassInternetPassword have this attribute.)
295 @constant kSecAttrProtocol Specifies a dictionary key whose value is the
296 item's protocol attribute. You use this key to set or get a value of
297 type CFNumberRef that denotes the protocol for this item (see the
298 SecProtocolType enum in SecKeychainItem.h). (Items of class
299 kSecClassInternetPassword have this attribute.)
300 @constant kSecAttrAuthenticationType Specifies a dictionary key whose value
301 is the item's authentication type attribute. You use this key to set
302 or get a value of type CFNumberRef that denotes the authentication
303 scheme for this item (see the kSecAttrAuthenticationType value
305 @constant kSecAttrPort Specifies a dictionary key whose value is the item's
306 port attribute. You use this key to set or get a CFNumberRef value
307 that represents an Internet port number. (Items of class
308 kSecClassInternetPassword have this attribute.)
309 @constant kSecAttrPath Specifies a dictionary key whose value is the item's
310 path attribute, typically this is the path component of the URL. You use
311 this key to set or get a CFStringRef value that represents a path. (Items
312 of class kSecClassInternetPassword have this attribute.)
313 @constant kSecAttrSubject (read-only) Specifies a dictionary key whose
314 value is the item's subject. You use this key to get a value of type
315 CFDataRef that contains the X.500 subject name of a certificate.
316 (Items of class kSecClassCertificate have this attribute.)
317 @constant kSecAttrIssuer (read-only) Specifies a dictionary key whose value
318 is the item's issuer. You use this key to get a value of type
319 CFDataRef that contains the X.500 issuer name of a certificate. (Items
320 of class kSecClassCertificate have this attribute.)
321 @constant kSecAttrSerialNumber (read-only) Specifies a dictionary key whose
322 value is the item's serial number. You use this key to get a value
323 of type CFDataRef that contains the serial number data of a
324 certificate. (Items of class kSecClassCertificate have this
326 @constant kSecAttrSubjectKeyID (read-only) Specifies a dictionary key whose
327 value is the item's subject key ID. You use this key to get a value
328 of type CFDataRef that contains the subject key ID of a certificate.
329 (Items of class kSecClassCertificate have this attribute.)
330 @constant kSecAttrPublicKeyHash (read-only) Specifies a dictionary key
331 whose value is the item's public key hash. You use this key to get a
332 value of type CFDataRef that contains the hash of a certificate's
333 public key. (Items of class kSecClassCertificate have this attribute.)
334 @constant kSecAttrCertificateType (read-only) Specifies a dictionary key
335 whose value is the item's certificate type. You use this key to get
336 a value of type CFNumberRef that denotes the certificate type
337 (Currently only the value of this attribute must be equal to the
338 version of the X509 certificate. So 1 for v1 2 for v2 and 3 for v3
339 certificates). Only items of class kSecClassCertificate have this
341 @constant kSecAttrCertificateEncoding (read-only) Specifies a dictionary
342 key whose value is the item's certificate encoding. You use this key
343 to get a value of type CFNumberRef that denotes the certificate
344 encoding (Currently only the value 3 meaning
345 kSecAttrCertificateEncodingDER is supported). Only items of class
346 kSecClassCertificate have this attribute.
347 @constant kSecAttrKeyClass (read only) Specifies a dictionary key whose
348 value is one of kSecAttrKeyClassPublic, kSecAttrKeyClassPrivate or
349 kSecAttrKeyClassSymmetric.
350 @constant kSecAttrApplicationLabel Specifies a dictionary key whose value
351 is the key's application label attribute. This is different from the
352 kSecAttrLabel (which is intended to be human-readable). This attribute
353 is used to look up a key programmatically; in particular, for keys of
354 class kSecAttrKeyClassPublic and kSecAttrKeyClassPrivate, the value of
355 this attribute is the hash of the public key.
356 @constant kSecAttrIsPermanent Specifies a dictionary key whose value is a
357 CFBooleanRef indicating whether the key in question will be stored
359 @constant kSecAttrApplicationTag Specifies a dictionary key whose value is a
360 CFDataRef containing private tag data.
361 @constant kSecAttrKeyType Specifies a dictionary key whose value is a
362 CFNumberRef indicating the algorithm associated with this key
363 (Currently only the value 42 is supported, alternatively you can use
365 @constant kSecAttrKeySizeInBits Specifies a dictionary key whose value
366 is a CFNumberRef indicating the number of bits in this key.
367 @constant kSecAttrEffectiveKeySize Specifies a dictionary key whose value
368 is a CFNumberRef indicating the effective number of bits in this key.
369 For example, a DES key has a kSecAttrKeySizeInBits of 64, but a
370 kSecAttrEffectiveKeySize of 56 bits.
371 @constant kSecAttrCanEncrypt Specifies a dictionary key whole value is a
372 CFBooleanRef indicating whether the key in question can be used to
374 @constant kSecAttrCanDecrypt Specifies a dictionary key whose value is a
375 CFBooleanRef indicating whether the key in question can be used to
377 @constant kSecAttrCanDerive Specifies a dictionary key whole value is a
378 CFBooleanRef indicating whether the key in question can be used to
380 @constant kSecAttrCanSign Specifies a dictionary key whole value is a
381 CFBooleanRef indicating whether the key in question can be used to
382 create a digital signature.
383 @constant kSecAttrCanVerify Specifies a dictionary key whole value is a
384 CFBooleanRef indicating whether the key in question can be used to
385 verify a digital signature.
386 @constant kSecAttrCanWrap Specifies a dictionary key whole value is a
387 CFBooleanRef indicating whether the key in question can be used to
389 @constant kSecAttrCanUnwrap Specifies a dictionary key whole value is a
390 CFBooleanRef indicating whether the key in question can be used to
392 @constant kSecAttrSyncViewHint Specifies a dictionary key whose value is
393 a CFStringRef. This value is part of the primary key of each item, and
394 can be used to help distiguish Sync Views when defining their
396 @constant kSecAttrTokenID Specifies a dictionary key whose presence
397 indicates that item is backed by external token. Value of this attribute
398 is CFStringRef uniquely identifying containing token. When this attribute
399 is not present, item is stored in internal keychain database.
400 Note that once item is created, this attribute cannot be changed - in other
401 words it is not possible to migrate existing items to, from or between tokens.
402 Currently the only available value for this attribute is
403 kSecAttrTokenIDSecureEnclave, which indicates that item (private key) is
404 backed by device's Secure Enclave.
406 extern const CFStringRef kSecAttrAccessible
407 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
408 extern const CFStringRef kSecAttrAccessControl
409 __OSX_AVAILABLE_STARTING(__MAC_10_10
, __IPHONE_8_0
);
410 extern const CFStringRef kSecAttrAccessGroup
411 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_3_0
);
412 extern const CFStringRef kSecAttrSynchronizable
413 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_7_0
);
414 extern const CFStringRef kSecAttrCreationDate
415 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
416 extern const CFStringRef kSecAttrModificationDate
417 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
418 extern const CFStringRef kSecAttrDescription
419 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
420 extern const CFStringRef kSecAttrComment
421 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
422 extern const CFStringRef kSecAttrCreator
423 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
424 extern const CFStringRef kSecAttrType
425 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
426 extern const CFStringRef kSecAttrLabel
427 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
428 extern const CFStringRef kSecAttrIsInvisible
429 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
430 extern const CFStringRef kSecAttrIsNegative
431 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
432 extern const CFStringRef kSecAttrAccount
433 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
434 extern const CFStringRef kSecAttrService
435 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
436 extern const CFStringRef kSecAttrGeneric
437 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
438 extern const CFStringRef kSecAttrSecurityDomain
439 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
440 extern const CFStringRef kSecAttrServer
441 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
442 extern const CFStringRef kSecAttrProtocol
443 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
444 extern const CFStringRef kSecAttrAuthenticationType
445 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
446 extern const CFStringRef kSecAttrPort
447 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
448 extern const CFStringRef kSecAttrPath
449 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
450 extern const CFStringRef kSecAttrSubject
451 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
452 extern const CFStringRef kSecAttrIssuer
453 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
454 extern const CFStringRef kSecAttrSerialNumber
455 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
456 extern const CFStringRef kSecAttrSubjectKeyID
457 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
458 extern const CFStringRef kSecAttrPublicKeyHash
459 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
460 extern const CFStringRef kSecAttrCertificateType
461 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
462 extern const CFStringRef kSecAttrCertificateEncoding
463 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
464 extern const CFStringRef kSecAttrKeyClass
465 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
466 extern const CFStringRef kSecAttrApplicationLabel
467 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
468 extern const CFStringRef kSecAttrIsPermanent
469 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
470 extern const CFStringRef kSecAttrApplicationTag
471 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
472 extern const CFStringRef kSecAttrKeyType
473 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
474 extern const CFStringRef kSecAttrKeySizeInBits
475 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
476 extern const CFStringRef kSecAttrEffectiveKeySize
477 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
478 extern const CFStringRef kSecAttrCanEncrypt
479 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
480 extern const CFStringRef kSecAttrCanDecrypt
481 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
482 extern const CFStringRef kSecAttrCanDerive
483 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
484 extern const CFStringRef kSecAttrCanSign
485 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
486 extern const CFStringRef kSecAttrCanVerify
487 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
488 extern const CFStringRef kSecAttrCanWrap
489 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
490 extern const CFStringRef kSecAttrCanUnwrap
491 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
492 extern const CFStringRef kSecAttrSyncViewHint
493 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
494 extern const CFStringRef kSecAttrTokenID
495 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
498 @enum kSecAttrAccessible Value Constants
499 @discussion Predefined item attribute constants used to get or set values
500 in a dictionary. The kSecAttrAccessible constant is the key and its
501 value is one of the constants defined here.
502 When asking SecItemCopyMatching to return the item's data, the error
503 errSecInteractionNotAllowed will be returned if the item's data is not
504 available until a device unlock occurs.
505 @constant kSecAttrAccessibleWhenUnlocked Item data can only be accessed
506 while the device is unlocked. This is recommended for items that only
507 need be accesible while the application is in the foreground. Items
508 with this attribute will migrate to a new device when using encrypted
510 @constant kSecAttrAccessibleAfterFirstUnlock Item data can only be
511 accessed once the device has been unlocked after a restart. This is
512 recommended for items that need to be accesible by background
513 applications. Items with this attribute will migrate to a new device
514 when using encrypted backups.
515 @constant kSecAttrAccessibleAlways Item data can always be accessed
516 regardless of the lock state of the device. This is not recommended
517 for anything except system use. Items with this attribute will migrate
518 to a new device when using encrypted backups.
519 @constant kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly Item data can
520 only be accessed while the device is unlocked. This class is only
521 available if a passcode is set on the device. This is recommended for
522 items that only need to be accessible while the application is in the
523 foreground. Items with this attribute will never migrate to a new
524 device, so after a backup is restored to a new device, these items
525 will be missing. No items can be stored in this class on devices
526 without a passcode. Disabling the device passcode will cause all
527 items in this class to be deleted.
528 @constant kSecAttrAccessibleWhenUnlockedThisDeviceOnly Item data can only
529 be accessed while the device is unlocked. This is recommended for items
530 that only need be accesible while the application is in the foreground.
531 Items with this attribute will never migrate to a new device, so after
532 a backup is restored to a new device, these items will be missing.
533 @constant kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly Item data can
534 only be accessed once the device has been unlocked after a restart.
535 This is recommended for items that need to be accessible by background
536 applications. Items with this attribute will never migrate to a new
537 device, so after a backup is restored to a new device these items will
539 @constant kSecAttrAccessibleAlwaysThisDeviceOnly Item data can always
540 be accessed regardless of the lock state of the device. This option
541 is not recommended for anything except system use. Items with this
542 attribute will never migrate to a new device, so after a backup is
543 restored to a new device, these items will be missing.
545 extern const CFStringRef kSecAttrAccessibleWhenUnlocked
546 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
547 extern const CFStringRef kSecAttrAccessibleAfterFirstUnlock
548 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
549 extern const CFStringRef kSecAttrAccessibleAlways
550 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
551 extern const CFStringRef kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly
552 __OSX_AVAILABLE_STARTING(__MAC_10_10
, __IPHONE_8_0
);
553 extern const CFStringRef kSecAttrAccessibleWhenUnlockedThisDeviceOnly
554 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
555 extern const CFStringRef kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
556 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
557 extern const CFStringRef kSecAttrAccessibleAlwaysThisDeviceOnly
558 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
561 @enum kSecAttrProtocol Value Constants
562 @discussion Predefined item attribute constants used to get or set values
563 in a dictionary. The kSecAttrProtocol constant is the key and its
564 value is one of the constants defined here.
565 @constant kSecAttrProtocolFTP.
566 @constant kSecAttrProtocolFTPAccount.
567 @constant kSecAttrProtocolHTTP.
568 @constant kSecAttrProtocolIRC.
569 @constant kSecAttrProtocolNNTP.
570 @constant kSecAttrProtocolPOP3.
571 @constant kSecAttrProtocolSMTP.
572 @constant kSecAttrProtocolSOCKS.
573 @constant kSecAttrProtocolIMAP.
574 @constant kSecAttrProtocolLDAP.
575 @constant kSecAttrProtocolAppleTalk.
576 @constant kSecAttrProtocolAFP.
577 @constant kSecAttrProtocolTelnet.
578 @constant kSecAttrProtocolSSH.
579 @constant kSecAttrProtocolFTPS.
580 @constant kSecAttrProtocolHTTPS.
581 @constant kSecAttrProtocolHTTPProxy.
582 @constant kSecAttrProtocolHTTPSProxy.
583 @constant kSecAttrProtocolFTPProxy.
584 @constant kSecAttrProtocolSMB.
585 @constant kSecAttrProtocolRTSP.
586 @constant kSecAttrProtocolRTSPProxy.
587 @constant kSecAttrProtocolDAAP.
588 @constant kSecAttrProtocolEPPC.
589 @constant kSecAttrProtocolIPP.
590 @constant kSecAttrProtocolNNTPS.
591 @constant kSecAttrProtocolLDAPS.
592 @constant kSecAttrProtocolTelnetS.
593 @constant kSecAttrProtocolIMAPS.
594 @constant kSecAttrProtocolIRCS.
595 @constant kSecAttrProtocolPOP3S.
597 extern const CFStringRef kSecAttrProtocolFTP
598 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
599 extern const CFStringRef kSecAttrProtocolFTPAccount
600 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
601 extern const CFStringRef kSecAttrProtocolHTTP
602 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
603 extern const CFStringRef kSecAttrProtocolIRC
604 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
605 extern const CFStringRef kSecAttrProtocolNNTP
606 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
607 extern const CFStringRef kSecAttrProtocolPOP3
608 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
609 extern const CFStringRef kSecAttrProtocolSMTP
610 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
611 extern const CFStringRef kSecAttrProtocolSOCKS
612 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
613 extern const CFStringRef kSecAttrProtocolIMAP
614 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
615 extern const CFStringRef kSecAttrProtocolLDAP
616 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
617 extern const CFStringRef kSecAttrProtocolAppleTalk
618 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
619 extern const CFStringRef kSecAttrProtocolAFP
620 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
621 extern const CFStringRef kSecAttrProtocolTelnet
622 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
623 extern const CFStringRef kSecAttrProtocolSSH
624 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
625 extern const CFStringRef kSecAttrProtocolFTPS
626 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
627 extern const CFStringRef kSecAttrProtocolHTTPS
628 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
629 extern const CFStringRef kSecAttrProtocolHTTPProxy
630 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
631 extern const CFStringRef kSecAttrProtocolHTTPSProxy
632 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
633 extern const CFStringRef kSecAttrProtocolFTPProxy
634 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
635 extern const CFStringRef kSecAttrProtocolSMB
636 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
637 extern const CFStringRef kSecAttrProtocolRTSP
638 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
639 extern const CFStringRef kSecAttrProtocolRTSPProxy
640 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
641 extern const CFStringRef kSecAttrProtocolDAAP
642 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
643 extern const CFStringRef kSecAttrProtocolEPPC
644 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
645 extern const CFStringRef kSecAttrProtocolIPP
646 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
647 extern const CFStringRef kSecAttrProtocolNNTPS
648 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
649 extern const CFStringRef kSecAttrProtocolLDAPS
650 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
651 extern const CFStringRef kSecAttrProtocolTelnetS
652 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
653 extern const CFStringRef kSecAttrProtocolIMAPS
654 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
655 extern const CFStringRef kSecAttrProtocolIRCS
656 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
657 extern const CFStringRef kSecAttrProtocolPOP3S
658 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
661 @enum kSecAttrAuthenticationType Value Constants
662 @discussion Predefined item attribute constants used to get or set values
663 in a dictionary. The kSecAttrAuthenticationType constant is the key
664 and its value is one of the constants defined here.
665 @constant kSecAttrAuthenticationTypeNTLM.
666 @constant kSecAttrAuthenticationTypeMSN.
667 @constant kSecAttrAuthenticationTypeDPA.
668 @constant kSecAttrAuthenticationTypeRPA.
669 @constant kSecAttrAuthenticationTypeHTTPBasic.
670 @constant kSecAttrAuthenticationTypeHTTPDigest.
671 @constant kSecAttrAuthenticationTypeHTMLForm.
672 @constant kSecAttrAuthenticationTypeDefault.
674 extern const CFStringRef kSecAttrAuthenticationTypeNTLM
675 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
676 extern const CFStringRef kSecAttrAuthenticationTypeMSN
677 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
678 extern const CFStringRef kSecAttrAuthenticationTypeDPA
679 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
680 extern const CFStringRef kSecAttrAuthenticationTypeRPA
681 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
682 extern const CFStringRef kSecAttrAuthenticationTypeHTTPBasic
683 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
684 extern const CFStringRef kSecAttrAuthenticationTypeHTTPDigest
685 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
686 extern const CFStringRef kSecAttrAuthenticationTypeHTMLForm
687 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
688 extern const CFStringRef kSecAttrAuthenticationTypeDefault
689 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
692 @enum kSecAttrKeyClass Value Constants
693 @discussion Predefined item attribute constants used to get or set values
694 in a dictionary. The kSecAttrKeyClass constant is the key
695 and its value is one of the constants defined here.
696 @constant kSecAttrKeyClassPublic.
697 @constant kSecAttrKeyClassPrivate.
698 @constant kSecAttrKeyClassSymmetric.
700 extern const CFStringRef kSecAttrKeyClassPublic
701 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
702 extern const CFStringRef kSecAttrKeyClassPrivate
703 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
704 extern const CFStringRef kSecAttrKeyClassSymmetric
705 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
708 @enum kSecAttrKeyType Value Constants
709 @discussion Predefined item attribute constants used to get or set values
710 in a dictionary. The kSecAttrKeyType constant is the key
711 and its value is one of the constants defined here.
712 @constant kSecAttrKeyTypeRSA.
713 @constant kSecAttrKeyTypeEC.
715 extern const CFStringRef kSecAttrKeyTypeRSA
716 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
717 extern const CFStringRef kSecAttrKeyTypeEC
718 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
721 @enum kSecAttrSynchronizable Value Constants
722 @discussion Predefined item attribute constants used to get or set values
723 in a dictionary. The kSecAttrSynchronizable constant is the key
724 and its value is one of the constants defined here.
725 @constant kSecAttrSynchronizableAny Specifies that both synchronizable and
726 non-synchronizable results should be returned from this query. This may
727 be used as a value for the kSecAttrSynchronizable dictionary key in a
728 call to SecItemCopyMatching, SecItemUpdate, or SecItemDelete.
730 extern const CFStringRef kSecAttrSynchronizableAny
731 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_7_0
);
734 @enum Search Constants
735 @discussion Predefined search constants used to set values in a query
736 dictionary. You can specify a combination of search attributes and
737 item attributes when looking for matching items with the
738 SecItemCopyMatching function.
739 @constant kSecMatchPolicy Specifies a dictionary key whose value is a
740 SecPolicyRef. If provided, returned certificates or identities must
741 verify with this policy.
742 @constant kSecMatchIssuers Specifies a dictionary key whose value is a
743 CFArray of X.500 names (of type CFDataRef). If provided, returned
744 certificates or identities will be limited to those whose
745 certificate chain contains one of the issuers provided in this list.
746 @constant kSecMatchEmailAddressIfPresent Specifies a dictionary key whose
747 value is a CFStringRef containing an RFC822 email address. If
748 provided, returned certificates or identities will be limited to those
749 that contain the address, or do not contain any email address.
750 @constant kSecMatchSubjectContains Specifies a dictionary key whose value
751 is a CFStringRef. If provided, returned certificates or identities
752 will be limited to those containing this string in the subject.
753 @constant kSecMatchCaseInsensitive Specifies a dictionary key whose value
754 is a CFBooleanRef. If this value is kCFBooleanFalse, or is not
755 provided, then case-sensitive string matching is performed.
756 @constant kSecMatchTrustedOnly Specifies a dictionary key whose value is
757 a CFBooleanRef. If provided with a value of kCFBooleanTrue, only
758 certificates which can be verified back to a trusted anchor will be
759 returned. If this value is kCFBooleanFalse, or is not provided, then
760 both trusted and untrusted certificates may be returned.
761 @constant kSecMatchValidOnDate Specifies a dictionary key whose value is
762 of type CFDateRef. If provided, returned keys, certificates or
763 identities will be limited to those which are valid for the given date.
764 Pass a value of kCFNull to indicate the current date.
765 @constant kSecMatchLimit Specifies a dictionary key whose value is a
766 CFNumberRef. If provided, this value specifies the maximum number of
767 results to return. If not provided, results are limited to the first
768 item found. Predefined values are provided for a single item
769 (kSecMatchLimitOne) and all matching items (kSecMatchLimitAll).
770 @constant kSecMatchLimitOne Specifies that results are limited to the first
771 item found; used as a value for the kSecMatchLimit dictionary key.
772 @constant kSecMatchLimitAll Specifies that an unlimited number of results
773 may be returned; used as a value for the kSecMatchLimit dictionary
776 extern const CFStringRef kSecMatchPolicy
777 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
778 extern const CFStringRef kSecMatchItemList
779 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
780 extern const CFStringRef kSecMatchSearchList
781 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
782 extern const CFStringRef kSecMatchIssuers
783 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
784 extern const CFStringRef kSecMatchEmailAddressIfPresent
785 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
786 extern const CFStringRef kSecMatchSubjectContains
787 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
788 extern const CFStringRef kSecMatchCaseInsensitive
789 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
790 extern const CFStringRef kSecMatchTrustedOnly
791 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
792 extern const CFStringRef kSecMatchValidOnDate
793 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
794 extern const CFStringRef kSecMatchLimit
795 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
796 extern const CFStringRef kSecMatchLimitOne
797 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
798 extern const CFStringRef kSecMatchLimitAll
799 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
803 @enum Return Type Key Constants
804 @discussion Predefined return type keys used to set values in a dictionary.
805 You use these keys to specify the type of results which should be
806 returned by the SecItemCopyMatching or SecItemAdd function. You can
807 specify zero or more of these return types. If more than one of these
808 result types is specified, the result is returned as a CFDictionaryRef
809 whose keys are the result types and values are the requested data.
810 @constant kSecReturnData Specifies a dictionary key whose value is of type
811 CFBooleanRef. A value of kCFBooleanTrue indicates that the data of
812 an item (CFDataRef) should be returned. For keys and password
813 items, data is secret (encrypted) and may require the user to enter
814 a password for access.
815 @constant kSecReturnAttributes Specifies a dictionary key whose value is
816 of type CFBooleanRef. A value of kCFBooleanTrue indicates that the
817 (non-encrypted) attributes of an item (CFDictionaryRef) should be
819 @constant kSecReturnRef Specifies a dictionary key whose value is a
820 CFBooleanRef. A value of kCFBooleanTrue indicates that a reference
821 should be returned. Depending on the item class requested, the
822 returned reference(s) may be of type SecKeychainItemRef, SecKeyRef,
823 SecCertificateRef, or SecIdentityRef.
824 @constant kSecReturnPersistentRef Specifies a dictionary key whose value
825 is of type CFBooleanRef. A value of kCFBooleanTrue indicates that a
826 persistent reference to an item (CFDataRef) should be returned.
828 extern const CFStringRef kSecReturnData
829 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
830 extern const CFStringRef kSecReturnAttributes
831 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
832 extern const CFStringRef kSecReturnRef
833 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
834 extern const CFStringRef kSecReturnPersistentRef
835 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
839 @enum Value Type Key Constants
840 @discussion Predefined value type keys used to pass values in a dictionary.
841 You can specify zero or more of these types depending on the function
842 you are calling. For SecItemCopyMatching or SecItemAdd these are
843 used as keys in the results dictionary.
844 @constant kSecValueData Specifies a dictionary key whose value is of type
845 CFDataRef. For keys and password items, data is secret (encrypted)
846 and may require the user to enter a password for access.
847 @constant kSecValueRef Specifies a dictionary key whose value, depending
848 on the item class requested, is of type SecKeychainItemRef, SecKeyRef,
849 SecCertificateRef, or SecIdentityRef.
850 @constant kSecValuePersistentRef Specifies a dictionary key whose value
851 is of type CFDataRef. The bytes in this CFDataRef can be stored by
852 the caller and used on a subsequent invocation of the application (or
853 even a different application) to retrieve the item referenced by it.
855 extern const CFStringRef kSecValueData
856 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
857 extern const CFStringRef kSecValueRef
858 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
859 extern const CFStringRef kSecValuePersistentRef
860 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
864 @enum Other Constants
865 @discussion Predefined constants used to set values in a dictionary.
866 @constant kSecUseItemList Specifies a dictionary key whose value is a
867 CFArray of items. If provided, this array is treated as the set of
868 all possible items to search, or add if the API being called is
869 SecItemAdd. The items in this array may be of type SecKeyRef,
870 SecCertificateRef, SecIdentityRef, or CFDataRef (for a persistent
871 item reference.) The items in the array must all be of the same
872 type. When this attribute is provided, no keychains are searched.
873 @constant kSecUseOperationPrompt Specifies a dictionary key whose value
874 is a CFStringRef that represents a user-visible string describing
875 the operation for which the application is attempting to authenticate.
876 The application is responsible for the text localization.
877 @constant kSecUseNoAuthenticationUI Specifies a dictionary key whose value
878 is a CFBooleanRef. If provided with a value of kCFBooleanTrue, the error
879 errSecInteractionNotAllowed will be returned if the item is attempting
880 to authenticate with UI.
881 @constant kSecUseAuthenticationUI Specifies a dictionary key whose value
882 is one of kSecUseAuthenticationUIAllow, kSecUseAuthenticationUIFail, kSecUseAuthenticationUISkip.
883 @constant kSecUseAuthenticationContext Specifies a dictionary key whose value
884 is LAContext to be used for keychain item authentication.
885 * If the item requires authentication and this key is omitted, a new context
886 will be created just for the purpose of the single call.
887 * If the specified context has been previously authenticated, the operation
888 will succeed without asking user for authentication.
889 * If the specified context has not been previously authenticated, the new
890 authentication will be started on this context, allowing caller to
891 eventually reuse the sucessfully authenticated context in subsequent
894 extern const CFStringRef kSecUseItemList
895 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
896 extern const CFStringRef kSecUseOperationPrompt
897 __OSX_AVAILABLE_STARTING(__MAC_10_10
, __IPHONE_8_0
);
898 extern const CFStringRef kSecUseNoAuthenticationUI
899 __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_10
, __MAC_10_11
, __IPHONE_8_0
, __IPHONE_9_0
, "Use a kSecAuthenticationUI instead.");
900 extern const CFStringRef kSecUseAuthenticationUI
901 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
902 extern const CFStringRef kSecUseAuthenticationContext
903 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
906 @enum kSecUseAuthenticationUI Value Constants
907 @discussion Predefined item attribute constants used to get or set values
908 in a dictionary. The kSecUseAuthenticationUI constant is the key and its
909 value is one of the constants defined here.
910 If the key kSecUseAuthenticationUI not provided then kSecUseAuthenticationUIAllow
912 @constant kSecUseAuthenticationUIAllow Specifies that authenticate UI can appear.
913 @constant kSecUseAuthenticationUIFail Specifies that the error
914 errSecInteractionNotAllowed will be returned if an item needs
915 to authenticate with UI
916 @constant kSecUseAuthenticationUIAllowSkip Specifies that all items which need
917 to authenticate with UI will be silently skipped. This value can be used
918 only with SecItemCopyMatching.
920 extern const CFStringRef kSecUseAuthenticationUIAllow
921 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
922 extern const CFStringRef kSecUseAuthenticationUIFail
923 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
924 extern const CFStringRef kSecUseAuthenticationUISkip
925 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
928 @enum kSecAttrTokenID Value Constants
929 @discussion Predefined item attribute constant used to get or set values
930 in a dictionary. The kSecAttrTokenID constant is the key and its value
931 can be kSecAttrTokenIDSecureEnclave.
932 @constant kSecAttrTokenIDSecureEnclave Specifies well-known identifier of the
933 token implemented using device's Secure Enclave. The only keychain items
934 supported by the Secure Enclave token are 256-bit elliptic curve keys
935 (kSecAttrKeyTypeEC). Keys must be generated on the secure enclave using
936 SecKeyGenerateKeyPair call with kSecAttrTokenID set to
937 kSecAttrTokenIDSecureEnclave in the parameters dictionary, it is not
938 possible to import pregenerated keys to kSecAttrTokenIDSecureEnclave token.
940 extern const CFStringRef kSecAttrTokenIDSecureEnclave
941 __OSX_AVAILABLE_STARTING(__MAC_NA
, __IPHONE_9_0
);
944 @function SecItemCopyMatching
945 @abstract Returns one or more items which match a search query.
946 @param query A dictionary containing an item class specification and
947 optional attributes for controlling the search. See the "Keychain
948 Search Attributes" section for a description of currently defined
950 @param result On return, a CFTypeRef reference to the found item(s). The
951 exact type of the result is based on the search attributes supplied
952 in the query, as discussed below.
953 @result A result code. See "Security Error Codes" (SecBase.h).
954 @discussion Attributes defining a search are specified by adding key/value
955 pairs to the query dictionary.
957 A typical query consists of:
959 * a kSecClass key, whose value is a constant from the Class
960 Constants section that specifies the class of item(s) to be searched
961 * one or more keys from the "Attribute Key Constants" section, whose value
962 is the attribute data to be matched
963 * one or more keys from the "Search Constants" section, whose value is
964 used to further refine the search
965 * a key from the "Return Type Key Constants" section, specifying the type of
968 Result types are specified as follows:
970 * To obtain the data of a matching item (CFDataRef), specify
971 kSecReturnData with a value of kCFBooleanTrue.
972 * To obtain the attributes of a matching item (CFDictionaryRef), specify
973 kSecReturnAttributes with a value of kCFBooleanTrue.
974 * To obtain a reference to a matching item (SecKeychainItemRef,
975 SecKeyRef, SecCertificateRef, or SecIdentityRef), specify kSecReturnRef
976 with a value of kCFBooleanTrue.
977 * To obtain a persistent reference to a matching item (CFDataRef),
978 specify kSecReturnPersistentRef with a value of kCFBooleanTrue. Note
979 that unlike normal references, a persistent reference may be stored
980 on disk or passed between processes.
981 * If more than one of these result types is specified, the result is
982 returned as a CFDictionaryRef containing all the requested data.
983 * If a result type is not specified, no results are returned.
985 By default, this function returns only the first match found. To obtain
986 more than one matching item at a time, specify kSecMatchLimit with a value
987 greater than 1. The result will be a CFArrayRef containing up to that
988 number of matching items; the items' types are described above.
990 To filter a provided list of items down to those matching the query,
991 specify a kSecMatchItemList whose value is a CFArray of SecKeychainItemRef,
992 SecKeyRef, SecCertificateRef, or SecIdentityRef items. The objects in the
993 provided array must be of the same type.
995 To convert from a persistent item reference to a normal item reference,
996 specify a kSecValuePersistentRef whose value a CFDataRef (the persistent
997 reference), and a kSecReturnRef whose value is kCFBooleanTrue.
999 OSStatus
SecItemCopyMatching(CFDictionaryRef query
, CFTypeRef
* __nullable CF_RETURNS_RETAINED result
)
1000 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
1003 @function SecItemAdd
1004 @abstract Add one or more items to a keychain.
1005 @param attributes A dictionary containing an item class specification and
1006 optional entries specifying the item's attribute values. See the
1007 "Attribute Key Constants" section for a description of currently defined
1009 @param result On return, a CFTypeRef reference to the newly added item(s).
1010 The exact type of the result is based on the values supplied
1011 in attributes, as discussed below. Pass NULL if this result is not
1013 @result A result code. See "Security Error Codes" (SecBase.h).
1014 @discussion Attributes defining an item are specified by adding key/value
1015 pairs to the attributes dictionary. To add multiple items to a keychain
1016 at once use the kSecUseItemList key with an array of items as its value.
1017 This is currently only supported for non password items.
1019 Result types are specified as follows:
1021 * To obtain the data of the added item (CFDataRef), specify
1022 kSecReturnData with a value of kCFBooleanTrue.
1023 * To obtain all the attributes of the added item (CFDictionaryRef),
1024 specify kSecReturnAttributes with a value of kCFBooleanTrue.
1025 * To obtain a reference to the added item (SecKeychainItemRef, SecKeyRef,
1026 SecCertificateRef, or SecIdentityRef), specify kSecReturnRef with a
1027 value of kCFBooleanTrue.
1028 * To obtain a persistent reference to the added item (CFDataRef), specify
1029 kSecReturnPersistentRef with a value of kCFBooleanTrue. Note that
1030 unlike normal references, a persistent reference may be stored on disk
1031 or passed between processes.
1032 * If more than one of these result types is specified, the result is
1033 returned as a CFDictionaryRef containing all the requested data.
1034 * If a result type is not specified, no results are returned.
1036 OSStatus
SecItemAdd(CFDictionaryRef attributes
, CFTypeRef
* __nullable CF_RETURNS_RETAINED result
)
1037 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
1040 @function SecItemUpdate
1041 @abstract Modify zero or more items which match a search query.
1042 @param query A dictionary containing an item class specification and
1043 optional attributes for controlling the search. See the "Attribute
1044 Constants" and "Search Constants" sections for a description of
1045 currently defined search attributes.
1046 @param attributesToUpdate A dictionary containing one or more attributes
1047 whose values should be set to the ones specified. Only real keychain
1048 attributes are permitted in this dictionary (no "meta" attributes are
1049 allowed.) See the "Attribute Key Constants" section for a description of
1050 currently defined value attributes.
1051 @result A result code. See "Security Error Codes" (SecBase.h).
1052 @discussion Attributes defining a search are specified by adding key/value
1053 pairs to the query dictionary.
1055 OSStatus
SecItemUpdate(CFDictionaryRef query
,
1056 CFDictionaryRef attributesToUpdate
)
1057 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
1060 @function SecItemDelete
1061 @abstract Delete zero or more items which match a search query.
1062 @param query A dictionary containing an item class specification and
1063 optional attributes for controlling the search. See the "Attribute
1064 Constants" and "Search Constants" sections for a description of
1065 currently defined search attributes.
1066 @result A result code. See "Security Error Codes" (SecBase.h).
1067 @discussion Attributes defining a search are specified by adding key/value
1068 pairs to the query dictionary.
1070 By default, this function deletes all items matching the specified query.
1071 You can change this behavior by specifying one of the follow keys:
1073 * To delete an item identified by a transient reference, specify
1074 kSecValueRef with a reference returned by using the kSecReturnRef
1075 key in a previous call to SecItemCopyMatching or SecItemAdd.
1076 * To delete an item identified by a persistent reference, specify
1077 kSecValuePersistentRef with a persistent reference returned by
1078 using the kSecReturnPersistentRef key to SecItemCopyMatching or
1080 * To delete multiple items specify kSecMatchItemList with an array
1082 * If more than one of these result keys is specified, the behavior is
1085 OSStatus
SecItemDelete(CFDictionaryRef query
)
1086 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
1088 CF_IMPLICIT_BRIDGING_DISABLED
1089 CF_ASSUME_NONNULL_END
1093 #endif /* !_SECURITY_SECITEM_H_ */