Next Page >

Hide TOC

Keychain Manager Reference

Framework	CoreServices/CoreServices.h, Carbon/Carbon.h
Declared in	KeychainCore.h KeychainHI.h

Overview

The Keychain Manager is an API that provides a uniform way for your application to handle passwords for multiple users, multiple databases, or any situation in which a user must enter single or multiple passwords. You can use the Keychain Manager to provide secure storage for a user's passwords, cryptographic keys, and digital certificates.

This document, which describes KeychainLib 2.0, is relevant to you if your application needs to create and manage passwords and other secure data.

Important: Keychain Manager is being phased out and replaced by Keychain Services. Any new development should use Keychain Services. See Keychain Services Reference.

Carbon fully supports the Keychain Manager.

Functions by Task

Getting Information About the Keychain Manager

Creating and Disposing of Keychain References

Managing Keychains

Storing and Retrieving Passwords

Creating and Disposing of Keychain Item References

Manipulating Keychain Items

Setting and Obtaining Keychain Item Data

Searching for Keychain Items

Managing User Interaction

Registering Your Keychain Event Callback Function

Working With Your Keychain Manager Callback Function

Unsupported Functions

Functions

DisposeKCCallbackUPP

Disposes of a UPP to your keychain event callback.

Not recommended

void DisposeKCCallbackUPP (
   KCCallbackUPP userUPP
);

Parameters

userUPP: A Universal Procedure Pointer (UPP) to your keychain event callback function.

Return Value

A result code. See “Keychain Manager Result Codes.”

Discussion

When you are finished with a UPP to your keychain event callback function, you should dispose of it by calling the DisposeKCCallbackUPP function.

Availability

Available in CarbonLib 1.1 and later.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

There is no replacement function available.

Declared In

KeychainCore.h

InvokeKCCallbackUPP

Invokes your keychain event callback.

Not recommended

OSStatus InvokeKCCallbackUPP (
   KCEvent keychainEvent,
   KCCallbackInfo *info,
   void *userContext,
   KCCallbackUPP userUPP
);

Parameters

keychainEvent: The keychain events you want your application to receive. See “Keychain Events Constants” for a description of possible values. The Keychain Manager tests the bitmask you pass in the eventMask parameter of the function KCAddCallback to determine which events to pass to your callback function. See “Keychain Events Mask” for a description of this bitmask.
info: A pointer to a structure of type KCCallbackInfo that provides information about the keychain event to your callback function. The Keychain Manager passes a pointer to this structure in the info parameter of your callback function.
userContext: A pointer to application-defined storage. The Keychain Manager passes this value in the userContext parameter of your callback function. Your application can use this to associate any particular call of the InvokeKCCallbackUPP function with any particular call of the keychain event callback function.
userUPP: A Universal Procedure Pointer to your keychain event callback function. For information on how to create a keychain event callback function, see KCCallbackProcPtr.

Return Value

A result code. See “Keychain Manager Result Codes.”

Discussion

You should not need to use the function InvokeKCCallbackUPP, as the system calls your KCAddCallback callback function for you.

Availability

Available in CarbonLib 1.1 and later.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

There is no replacement function available.

Declared In

KeychainCore.h

KCAddAppleSharePassword

Adds a new AppleShare server password to the default keychain.

Not recommended

OSStatus KCAddAppleSharePassword (
   AFPServerSignature *serverSignature,
   StringPtr serverAddress,
   StringPtr serverName,
   StringPtr volumeName,
   StringPtr accountName,
   UInt32 passwordLength,
   const void *passwordData,
   KCItemRef *item
);

Parameters

serverSignature: A pointer to a 16-byte Apple File Protocol server signature block. Pass a value of type AFPServerSignature. Pass NULL to match any server signature. The Keychain Manager identifies the location for the password by the information passed in the serverAddress and serverSignature parameters. You must pass a valid value in at least one of these parameters.
serverAddress: A pointer to a Pascal string containing the server address, which may be specified as an AppleTalk zone name, a DNS domain name (in the format "xxx.yyy.zzz"), or an IP address (in the format "111.222.333.444"). The Keychain Manager identifies the location for the password by the information passed in the serverAddress and serverSignature parameters. You must pass a valid value in at least one of these parameters.
serverName: A pointer to a Pascal string containing the server name.
volumeName: A pointer to a Pascal string containing the volume name.
accountName: A pointer to a Pascal string containing the account name.
passwordLength: The length of the buffer pointed to by passwordData.
passwordData: A pointer to a buffer which will hold the returned password data. Before calling KCAddAppleSharePassword, allocate enough memory for the buffer to hold the data you want to store.
item: On return, a pointer to a reference to the added item. Pass NULL if you don’t want to obtain this reference.

Return Value

A result code. See “Keychain Manager Result Codes.” The result code errKCNoDefaultKeychain indicates that no default keychain could be found. The result code errKCDuplicateItem indicates that you tried to add a password that already exists in the keychain. The result code errKCDataTooLarge indicates that you tried to add more data than is allowed for a record of this type.

Discussion

The KCAddAppleSharePassword function adds a new AppleShare server password to the default keychain that is uniquely identified by the serverName, volumeName, and accountName parameters, and a location specified either by the serverAddress or serverSignature parameters. The KCAddAppleSharePassword function optionally returns a reference to the newly added item.

Most applications do not need to store AppleShare password data, as this is handled transparently by the AppleShare client software. To be compatible with the AppleShare client, you should store a fully-specified File Manager structure AFPXVolMountInfo as the password data.

The KCAddAppleSharePassword function automatically calls the function KCUnlock to display the Unlock Keychain dialog box if the keychain containing the password is currently locked.

You can also call the function kcaddapplesharepassword to add an AppleShare server password to the default keychain. kcaddapplesharepassword requires that you pass a pointer to a C string instead of a pointer to a Pascal string for the serverAddress, serverName, volumeName, accountName, and passwordData parameters.

Version Notes

Available beginning with KeychainLib 1.0. In KeychainLib 1.0, the kcaddapplesharepassword function provides the same functionality as KCAddAppleSharePassword, except that it accepts C strings rather than Pascal strings as arguments. In KeychainLib 2.0, you should use KCAddAppleSharePassword, since kcaddapplesharepassword is provided for convenience only and may be removed from the header file at some point in the future.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

It is recommended that you use internet passwords instead of AppleShare passwords. Use the SecKeychainAddInternetPassword function in Keychain Services instead.

Declared In

KeychainHI.h

kcaddapplesharepassword

Not recommended

OSStatus kcaddapplesharepassword (
   AFPServerSignature *serverSignature,
   const char *serverAddress,
   const char *serverName,
   const char *volumeName,
   const char *accountName,
   UInt32 passwordLength,
   const void *passwordData,
   KCItemRef *item
);

Discussion

This function is available for convenience only and may be removed. Use the function KCAddAppleSharePassword instead.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

It is recommended that you use internet passwords instead of AppleShare passwords. Use the SecKeychainAddInternetPassword function in Keychain Services instead.

Declared In

KeychainHI.h

KCAddCallback

Registers your keychain event callback function.

Not recommended

OSStatus KCAddCallback (
   KCCallbackUPP callbackProc,
   KCEventMask eventMask,
   void *userContext
);

Parameters

callbackProc: A Universal Procedure Pointer (UPP) to your keychain event callback function, described in KCCallbackProcPtr. You indicate the type of keychain events you want to receive by passing a bitmask of the desired events in the eventMask parameter. To create a UPP to your callback function, call the function NewKCCallbackUPP.
eventMask: A bitmask indicating the keychain events that your application wishes to be notified of. See “Keychain Events Mask” for a description of this bitmask. 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 “Keychain Events Constants” for a description of these events.
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 the KCAddCallback function with any particular call of your keychain event callback function.

Return Value

A result code. See “Keychain Manager Result Codes.” The result code errKCDuplicateCallback indicates that your callback function is already registered.

Discussion

You can register your callback function by passing a UPP to it in the callbackProc parameter of the KCAddCallback function. Once you have done so, the Keychain Manager calls the function InvokeKCCallbackUPP when the keychain event specified in the eventMask parameter occurs. In turn, the function InvokeKCCallbackUPP passes the keychain event, information about the event, and application-defined storage to your keychain event callback function.

Version Notes

Available beginning with KeychainLib 1.0.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainAddCallback function in Keychain Services instead.

Declared In

KeychainCore.h

KCAddGenericPassword

Adds a new generic password to the default keychain.

Not recommended

OSStatus KCAddGenericPassword (
   StringPtr serviceName,
   StringPtr accountName,
   UInt32 passwordLength,
   const void *passwordData,
   KCItemRef *item
);

Parameters

serviceName: A pointer to a Pascal string containing an application-defined service name.
accountName: A pointer to a Pascal string containing an application-defined account name.
passwordLength: The length of the password data to be stored
passwordData: A pointer to the buffer that holds the returned password data. Before calling the KCAddGenericPassword function, allocate enough memory for the buffer to hold the data you want to store.
item: On return, a pointer to a reference to the added item. Pass NULL if you don’t want to obtain this reference.

Return Value

Discussion

The KCAddGenericPassword 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. The KCAddGenericPassword function optionally returns a reference to the newly added item.

You can use the KCAddGenericPassword function to add passwords for accounts other than Internet or AppleShare. For example, you might add passwords for your database or scheduling programs.

You can also call the function kcaddgenericpassword to add a new generic password to the default keychain. The difference between the two functions is that the kcaddgenericpassword function takes a pointer to a C string instead of a Pascal string in the serverAddress, serverName, volumeName, accountName, and passwordData parameters.

The KCAddGenericPassword function automatically calls the function KCUnlock to display the Unlock Keychain dialog box if the keychain containing the password is currently locked.

Version Notes

Available beginning with KeychainLib 1.0. In KeychainLib 1.0, the kcaddgenericpassword function provides the same functionality as the function KCAddGenericPassword, except that it accepts C strings rather than Pascal strings as arguments. In KeychainLib 2.0, you should use the KCAddGenericPassword function, since the kcaddgenericpassword function is provided for convenience only and may be removed from the header file at some point in the future.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainAddGenericPassword function in Keychain Services instead.

Declared In

KeychainHI.h

kcaddgenericpassword

Not recommended

OSStatus kcaddgenericpassword (
   const char *serviceName,
   const char *accountName,
   UInt32 passwordLength,
   const void *passwordData,
   KCItemRef *item
);

Discussion

This function is available for convenience only and may be removed. Use the function KCAddGenericPassword instead.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainAddGenericPassword function in Keychain Services instead.

Declared In

KeychainHI.h

KCAddInternetPassword

Adds a new Internet server password to the default keychain.

Not recommended

OSStatus KCAddInternetPassword (
   StringPtr serverName,
   StringPtr securityDomain,
   StringPtr accountName,
   UInt16 port,
   OSType protocol,
   OSType authType,
   UInt32 passwordLength,
   const void *passwordData,
   KCItemRef *item
);

Parameters

serverName: A pointer to a Pascal string containing the server name.
securityDomain: A pointer to a Pascal string containing the security domain. This parameter is optional, as not all protocols will require it.
accountName: A pointer to a Pascal string containing the account name.
port: The TCP/IP port number. Pass the constant kAnyPort, described in “Default Internet Port Constant,” to specify any port.
protocol: The protocol associated with this password. See “Keychain Protocol Type Constants” for a description of possible values. Pass the constant kAnyProtocol, described in “Default Internet Protocol And Authentication Type Constants,” to specify any protocol.
authType: The authentication scheme used. See “Authentication Type Constants” for a description of possible values. Pass the constant kAnyAuthType, described in “Default Internet Protocol And Authentication Type Constants,” to specify any authentication scheme.
passwordLength: The length of the buffer pointed to by passwordData.
passwordData: A pointer to a buffer that holds the returned password data. Before calling the KCAddInternetPasswordWithPath function, allocate enough memory for the buffer to hold the data you want to store.
item: On return, a pointer to a reference to the added item. Pass NULL if you don’t want to obtain this reference.

Return Value

Discussion

The KCAddInternetPassword function adds a new Internet server password to the default keychain. Required parameters to identify the password are serviceName and accountName (you cannot pass NULL for both parameters). In addition, some protocols may require an optional value in the securityDomain parameter when authentication is requested. KCAddInternetPassword optionally returns a reference to the newly added item.

The KCAddInternetPassword function automatically calls the function KCUnlock to display the Unlock Keychain dialog box if the keychain containing the password is currently locked.

You can also call the function kcaddinternetpassword to add a new Internet server password to the default keychain. The kcaddinternetpassword function requires that you pass a pointer to a C string instead of a pointer to a Pascal string for the serverAddress, serverName, volumeName, accountName, and passwordData parameters.

Version Notes

Available beginning with KeychainLib 1.0. In KeychainLib 1.0, the kcaddinternetpassword function provides the same functionality as KCAddInternetPassword, except that it accepts C strings rather than Pascal strings as arguments. In KeychainLib 2.0, you should use KCAddInternetPassword, since kcaddinternetpassword is provided for convenience only and may be removed from the header file at some point in the future.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainAddInternetPassword function in Keychain Services instead.

Declared In

KeychainHI.h

kcaddinternetpassword

Not recommended

OSStatus kcaddinternetpassword (
   const char *serverName,
   const char *securityDomain,
   const char *accountName,
   UInt16 port,
   OSType protocol,
   OSType authType,
   UInt32 passwordLength,
   const void *passwordData,
   KCItemRef *item
);

Discussion

This function is available for convenience only and may be removed. Use the function KCAddInternetPassword instead.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainAddInternetPassword function in Keychain Services instead.

Declared In

KeychainHI.h

KCAddInternetPasswordWithPath

Adds a new Internet server password with a specified path to the default keychain.

Not recommended

OSStatus KCAddInternetPasswordWithPath (
   StringPtr serverName,
   StringPtr securityDomain,
   StringPtr accountName,
   StringPtr path,
   UInt16 port,
   OSType protocol,
   OSType authType,
   UInt32 passwordLength,
   const void *passwordData,
   KCItemRef *item
);

Parameters

serverName: A pointer to a Pascal string containing the server name.
securityDomain: A pointer to a Pascal string containing the security domain. This parameter is optional, as not all protocols will require it.
accountName: A pointer to a Pascal string containing the account name.
path: A pointer to a Pascal string containing additional information that specifies a file or directory on the server specified by the serverName parameter. In a typical URL, path information begins directly after the first slash (“/”) character following the server name. This parameter is optional.
port: The TCP/IP port number. Pass the constant kAnyPort, described in “Default Internet Port Constant,” to specify any port.
protocol: The protocol associated with this password. See “Keychain Protocol Type Constants” for a description of possible values. Pass the constant kAnyProtocol, described in “Default Internet Protocol And Authentication Type Constants,” to specify any protocol.
authType: The authentication scheme used. See “Authentication Type Constants” for a description of possible values. Pass the constant kAnyAuthType, described in “Default Internet Protocol And Authentication Type Constants,” to specify any authentication scheme.
passwordLength: The length of the buffer pointed to by passwordData.
passwordData: A pointer to a buffer which will hold the returned password data. Before calling KCAddInternetPasswordWithPath, allocate enough memory for the buffer to hold the data you want to store.
item: On return, a pointer to a reference to the added item. Pass NULL if you don’t want to obtain this reference.

Return Value

Discussion

The KCAddInternetPasswordWithPath function enables you to specify path information when adding a new Internet server password to the default keychain. Required parameters to identify the password are serviceName and accountName (you cannot pass NULL for both parameters). In addition, some protocols may require an optional securityDomain when authentication is requested. KCAddInternetPasswordWithPath optionally returns a reference to the newly added item.

The KCAddInternetPasswordWithPath function automatically calls the function KCUnlock to display the Unlock Keychain dialog box if the keychain containing the password is currently locked.

You can also call the function kcaddinternetpasswordwithpath to add a new Internet server password to the default keychain. The function kcaddinternetpasswordwithpath requires that you pass a pointer to a C string instead of a pointer to a Pascal string for the serverAddress, serverName, volumeName, accountName, and passwordData parameters.

Version Notes

Available beginning with KeychainLib 2.0. In KeychainLib 1.0, the kcaddinternetpasswordwithpath function provides the same functionality as the KCAddInternetPasswordWithPath function, except that it accepts C strings rather than Pascal strings as arguments. In KeychainLib 2.0, you should use the KCAddInternetPasswordWithPath function, since the function kcaddinternetpasswordwithpath is provided for convenience only and may be removed from the header file at some point in the future.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainAddInternetPassword function in Keychain Services instead.

Declared In

KeychainHI.h

kcaddinternetpasswordwithpath

Not recommended

OSStatus kcaddinternetpasswordwithpath (
   const char *serverName,
   const char *securityDomain,
   const char *accountName,
   const char *path,
   UInt16 port,
   OSType protocol,
   OSType authType,
   UInt32 passwordLength,
   const void *passwordData,
   KCItemRef *item
);

Discussion

This function is available for convenience only and may be removed. Use the function KCAddInternetPasswordWithPath instead.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainAddInternetPassword function in Keychain Services instead.

Declared In

KeychainHI.h

KCAddItem

Adds a password or other keychain item to the default keychain.

Not recommended

OSStatus KCAddItem (
   KCItemRef item
);

Parameters

item: A reference to the keychain item you wish to add. If you pass an existing item in the keychain, the item is updated. If you pass an item that has not been previously added to the keychain and an identical item already exists in the keychain, KCAddItem returns the result code errKCDuplicateItem.

Return Value

A result code. See “Keychain Manager Result Codes.” The result code errKCNoDefaultKeychain indicates that no default keychain could be found. The result code errKCInvalidItemRef indicates that the specified keychain item reference was invalid. The result code errKCDuplicateItem indicates that you tried to add a new item that already exists in the keychain.

Discussion

You can use the KCAddItem function to add a password or other keychain item to the permanent data store of the default keychain. If you want to add a password to a keychain other than the default, call the function KCSetDefaultKeychain to change the default keychain. The KCAddItem function automatically calls the function KCUnlock to display the Unlock Keychain dialog box if the keychain containing the item is currently locked.

Version Notes

Available beginning with KeychainLib 1.0.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

When you use Keychain Services to create an item, it is always added to the specified keychain at creation time.

Declared In

KeychainHI.h

KCChangeSettings

Displays a dialog box enabling the user to change the name, password, or settings of a keychain.

Not recommended

OSStatus KCChangeSettings (
   KCRef keychain
);

Parameters

keychain: A reference to an unlocked keychain. Pass in NULL to specify the default keychain.

Return Value

A result code. See “Keychain Manager Result Codes.” The result code errUserCanceled indicates that the user pressed the Cancel button in the Change Settings dialog box. The result code errKCNoDefaultKeychain indicates that the default keychain could not be found. The result code errKCInvalidKeychain indicates that the specified keychain is invalid.

Discussion

Typically, your application should not call the KCChangeSettings function. You would only call the KCChangeSettings function in response to a user's request to change keychain settings, name, or password. Note that you cannot change a keychain passphrase directly. You must call the KCChangeSettings function and allow the user to change it.

Version Notes

Available beginning with KeychainLib 2.0.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainSetSettings function in Keychain Services instead.

Declared In

KeychainHI.h

KCChooseCertificate

Displays a list of certificates that the user can choose from.

Unsupported

OSStatus KCChooseCertificate (
   CFArrayRef items,
   KCItemRef *certificate,
   CFArrayRef policyOIDs,
   KCVerifyStopOn stopOn
);

Parameters

items: An array of certificate references.
certificate: If the items array only contains one certificate, on return, a pointer to that certificate. In this case, no user interface is displayed.
policyOIDs: An array of trust policy options used for Macintosh file signing. To obtain a pointer to this array, call the function SecMacGetDefaultPolicyOIDs.
stopOn: The criteria to use in selecting the certificates to display. See “Certificate Verification Criteria” for a description of this mask.

Return Value

A result code. See “Keychain Manager Result Codes.” The result code userCanceledErr indicates that the user pressed the Cancel button in the user interface.

Discussion

The KCChooseCertificate function displays a list of the certificates from which the user can choose. If only one certificate matches the criteria, the reference is passed back in the certificate parameter and no user interface is presented.

Version Notes

Available beginning with KeychainLib 2.0.

Carbon Porting Notes

This function is obsolete. There is currently no replacement.

Declared In

KeychainHI.h

KCCopyItem

Copies a password or other keychain item from one keychain to another.

Not recommended

OSStatus KCCopyItem (
   KCItemRef item,
   KCRef destKeychain,
   KCItemRef *copy
);

Parameters

item: A reference to the keychain item you wish to copy.
destKeychain: A reference to the keychain into which the item is to be copied.
copy: A pointer to a reference to the new copied keychain item.

Return Value

A result code. See “Keychain Manager Result Codes.” The result code errKCReadOnly indicates that the destination keychain is read only. The result code errKCNoSuchClass indicates that the item has an invalid keychain item class. The result code errKCInvalidItemRef indicates that the specified keychain item reference was invalid.

Discussion

You can use the KCCopyItem function to copy a keychain item from one keychain to another. The KCCopyItem function automatically calls the function KCUnlock to display the Unlock Keychain dialog box if the keychain containing the item to be copied is currently locked.

Version Notes

Available beginning with KeychainLib 2.0.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainItemCopyContent function in Keychain Services instead.

Declared In

KeychainCore.h

KCCountKeychains

Determines the number of available keychains.

Not recommended

UInt16 KCCountKeychains (
   void
);

Parameters

Return Value

The number of available keychains. This includes all keychains in the Keychains folder, as well as any other keychains known to the Keychain Manager.

Discussion

This function reports the number of keychains known to the Keychain Manager. These keychains are created by the function KCCreateKeychain.

Version Notes

Available beginning with KeychainLib 1.0.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainCopySearchList function in Keychain Services followed by a call to CFArrayGetCount instead.

Declared In

KeychainCore.h

KCCreateKeychain

Creates an empty keychain.

Not recommended

OSStatus KCCreateKeychain (
   StringPtr password,
   KCRef *keychain
);

Parameters

password: A pointer to a Pascal string representing the password string which will be used to protect the new keychain. If you pass NULL, the Keychain Setup dialog box will be displayed to obtain it.
keychain: A pointer to a reference to the keychain you wish to create. You create a keychain reference by calling the function KCMakeKCRefFromFSSpec or KCMakeKCRefFromAlias. If you pass a pointer to a keychain reference, the user will not need to be prompted for a name and location; in all other cases, KCCreateKeychain will interactively request this information from the user. If you pass a pointer to a NULL keychain reference, the Keychain Manager allocates the memory for the keychain reference and returns it in this parameter. Pass a NULL pointer if you do not need a reference returned.

Return Value

A result code. See “Keychain Manager Result Codes.” The result code userCanceledErr indicates that the user pressed the Cancel button in the create keychain. The result code errKCDuplicateKeychain indicates that the user tried to create a keychain which already exists. The result code errKCInvalidKeychain indicates that the specified keychain is invalid. Additional errors may be returned if the keychain could not be created (for example, a file system or network error may be returned if there is no write access to the storage media).

Discussion

The KCCreateKeychain function creates an empty keychain. The keychain and password parameters are optional. If user interaction to create a keychain is posted, the newly-created keychain is automatically unlocked after creation.

You can also call the function kccreatekeychain to create an empty keychain. The function kccreatekeychain requires that you pass a pointer to a C string instead of a pointer to a Pascal string in the password parameter.

Special Considerations

It is recommended that the KCCreateKeychain function not be explicitly called by applications. Instead, you should call one of the add functions in “Storing and Retrieving Passwords” to add a password to the default keychain. If a default keychain does not exist, it is created automatically.

When you are finished with a keychain, you must deallocate its memory by calling the function KCReleaseKeychain.

Version Notes

Available beginning with KeychainLib 1.0. In KeychainLib 1.0, the kccreatekeychain function provides the same functionality as KCCreateKeychain. In KeychainLib 2.0, you should use KCCreateKeychain, since kccreatekeychain is provided for convenience only and may be removed from the header file at some point in the future.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainCreate function in Keychain Services instead.

Declared In

KeychainHI.h

kccreatekeychain

Not recommended

OSStatus kccreatekeychain (
   const char *password,
   KCRef *keychain
);

Discussion

This function is available for convenience only and may be removed. Use the function KCCreateKeychain instead.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainCreate function in Keychain Services instead.

Declared In

KeychainHI.h

KCDeleteItem

Deletes a password or other keychain item from the default keychain.

Not recommended

OSStatus KCDeleteItem (
   KCItemRef item
);

Parameters

item: A reference to the keychain item you wish to delete. If you pass an item that has not been previously added to the keychain, the function KCDeleteItem does nothing and returns noErr.

Return Value

Discussion

You can use the KCDeleteItem function to delete a keychain item from the permanent data store of the default keychain. The KCDeleteItem function automatically calls the function KCUnlock to display the Unlock Keychain dialog box if the keychain containing the item is currently locked.

Special Considerations

The KCDeleteItem function does not dispose the memory occupied by the item reference. To do so, call the function KCReleaseItem when you are finished with an item.

Version Notes

Available beginning with KeychainLib 1.0.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainItemDelete function in Keychain Services instead.

Declared In

KeychainCore.h

KCFindAppleSharePassword

Finds the first AppleShare password in the default keychain that matches the specified parameters.

Not recommended

OSStatus KCFindAppleSharePassword (
   AFPServerSignature *serverSignature,
   ConstStringPtr serverAddress,
   ConstStringPtr serverName,
   ConstStringPtr volumeName,
   ConstStringPtr accountName,
   UInt32 maxLength,
   void *passwordData,
   UInt32 *actualLength,
   KCItemRef *item
);

Parameters

serverSignature: A pointer to a 16-byte Apple File Protocol server signature block. Pass a value of type AFPServerSignature. Pass NULL to match any server signature. The Keychain Manager identifies the location for the password by the information passed in the serverAddress and serverSignature parameters. You must pass a valid value in at least one of these parameters.
serverAddress: A pointer to a Pascal string containing the server address, which may be specified as an AppleTalk zone name, a DNS domain name (in the format "xxx.yyy.zzz"), or an IP address (in the format "111.222.333.444"). The Keychain Manager identifies the location for the password by the information passed in the serverAddress and serverSignature parameters. You must pass a valid value in at least one of these parameters.
serverName: A pointer to a Pascal string containing the server name. Pass NULL to match any server name.
volumeName: A pointer to a Pascal string containing the volume name. Pass NULL to match any volume name.
accountName: A pointer to a Pascal string containing the account name. Pass NULL to match any account name.
maxLength: The length of the buffer pointed to by passwordData.
passwordData: A pointer to a buffer which will hold the returned password data. Before calling KCFindAppleSharePassword, allocate enough memory for the buffer to hold the data you want to store. Pass NULL if you want to obtain the item reference but not the password data. In this case, you must also pass NULL in the actualLength parameter. On return, a pointer to the returned password data.
actualLength: On return, the actual length of the password data that was retrieved. If the buffer pointed to by passwordData is smaller than the actual length of the data, KCFindAppleSharePassword returns the result code errKCBufferTooSmall. In this case, your application must allocate a new buffer of sufficient size before calling KCFindAppleSharePassword again.
item: On return, a pointer to a reference to the found item. Pass NULL if you don’t want to obtain this reference.

Return Value

A result code. See “Keychain Manager Result Codes.” The result code errKCNoDefaultKeychain indicates that no default keychain was found. The result code errKCItemNotFound indicates that no matching password item was found. The result code errKCBufferTooSmall indicates that your application must allocate a new buffer of sufficient size before calling KCFindAppleSharePassword again.

Discussion

The KCFindAppleSharePassword function finds the first AppleShare 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 KCFindAppleSharePassword returns the result code errKCBufferTooSmall. In this case, your application must allocate a new buffer of sufficient size before calling the KCFindAppleSharePassword function again. The KCFindAppleSharePassword function optionally returns a reference to the found item.

The KCFindAppleSharePassword function automatically calls the function KCUnlock to display the Unlock Keychain dialog box if the keychain containing the password is currently locked.

You can also call the function kcfindapplesharepassword to find the first AppleShare server password matching specified attributes. kcfindapplesharepassword requires that you pass a pointer to a C string instead of a pointer to a Pascal string for the serverAddress, serverName, volumeName, accountName, and passwordData parameters.

Version Notes

Available beginning with KeychainLib 1.0. In KeychainLib 1.0, the kcfindapplesharepassword function provides the same functionality as KCFindAppleSharePassword, except that it accepts C strings rather than Pascal strings as arguments. In KeychainLib 2.0, you should use KCFindAppleSharePassword, since kcfindapplesharepassword is provided for convenience only and may be removed from the header file at some point in the future.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the Keychain Services function SecKeychainSearchCreateFromAttributes followed by the SecKeychainSearchCopyNext function instead.

Declared In

KeychainCore.h

kcfindapplesharepassword

Not recommended

OSStatus kcfindapplesharepassword (
   AFPServerSignature *serverSignature,
   const char *serverAddress,
   const char *serverName,
   const char *volumeName,
   const char *accountName,
   UInt32 maxLength,
   void *passwordData,
   UInt32 *actualLength,
   KCItemRef *item
);

Discussion

This function is available for convenience only and may be removed. Use the function KCFindAppleSharePassword instead.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the Keychain Services function SecKeychainSearchCreateFromAttributes followed by the SecKeychainSearchCopyNext function instead.

Declared In

KeychainCore.h

KCFindFirstItem

Finds the first keychain item in a specified keychain that matches specified attributes.

Not recommended

OSStatus KCFindFirstItem (
   KCRef keychain,
   const KCAttributeList *attrList,
   KCSearchRef *search,
   KCItemRef *item
);

Parameters

keychain: A reference to the keychain that you wish to search. If you pass a locked keychain, the Unlock Keychain dialog box is displayed. If you pass NULL, the KCFindFirstItem function searches all unlocked keychains.
attrList: A pointer to a list of 0 or more structures containing information about the keychain item attributes to be matched. Pass NULL to match any attribute.
search: On return, a pointer to a reference to the current search criteria.
item: On return, a pointer to the first matching keychain item.

Return Value

A result code. See “Keychain Manager Result Codes.” The result code errKCNoDefaultKeychain indicates that no default keychain could be found. The result code errKCItemNotFound indicates that no matching keychain item was found. The result code errKCNoSuchAttr indicates that the specified attribute is undefined for this item class.

Discussion

The KCFindFirstItem function returns a reference to the first keychain item in a keychain that matches a list of attributes. The KCFindFirstItem function also returns a reference to the search criteria used. You should pass the returned search criteria in the searchRef parameter of the function KCFindNextItem.

The KCFindFirstItem function automatically calls the function KCUnlock to display the Unlock Keychain dialog box if the keychain containing the item you are searching for is currently locked.

Special Considerations

When you are completely finished with a search, you should the functions KCReleaseItem and KCReleaseSearch to release the memory occupied by the keychain item and search criteria reference.

Version Notes

Available beginning with KeychainLib 1.0.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the Keychain Services function SecKeychainSearchCreateFromAttributes followed by a call to SecKeychainSearchCopyNext instead.

Declared In

KeychainCore.h

KCFindGenericPassword

Finds the first generic password in the default keychain matching the specified parameters.

Not recommended

OSStatus KCFindGenericPassword (
   ConstStringPtr serviceName,
   ConstStringPtr accountName,
   UInt32 maxLength,
   void *passwordData,
   UInt32 *actualLength,
   KCItemRef *item
);

Parameters

serviceName: A pointer to a Pascal string containing an application-defined service name. Pass NULL to match any service name.
accountName: A pointer to a Pascal string containing an application-defined account name. Pass NULL to match any account name.
maxLength: The length of the buffer pointed to by passwordData.
passwordData: A pointer to the buffer that holds the returned password data. Before calling the KCFindGenericPassword function, allocate enough memory for the buffer to hold the data you want to store. Pass NULL if you want to obtain the item reference but not the password data. In this case, you must also pass NULL in the actualLength parameter. On return, a pointer to the returned password data.
actualLength: On return, the actual length of the password data that was retrieved. If the buffer pointed to by the passwordData parameter is smaller than the actual length of the data, the KCFindGenericPassword function returns the result code errKCBufferTooSmall. In this case, your application must allocate a new buffer of sufficient size before calling the KCFindGenericPassword function again.
item: On return, a pointer to a reference to the found item. Pass NULL if you don’t want to obtain this reference.

Return Value

Discussion

The KCFindGenericPassword 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 the function KCFindGenericPassword returns the result code errKCBufferTooSmall. In this case, your application must allocate a new buffer of sufficient size before calling the function KCFindGenericPassword again. The KCFindGenericPassword function optionally returns a reference to the found item.

The KCFindGenericPassword function automatically calls the function KCUnlock to display the Unlock Keychain dialog box if the keychain containing the password is currently locked.

You can also call the function kcfindgenericpassword to find the first generic password matching specified attributes. The kcfindgenericpassword function requires that you pass a pointer to a C string instead of a pointer to a Pascal string for the serverAddress, serverName, volumeName, accountName, and passwordData parameters.

Version Notes

Available beginning with KeychainLib 1.0. In KeychainLib 1.0, the kcfindgenericpassword function provides the same functionality as the function KCFindGenericPassword, except that it accepts C strings rather than Pascal strings as arguments. In KeychainLib 2.0, you should use the KCFindGenericPassword function, since the kcfindgenericpassword function is provided for convenience only and may be removed from the header file at some point in the future.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainFindGenericPassword function in Keychain Services instead.

Declared In

KeychainCore.h

kcfindgenericpassword

Not recommended

OSStatus kcfindgenericpassword (
   const char *serviceName,
   const char *accountName,
   UInt32 maxLength,
   void *passwordData,
   UInt32 *actualLength,
   KCItemRef *item
);

Discussion

This function is available for convenience only and may be removed. Use the function KCFindGenericPassword instead.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainFindGenericPassword function in Keychain Services instead.

Declared In

KeychainCore.h

KCFindInternetPassword

Finds the first Internet password in the default keychain that matches the specified parameters.

Not recommended

OSStatus KCFindInternetPassword (
   ConstStringPtr serverName,
   ConstStringPtr securityDomain,
   ConstStringPtr accountName,
   UInt16 port,
   OSType protocol,
   OSType authType,
   UInt32 maxLength,
   void *passwordData,
   UInt32 *actualLength,
   KCItemRef *item
);

Parameters

serverName: A pointer to a Pascal string containing the server name. Pass NULL to match any server name.
securityDomain: A pointer to a Pascal string containing the security domain. Pass NULL to match any domain.
accountName: A pointer to a Pascal string containing the account name. Pass NULL to match any account name.
port: The TCP/IP port number. Pass the constant kAnyPort, described in “Default Internet Port Constant,” to match any port.
protocol: The protocol associated with this password. See “Keychain Protocol Type Constants” for a description of possible values. Pass the constant kAnyProtocol, described in “Default Internet Protocol And Authentication Type Constants,” to match any protocol.
authType: The authentication scheme used. See “Authentication Type Constants” for a description of possible values. Pass the constant kAnyAuthType, described in “Default Internet Protocol And Authentication Type Constants,” to match any authentication scheme.
maxLength: The length of the buffer pointed to by passwordData.
passwordData: A pointer to the buffer that holds the returned password data. Before calling the KCFindInternetPassword function, allocate enough memory for the buffer to hold the data you want to store. Pass NULL if you want to obtain the item reference but not the password data. In this case, you must also pass NULL in the actualLength parameter. On return, a pointer to the returned password data.
actualLength: On return, the actual length of the password data that was retrieved. If the buffer pointed to by the passwordData parameter is smaller than the actual length of the data, the KCFindInternetPassword function returns the result code errKCBufferTooSmall. In this case, your application must allocate a new buffer of sufficient size before calling the KCFindInternetPassword function again.
item: On return, a pointer to a reference to the found item. Pass NULL if you don’t want to obtain this reference.

Return Value

Discussion

The KCFindInternetPassword function finds the first Internet password item that matches the attributes you provide. The buffer specified in the passwordData parameter must be large enough to hold the password data, otherwise the function KCFindInternetPassword returns the result code errKCBufferTooSmall. In this case, your application must allocate a new buffer of sufficient size before calling the function KCFindInternetPassword again. The KCFindInternetPassword function optionally returns a reference to the found item.

The KCFindInternetPassword function automatically calls the function KCUnlock to display the Unlock Keychain dialog box if the keychain containing the password is currently locked.

You can also call the function kcfindinternetpassword to find the first Internet password item matching specified attributes. The kcfindinternetpassword function requires that you pass a pointer to a C string instead of a Pascal string for the serverAddress, serverName, volumeName, accountName, and passwordData parameters.

Version Notes

Available beginning with KeychainLib 1.0. In KeychainLib 1.0, the kcfindinternetpassword function provides the same functionality as the function KCFindInternetPassword, except that it accepts C strings rather than Pascal strings as arguments. In KeychainLib 2.0, you should use the KCFindInternetPassword function, since kcfindinternetpassword is provided for convenience only and may be removed from the header file at some point in the future.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainFindInternetPassword function in Keychain Services instead.

Declared In

KeychainCore.h

kcfindinternetpassword

Not recommended

OSStatus kcfindinternetpassword (
   const char *serverName,
   const char *securityDomain,
   const char *accountName,
   UInt16 port,
   OSType protocol,
   OSType authType,
   UInt32 maxLength,
   void *passwordData,
   UInt32 *actualLength,
   KCItemRef *item
);

Discussion

This function is available for convenience only and may be removed. Use the function KCFindInternetPassword instead.

Availability

Available in CarbonLib 1.1 and later when KeychainLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Carbon Porting Notes

Use the SecKeychainFindInternetPassword function in Keychain Services instead.

Declared In

KeychainCore.h<