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