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/CFNumber.h>
36 #include <CoreFoundation/CFArray.h>
37 #include <CoreFoundation/CFDictionary.h>
41 CF_ASSUME_NONNULL_BEGIN
42 CF_IMPLICIT_BRIDGING_ENABLED
45 @enum Class Key Constant
46 @discussion Predefined key constant used to get or set item class values in
47 a dictionary. Its value is one of the constants defined in the Value
48 Constants for kSecClass.
49 @constant kSecClass Specifies a dictionary key whose value is the item's
50 class code. You use this key to get or set a value of type CFTypeRef
51 that contains the item class code.
53 extern const CFStringRef kSecClass
54 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
57 @enum Class Value Constants
58 @discussion Predefined item class constants used to get or set values in
59 a dictionary. The kSecClass constant is the key and its value is one
60 of the constants defined here. Note: on Mac OS X 10.6, only items
61 of class kSecClassInternetPassword are supported.
62 @constant kSecClassInternetPassword Specifies Internet password items.
63 @constant kSecClassGenericPassword Specifies generic password items.
64 @constant kSecClassCertificate Specifies certificate items.
65 @constant kSecClassKey Specifies key items.
66 @constant kSecClassIdentity Specifies identity items.
68 extern const CFStringRef kSecClassInternetPassword
69 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
70 extern const CFStringRef kSecClassGenericPassword
71 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
72 extern const CFStringRef kSecClassCertificate
73 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
74 extern const CFStringRef kSecClassKey
75 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
76 extern const CFStringRef kSecClassIdentity
77 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
80 @enum Attribute Key Constants
81 @discussion Predefined item attribute keys used to get or set values in a
82 dictionary. Not all attributes apply to each item class. The table
83 below lists the currently defined attributes for each item class:
85 kSecClassGenericPassword item attributes:
86 kSecAttrAccess (OS X only)
88 kSecAttrAccessGroup (iOS; also OS X if kSecAttrSynchronizable specified)
89 kSecAttrAccessible (iOS; also OS X if kSecAttrSynchronizable specified)
91 kSecAttrModificationDate
102 kSecAttrSynchronizable
104 kSecClassInternetPassword item attributes:
105 kSecAttrAccess (OS X only)
106 kSecAttrAccessControl
107 kSecAttrAccessGroup (iOS; also OS X if kSecAttrSynchronizable specified)
108 kSecAttrAccessible (iOS; also OS X if kSecAttrSynchronizable specified)
110 kSecAttrModificationDate
119 kSecAttrSecurityDomain
122 kSecAttrAuthenticationType
125 kSecAttrSynchronizable
127 kSecClassCertificate item attributes:
128 kSecAttrAccessible (iOS only)
129 kSecAttrAccessControl (iOS only)
130 kSecAttrAccessGroup (iOS only)
131 kSecAttrCertificateType
132 kSecAttrCertificateEncoding
138 kSecAttrPublicKeyHash
139 kSecAttrSynchronizable
141 kSecClassKey item attributes:
142 kSecAttrAccess (OS X only)
143 kSecAttrAccessControl
144 kSecAttrAccessGroup (iOS; also OS X if kSecAttrSynchronizable specified)
145 kSecAttrAccessible (iOS; also OS X if kSecAttrSynchronizable specified)
148 kSecAttrApplicationLabel
150 kSecAttrApplicationTag
152 kSecAttrPRF (iOS only)
153 kSecAttrSalt (iOS only)
154 kSecAttrRounds (iOS only)
155 kSecAttrKeySizeInBits
156 kSecAttrEffectiveKeySize
164 kSecAttrSynchronizable
166 Note that the attributes kSecAttrCan* describe attributes of the
167 key itself at relatively high level. Some of these attributes are
168 mathematical -- for example, a DSA key cannot encrypt. Others are
169 key-level policy issues -- for example, it is good cryptographic
170 hygiene to use an RSA key either for encryption or signing but not
171 both. Compare these to the certificate-level policy values in
174 kSecClassIdentity item attributes:
175 Since an identity is the combination of a private key and a
176 certificate, this class shares attributes of both kSecClassKey and
177 kSecClassCertificate.
179 @constant kSecAttrAccessible Specifies a dictionary key whose value
180 indicates when your application needs access to an item's data. You
181 should choose the most restrictive option that meets your application's
182 needs to allow the system to protect that item in the best way possible.
183 See the "kSecAttrAccessible Value Constants" section for a list of
184 values which can be specified.
185 IMPORTANT: This attribute is currently not supported for OS X keychain
186 items, unless the kSecAttrSynchronizable attribute is also present. If
187 both attributes are specified on either OS X or iOS, the value for the
188 kSecAttrAccessible key may only be one whose name does not end with
189 "ThisDeviceOnly", as those cannot sync to another device.
191 @constant kSecAttrAccessControl Specifies a dictionary key whose value
192 is SecAccessControl instance which contains access control conditions
194 IMPORTANT: This attribute is mutually exclusive with kSecAttrAccess
197 @constant kSecAttrAccess Specifies a dictionary key whose value
198 is a SecAccessRef describing the access control settings for this item.
199 This key is available on OS X only.
201 @constant kSecAttrAccessGroup Specifies a dictionary key whose value is
202 a CFStringRef indicating which access group a item is in. The access
203 groups that a particular application has membership in are determined by
204 two entitlements for that application. The application-identifier
205 entitlement contains the application's single access group, unless
206 there is a keychain-access-groups entitlement present. The latter
207 has as its value a list of access groups; the first item in this list
208 is the default access group. Unless a specific access group is provided
209 as the value of kSecAttrAccessGroup when SecItemAdd is called, new items
210 are created in the application's default access group. Specifying this
211 attribute in SecItemCopyMatching, SecItemUpdate, or SecItemDelete calls
212 limits the search to the specified access group (of which the calling
213 application must be a member to obtain matching results.) To share
214 keychain items between multiple applications, each application must have
215 a common group listed in its keychain-access-groups entitlement, and each
216 must specify this shared access group name as the value for the
217 kSecAttrAccessGroup key in the dictionary passed to SecItem functions.
219 @constant kSecAttrSynchronizable Specifies a dictionary key whose value is
220 a CFBooleanRef indicating whether the item in question can be synchronized.
221 To add a new item which can be synced to other devices, or to obtain
222 synchronizable results from a query, supply this key with a value of
223 kCFBooleanTrue. If the key is not supplied, or has a value of
224 kCFBooleanFalse, then no synchronizable items will be added or returned.
225 A predefined value, kSecAttrSynchronizableAny, may be provided instead of
226 kCFBooleanTrue if both synchronizable and non-synchronizable results are
229 IMPORTANT: Specifying the kSecAttrSynchronizable key has several caveats:
231 - Updating or deleting items using the kSecAttrSynchronizable key will
232 affect all copies of the item, not just the one on your local device.
233 Be sure that it makes sense to use the same password on all devices
234 before deciding to make a password synchronizable.
235 - Only password items can currently be synchronized. Keychain syncing
236 is not supported for certificates or cryptographic keys.
237 - Items stored or obtained using the kSecAttrSynchronizable key cannot
238 specify SecAccessRef-based access control with kSecAttrAccess. If a
239 password is intended to be shared between multiple applications, the
240 kSecAttrAccessGroup key must be specified, and each application
241 using this password must have a 'keychain-access-groups' entitlement
242 with the specified access group value.
243 - Items stored or obtained using the kSecAttrSynchronizable key may
244 not also specify a kSecAttrAccessible value which is incompatible
245 with syncing (namely, those whose names end with "ThisDeviceOnly".)
246 - Items stored or obtained using the kSecAttrSynchronizable key cannot
247 be specified by reference. You must pass kSecReturnAttributes and/or
248 kSecReturnData to retrieve results; kSecReturnRef is currently not
249 supported for synchronizable items.
250 - Persistent references to synchronizable items should be avoided;
251 while they may work locally, they cannot be moved between devices,
252 and may not resolve if the item is modified on some other device.
253 - When specifying a query that uses the kSecAttrSynchronizable key,
254 search keys are limited to the item's class and attributes.
255 The only search constant which may be used is kSecMatchLimit; other
256 constants using the kSecMatch prefix are not supported at this time.
258 @constant kSecAttrSynchronizableAny Specifies that both synchronizable and
259 non-synchronizable results should be returned from this query. This may be
260 used as a value for the kSecAttrSynchronizable dictionary key in a call to
261 SecItemCopyMatching, SecItemUpdate, or SecItemDelete.
263 @constant kSecAttrCreationDate (read-only) Specifies a dictionary key whose
264 value is the item's creation date. You use this key to get a value
265 of type CFDateRef that represents the date the item was created.
266 @constant kSecAttrModificationDate (read-only) Specifies a dictionary key
267 whose value is the item's modification date. You use this key to get
268 a value of type CFDateRef that represents the last time the item was
270 @constant kSecAttrDescription Specifies a dictionary key whose value is
271 the item's description attribute. You use this key to set or get a
272 value of type CFStringRef that represents a user-visible string
273 describing this particular kind of item (e.g., "disk image password").
274 @constant kSecAttrComment Specifies a dictionary key whose value is the
275 item's comment attribute. You use this key to set or get a value of
276 type CFStringRef containing the user-editable comment for this item.
277 @constant kSecAttrCreator Specifies a dictionary key whose value is the
278 item's creator attribute. You use this key to set or get a value of
279 type CFNumberRef that represents the item's creator. This number is
280 the unsigned integer representation of a four-character code (e.g.,
282 @constant kSecAttrType Specifies a dictionary key whose value is the item's
283 type attribute. You use this key to set or get a value of type
284 CFNumberRef that represents the item's type. This number is the
285 unsigned integer representation of a four-character code (e.g.,
287 @constant kSecAttrLabel Specifies a dictionary key whose value is the
288 item's label attribute. You use this key to set or get a value of
289 type CFStringRef containing the user-visible label for this item.
290 @constant kSecAttrIsInvisible Specifies a dictionary key whose value is the
291 item's invisible attribute. You use this key to set or get a value
292 of type CFBooleanRef that indicates whether the item is invisible
293 (i.e., should not be displayed.)
294 @constant kSecAttrIsNegative Specifies a dictionary key whose value is the
295 item's negative attribute. You use this key to set or get a value of
296 type CFBooleanRef that indicates whether there is a valid password
297 associated with this keychain item. This is useful if your application
298 doesn't want a password for some particular service to be stored in
299 the keychain, but prefers that it always be entered by the user.
300 @constant kSecAttrAccount Specifies a dictionary key whose value is the
301 item's account attribute. You use this key to set or get a CFStringRef
302 that contains an account name. (Items of class
303 kSecClassGenericPassword, kSecClassInternetPassword have this
305 @constant kSecAttrService Specifies a dictionary key whose value is the
306 item's service attribute. You use this key to set or get a CFStringRef
307 that represents the service associated with this item. (Items of class
308 kSecClassGenericPassword have this attribute.)
309 @constant kSecAttrGeneric Specifies a dictionary key whose value is the
310 item's generic attribute. You use this key to set or get a value of
311 CFDataRef that contains a user-defined attribute. (Items of class
312 kSecClassGenericPassword have this attribute.)
313 @constant kSecAttrSecurityDomain Specifies a dictionary key whose value
314 is the item's security domain attribute. You use this key to set or
315 get a CFStringRef value that represents the Internet security domain.
316 (Items of class kSecClassInternetPassword have this attribute.)
317 @constant kSecAttrServer Specifies a dictionary key whose value is the
318 item's server attribute. You use this key to set or get a value of
319 type CFStringRef that contains the server's domain name or IP address.
320 (Items of class kSecClassInternetPassword have this attribute.)
321 @constant kSecAttrProtocol Specifies a dictionary key whose value is the
322 item's protocol attribute. You use this key to set or get a value of
323 type CFNumberRef that denotes the protocol for this item (see the
324 SecProtocolType enum in SecKeychainItem.h). (Items of class
325 kSecClassInternetPassword have this attribute.)
326 @constant kSecAttrAuthenticationType Specifies a dictionary key whose value
327 is the item's authentication type attribute. You use this key to set
328 or get a value of type CFNumberRef that denotes the authentication
329 scheme for this item (see the kSecAttrAuthenticationType value
331 @constant kSecAttrPort Specifies a dictionary key whose value is the item's
332 port attribute. You use this key to set or get a CFNumberRef value
333 that represents an Internet port number. (Items of class
334 kSecClassInternetPassword have this attribute.)
335 @constant kSecAttrPath Specifies a dictionary key whose value is the item's
336 path attribute, typically this is the path component of the URL. You use
337 this key to set or get a CFStringRef value that represents a path. (Items
338 of class kSecClassInternetPassword have this attribute.)
339 @constant kSecAttrSubject (read-only) Specifies a dictionary key whose
340 value is the item's subject. You use this key to get a value of type
341 CFDataRef that contains the X.500 subject name of a certificate.
342 (Items of class kSecClassCertificate have this attribute.)
343 @constant kSecAttrIssuer (read-only) Specifies a dictionary key whose value
344 is the item's issuer. You use this key to get a value of type
345 CFDataRef that contains the X.500 issuer name of a certificate. (Items
346 of class kSecClassCertificate have this attribute.)
347 @constant kSecAttrSerialNumber (read-only) Specifies a dictionary key whose
348 value is the item's serial number. You use this key to get a value
349 of type CFDataRef that contains the serial number data of a
350 certificate. (Items of class kSecClassCertificate have this
352 @constant kSecAttrSubjectKeyID (read-only) Specifies a dictionary key whose
353 value is the item's subject key ID. You use this key to get a value
354 of type CFDataRef that contains the subject key ID of a certificate.
355 (Items of class kSecClassCertificate have this attribute.)
356 @constant kSecAttrPublicKeyHash (read-only) Specifies a dictionary key
357 whose value is the item's public key hash. You use this key to get a
358 value of type CFDataRef that contains the hash of a certificate's
359 public key. (Items of class kSecClassCertificate have this attribute.)
360 @constant kSecAttrCertificateType (read-only) Specifies a dictionary key
361 whose value is the item's certificate type. You use this key to get
362 a value of type CFNumberRef that denotes the certificate type
363 (On iOS, currently the value of this attribute must be equal to the
364 version of the X509 certificate. So, 1 for v1, 2 for v2, and 3 for v3
365 certificates). (On OSX, see the CSSM_CERT_TYPE enum in cssmtype.h).
366 Only items of class kSecClassCertificate have this attribute.
367 @constant kSecAttrCertificateEncoding (read-only) Specifies a dictionary
368 key whose value is the item's certificate encoding. You use this key
369 to get a value of type CFNumberRef that denotes the certificate
370 encoding (On iOS, currently only the value 3 meaning
371 kSecAttrCertificateEncodingDER is supported). On OSX, see the
372 CSSM_CERT_ENCODING enum in cssmtype.h. Only items of class
373 kSecClassCertificate have this attribute.
374 @constant kSecAttrKeyClass (read only) Specifies a dictionary key whose
375 value is one of kSecAttrKeyClassPublic, kSecAttrKeyClassPrivate or
376 kSecAttrKeyClassSymmetric.
377 @constant kSecAttrApplicationLabel Specifies a dictionary key whose value
378 is the key's application label attribute. This is different from the
379 kSecAttrLabel (which is intended to be human-readable). This attribute
380 is used to look up a key programmatically; in particular, for keys of
381 class kSecAttrKeyClassPublic and kSecAttrKeyClassPrivate, the value of
382 this attribute is the hash of the public key. This item is a type of CFDataRef.
383 Legacy keys may contain a UUID in this field as a CFStringRef.
384 @constant kSecAttrIsPermanent Specifies a dictionary key whose value is a
385 CFBooleanRef indicating whether the key in question will be stored
387 @constant kSecAttrIsSensitive Specifies a dictionary key whose value is a
388 CFBooleanRef indicating that the key in question can only be exported
389 in a wrapped (encrypted) format. OS X only.
390 @constant kSecAttrIsExtractable Specifies a dictionary key whose value is a
391 CFBooleanRef indicating whether the key in question can be exported from
392 its keychain container. OS X only.
393 @constant kSecAttrApplicationTag Specifies a dictionary key whose value is a
394 CFDataRef containing private tag data.
395 @constant kSecAttrKeyType Specifies a dictionary key whose value is a
396 CFNumberRef indicating the algorithm associated with this key
397 (On iOS, currently only the value 42 is supported, alternatively you can use
398 kSecAttrKeyTypeRSA). (On OSX, see the CSSM_ALGORITHMS enum in cssmtype.h).
400 @constant kSecAttrPRF Specifies a dictionary key whose value is the PRF
401 (pseudo-random function) for this key (see "kSecAttrPRF Value Constants".)
403 @constant kSecAttrSalt Specifies a dictionary key whose value is a
404 CFData containing the salt to use for this key. iOS only.
405 @constant kSecAttrRounds Specifies a dictionary key whose value is the
406 number of rounds for the pseudo-random function specified by kSecAttrPRF.
408 @constant kSecAttrKeySizeInBits Specifies a dictionary key whose value
409 is a CFNumberRef indicating the number of bits in this key.
410 @constant kSecAttrEffectiveKeySize Specifies a dictionary key whose value
411 is a CFNumberRef indicating the effective number of bits in this key.
412 For example, a DES key has a kSecAttrKeySizeInBits of 64, but a
413 kSecAttrEffectiveKeySize of 56 bits.
414 @constant kSecAttrCanEncrypt Specifies a dictionary key whole value is a
415 CFBooleanRef indicating whether the key in question can be used to
417 @constant kSecAttrCanDecrypt Specifies a dictionary key whose value is a
418 CFBooleanRef indicating whether the key in question can be used to
420 @constant kSecAttrCanDerive Specifies a dictionary key whole value is a
421 CFBooleanRef indicating whether the key in question can be used to
423 @constant kSecAttrCanSign Specifies a dictionary key whole value is a
424 CFBooleanRef indicating whether the key in question can be used to
425 create a digital signature.
426 @constant kSecAttrCanVerify Specifies a dictionary key whole value is a
427 CFBooleanRef indicating whether the key in question can be used to
428 verify a digital signature.
429 @constant kSecAttrCanWrap Specifies a dictionary key whole value is a
430 CFBooleanRef indicating whether the key in question can be used to
432 @constant kSecAttrCanUnwrap Specifies a dictionary key whole value is a
433 CFBooleanRef indicating whether the key in question can be used to
435 @constant kSecAttrSyncViewHint Specifies a dictionary key whose value is
436 a CFStringRef. This value is part of the primary key of each item, and
437 can be used to help distiguish Sync Views when defining their
438 queries. iOS and sychronizable items only.
439 @constant kSecAttrTokenID Specifies a dictionary key whose presence
440 indicates that item is backed by external token. Value of this attribute
441 is CFStringRef uniquely identifying containing token. When this attribute
442 is not present, item is stored in internal keychain database.
443 Note that once item is created, this attribute cannot be changed - in other
444 words it is not possible to migrate existing items to, from or between tokens.
445 Currently the only available value for this attribute is
446 kSecAttrTokenIDSecureEnclave, which indicates that item (private key) is
447 backed by device's Secure Enclave. iOS only.
449 extern const CFStringRef kSecAttrAccessible
450 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
451 extern const CFStringRef kSecAttrAccess
452 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
453 extern const CFStringRef kSecAttrAccessControl
454 __OSX_AVAILABLE_STARTING(__MAC_10_10
, __IPHONE_8_0
);
455 extern const CFStringRef kSecAttrAccessGroup
456 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_3_0
);
457 extern const CFStringRef kSecAttrSynchronizable
458 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_7_0
);
459 extern const CFStringRef kSecAttrSynchronizableAny
460 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_7_0
);
461 extern const CFStringRef kSecAttrCreationDate
462 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
463 extern const CFStringRef kSecAttrModificationDate
464 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
465 extern const CFStringRef kSecAttrDescription
466 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
467 extern const CFStringRef kSecAttrComment
468 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
469 extern const CFStringRef kSecAttrCreator
470 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
471 extern const CFStringRef kSecAttrType
472 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
473 extern const CFStringRef kSecAttrLabel
474 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
475 extern const CFStringRef kSecAttrIsInvisible
476 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
477 extern const CFStringRef kSecAttrIsNegative
478 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
479 extern const CFStringRef kSecAttrAccount
480 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
481 extern const CFStringRef kSecAttrService
482 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
483 extern const CFStringRef kSecAttrGeneric
484 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
485 extern const CFStringRef kSecAttrSecurityDomain
486 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
487 extern const CFStringRef kSecAttrServer
488 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
489 extern const CFStringRef kSecAttrProtocol
490 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
491 extern const CFStringRef kSecAttrAuthenticationType
492 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
493 extern const CFStringRef kSecAttrPort
494 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
495 extern const CFStringRef kSecAttrPath
496 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
497 extern const CFStringRef kSecAttrSubject
498 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
499 extern const CFStringRef kSecAttrIssuer
500 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
501 extern const CFStringRef kSecAttrSerialNumber
502 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
503 extern const CFStringRef kSecAttrSubjectKeyID
504 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
505 extern const CFStringRef kSecAttrPublicKeyHash
506 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
507 extern const CFStringRef kSecAttrCertificateType
508 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
509 extern const CFStringRef kSecAttrCertificateEncoding
510 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
511 extern const CFStringRef kSecAttrKeyClass
512 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
513 extern const CFStringRef kSecAttrApplicationLabel
514 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
515 extern const CFStringRef kSecAttrIsPermanent
516 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
517 extern const CFStringRef kSecAttrIsSensitive
518 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
519 extern const CFStringRef kSecAttrIsExtractable
520 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
521 extern const CFStringRef kSecAttrApplicationTag
522 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
523 extern const CFStringRef kSecAttrKeyType
524 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
525 extern const CFStringRef kSecAttrPRF
526 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
527 extern const CFStringRef kSecAttrSalt
528 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
529 extern const CFStringRef kSecAttrRounds
530 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
531 extern const CFStringRef kSecAttrKeySizeInBits
532 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
533 extern const CFStringRef kSecAttrEffectiveKeySize
534 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
535 extern const CFStringRef kSecAttrCanEncrypt
536 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
537 extern const CFStringRef kSecAttrCanDecrypt
538 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
539 extern const CFStringRef kSecAttrCanDerive
540 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
541 extern const CFStringRef kSecAttrCanSign
542 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
543 extern const CFStringRef kSecAttrCanVerify
544 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
545 extern const CFStringRef kSecAttrCanWrap
546 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
547 extern const CFStringRef kSecAttrCanUnwrap
548 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
549 extern const CFStringRef kSecAttrSyncViewHint
550 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
551 extern const CFStringRef kSecAttrTokenID
552 __OSX_AVAILABLE_STARTING(__MAC_10_12
, __IPHONE_9_0
);
555 @enum kSecAttrAccessible Value Constants
556 @discussion Predefined item attribute constants used to get or set values
557 in a dictionary. The kSecAttrAccessible constant is the key and its
558 value is one of the constants defined here.
559 When asking SecItemCopyMatching to return the item's data, the error
560 errSecInteractionNotAllowed will be returned if the item's data is not
561 available until a device unlock occurs.
562 @constant kSecAttrAccessibleWhenUnlocked Item data can only be accessed
563 while the device is unlocked. This is recommended for items that only
564 need be accesible while the application is in the foreground. Items
565 with this attribute will migrate to a new device when using encrypted
567 @constant kSecAttrAccessibleAfterFirstUnlock Item data can only be
568 accessed once the device has been unlocked after a restart. This is
569 recommended for items that need to be accesible by background
570 applications. Items with this attribute will migrate to a new device
571 when using encrypted backups.
572 @constant kSecAttrAccessibleAlways Item data can always be accessed
573 regardless of the lock state of the device. This is not recommended
574 for anything except system use. Items with this attribute will migrate
575 to a new device when using encrypted backups.
576 @constant kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly Item data can
577 only be accessed while the device is unlocked. This is recommended for
578 items that only need to be accessible while the application is in the
579 foreground and requires a passcode to be set on the device. Items with
580 this attribute will never migrate to a new device, so after a backup
581 is restored to a new device, these items will be missing. This
582 attribute will not be available on devices without a passcode. Disabling
583 the device passcode will cause all previously protected items to
585 @constant kSecAttrAccessibleWhenUnlockedThisDeviceOnly Item data can only
586 be accessed while the device is unlocked. This is recommended for items
587 that only need be accesible while the application is in the foreground.
588 Items with this attribute will never migrate to a new device, so after
589 a backup is restored to a new device, these items will be missing.
590 @constant kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly Item data can
591 only be accessed once the device has been unlocked after a restart.
592 This is recommended for items that need to be accessible by background
593 applications. Items with this attribute will never migrate to a new
594 device, so after a backup is restored to a new device these items will
596 @constant kSecAttrAccessibleAlwaysThisDeviceOnly Item data can always
597 be accessed regardless of the lock state of the device. This option
598 is not recommended for anything except system use. Items with this
599 attribute will never migrate to a new device, so after a backup is
600 restored to a new device, these items will be missing.
602 extern const CFStringRef kSecAttrAccessibleWhenUnlocked
603 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
604 extern const CFStringRef kSecAttrAccessibleAfterFirstUnlock
605 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
606 extern const CFStringRef kSecAttrAccessibleAlways
607 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
608 extern const CFStringRef kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly
609 __OSX_AVAILABLE_STARTING(__MAC_10_10
, __IPHONE_8_0
);
610 extern const CFStringRef kSecAttrAccessibleWhenUnlockedThisDeviceOnly
611 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
612 extern const CFStringRef kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
613 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
614 extern const CFStringRef kSecAttrAccessibleAlwaysThisDeviceOnly
615 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
618 @enum kSecAttrProtocol Value Constants
619 @discussion Predefined item attribute constants used to get or set values
620 in a dictionary. The kSecAttrProtocol constant is the key and its
621 value is one of the constants defined here.
622 @constant kSecAttrProtocolFTP.
623 @constant kSecAttrProtocolFTPAccount.
624 @constant kSecAttrProtocolHTTP.
625 @constant kSecAttrProtocolIRC.
626 @constant kSecAttrProtocolNNTP.
627 @constant kSecAttrProtocolPOP3.
628 @constant kSecAttrProtocolSMTP.
629 @constant kSecAttrProtocolSOCKS.
630 @constant kSecAttrProtocolIMAP.
631 @constant kSecAttrProtocolLDAP.
632 @constant kSecAttrProtocolAppleTalk.
633 @constant kSecAttrProtocolAFP.
634 @constant kSecAttrProtocolTelnet.
635 @constant kSecAttrProtocolSSH.
636 @constant kSecAttrProtocolFTPS.
637 @constant kSecAttrProtocolHTTPS.
638 @constant kSecAttrProtocolHTTPProxy.
639 @constant kSecAttrProtocolHTTPSProxy.
640 @constant kSecAttrProtocolFTPProxy.
641 @constant kSecAttrProtocolSMB.
642 @constant kSecAttrProtocolRTSP.
643 @constant kSecAttrProtocolRTSPProxy.
644 @constant kSecAttrProtocolDAAP.
645 @constant kSecAttrProtocolEPPC.
646 @constant kSecAttrProtocolIPP.
647 @constant kSecAttrProtocolNNTPS.
648 @constant kSecAttrProtocolLDAPS.
649 @constant kSecAttrProtocolTelnetS.
650 @constant kSecAttrProtocolIMAPS.
651 @constant kSecAttrProtocolIRCS.
652 @constant kSecAttrProtocolPOP3S.
654 extern const CFStringRef kSecAttrProtocolFTP
655 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
656 extern const CFStringRef kSecAttrProtocolFTPAccount
657 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
658 extern const CFStringRef kSecAttrProtocolHTTP
659 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
660 extern const CFStringRef kSecAttrProtocolIRC
661 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
662 extern const CFStringRef kSecAttrProtocolNNTP
663 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
664 extern const CFStringRef kSecAttrProtocolPOP3
665 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
666 extern const CFStringRef kSecAttrProtocolSMTP
667 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
668 extern const CFStringRef kSecAttrProtocolSOCKS
669 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
670 extern const CFStringRef kSecAttrProtocolIMAP
671 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
672 extern const CFStringRef kSecAttrProtocolLDAP
673 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
674 extern const CFStringRef kSecAttrProtocolAppleTalk
675 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
676 extern const CFStringRef kSecAttrProtocolAFP
677 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
678 extern const CFStringRef kSecAttrProtocolTelnet
679 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
680 extern const CFStringRef kSecAttrProtocolSSH
681 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
682 extern const CFStringRef kSecAttrProtocolFTPS
683 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
684 extern const CFStringRef kSecAttrProtocolHTTPS
685 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
686 extern const CFStringRef kSecAttrProtocolHTTPProxy
687 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
688 extern const CFStringRef kSecAttrProtocolHTTPSProxy
689 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
690 extern const CFStringRef kSecAttrProtocolFTPProxy
691 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
692 extern const CFStringRef kSecAttrProtocolSMB
693 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
694 extern const CFStringRef kSecAttrProtocolRTSP
695 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
696 extern const CFStringRef kSecAttrProtocolRTSPProxy
697 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
698 extern const CFStringRef kSecAttrProtocolDAAP
699 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
700 extern const CFStringRef kSecAttrProtocolEPPC
701 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
702 extern const CFStringRef kSecAttrProtocolIPP
703 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
704 extern const CFStringRef kSecAttrProtocolNNTPS
705 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
706 extern const CFStringRef kSecAttrProtocolLDAPS
707 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
708 extern const CFStringRef kSecAttrProtocolTelnetS
709 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
710 extern const CFStringRef kSecAttrProtocolIMAPS
711 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
712 extern const CFStringRef kSecAttrProtocolIRCS
713 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
714 extern const CFStringRef kSecAttrProtocolPOP3S
715 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
718 @enum kSecAttrAuthenticationType Value Constants
719 @discussion Predefined item attribute constants used to get or set values
720 in a dictionary. The kSecAttrAuthenticationType constant is the key
721 and its value is one of the constants defined here.
722 @constant kSecAttrAuthenticationTypeNTLM.
723 @constant kSecAttrAuthenticationTypeMSN.
724 @constant kSecAttrAuthenticationTypeDPA.
725 @constant kSecAttrAuthenticationTypeRPA.
726 @constant kSecAttrAuthenticationTypeHTTPBasic.
727 @constant kSecAttrAuthenticationTypeHTTPDigest.
728 @constant kSecAttrAuthenticationTypeHTMLForm.
729 @constant kSecAttrAuthenticationTypeDefault.
731 extern const CFStringRef kSecAttrAuthenticationTypeNTLM
732 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
733 extern const CFStringRef kSecAttrAuthenticationTypeMSN
734 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
735 extern const CFStringRef kSecAttrAuthenticationTypeDPA
736 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
737 extern const CFStringRef kSecAttrAuthenticationTypeRPA
738 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
739 extern const CFStringRef kSecAttrAuthenticationTypeHTTPBasic
740 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
741 extern const CFStringRef kSecAttrAuthenticationTypeHTTPDigest
742 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
743 extern const CFStringRef kSecAttrAuthenticationTypeHTMLForm
744 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
745 extern const CFStringRef kSecAttrAuthenticationTypeDefault
746 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
749 @enum kSecAttrKeyClass Value Constants
750 @discussion Predefined item attribute constants used to get or set values
751 in a dictionary. The kSecAttrKeyClass constant is the key
752 and its value is one of the constants defined here.
753 @constant kSecAttrKeyClassPublic.
754 @constant kSecAttrKeyClassPrivate.
755 @constant kSecAttrKeyClassSymmetric.
757 extern const CFStringRef kSecAttrKeyClassPublic
758 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
759 extern const CFStringRef kSecAttrKeyClassPrivate
760 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
761 extern const CFStringRef kSecAttrKeyClassSymmetric
762 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
765 @enum kSecAttrKeyType Value Constants
766 @discussion Predefined item attribute constants used to get or set values
767 in a dictionary. The kSecAttrKeyType constant is the key
768 and its value is one of the constants defined here.
769 @constant kSecAttrKeyTypeECSECPrimeRandom.
770 @constant kSecAttrKeyTypeEC This is the legacy name for kSecAttrKeyTypeECSECPrimeRandom, new applications should not use it.
771 @constant kSecAttrKeyTypeDSA (OSX only)
772 @constant kSecAttrKeyTypeAES (OSX only)
773 @constant kSecAttrKeyType3DES (OSX only)
774 @constant kSecAttrKeyTypeRC4 (OSX only)
775 @constant kSecAttrKeyTypeRC2 (OSX only)
776 @constant kSecAttrKeyTypeCAST (OSX only)
777 @constant kSecAttrKeyTypeECDSA (deprecated; use kSecAttrKeyTypeEC instead.) (OSX only)
779 extern const CFStringRef kSecAttrKeyTypeRSA
780 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_2_0
);
781 extern const CFStringRef kSecAttrKeyTypeDSA
782 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
783 extern const CFStringRef kSecAttrKeyTypeAES
784 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
785 extern const CFStringRef kSecAttrKeyTypeDES
786 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
787 extern const CFStringRef kSecAttrKeyType3DES
788 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
789 extern const CFStringRef kSecAttrKeyTypeRC4
790 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
791 extern const CFStringRef kSecAttrKeyTypeRC2
792 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
793 extern const CFStringRef kSecAttrKeyTypeCAST
794 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
795 extern const CFStringRef kSecAttrKeyTypeECDSA
796 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
797 extern const CFStringRef kSecAttrKeyTypeEC
798 __OSX_AVAILABLE_STARTING(__MAC_10_9
, __IPHONE_4_0
);
799 extern const CFStringRef kSecAttrKeyTypeECSECPrimeRandom
800 __OSX_AVAILABLE_STARTING(__MAC_10_12
, __IPHONE_10_0
);
803 @enum kSecAttrPRF Value Constants
804 @discussion Predefined item attribute constants used to specify the PRF
805 to use with SecKeyDeriveFromPassword. OS X only.
806 @constant kSecAttrPRFHmacAlgSHA1
807 @constant kSecAttrPRFHmacAlgSHA224
808 @constant kSecAttrPRFHmacAlgSHA256
809 @constant kSecAttrPRFHmacAlgSHA384
810 @constant kSecAttrPRFHmacAlgSHA512
812 extern const CFStringRef kSecAttrPRFHmacAlgSHA1
813 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
814 extern const CFStringRef kSecAttrPRFHmacAlgSHA224
815 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
816 extern const CFStringRef kSecAttrPRFHmacAlgSHA256
817 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
818 extern const CFStringRef kSecAttrPRFHmacAlgSHA384
819 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
820 extern const CFStringRef kSecAttrPRFHmacAlgSHA512
821 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
825 @enum Search Constants
826 @discussion Predefined search constants used to set values in a query
827 dictionary. You can specify a combination of search attributes and
828 item attributes when looking for matching items with the
829 SecItemCopyMatching function.
830 @constant kSecMatchPolicy Specifies a dictionary key whose value is a
831 SecPolicyRef. If provided, returned certificates or identities must
832 verify with this policy.
833 @constant kSecMatchItemList OS X only. Specifies a dictionary key whose value is a
834 CFArray of SecKeychainItemRef items. If provided, returned items will be
835 limited to the subset which are contained in this list.
836 @constant kSecMatchSearchList Specifies a dictionary key whose value is a
837 CFArray of SecKeychainRef items. If provided, the search will be limited
838 to the keychains contained in this list.
839 @constant kSecMatchIssuers Specifies a dictionary key whose value is a
840 CFArray of X.500 names (of type CFDataRef). If provided, returned
841 certificates or identities will be limited to those whose
842 certificate chain contains one of the issuers provided in this list.
843 @constant kSecMatchEmailAddressIfPresent Specifies a dictionary key whose
844 value is a CFStringRef containing an RFC822 email address. If
845 provided, returned certificates or identities will be limited to those
846 that contain the address, or do not contain any email address.
847 @constant kSecMatchSubjectContains Specifies a dictionary key whose value
848 is a CFStringRef. If provided, returned certificates or identities
849 will be limited to those containing this string in the subject.
850 @constant kSecMatchSubjectStartsWith OS X only. Specifies a dictionary key whose value
851 is a CFStringRef. If provided, returned certificates or identities
852 will be limited to those with subject names that start with this string.
853 @constant kSecMatchSubjectEndsWith OS X only. Specifies a dictionary key whose value
854 is a CFStringRef. If provided, returned certificates or identities
855 will be limited to those with subject names that end with this string.
856 @constant kSecMatchSubjectWholeString OS X only. Specifies a dictionary key whose
857 value is a CFStringRef. If provided, returned certificates or identities
858 will be limited to those matching this string exactly in the subject.
859 @constant kSecMatchCaseInsensitive Specifies a dictionary key whose value
860 is a CFBooleanRef. If this value is kCFBooleanFalse, or is not
861 provided, then case-sensitive string matching is performed.
862 @constant kSecMatchDiacriticInsensitive OS X only. Specifies a dictionary key whose
863 value is a CFBooleanRef. If this value is kCFBooleanFalse, or is not
864 provided, then diacritic-sensitive string matching is performed.
865 @constant kSecMatchWidthInsensitive OS X only. Specifies a dictionary key whose
866 value is a CFBooleanRef. If this value is kCFBooleanFalse, or is not
867 provided, then string matching is width-sensitive (e.g. 'a' != 0xFF41).
868 @constant kSecMatchTrustedOnly Specifies a dictionary key whose value is
869 a CFBooleanRef. If provided with a value of kCFBooleanTrue, only
870 certificates which can be verified back to a trusted anchor will be
871 returned. If this value is kCFBooleanFalse, or is not provided, then
872 both trusted and untrusted certificates may be returned.
873 @constant kSecMatchValidOnDate Specifies a dictionary key whose value is
874 of type CFDateRef. If provided, returned keys, certificates or
875 identities will be limited to those which are valid for the given date.
876 Pass a value of kCFNull to indicate the current date.
877 @constant kSecMatchLimit Specifies a dictionary key whose value is a
878 CFNumberRef. If provided, this value specifies the maximum number of
879 results to return. If not provided, results are limited to the first
880 item found. Predefined values are provided for a single item
881 (kSecMatchLimitOne) and all matching items (kSecMatchLimitAll).
882 @constant kSecMatchLimitOne Specifies that results are limited to the first
883 item found; used as a value for the kSecMatchLimit dictionary key.
884 @constant kSecMatchLimitAll Specifies that an unlimited number of results
885 may be returned; used as a value for the kSecMatchLimit dictionary
888 extern const CFStringRef kSecMatchPolicy
889 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
890 extern const CFStringRef kSecMatchItemList
891 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
892 extern const CFStringRef kSecMatchSearchList
893 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
894 extern const CFStringRef kSecMatchIssuers
895 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
896 extern const CFStringRef kSecMatchEmailAddressIfPresent
897 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
898 extern const CFStringRef kSecMatchSubjectContains
899 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
900 extern const CFStringRef kSecMatchSubjectStartsWith
901 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
902 extern const CFStringRef kSecMatchSubjectEndsWith
903 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
904 extern const CFStringRef kSecMatchSubjectWholeString
905 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
906 extern const CFStringRef kSecMatchCaseInsensitive
907 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
908 extern const CFStringRef kSecMatchDiacriticInsensitive
909 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
910 extern const CFStringRef kSecMatchWidthInsensitive
911 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
912 extern const CFStringRef kSecMatchTrustedOnly
913 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
914 extern const CFStringRef kSecMatchValidOnDate
915 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
916 extern const CFStringRef kSecMatchLimit
917 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
918 extern const CFStringRef kSecMatchLimitOne
919 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
920 extern const CFStringRef kSecMatchLimitAll
921 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
925 @enum Return Type Key Constants
926 @discussion Predefined return type keys used to set values in a dictionary.
927 You use these keys to specify the type of results which should be
928 returned by the SecItemCopyMatching or SecItemAdd function. You can
929 specify zero or more of these return types. If more than one of these
930 result types is specified, the result is returned as a CFDictionaryRef
931 whose keys are the result types and values are the requested data.
932 @constant kSecReturnData Specifies a dictionary key whose value is of type
933 CFBooleanRef. A value of kCFBooleanTrue indicates that the data of
934 an item (CFDataRef) should be returned. For keys and password
935 items, data is secret (encrypted) and may require the user to enter
936 a password for access.
937 @constant kSecReturnAttributes Specifies a dictionary key whose value is
938 of type CFBooleanRef. A value of kCFBooleanTrue indicates that the
939 (non-encrypted) attributes of an item (CFDictionaryRef) should be
941 @constant kSecReturnRef Specifies a dictionary key whose value is a
942 CFBooleanRef. A value of kCFBooleanTrue indicates that a reference
943 should be returned. Depending on the item class requested, the
944 returned reference(s) may be of type SecKeychainItemRef, SecKeyRef,
945 SecCertificateRef, or SecIdentityRef.
946 @constant kSecReturnPersistentRef Specifies a dictionary key whose value
947 is of type CFBooleanRef. A value of kCFBooleanTrue indicates that a
948 persistent reference to an item (CFDataRef) should be returned.
950 extern const CFStringRef kSecReturnData
951 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
952 extern const CFStringRef kSecReturnAttributes
953 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
954 extern const CFStringRef kSecReturnRef
955 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
956 extern const CFStringRef kSecReturnPersistentRef
957 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
961 @enum Value Type Key Constants
962 @discussion Predefined value type keys used to pass values in a dictionary.
963 You can specify zero or more of these types depending on the function
964 you are calling. For SecItemCopyMatching or SecItemAdd these are
965 used as keys in the results dictionary.
966 @constant kSecValueData Specifies a dictionary key whose value is of type
967 CFDataRef. For keys and password items, data is secret (encrypted)
968 and may require the user to enter a password for access.
969 @constant kSecValueRef Specifies a dictionary key whose value, depending
970 on the item class requested, is of type SecKeychainItemRef, SecKeyRef,
971 SecCertificateRef, or SecIdentityRef.
972 @constant kSecValuePersistentRef Specifies a dictionary key whose value
973 is of type CFDataRef. The bytes in this CFDataRef can be stored by
974 the caller and used on a subsequent invocation of the application (or
975 even a different application) to retrieve the item referenced by it.
977 extern const CFStringRef kSecValueData
978 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
979 extern const CFStringRef kSecValueRef
980 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
981 extern const CFStringRef kSecValuePersistentRef
982 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
986 @enum Other Constants
987 @discussion Predefined constants used to set values in a dictionary.
988 @constant kSecUseItemList Specifies a dictionary key whose value is a
989 CFArray of items. If provided, this array is treated as the set of
990 all possible items to search, or add if the API being called is
991 SecItemAdd. The items in this array may be of type SecKeyRef,
992 SecCertificateRef, SecIdentityRef, or CFDataRef (for a persistent
993 item reference.) The items in the array must all be of the same
994 type. When this attribute is provided, no keychains are searched.
995 @constant kSecUseKeychain OS X only. Specifies a dictionary key whose value is a
996 keychain reference. You use this key to specify a value of type
997 SecKeychainRef to which SecItemAdd will add the provided item(s).
998 @constant kSecUseOperationPrompt Specifies a dictionary key whose value
999 is a CFStringRef that represents a user-visible string describing
1000 the operation for which the application is attempting to authenticate.
1001 The application is responsible for the text localization.
1002 @constant kSecUseNoAuthenticationUI OS X only. Specifies a dictionary key whose value
1003 is a CFBooleanRef. If provided with a value of kCFBooleanTrue, the error
1004 errSecInteractionNotAllowed will be returned if the item is attempting
1005 to authenticate with UI.
1006 @constant kSecUseAuthenticationUI Specifies a dictionary key whose value
1007 is one of kSecUseAuthenticationUIAllow, kSecUseAuthenticationUIFail, kSecUseAuthenticationUISkip.
1008 @constant kSecUseAuthenticationContext Specifies a dictionary key whose value
1009 is LAContext to be used for keychain item authentication.
1010 * If the item requires authentication and this key is omitted, a new context
1011 will be created just for the purpose of the single call.
1012 * If the specified context has been previously authenticated, the operation
1013 will succeed without asking user for authentication.
1014 * If the specified context has not been previously authenticated, the new
1015 authentication will be started on this context, allowing caller to
1016 eventually reuse the sucessfully authenticated context in subsequent
1017 keychain operations.
1019 extern const CFStringRef kSecUseItemList
1020 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
1021 extern const CFStringRef kSecUseKeychain
1022 __OSX_AVAILABLE_STARTING(__MAC_10_7
, __IPHONE_NA
);
1023 extern const CFStringRef kSecUseOperationPrompt
1024 __OSX_AVAILABLE_STARTING(__MAC_10_10
, __IPHONE_8_0
);
1025 extern const CFStringRef kSecUseNoAuthenticationUI
1026 __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_10
, __MAC_10_11
, __IPHONE_8_0
, __IPHONE_9_0
, "Use a kSecUseAuthenticationUI instead.");
1027 extern const CFStringRef kSecUseAuthenticationUI
1028 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
1029 extern const CFStringRef kSecUseAuthenticationContext
1030 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
1033 @enum kSecUseAuthenticationUI Value Constants
1034 @discussion Predefined item attribute constants used to get or set values
1035 in a dictionary. The kSecUseAuthenticationUI constant is the key and its
1036 value is one of the constants defined here.
1037 If the key kSecUseAuthenticationUI not provided then kSecUseAuthenticationUIAllow
1039 @constant kSecUseAuthenticationUIAllow Specifies that authenticate UI can appear.
1040 @constant kSecUseAuthenticationUIFail Specifies that the error
1041 errSecInteractionNotAllowed will be returned if an item needs
1042 to authenticate with UI
1043 @constant kSecUseAuthenticationUIAllowSkip Specifies that all items which need
1044 to authenticate with UI will be silently skipped. This value can be used
1045 only with SecItemCopyMatching.
1047 extern const CFStringRef kSecUseAuthenticationUIAllow
1048 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
1049 extern const CFStringRef kSecUseAuthenticationUIFail
1050 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
1051 extern const CFStringRef kSecUseAuthenticationUISkip
1052 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
1055 @enum kSecAttrTokenID Value Constants
1056 @discussion Predefined item attribute constant used to get or set values
1057 in a dictionary. The kSecAttrTokenID constant is the key and its value
1058 can be kSecAttrTokenIDSecureEnclave.
1059 @constant kSecAttrTokenIDSecureEnclave Specifies well-known identifier of the
1060 token implemented using device's Secure Enclave. The only keychain items
1061 supported by the Secure Enclave token are 256-bit elliptic curve keys
1062 (kSecAttrKeyTypeEC). Keys must be generated on the secure enclave using
1063 SecKeyGenerateKeyPair call with kSecAttrTokenID set to
1064 kSecAttrTokenIDSecureEnclave in the parameters dictionary, it is not
1065 possible to import pregenerated keys to kSecAttrTokenIDSecureEnclave token.
1067 extern const CFStringRef kSecAttrTokenIDSecureEnclave
1068 __OSX_AVAILABLE_STARTING(__MAC_10_12
, __IPHONE_9_0
);
1071 @enum kSecAttrAccessGroup Value Constants
1072 @constant kSecAttrAccessGroupToken Represents well-known access group
1073 which contains items provided by external token (typically smart card).
1074 This may be used as a value for kSecAttrAccessGroup attribute. Every
1075 application has access to this access group so it is not needed to
1076 explicitly list it in keychain-access-groups entitlement, but application
1077 must explicitly state this access group in keychain queries in order to
1078 be able to access items from external tokens.
1080 extern const CFStringRef kSecAttrAccessGroupToken
1081 __OSX_AVAILABLE_STARTING(__MAC_10_12
, __IPHONE_10_0
);
1084 @function SecItemCopyMatching
1085 @abstract Returns one 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 "Keychain
1088 Search Attributes" section for a description of currently defined
1090 @param result On return, a CFTypeRef reference to the found item(s). The
1091 exact type of the result is based on the search attributes supplied
1092 in the query, as discussed below.
1093 @result A result code. See "Security Error Codes" (SecBase.h).
1094 @discussion Attributes defining a search are specified by adding key/value
1095 pairs to the query dictionary.
1097 A typical query consists of:
1099 * a kSecClass key, whose value is a constant from the Class
1100 Constants section that specifies the class of item(s) to be searched
1101 * one or more keys from the "Attribute Key Constants" section, whose value
1102 is the attribute data to be matched
1103 * one or more keys from the "Search Constants" section, whose value is
1104 used to further refine the search
1105 * a key from the "Return Type Key Constants" section, specifying the type of
1108 Result types are specified as follows:
1110 * To obtain the data of a matching item (CFDataRef), specify
1111 kSecReturnData with a value of kCFBooleanTrue.
1112 * To obtain the attributes of a matching item (CFDictionaryRef), specify
1113 kSecReturnAttributes with a value of kCFBooleanTrue.
1114 * To obtain a reference to a matching item (SecKeychainItemRef,
1115 SecKeyRef, SecCertificateRef, or SecIdentityRef), specify kSecReturnRef
1116 with a value of kCFBooleanTrue.
1117 * To obtain a persistent reference to a matching item (CFDataRef),
1118 specify kSecReturnPersistentRef with a value of kCFBooleanTrue. Note
1119 that unlike normal references, a persistent reference may be stored
1120 on disk or passed between processes.
1121 * If more than one of these result types is specified, the result is
1122 returned as a CFDictionaryRef containing all the requested data.
1123 * If a result type is not specified, no results are returned.
1125 By default, this function returns only the first match found. To obtain
1126 more than one matching item at a time, specify kSecMatchLimit with a value
1127 greater than 1. The result will be a CFArrayRef containing up to that
1128 number of matching items; the items' types are described above.
1130 To filter a provided list of items down to those matching the query,
1131 specify a kSecMatchItemList whose value is a CFArray of SecKeychainItemRef,
1132 SecKeyRef, SecCertificateRef, or SecIdentityRef items. The objects in the
1133 provided array must be of the same type.
1135 On iOS, to convert from a persistent item reference to a normal item reference,
1136 specify a kSecValuePersistentRef whose value a CFDataRef (the persistent
1137 reference), and a kSecReturnRef whose value is kCFBooleanTrue.
1139 On OSX, to convert from persistent item references to normal item references,
1140 specify a kSecMatchItemList whose value is a CFArray containing one or
1141 more CFDataRef elements (the persistent reference), and a kSecReturnRef
1142 whose value is kCFBooleanTrue. The objects in the provided array must be
1145 OSStatus
SecItemCopyMatching(CFDictionaryRef query
, CFTypeRef
* __nullable CF_RETURNS_RETAINED result
)
1146 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
1149 @function SecItemAdd
1150 @abstract Add one or more items to a keychain.
1151 @param attributes A dictionary containing an item class specification and
1152 optional entries specifying the item's attribute values. See the
1153 "Attribute Key Constants" section for a description of currently defined
1155 @param result On return, a CFTypeRef reference to the newly added item(s).
1156 The exact type of the result is based on the values supplied
1157 in attributes, as discussed below. Pass NULL if this result is not
1159 @result A result code. See "Security Error Codes" (SecBase.h).
1160 @discussion Attributes defining an item are specified by adding key/value
1161 pairs to the attributes dictionary. To add multiple items to a keychain
1162 at once use the kSecUseItemList key with an array of items as its value.
1163 This is currently only supported for non password items.
1165 On OSX, To add an item to a particular keychain, supply kSecUseKeychain
1166 with a SecKeychainRef as its value.
1168 Result types are specified as follows:
1170 * To obtain the data of the added item (CFDataRef), specify
1171 kSecReturnData with a value of kCFBooleanTrue.
1172 * To obtain all the attributes of the added item (CFDictionaryRef),
1173 specify kSecReturnAttributes with a value of kCFBooleanTrue.
1174 * To obtain a reference to the added item (SecKeychainItemRef, SecKeyRef,
1175 SecCertiicateRef, or SecIdentityRef), specify kSecReturnRef with a
1176 value of kCFBooleanTrue.
1177 * To obtain a persistent reference to the added item (CFDataRef), specify
1178 kSecReturnPersistentRef with a value of kCFBooleanTrue. Note that
1179 unlike normal references, a persistent reference may be stored on disk
1180 or passed between processes.
1181 * If more than one of these result types is specified, the result is
1182 returned as a CFDictionaryRef containing all the requested data.
1183 * On iOS, if a result type is not specified, no results are returned.
1184 On OSX, the added item is returned.
1186 OSStatus
SecItemAdd(CFDictionaryRef attributes
, CFTypeRef
* __nullable CF_RETURNS_RETAINED result
)
1187 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
1190 @function SecItemUpdate
1191 @abstract Modify zero or more items which match a search query.
1192 @param query A dictionary containing an item class specification and
1193 optional attributes for controlling the search. See the "Attribute
1194 Constants" and "Search Constants" sections for a description of
1195 currently defined search attributes.
1196 @param attributesToUpdate A dictionary containing one or more attributes
1197 whose values should be set to the ones specified. Only real keychain
1198 attributes are permitted in this dictionary (no "meta" attributes are
1199 allowed.) See the "Attribute Key Constants" section for a description of
1200 currently defined value attributes.
1201 @result A result code. See "Security Error Codes" (SecBase.h).
1202 @discussion Attributes defining a search are specified by adding key/value
1203 pairs to the query dictionary.
1205 OSStatus
SecItemUpdate(CFDictionaryRef query
, CFDictionaryRef attributesToUpdate
)
1206 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
1209 @function SecItemDelete
1210 @abstract Delete zero or more items which match a search query.
1211 @param query A dictionary containing an item class specification and
1212 optional attributes for controlling the search. See the "Attribute
1213 Constants" and "Search Constants" sections for a description of
1214 currently defined search attributes.
1215 @result A result code. See "Security Error Codes" (SecBase.h).
1216 @discussion Attributes defining a search are specified by adding key/value
1217 pairs to the query dictionary.
1219 By default, this function deletes all items matching the specified query.
1220 You can change this behavior by specifying one of the follow keys:
1222 * To delete an item identified by a transient reference, on iOS, specify
1223 kSecValueRef with a item reference. On OS X, give a kSecMatchItemList
1224 containing an item reference.
1225 * To delete an item identified by a persistent reference, on iOS, specify
1226 kSecValuePersistentRef with a persistent reference returned by
1227 using the kSecReturnPersistentRef key to SecItemCopyMatching or
1228 SecItemAdd. on OSX, use kSecMatchItemList with a persistent reference
1229 returned by using the kSecReturnPersistentRef key with
1230 SecItemCopyMatching or SecItemAdd.
1231 * To delete multiple items specify kSecMatchItemList with an array
1233 * If more than one of these result keys is specified, the behavior is
1236 OSStatus
SecItemDelete(CFDictionaryRef query
)
1237 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_2_0
);
1239 CF_IMPLICIT_BRIDGING_DISABLED
1240 CF_ASSUME_NONNULL_END
1244 #endif /* !_SECURITY_SECITEM_H_ */
projects / apple / security.git / blob