Most applications using the Keychain Manager will need to call the following high-level functions for storing and obtaining passwords:
KCAddAppleSharePassword
,
KCFindAppleSharePassword
,
KCAddInternetPassword
,
KCAddInternetPasswordWithPath
,
KCFindInternetPassword
,
KCFindInternetPasswordWithPath
,
KCAddGenericPassword
, and
KCFindGenericPassword
. These functions automatically query the user to unlock the keychain being searched.
When these functions search for a password, they search all unlocked keychains, then search all locked keychains. If the password is found in a locked keychain, the user will be prompted to unlock the keychain so the password can be retrieved. If it is not found in any keychain, these functions return the result code
itemNotFound
and prompt the user for interaction.
Note: Keychain Manager functions which store and retrieve passwords may involve file system or network accesses, and may move or allocate memory. These functions should not be called at interrupt time. You should keep this in mind if you are writing driver or other code that relies on interrupts.
The Keychain Manager also provides the following low-level functions for manipulating passwords and other keychain items:
KCAddItem
,
KCDeleteItem
,
KCUpdateItem
, and
KCCopyItem
. These functions require that you call the function
KCUnlock
to unlock a keychain before manipulating items in it. You should then call the function
KCLock
to lock the keychain when you are through.
Listing 3-1 example demonstrates how a typical application might use the high-level keychain interfaces to store password data. Notice that an explicit call to unlock the keychain is not required. You should call the function
KeychainManagerAvailable
before calling the rest of the API to determine whether the Keychain Manager is available. If you wish to utilize the maximum memory available, you should call the Memory Manager function
MaxApplZone
.
Listing 3-1 Storing password data
OSStatus StorePasswordInKeychain (ConstStr255Param password) { OSStatus status; if (!KeychainManagaerAvailable ()) //Is the Keychain Manager there? return ((OSStatus) MY_ERROR); status = KCAddGenericPassword ( "\pMy_App_Pwd", // service name "\pBillBraskey", // account name password [0], // length of password &password[1] ); // pointer to password data return (status); }
Figure 3-1 shows a flowchart illustrating how Keychain Manager might add an Internet password to a keychain or use an existing one. The user starts by selecting a File Transfer Protocol (FTP) server. A dialog box appears, asking if the user wishes to use the Keychain Manager. If the user says no, the server asks for authentication in its usual fashion. If the user says yes, the Keychain Manager calls function
KCFindInternetPassword
, which finds the password and sends it to the user's server. If the password does not exist, or the user has modified it, the Keychain Manager will call
KCAddInternetPassword
to bring up an authentication dialog box that will get the correct username and password, or allow the user to add a new username or password to the keychain.