2 * Copyright (c) 2000-2002 Apple Computer, Inc. All Rights Reserved.
4 * The contents of this file constitute Original Code as defined in and are
5 * subject to the Apple Public Source License Version 1.2 (the 'License').
6 * You may not use this file except in compliance with the License. Please obtain
7 * a copy of the License at http://www.apple.com/publicsource and read it before
10 * This Original Code and all software distributed under the License are
11 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
12 * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
13 * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
14 * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
15 * specific language governing rights and limitations under the License.
20 SecKeychain implements a repository for securely storing items with publicly visible attributes by which to find the items.
23 #ifndef _SECURITY_SECKEYCHAIN_H_
24 #define _SECURITY_SECKEYCHAIN_H_
26 #include <Security/SecBase.h>
27 #include <Security/cssmapple.h>
28 #include <CoreFoundation/CFArray.h>
31 #if defined(__cplusplus)
37 @abstract Defines the current status of a keychain.
38 @constant kSecUnlockStateStatus Indicates the keychain is unlocked.
39 @constant kSecReadPermStatus Indicates the keychain is readable.
40 @constant kSecWritePermStatus Indicates the keychain is writable.
44 kSecUnlockStateStatus
= 1,
45 kSecReadPermStatus
= 2,
46 kSecWritePermStatus
= 4
49 #define SEC_KEYCHAIN_SETTINGS_VERS1 1
52 @typedef SecKeychainSettings
53 @abstract Contains keychain settings.
54 @field version An unsigned 32-bit integer representing the keychain version.
55 @field lockOnSleep A boolean value indicating whether the keychain locks when the system sleeps.
56 @field useLockInterval A boolean value indicating whether the keychain automatically locks after a certain period of time.
57 @field lockInterval An unsigned 32-bit integer representing the number of seconds before the keychain locks.
59 struct SecKeychainSettings
63 Boolean useLockInterval
;
66 typedef struct SecKeychainSettings SecKeychainSettings
;
69 @typedef SecAuthenticationType
70 @abstract Represents the type of authentication to use for an Internet password.
72 typedef FourCharCode SecAuthenticationType
;
75 @enum AuthenticationConstants
76 @abstract Defines constants you can use to identify the type of authentication to use for an Internet password.
77 @constant kSecAuthenticationTypeNTLM Specifies Windows NT LAN Manager authentication.
78 @constant kSecAuthenticationTypeMSN Specifies Microsoft Network default authentication.
79 @constant kSecAuthenticationTypeDPA Specifies Distributed Password authentication.
80 @constant kSecAuthenticationTypeRPA Specifies Remote Password authentication.
81 @constant kSecAuthenticationTypeHTTPDigest Specifies HTTP Digest Access authentication.
82 @constant kSecAuthenticationTypeDefault Specifies the default authentication type.
86 kSecAuthenticationTypeNTLM
= 'ntlm',
87 kSecAuthenticationTypeMSN
= 'msna',
88 kSecAuthenticationTypeDPA
= 'dpaa',
89 kSecAuthenticationTypeRPA
= 'rpaa',
90 kSecAuthenticationTypeHTTPDigest
= 'httd',
91 kSecAuthenticationTypeDefault
= 'dflt'
95 @typedef SecProtocolType
96 @abstract Represents the protocol type associated with an AppleShare or Internet password.
98 typedef FourCharCode SecProtocolType
;
101 @enum ProtocolTypeConstants
102 @abstract Defines the protocol type associated with an AppleShare or Internet password.
103 @constant kSecProtocolTypeFTP Indicates FTP.
104 @constant kSecProtocolTypeFTPAccount Indicates FTP Account.
105 @constant kSecProtocolTypeHTTP Indicates HTTP.
106 @constant kSecProtocolTypeIRC Indicates IRC.
107 @constant kSecProtocolTypeNNTP Indicates NNTP.
108 @constant kSecProtocolTypePOP3 Indicates POP3.
109 @constant kSecProtocolTypeSMTP Indicates SMTP.
110 @constant kSecProtocolTypeSOCKS Indicates SOCKS.
111 @constant kSecProtocolTypeIMAP Indicates IMAP.
112 @constant kSecProtocolTypeLDAP Indicates LDAP.
113 @constant kSecProtocolTypeAppleTalk Indicates AFP over AppleTalk.
114 @constant kSecProtocolTypeAFP Indicates AFP.
115 @constant kSecProtocolTypeTelnet Indicates Telnet.
116 @constant kSecProtocolTypeSSH Indicates SSH.
120 kSecProtocolTypeFTP
= 'ftp ',
121 kSecProtocolTypeFTPAccount
= 'ftpa',
122 kSecProtocolTypeHTTP
= 'http',
123 kSecProtocolTypeIRC
= 'irc ',
124 kSecProtocolTypeNNTP
= 'nntp',
125 kSecProtocolTypePOP3
= 'pop3',
126 kSecProtocolTypeSMTP
= 'smtp',
127 kSecProtocolTypeSOCKS
= 'sox ',
128 kSecProtocolTypeIMAP
= 'imap',
129 kSecProtocolTypeLDAP
= 'ldap',
130 kSecProtocolTypeAppleTalk
= 'atlk',
131 kSecProtocolTypeAFP
= 'afp ',
132 kSecProtocolTypeTelnet
= 'teln',
133 kSecProtocolTypeSSH
= 'ssh '
137 @typedef SecKeychainEvent
138 @abstract Represents an event in which the state of a keychain or one of its items changed.
140 typedef UInt32 SecKeychainEvent
;
143 @enum KeychainEventConstants
144 @abstract Defines the keychain-related event.
145 @constant kSecLockEvent Indicates a keychain was locked.
146 @constant kSecUnlockEvent Indicates a keychain was unlocked.
147 @constant kSecAddEvent Indicates an item was added to a keychain.
148 @constant kSecDeleteEvent Indicates an item was deleted from a keychain.
149 @constant kSecUpdateEvent Indicates a keychain item was updated.
150 @constant kSecPasswordChangedEvent Indicates the keychain password was changed.
151 @constant kSecDefaultChangedEvent Indicates that a different keychain was specified as the default.
152 @constant kSecDataAccessEvent Indicates a process has accessed a keychain item's data.
153 @constant kSecKeychainListChangedEvent Indicates the list of keychains has changed.
162 kSecPasswordChangedEvent
= 6,
163 kSecDefaultChangedEvent
= 9,
164 kSecDataAccessEvent
= 10,
165 kSecKeychainListChangedEvent
= 11
169 @typedef SecKeychainEventMask
170 @abstract Represents a bit mask of keychain events
172 typedef UInt32 SecKeychainEventMask
;
175 @enum KeychainEventConstants
176 @abstract Defines keychain event constants
177 @constant kSecLockEventMask If the bit specified by this mask is set, your callback function will be invoked when a keychain is locked.
178 @constant kSecUnlockEventMask If the bit specified by this mask is set, your callback function will be invoked when a keychain is unlocked.
179 @constant kSecAddEventMask If the bit specified by this mask is set, your callback function will be invoked when an item is added to a keychain.
180 @constant kSecDeleteEventMask If the bit specified by this mask is set, your callback function will be invoked when an item is deleted from a keychain.
181 @constant kSecUpdateEventMask If the bit specified by this mask is set, your callback function will be invoked when a keychain item is updated.
182 @constant kSecPasswordChangedEventMask If the bit specified by this mask is set, your callback function will be invoked when the keychain password is changed.
183 @constant kSecDefaultChangedEventMask If the bit specified by this mask is set, your callback function will be invoked when a different keychain is specified as the default.
184 @constant kSecDataAccessEventMask If the bit specified by this mask is set, your callback function will be invoked when a process accesses a keychain item's data.
185 @constant kSecEveryEventMask If all the bits are set, your callback function will be invoked whenever any event occurs.
189 kSecLockEventMask
= 1 << kSecLockEvent
,
190 kSecUnlockEventMask
= 1 << kSecUnlockEvent
,
191 kSecAddEventMask
= 1 << kSecAddEvent
,
192 kSecDeleteEventMask
= 1 << kSecDeleteEvent
,
193 kSecUpdateEventMask
= 1 << kSecUpdateEvent
,
194 kSecPasswordChangedEventMask
= 1 << kSecPasswordChangedEvent
,
195 kSecDefaultChangedEventMask
= 1 << kSecDefaultChangedEvent
,
196 kSecDataAccessEventMask
= 1 << kSecDataAccessEvent
,
197 kSecKeychainListChangedMask
= 1 << kSecKeychainListChangedEvent
,
198 kSecEveryEventMask
= 0xffffffff
202 @typedef SecKeychainCallbackInfo
203 @abstract Contains information about a keychain event.
204 @field version The version of this structure.
205 @field item A reference to the keychain item associated with this event, if any. Note that some events do not involve a particular keychain item.
206 @field keychain A reference to the keychain in which the event occurred.
207 @field pid The id of the process that generated this event.
208 @discussion The SecKeychainCallbackInfo type represents a structure that contains information about the keychain event for which your application is being notified. For information on how to write a keychain event callback function, see SecKeychainCallback.
210 struct SecKeychainCallbackInfo
213 SecKeychainItemRef item
;
214 SecKeychainRef keychain
;
217 typedef struct SecKeychainCallbackInfo SecKeychainCallbackInfo
;
220 @function SecKeychainGetTypeID
221 @abstract Returns the type identifier of SecKeychain instances.
222 @result The CFTypeID of SecKeychain instances.
224 CFTypeID
SecKeychainGetTypeID(void);
227 @function SecKeychainGetVersion
228 @abstract Determines the version of the Keychain Manager installed on the userÕs system.
229 @param returnVers On return, a pointer to the version number of the Keychain Manager installed on the current system.
230 @result A result code. See "Security Error Codes" (SecBase.h).
232 OSStatus
SecKeychainGetVersion(UInt32
*returnVers
);
234 #pragma mark ÑÑÑÑ Keychain Management ÑÑÑÑ
236 @function SecKeychainOpen
237 @abstract Opens a keychain.
238 @param pathName The POSIX path to a keychain.
239 @param keychain On return, a pointer to the keychain reference. The memory that keychain occupies must be released by calling CFRelease when finished with it.
240 @result A result code. See "Security Error Codes" (SecBase.h). In addition, paramErr (-50) may be returned if the keychain parameter is invalid (NULL).
242 OSStatus
SecKeychainOpen(const char *pathName
, SecKeychainRef
*keychain
);
245 @function SecKeychainCreateNew
246 @abstract Creates a new keychain.
247 @param pathName The POSIX path to a keychain file.
248 @param passwordLength An unsigned 32-bit integer representing the length of the password buffer.
249 @param password A pointer to the buffer containing the password. The password must be in canonical UTF8 encoding.
250 @param promptUser A boolean representing whether to display a password dialog to the user.
251 @param initialAccess An access reference.
252 @param keychain On return, a pointer to a keychain reference. The memory that keychain occupies must be released by calling CFRelease when finished with it.
253 @result A result code. See "Security Error Codes" (SecBase.h). In addition, paramErr (-50) may be returned if the keychain parameter is invalid (NULL).
255 OSStatus
SecKeychainCreate(const char *pathName
, UInt32 passwordLength
, const void *password
, Boolean promptUser
, SecAccessRef initialAccess
, SecKeychainRef
*keychain
);
258 @function SecKeychainDelete
259 @abstract Deletes a keychain from the default searchlist, and removes the keychain itself if it is a file.
260 @param keychain A pointer to a keychain reference.
261 @result A result code. See "Security Error Codes" (SecBase.h). In addition, paramErr (-50) may be returned if the keychain parameter is invalid (NULL).
263 OSStatus
SecKeychainDelete(SecKeychainRef keychain
);
266 @function SecKeychainSetSettings
267 @abstract Changes the settings of a keychain.
268 @param keychain A reference to a keychain.
269 @param newSettings A pointer to the new keychain settings.
270 @result A result code. See "Security Error Codes" (SecBase.h).
272 OSStatus
SecKeychainSetSettings(SecKeychainRef keychain
, const SecKeychainSettings
*newSettings
);
275 @function SecKeychainCopySettings
276 @abstract Copy the keychain settings.
277 @param keychain A reference to the keychain from which to copy its settings.
278 @param outSettings A pointer to a keychain settings structure. Since this structure is versioned, you must preallocate it and fill in the version of the structure.
279 @result A result code. See "Security Error Codes" (SecBase.h).
281 OSStatus
SecKeychainCopySettings(SecKeychainRef keychain
, SecKeychainSettings
*outSettings
);
284 @function SecKeychainUnlock
285 @abstract Unlocks the specified keychain.
286 @param keychain A reference to the keychain to unlock. Pass NULL to specify the default keychain. If you pass NULL and the default keychain is currently locked, the keychain will appear as the default choice. If you pass a locked keychain, SecKeychainUnlock will use the password provided to unlock it. If the default keychain is currently unlocked, SecKeychainUnlock returns noErr.
287 @param passwordLength An unsigned 32-bit integer representing the length of the password buffer.
288 @param password A buffer containing the password for the keychain. Pass NULL if the user password is unknown. In this case, SecKeychainUnlock displays the Unlock Keychain dialog box, and the authentication user interface associated with the keychain about to be unlocked.
289 @param usePassword A boolean indicating whether the password parameter is used. You should pass TRUE if it is used or FALSE if it is ignored.
290 @result A result code. See "Security Error Codes" (SecBase.h).
291 @discussion In most cases, your application does not need to call the SecKeychainUnlock function directly, since most Keychain Manager functions that require an unlocked keychain call SecKeychainUnlock automatically. If your application needs to verify that a keychain is unlocked, call the function SecKeychainGetStatus.
293 OSStatus
SecKeychainUnlock(SecKeychainRef keychain
, UInt32 passwordLength
, void *password
, Boolean usePassword
);
296 @function SecKeychainLock
297 @abstract Locks the specified keychain.
298 @param keychain A reference to the keychain to lock.
299 @result A result code. See "Security Error Codes" (SecBase.h).
301 OSStatus
SecKeychainLock(SecKeychainRef keychain
);
304 @function SecKeychainLockAll
305 @abstract Locks all keychains belonging to the current user.
306 @result A result code. See "Security Error Codes" (SecBase.h).
308 OSStatus
SecKeychainLockAll(void);
311 @function SecKeychainCopyDefault
312 @abstract Retrieves a reference to the default keychain.
313 @param keychain On return, a pointer to the default keychain reference.
314 @result A result code. See "Security Error Codes" (SecBase.h).
316 OSStatus
SecKeychainCopyDefault(SecKeychainRef
*keychain
);
319 @function SecKeychainSetDefault
320 @abstract Sets the default keychain.
321 @param keychain A reference to the keychain to set as default.
322 @result A result code. See "Security Error Codes" (SecBase.h). In addition, paramErr (-50) may be returned if the keychain parameter is invalid (NULL).
324 OSStatus
SecKeychainSetDefault(SecKeychainRef keychain
);
327 @function SecKeychainCopySearchList
328 @abstract Retrieves a keychain search list.
329 @param searchList The returned list of keychains to search. When finished with the array, you must call CFRelease() to release the memory.
330 @result A result code. See "Security Error Codes" (SecBase.h). In addition, paramErr (-50) may be returned if the keychain list is not specified (NULL).
332 OSStatus
SecKeychainCopySearchList(CFArrayRef
*searchList
);
335 @function SecKeychainSetSearchList
336 @abstract Specifies the list of keychains to use in a keychain search list.
337 @param searchList The list of keychains to use in a search list when the SecKeychainCopySearchList function is called.
338 @result A result code. See "Security Error Codes" (SecBase.h). In addition, paramErr (-50) may be returned if the keychain list is not specified (NULL).
340 OSStatus
SecKeychainSetSearchList(CFArrayRef searchList
);
343 @function SecKeychainGetStatus
344 @abstract Retrieves status information for the specified keychain.
345 @param keychain A keychain reference. Pass NULL to specify the default keychain.
346 @param keychainStatus On return, a pointer to the status of the specified keychain. See KeychainStatus for valid status constants.
347 @result A result code. See "Security Error Codes" (SecBase.h).
349 OSStatus
SecKeychainGetStatus(SecKeychainRef keychain
, SecKeychainStatus
*keychainStatus
);
352 @function SecKeychainGetPath
353 @abstract Get the path of the specified keychain.
354 @param keychain A reference to a keychain.
355 @param ioPathLength On input, a pointer to the size or the buffer pointed to by pathName. On return, the size of the buffer without the zero termination.
356 @param pathName On return, the POSIX path to the keychain.
357 @result A result code. See "Security Error Codes" (SecBase.h).
359 OSStatus
SecKeychainGetPath(SecKeychainRef keychain
, UInt32
*ioPathLength
, char *pathName
);
361 #pragma mark ÑÑÑÑ Keychain Item Attribute Information ÑÑÑÑ
363 @function SecKeychainAttributeInfoForItemID
364 @abstract Obtains tags for all possible attributes for a given item class.
365 @param keychain A keychain reference.
366 @param itemID The relation identifier of the item tags.
367 @param info On return, a pointer to the keychain attribute information. User should call the SecKeychainFreeAttributeInfo function to release the structure when done with it.
368 @result A result code. See "Security Error Codes" (SecBase.h). In addition, paramErr (-50) may be returned if not enough valid parameters were supplied (NULL).
369 @discussion Warning, this call returns more attributes than are support by the old style Keychain API and passing them into older calls will yield an invalid attribute error. The recommended call to retrieve the attribute values is the SecKeychainItemCopyAttributesAndData function.
371 OSStatus
SecKeychainAttributeInfoForItemID(SecKeychainRef keychain
, UInt32 itemID
, SecKeychainAttributeInfo
**info
);
374 @function SecKeychainFreeAttributeInfo
375 @abstract Releases the memory acquired by calling the SecKeychainAttributeInfoForItemID function.
376 @param info A pointer to the keychain attribute information to release.
377 @result A result code. See "Security Error Codes" (SecBase.h). In addition, paramErr (-50) may be returned if not enough valid parameters were supplied (NULL).
379 OSStatus
SecKeychainFreeAttributeInfo(SecKeychainAttributeInfo
*info
);
381 #pragma mark ÑÑÑÑ Keychain Manager Callbacks ÑÑÑÑ
384 @typedef SecKeychainCallback
385 @abstract Defines a pointer to a customized callback function. You supply the customized callback function to do a callback tailored to your application's needs.
386 @param keychainEvent The keychain event that your application wishes to be notified of. See SecKeychainEvent for a description of possible values. The type of event that can trigger your callback depends on the bit mask you passed in the eventMask parameter of the function SecKeychainAddCallback. For more information, see the discussion.
387 @param info A pointer to a structure of type SecKeychainCallbackInfo. On return, the structure contains information about the keychain event that occurred. The Keychain Manager passes this information to your callback function via the info parameter.
388 @param context A pointer to application-defined storage that your application previously passed to the function SecKeychainAddCallback. You can use this value to perform operations like track which instance of a function is operating.
389 @result A result code. See "Security Error Codes" (SecBase.h).
390 @discussion If you name your function MyKeychainEventCallback, you would declare it like this:
391 OSStatus MyKeychainEventCallback (
392 SecKeychainEvent keychainEvent,
393 SecKeychainCallbackInfo *info,
396 To add your callback function, use the SecKeychainAddCallback function. To remove your callback function, use the SecKeychainRemoveCallback function.
398 typedef OSStatus (*SecKeychainCallback
)(SecKeychainEvent keychainEvent
, SecKeychainCallbackInfo
*info
, void *context
);
401 @function SecKeychainAddCallback
402 @abstract Registers your keychain event callback function
403 @param callbackFunction A pointer to your keychain event callback function, described in SecKeychainCallback. You indicate the type of keychain events you want to receive by passing a bit mask of the desired events in the eventMask parameter.
404 @param eventMask A bit mask indicating the keychain events that your application wishes to be notified of. See SecKeychainEventMask for a description of this bit mask. The Keychain Manager tests this mask to determine the keychain events that you wish to receive, and passes these events in the keychainEvent parameter of your callback function. See SecKeychainEvent for a description of these events.
405 @param userContext A pointer to application-defined storage that will be passed to your callback function. Your application can use this to associate any particular call of SecKeychainAddCallback with any particular call of your keychain event callback function.
406 @result A result code. See "Security Error Codes" (SecBase.h).
408 OSStatus
SecKeychainAddCallback(SecKeychainCallback callbackFunction
, SecKeychainEventMask eventMask
, void* userContext
);
411 @function SecKeychainRemoveCallback
412 @abstract Unregisters your keychain event callback function. Once removed, keychain events won't be sent to the owner of the callback.
413 @param callbackFunction The callback function pointer to remove
414 @result A result code. See "Security Error Codes" (SecBase.h).
416 OSStatus
SecKeychainRemoveCallback(SecKeychainCallback callbackFunction
);
418 #pragma mark ÑÑÑÑ High Level Keychain Manager Calls ÑÑÑÑ
420 @function SecKeychainAddInternetPassword
421 @abstract Adds an internet password as a keychain item to the specified keychain.
422 @param keychain A reference to keychain in which to store an internet password.
423 @param serverNameLength The length of the buffer pointed to by server name.
424 @param serverName A pointer to a string containing the server name.
425 @param securityDomainLength The length of the buffer pointed to by security domain.
426 @param securityDomain A pointer to a string containing the security domain. This parameter is optional, as not all protocols will require it.
427 @param accountNameLength The length of the buffer pointed to by account name.
428 @param accountName A pointer to a string containing the account name.
429 @param pathLength The length of the buffer pointed to by path.
430 @param path A pointer to a string containing the path.
431 @param port The TCP/IP port number.
432 @param protocol The protocol associated with this password. See SecProtocolType for a description of possible values.
433 @param authenticationType The authentication scheme used. See SecAuthenticationType for a description of possible values. Pass the constant kSecAuthenticationTypeDefault, to specify the default authentication scheme.
434 @param passwordLength The length of the buffer pointed to by passwordData.
435 @param passwordData A pointer to a buffer which will hold the returned password data. Before calling SecKeychainAddInternetPassword, allocate enough memory for the buffer to hold the data you want to store.
436 @param itemRef On return, a pointer to the new keychain item.
437 @result A result code. See "Security Error Codes" (SecBase.h).
438 @discussion The SecKeychainAddInternetPassword function adds a new internet server password to the default keychain. Required parameters to identify the password are serverName and accountName (you cannot pass NULL for both parameters). In addition, some protocols may require an optional securityDomain when authentication is requested. SecKeychainAddInternetPassword optionally returns a reference to the newly added item.
440 OSStatus
SecKeychainAddInternetPassword(SecKeychainRef keychain
, UInt32 serverNameLength
, const char *serverName
, UInt32 securityDomainLength
, const char *securityDomain
, UInt32 accountNameLength
, const char *accountName
, UInt32 pathLength
, const char *path
, UInt16 port
, SecProtocolType protocol
, SecAuthenticationType authenticationType
, UInt32 passwordLength
, const void *passwordData
, SecKeychainItemRef
*itemRef
);
443 @function SecKeychainFindInternetPassword
444 @abstract Finds an internet password based on the attributes passed.
445 @param keychainOrArray An reference to an array of keychains to search, a single keychain or NULL to search the user's default keychain search list.
446 @param serverNameLength The length of the buffer pointed to by server name.
447 @param serverName A pointer to a string containing the server name.
448 @param securityDomainLength The length of the buffer pointed to by security domain.
449 @param securityDomain A pointer to a string containing the security domain. This parameter is optional, as not all protocols will require it.
450 @param accountNameLength The length of the buffer pointed to by account name.
451 @param accountName A pointer to a string containing the account name.
452 @param pathLength The length of the buffer pointed to by path.
453 @param path A pointer to a string containing the path.
454 @param port The TCP/IP port number.
455 @param protocol The protocol associated with this password. See SecProtocolType for a description of possible values.
456 @param authenticationType The authentication scheme used. See SecAuthenticationType for a description of possible values. Pass the constant kSecAuthenticationTypeDefault, to specify the default authentication scheme.
457 @param passwordLength The length of the buffer pointed to by passwordData.
458 @param passwordData A pointer to a buffer which will hold the returned password data. Before calling SecKeychainFindInternetPassword, allocate enough memory for the buffer to hold the data you want to store.
459 @param itemRef The item reference of the internet password.
460 @result A result code. See "Security Error Codes" (SecBase.h).
461 @discussion The SecKeychainFindInternetPassword function finds the first internet password item which matches the attributes you provide. The buffer specified in the passwordData parameter must be large enough to hold the password data, otherwise SecKeychainFindInternetPassword returns the result code errSecBufferTooSmall. In this case, your application must allocate a new buffer of sufficient size before calling SecKeychainFindInternetPassword again. SecKeychainFindInternetPassword optionally returns a reference to the found item.
464 OSStatus
SecKeychainFindInternetPassword(CFTypeRef keychainOrArray
, UInt32 serverNameLength
, const char *serverName
, UInt32 securityDomainLength
, const char *securityDomain
, UInt32 accountNameLength
, const char *accountName
, UInt32 pathLength
, const char *path
, UInt16 port
, SecProtocolType protocol
, SecAuthenticationType authenticationType
, UInt32
*passwordLength
, void **passwordData
, SecKeychainItemRef
*itemRef
);
467 @function SecKeychainAddGenericPassword
468 @abstract Adds a generic password to the specified keychain.
469 @param keychain A reference to keychain in which to store a generic password.
470 @param serviceNameLength The length of the buffer pointed to by service name.
471 @param serviceName A pointer to a string containing the service name.
472 @param accountNameLength The length of the buffer pointed to by account name.
473 @param accountName A pointer to a string containing the account name.
474 @param passwordLength The length of the buffer pointed to by passwordData.
475 @param passwordData A pointer to a buffer which will hold the returned password data. Before calling SecKeychainAddInternetPassword, allocate enough memory for the buffer to hold the data you want to store.
476 @param itemRef On return, a pointer to the new keychain item reference.
477 @result A result code. See "Security Error Codes" (SecBase.h).
478 @discussion The SecKeychainAddGenericPassword function adds a new generic password to the default keychain. Required parameters to identify the password are serviceName and accountName, which are application-defined strings. SecKeychainAddGenericPassword optionally returns a reference to the newly added item.
480 You can use SecKeychainAddGenericPassword to add passwords for accounts other than Internet or Appleshare. For example, you might add passwords for your database or scheduling programs.
482 OSStatus
SecKeychainAddGenericPassword(SecKeychainRef keychain
, UInt32 serviceNameLength
, const char *serviceName
, UInt32 accountNameLength
, const char *accountName
, UInt32 passwordLength
, const void *passwordData
, SecKeychainItemRef
*itemRef
);
485 @function SecKeychainFindGenericPassword
486 @abstract Find a generic password based on the attributes passed.
487 @param keychainOrArray An reference to an array of keychains to search, a single keychain or NULL to search the user's default keychain search list.
488 @param serviceNameLength The length of the buffer pointed to by service name.
489 @param serviceName A pointer to a string containing the service name.
490 @param accountNameLength The length of the buffer pointed to by account name.
491 @param accountName A pointer to a string containing the account name.
492 @param passwordLength The length of the buffer pointed to by passwordData.
493 @param passwordData A pointer to a buffer which will hold the returned password data. Before calling SecKeychainAddInternetPassword, allocate enough memory for the buffer to hold the data you want to store.
494 @param itemRef On return, a pointer to the new keychain item reference.
495 @result A result code. See "Security Error Codes" (SecBase.h).
496 @discussion The SecKeychainFindGenericPassword function finds the first generic password item which matches the attributes you provide. The buffer specified in the passwordData parameter must be large enough to hold the password data, otherwise SecKeychainFindGenericPassword returns the result code errSecBufferTooSmall. In this case, your application must allocate a new buffer of sufficient size before calling SecKeychainFindGenericPassword again. SecKeychainFindGenericPassword optionally returns a reference to the found item.
498 OSStatus
SecKeychainFindGenericPassword(CFTypeRef keychainOrArray
, UInt32 serviceNameLength
, const char *serviceName
, UInt32 accountNameLength
, const char *accountName
, UInt32
*passwordLength
, void **passwordData
, SecKeychainItemRef
*itemRef
);
500 #pragma mark ÑÑÑÑ Managing User Interaction ÑÑÑÑ
502 @function SecKeychainSetUserInteractionAllowed
503 @abstract Turns on or off any optional user interaction
504 @param state A boolean representing the state of user interaction. You should pass TRUE to allow user interaction, and FALSE to disallow user interaction
505 @result A result code. See "Security Error Codes" (SecBase.h).
507 OSStatus
SecKeychainSetUserInteractionAllowed(Boolean state
);
510 @function SecKeychainGetUserInteractionAllowed
511 @abstract Retrieves the current state of user interaction.
512 @param state On return, a pointer to the current state of user interaction. If this is TRUE then user interaction is allowed, if it is FALSE, then user interaction is not allowed.
513 @result A result code. See "Security Error Codes" (SecBase.h).
515 OSStatus
SecKeychainGetUserInteractionAllowed(Boolean
*state
);
517 #pragma mark ÑÑÑÑ CSSM Bridge Functions ÑÑÑÑ
519 @function SecKeychainGetCSPHandle
520 @abstract Returns the CSSM_CSP_HANDLE attachment for the given keychain reference. The handle is valid until the keychain reference is released.
521 @param keychain A keychain reference.
522 @param cspHandle On return, a pointer to the CSSM_CSP_HANDLE for the given keychain.
523 @result A result code. See "Security Error Codes" (SecBase.h).
525 OSStatus
SecKeychainGetCSPHandle(SecKeychainRef keychain
, CSSM_CSP_HANDLE
*cspHandle
);
528 @function SecKeychainGetDLDBHandle
529 @abstract Returns the CSSM_DL_DB_HANDLE for a given keychain reference. The handle is valid until the keychain reference is released.
530 @param keychain A keychain reference.
531 @param dldbHandle On return, a pointer to the CSSM_DL_DB_HANDLE for the given keychain.
532 @result A result code. See "Security Error Codes" (SecBase.h).
534 OSStatus
SecKeychainGetDLDBHandle(SecKeychainRef keychain
, CSSM_DL_DB_HANDLE
*dldbHandle
);
536 #pragma mark ÑÑÑÑ Keychain Access Management ÑÑÑÑ
538 @function SecKeychainCopyAccess
539 @abstract Retrieves the access for a keychain.
540 @param keychain A reference to the keychain from which to copy the access.
541 @param accessRef On return, a pointer to the access reference.
542 @result A result code. See "Security Error Codes" (SecBase.h).
544 OSStatus
SecKeychainCopyAccess(SecKeychainRef keychain
, SecAccessRef
*access
);
547 @function SecKeychainSetAccess
548 @abstract Sets the access for a keychain.
549 @param keychain A reference to the keychain for which to set the access.
550 @param accessRef An access reference.
551 @result A result code. See "Security Error Codes" (SecBase.h).
553 OSStatus
SecKeychainSetAccess(SecKeychainRef keychain
, SecAccessRef access
);
555 #if defined(__cplusplus)
559 #endif /* !_SECURITY_SECKEYCHAIN_H_ */