A function identified as deprecated has been superseded and may become unsupported in the future.
Creates a keychain reference from a file specification record. (Deprecated in Mac OS X v10.5.)
Not Recommended
OSStatus KCMakeKCRefFromFSSpec ( FSSpec *keychainFSSpec, KCRef *keychain );
A pointer to a keychain file specification record.
On return, a pointer to a reference to the
keychain specified by the file in the keychainFSSpec parameter.
A result code. See “Keychain Manager Result Codes.”
When you are finished with a keychain, you should call the
function KCReleaseKeychain to deallocate
its memory. You should not use the keychain after its memory has
been deallocated.
Available beginning with KeychainLib 2.0.
Use the SecKeychainOpen function
in Keychain Services instead. If the keychain doesn’t exist, use
the SecKeychainCreate function in Keychain
Services.
KeychainCore.hDisposes of a UPP to your keychain event callback. (Deprecated in Mac OS X v10.6.)
Not recommended
void DisposeKCCallbackUPP ( KCCallbackUPP userUPP );
A Universal Procedure Pointer (UPP) to your keychain event callback function.
A result code. See “Keychain Manager Result Codes.”
When you are finished with a UPP to your keychain event callback
function, you should dispose of it by calling the DisposeKCCallbackUPP function.
There is no replacement function available.
KeychainCore.hInvokes your keychain event callback. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus InvokeKCCallbackUPP ( KCEvent keychainEvent, KCCallbackInfo *info, void *userContext, KCCallbackUPP userUPP );
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.
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.
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.
A Universal Procedure Pointer to your keychain
event callback function. For information on how to create a keychain
event callback function, see KCCallbackProcPtr.
A result code. See “Keychain Manager Result Codes.”
You should not need to use the function InvokeKCCallbackUPP,
as the system calls your KCAddCallback callback
function for you.
There is no replacement function available.
KeychainCore.hAdds a new AppleShare server password to the default keychain. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCAddAppleSharePassword ( AFPServerSignature *serverSignature, StringPtr serverAddress, StringPtr serverName, StringPtr volumeName, StringPtr accountName, UInt32 passwordLength, const void *passwordData, KCItemRef *item );
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.
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.
A pointer to a Pascal string containing the server name.
A pointer to a Pascal string containing the volume name.
A pointer to a Pascal string containing the account name.
The length of the buffer pointed to by 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.
On return, a pointer to a reference to the
added item. Pass NULL if
you don’t want to obtain this reference.
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.
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.
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.
It is recommended that you use internet passwords instead
of AppleShare passwords. Use the SecKeychainAddInternetPassword function
in Keychain Services instead.
KeychainHI.h(Deprecated in Mac OS X v10.6.)
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 );
This function is available for convenience only and may be
removed. Use the function KCAddAppleSharePassword instead.
It is recommended that you use internet passwords instead
of AppleShare passwords. Use the SecKeychainAddInternetPassword function
in Keychain Services instead.
KeychainHI.hRegisters your keychain event callback function. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCAddCallback ( KCCallbackUPP callbackProc, KCEventMask eventMask, void *userContext );
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.
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.
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.
A result
code. See “Keychain Manager Result Codes.” The result code errKCDuplicateCallback indicates
that your callback function is already registered.
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.
Available beginning with KeychainLib 1.0.
Use the SecKeychainAddCallback function
in Keychain Services instead.
KeychainCore.hAdds a new generic password to the default keychain. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCAddGenericPassword ( StringPtr serviceName, StringPtr accountName, UInt32 passwordLength, const void *passwordData, KCItemRef *item );
A pointer to a Pascal string containing an application-defined service name.
A pointer to a Pascal string containing an application-defined account name.
The length of the password data to be stored
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.
On return, a pointer to a reference to the
added item. Pass NULL if
you don’t want to obtain this reference.
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.
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.
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.
Use the SecKeychainAddGenericPassword function
in Keychain Services instead.
KeychainHI.h(Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus kcaddgenericpassword ( const char *serviceName, const char *accountName, UInt32 passwordLength, const void *passwordData, KCItemRef *item );
This function is available for convenience only and may be
removed. Use the function KCAddGenericPassword instead.
Use the SecKeychainAddGenericPassword function
in Keychain Services instead.
KeychainHI.hAdds a new Internet server password to the default keychain. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCAddInternetPassword ( StringPtr serverName, StringPtr securityDomain, StringPtr accountName, UInt16 port, OSType protocol, OSType authType, UInt32 passwordLength, const void *passwordData, KCItemRef *item );
A pointer to a Pascal string containing the server name.
A pointer to a Pascal string containing the security domain. This parameter is optional, as not all protocols will require it.
A pointer to a Pascal string containing the account name.
The TCP/IP port number. Pass the constant kAnyPort,
described in “Default Internet Port Constant,” to specify any port.
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.
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.
The length of the buffer pointed to by 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.
On return, a pointer to a reference to the
added item. Pass NULL if
you don’t want to obtain this reference.
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.
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.
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.
Use the SecKeychainAddInternetPassword function
in Keychain Services instead.
KeychainHI.h(Deprecated in Mac OS X v10.6.)
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 );
This function is available for convenience only and may be
removed. Use the function KCAddInternetPassword instead.
Use the SecKeychainAddInternetPassword function
in Keychain Services instead.
KeychainHI.hAdds a new Internet server password with a specified path to the default keychain. (Deprecated in Mac OS X v10.6.)
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 );
A pointer to a Pascal string containing the server name.
A pointer to a Pascal string containing the security domain. This parameter is optional, as not all protocols will require it.
A pointer to a Pascal string containing the account name.
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.
The TCP/IP port number. Pass the constant kAnyPort,
described in “Default Internet Port Constant,” to specify any port.
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.
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.
The length of the buffer pointed to by 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.
On return, a pointer to a reference to the
added item. Pass NULL if
you don’t want to obtain this reference.
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.
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.
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.
Use the SecKeychainAddInternetPassword function
in Keychain Services instead.
KeychainHI.h(Deprecated in Mac OS X v10.6.)
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 );
This function is available for convenience only and may be
removed. Use the function KCAddInternetPasswordWithPath instead.
Use the SecKeychainAddInternetPassword function
in Keychain Services instead.
KeychainHI.hAdds a password or other keychain item to the default keychain. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCAddItem ( KCItemRef 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.
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.
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.
Available beginning with KeychainLib 1.0.
When you use Keychain Services to create an item, it is always added to the specified keychain at creation time.
KeychainHI.hDisplays a dialog box enabling the user to change the name, password, or settings of a keychain. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCChangeSettings ( KCRef keychain );
A reference to an unlocked keychain. Pass
in NULL to specify the
default keychain.
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.
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.
Available beginning with KeychainLib 2.0.
Use the SecKeychainSetSettings function
in Keychain Services instead.
KeychainHI.hCopies a password or other keychain item from one keychain to another. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCCopyItem ( KCItemRef item, KCRef destKeychain, KCItemRef *copy );
A reference to the keychain item you wish to copy.
A reference to the keychain into which the item is to be copied.
A pointer to a reference to the new copied keychain item.
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.
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.
Available beginning with KeychainLib 2.0.
Use the SecKeychainItemCopyContent function
in Keychain Services instead.
KeychainCore.hDetermines the number of available keychains. (Deprecated in Mac OS X v10.6.)
Not recommended
UInt16 KCCountKeychains ( void );
The number of available keychains. This includes all keychains in the Keychains folder, as well as any other keychains known to the Keychain Manager.
This function reports the number of keychains known to the
Keychain Manager. These keychains are created by the function KCCreateKeychain.
Available beginning with KeychainLib 1.0.
Use the SecKeychainCopySearchList function
in Keychain Services followed by a call to CFArrayGetCount instead.
KeychainCore.hCreates an empty keychain. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCCreateKeychain ( StringPtr password, KCRef *keychain );
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.
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.
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).
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.
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.
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.
Use the SecKeychainCreate function
in Keychain Services instead.
KeychainHI.h(Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus kccreatekeychain ( const char *password, KCRef *keychain );
This function is available for convenience only and may be
removed. Use the function KCCreateKeychain instead.
Use the SecKeychainCreate function
in Keychain Services instead.
KeychainHI.hDeletes a password or other keychain item from the default keychain. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCDeleteItem ( KCItemRef 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.
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.
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.
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.
Available beginning with KeychainLib 1.0.
Use the SecKeychainItemDelete function
in Keychain Services instead.
KeychainCore.hFinds the first AppleShare password in the default keychain that matches the specified parameters. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCFindAppleSharePassword ( AFPServerSignature *serverSignature, ConstStringPtr serverAddress, ConstStringPtr serverName, ConstStringPtr volumeName, ConstStringPtr accountName, UInt32 maxLength, void *passwordData, UInt32 *actualLength, KCItemRef *item );
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.
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.
A pointer to a Pascal string containing the
server name. Pass NULL to
match any server name.
A pointer to a Pascal string containing the
volume name. Pass NULL to
match any volume name.
A pointer to a Pascal string containing the
account name. Pass NULL to
match any account name.
The length of the buffer pointed to by 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.
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.
On return, a pointer to a reference to the
found item. Pass NULL if
you don’t want to obtain this reference.
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.
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.
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.
Use the Keychain Services function SecKeychainSearchCreateFromAttributes followed
by the SecKeychainSearchCopyNext function
instead.
KeychainCore.h(Deprecated in Mac OS X v10.6.)
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 );
This function is available for convenience only and may be
removed. Use the function KCFindAppleSharePassword instead.
Use the Keychain Services function SecKeychainSearchCreateFromAttributes followed
by the SecKeychainSearchCopyNext function
instead.
KeychainCore.hFinds the first keychain item in a specified keychain that matches specified attributes. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCFindFirstItem ( KCRef keychain, const KCAttributeList *attrList, KCSearchRef *search, KCItemRef *item );
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.
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.
On return, a pointer to a reference to the current search criteria.
On return, a pointer to the first matching keychain item.
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.
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.
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.
Available beginning with KeychainLib 1.0.
Use the Keychain Services function SecKeychainSearchCreateFromAttributes followed
by a call to SecKeychainSearchCopyNext instead.
KeychainCore.hFinds the first generic password in the default keychain matching the specified parameters. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCFindGenericPassword ( ConstStringPtr serviceName, ConstStringPtr accountName, UInt32 maxLength, void *passwordData, UInt32 *actualLength, KCItemRef *item );
A pointer to a Pascal string containing an
application-defined service name. Pass NULL to
match any service name.
A pointer to a Pascal string containing an
application-defined account name. Pass NULL to
match any account name.
The length of the buffer pointed to by 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.
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.
On return, a pointer to a reference to the
found item. Pass NULL if
you don’t want to obtain this reference.
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 the function KCFindGenericPassword again.
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.
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.
Use the SecKeychainFindGenericPassword function
in Keychain Services instead.
KeychainCore.h(Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus kcfindgenericpassword ( const char *serviceName, const char *accountName, UInt32 maxLength, void *passwordData, UInt32 *actualLength, KCItemRef *item );
This function is available for convenience only and may be
removed. Use the function KCFindGenericPassword instead.
Use the SecKeychainFindGenericPassword function
in Keychain Services instead.
KeychainCore.hFinds the first Internet password in the default keychain that matches the specified parameters. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCFindInternetPassword ( ConstStringPtr serverName, ConstStringPtr securityDomain, ConstStringPtr accountName, UInt16 port, OSType protocol, OSType authType, UInt32 maxLength, void *passwordData, UInt32 *actualLength, KCItemRef *item );
A pointer to a Pascal string containing the
server name. Pass NULL to
match any server name.
A pointer to a Pascal string containing the
security domain. Pass NULL to match
any domain.
A pointer to a Pascal string containing the
account name. Pass NULL to
match any account name.
The TCP/IP port number. Pass the constant kAnyPort,
described in “Default Internet Port Constant,” to match any port.
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.
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.
The length of the buffer pointed to by 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.
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.
On return, a pointer to a reference to the
found item. Pass NULL if
you don’t want to obtain this reference.
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 the function KCFindInternetPassword again.
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.
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.
Use the SecKeychainFindInternetPassword function
in Keychain Services instead.
KeychainCore.h(Deprecated in Mac OS X v10.6.)
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 );
This function is available for convenience only and may be
removed. Use the function KCFindInternetPassword instead.
Use the SecKeychainFindInternetPassword function
in Keychain Services instead.
KeychainCore.hFinds the first Internet password in the default keychain that matches the specified parameters, including path information. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCFindInternetPasswordWithPath ( ConstStringPtr serverName, ConstStringPtr securityDomain, ConstStringPtr accountName, ConstStringPtr path, UInt16 port, OSType protocol, OSType authType, UInt32 maxLength, void *passwordData, UInt32 *actualLength, KCItemRef *item );
A pointer to a Pascal string containing the
server name. Pass NULL to
match any server name.
A pointer to a Pascal string containing the
security domain. Pass NULL to match
any domain.
A pointer to a Pascal string containing the
account name. Pass NULL to
match any account name.
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.
The TCP/IP port number. Pass the constant kAnyPort,
described in “Default Internet Port Constant,” to match any port.
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.
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.
The length of the buffer pointed to by passwordData.
A pointer to a buffer which will hold the
returned password data. Before calling the KCFindInternetPasswordWithPath 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.
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 function KCFindInternetPasswordWithPath returns
the result code errKCBufferTooSmall.
In this case, your application must allocate a new buffer of sufficient
size before calling the function KCFindInternetPasswordWithPath again.
On return, a pointer to a reference to the
found item. Pass NULL if
you don’t want to obtain this reference.
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 the function KCFindInternetPasswordWithPath again.
The KCFindInternetPasswordWithPath function
finds the first Internet password item which matches the attributes
you provide, including path information. The buffer specified in
the passwordData parameter
must be large enough to hold the password data, otherwise the function KCFindInternetPasswordWithPath returns
the result code errKCBufferTooSmall.
In this case, your application must allocate a new buffer of sufficient
size before calling the KCFindInternetPasswordWithPath function
again. The KCFindInternetPasswordWithPath function
optionally returns a reference to the found item.
The KCFindInternetPasswordWithPath 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 kcfindinternetpasswordwithpath to
find the first Internet password item matching specified attributes.
The function kcfindinternetpasswordwithpath 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.
Available beginning with KeychainLib 2.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 KCFindInternetPassword,
since kcfindinternetpassword is
provided for convenience only and may be removed from the header
file at some point in the future.
Use the SecKeychainFindInternetPassword function
in Keychain Services instead.
KeychainCore.h(Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus kcfindinternetpasswordwithpath ( const char *serverName, const char *securityDomain, const char *accountName, const char *path, UInt16 port, OSType protocol, OSType authType, UInt32 maxLength, void *passwordData, UInt32 *actualLength, KCItemRef *item );
This function is available for convenience only and may be
removed. Use the function KCFindInternetPasswordWithPath instead.
Use the SecKeychainFindInternetPassword function
in Keychain Services instead.
KeychainCore.hFinds the next keychain item matching the previously specified search criteria. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCFindNextItem ( KCSearchRef search, KCItemRef *item );
A reference to the previously-specified search
criteria. Pass the reference passed back in the searchRef parameter
of the function KCFindFirstItem.
On return, a pointer to the next matching keychain item, if any.
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 errKCInvalidSearchRef indicates
that the specified search reference was invalid.
The KCFindNextItem function
finds the next keychain item matching the search criteria previously
specified by a call to the function KCFindFirstItem. The KCFindNextItem function returns
a reference to the matching item, if any. The KCFindNextItem 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.
When you are completely finished with a search, you should
use the functions KCReleaseItem and KCReleaseSearch to
release the keychain item and search criteria reference.
Available beginning with KeychainLib 1.0.
Use the SecKeychainSearchCopyNext function
in Keychain Services instead.
KeychainCore.hDetermines keychain item data using a keychain item attribute structure. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCGetAttribute ( KCItemRef item, KCAttribute *attr, UInt32 *actualLength );
A reference to the keychain item whose attribute data you wish to determine.
A pointer to a structure of type KCAttribute. Before
calling the KCGetAttribute function,
fill in the tag, length,
and data fields (the data field
should contain a pointer to a buffer of sufficient length for the
type of data to be returned). On return, the KCGetAttribute function
passes back the requested data in the data field.
On return, a pointer to the actual length of the attribute data. This may be more than the length you allocated in the length field of the attribute structure.
A result
code. See “Keychain Manager Result Codes.” The result code errKCInvalidItemRef indicates
that the specified keychain item reference was invalid. The result
code errKCNoSuchAttr indicates
that you tried to set an attribute which is undefined for this item
class. The result code errKCBufferTooSmall indicates
that your application must allocate a new buffer of sufficient size
before calling KCGetAttribute again.
You can call the function KCGetAttribute or
the function KCGetData to
obtain keychain item data. The difference between the functions
is that the function KCGetData requires
that you pass the length of the data and a pointer to that data
as separate parameters rather than fields in a keychain item attribute
structure.
If the keychain that contains the item is locked, before calling
the KCGetAttribute function you
should call the function KCUnlock to
prompt the user to unlock the keychain.
You can determine any of the standard item attributes identified
by the following tag constants: kClassKCItemAttr, kCreationDateKCItemAttr, kModDateKCItemAttr, kDescriptionKCItemAttr, kCommentKCItemAttr, kLabelKCItemAttr, kCreatorKCItemAttr, kScriptCodeKCItemAttr,
and kCustomIconKCItemAttr.
There is additional data you can determine, depending upon the type
of keychain item whose data you wish to obtain. See “Keychain Item Attribute Tag Constants” for more information.
Available beginning with KeychainLib 1.0.
Use the SecKeychainItemCopyAttributesAndData function
in Keychain Services instead.
KeychainCore.hDetermines keychain item data. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCGetData ( KCItemRef item, UInt32 maxLength, void *data, UInt32 *actualLength );
A reference to the keychain item whose data you wish to determine.
The length of the data buffer pointed to by
the data parameter.
A pointer to the buffer that holds the returned
data. Before calling the KCGetData function,
allocate enough memory for the buffer to hold the data you want
to store. On return, a pointer to the attribute data you requested.
On return, a pointer to the actual length
of the data being retrieved. If the buffer pointed to by the data parameter
is smaller than the actual length of the data, the KCGetData function
returns the result code errKCBufferTooSmall.
In this case, your application must allocate a new buffer of sufficient
size before calling KCGetData again.
A result
code. See “Keychain Manager Result Codes.” The result code errKCInvalidItemRef indicates
that the specified keychain item reference was invalid. The result
code errKCBufferTooSmall indicates
that your application must allocate a new buffer of sufficient size
before calling KCGetData again.
The result code errKCDataNotModifiable indicates
that the data is not available for this item.
You can call the function KCGetData or
the function KCGetAttribute to
obtain keychain item data. The difference between the functions
is that the function KCGetAttribute requires
that you pass the length of the data and a pointer to that data
as fields in a keychain item attribute structure rather than as
separate parameters.
If the keychain that contains the item is locked, before calling
the function KCGetData you should
call the function KCUnlock to
prompt the user to unlock the keychain. You cannot call the KCGetData function
for a private key.
You can determine any of the standard item attributes identified
by the following tag constants: kClassKCItemAttr, kCreationDateKCItemAttr, kModDateKCItemAttr, kDescriptionKCItemAttr, kCommentKCItemAttr, kLabelKCItemAttr, kCreatorKCItemAttr, kScriptCodeKCItemAttr,
and kCustomIconKCItemAttr.
There is additional data you can determine, depending upon the type
of keychain item whose data you wish to obtain. See “Keychain Item Attribute Tag Constants” for more information.
Available beginning with KeychainLib 1.0.
Use the SecKeychainItemCopyContent function
in Keychain Services instead.
KeychainCore.hObtains the default keychain. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCGetDefaultKeychain ( KCRef *keychain );
On return, a pointer to default keychain reference.
A result
code. See “Keychain Manager Result Codes.” The result code errKCNoDefaultKeychain indicates
that there is no default keychain.
You can determine the name of the default keychain by passing
the returned keychain reference to the function KCGetKeychainName.
Available beginning with KeychainLib 2.0.
Use the SecKeychainCopyDefault function
in Keychain Services instead.
KeychainCore.hObtains the reference to an indexed keychain. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCGetIndKeychain ( UInt16 index, KCRef *keychain );
An index of the list of available keychains.
Pass a value between 1 and the number returned by the function KCCountKeychains.
On return, pointer to the keychain reference
corresponding to the index in the index parameter.
A result
code. See “Keychain Manager Result Codes.” The result code errKCNoSuchKeychain indicates
that the index value is out of range.
To guarantee correct operation, you should call the function KCCountKeychains once
before calling KCGetIndKeychain.
The memory that the keychain reference occupies must be released
by calling the function KCReleaseKeychain when
you are finished with it.
Available beginning with KeychainLib 1.0.
Use the SecKeychainCopySearchList function
in Keychain Services followed by a call to CFArrayGetValueAtIndex instead.
KeychainCore.hDetermines the location of a password or other keychain item. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCGetKeychain ( KCItemRef item, KCRef *keychain );
A reference to the keychain item whose keychain
location you wish to determine. If you pass a reference to a keychain
item whose keychain is locked, the KCGetKeychain function
returns the result code errKCInvalidItemRef.
On return, a pointer to the keychain containing the specified item.
A result
code. See “Keychain Manager Result Codes.” The result code errKCInvalidItemRef indicates
that the keychain item reference was invalid.
The KCGetKeychain function
determines the location of a keychain item in an unlocked keychain.
It does not search locked keychains. Calling the KCGetKeychain function
displays the Unlock Keychain dialog box if the keychain containing
the item is currently locked.
The keychain reference returned by KCGetKeychain should
be released by calling the function KCReleaseItem.
Available beginning with KeychainLib 1.0.
Use the SecKeychainItemCopyKeychain function
in Keychain Services instead.
KeychainCore.hDetermines the name of a keychain. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCGetKeychainName ( KCRef keychain, StringPtr keychainName );
A reference to the keychain whose name you wish to obtain.
A pointer to a Pascal string. On return, this string contains the name of the keychain.
A result
code. See “Keychain Manager Result Codes.” The result code errKCInvalidKeychain indicates
that the keychain is invalid.
You can also call the function kcgetkeychainname to
obtain the name of a keychain. kcgetkeychainname requires
that you pass a pointer to a C string instead of a pointer to a Pascal
string in the keychainName parameter.
Available beginning with KeychainLib 2.0.
Use the SecKeychainGetPath function
in Keychain Services instead.
KeychainCore.h(Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus kcgetkeychainname ( KCRef keychain, char *keychainName );
This function is available for convenience only and may be
removed. Use the function KCGetKeychainName instead.
Use the SecKeychainGetPath function
in Keychain Services instead.
KeychainCore.hDetermines the permissions that are set in a keychain. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCGetStatus ( KCRef keychain, UInt32 *keychainStatus );
A pointer to the keychain reference whose
permissions you wish to determine. Pass NULL to
obtain the status of the default keychain.
On return, a pointer to a bitmask that you can test to determine the permissions that are set in a keychain. See “Keychain Status Constants” for a description of this mask.
A result
code. See “Keychain Manager Result Codes.” The result code errKCNoSuchKeychain indicates
that the specified keychain could not be found. The result code errKCInvalidKeychain indicates
that the specified keychain is invalid.
Available beginning with KeychainLib 1.0.
Use the SecKeychainGetStatus function
in Keychain Services instead.
KeychainCore.hIndicates whether Keychain Manager functions that display a user interaction will do so. (Deprecated in Mac OS X v10.6.)
Not recommended
Boolean KCIsInteractionAllowed ( void );
A Boolean value
indicating whether user interaction is permitted. If true, user
interaction is allowed, and Keychain Manager functions that display
a user interface can do so as appropriate.
Available beginning with KeychainLib 2.0.
Use the SecKeychainGetUserInteractionAllowed function
in Keychain Services instead.
KeychainCore.hLocks a keychain. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCLock ( KCRef keychain );
A reference to the keychain to lock. Pass NULL to
lock all unlocked keychains.
A result
code. See “Keychain Manager Result Codes.” The result code errKCNoSuchKeychain indicates
that specified keychain could not be found. The result code errKCInvalidKeychain indicates
that the specified keychain is invalid.
Your application should not call the KCLock function
unless you are responding to a user's request to lock a keychain.
In general, you should leave the keychain unlocked so that the user
does not have to unlock it again in another application.
The function KCLock replaces
the function KCLockKeychain,
which was available in KeychainLib 1.0.
Use the SecKeychainLock function
in Keychain Services instead.
KeychainCore.hCreates an alias to a keychain reference. (Deprecated in Mac OS X v10.6.)
Not Recommended
OSStatus KCMakeAliasFromKCRef ( KCRef keychain, AliasHandle *keychainAlias );
A reference to the keychain for which you want to create an alias.
On return, a pointer to an alias handle to the file referred to by the keychain reference.
A result code. See “Keychain Manager Result Codes.”
You may wish to call the KCMakeAliasFromKCRef function
to determine the location of a keychain.
When you are finished with a keychain, you should call the
function KCReleaseKeychain to deallocate
its memory. You should not use the keychain after its memory has
been deallocated.
Available beginning with KeychainLib 2.0.
Use the SecKeychainGetPath function
in Keychain Services followed by calls to the function FSPathMakeRef and FSNewAlias instead.
KeychainCore.hCreates a keychain reference from a keychain alias. (Deprecated in Mac OS X v10.6.)
Not Recommended
OSStatus KCMakeKCRefFromAlias ( AliasHandle keychainAlias, KCRef *keychain );
A handle to an alias record of the keychain file. Since the keychain is a file, an alias can be made to the keychain file.
On return, a pointer to a reference to the
keychain specified by the alias in the keychainAlias parameter.
A result code. See “Keychain Manager Result Codes.”
When you are finished with a keychain, you should call the
function KCReleaseKeychain to deallocate
its memory. You should not use the keychain after its memory has
been deallocated.
Available beginning with KeychainLib 2.0.
Use the SecKeychainOpen function
in Keychain Services instead. If the keychain doesn’t exist, use
the SecKeychainCreate function in Keychain
Services.
KeychainCore.hCreates a reference to a keychain item. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCNewItem ( KCItemClass itemClass, OSType itemCreator, UInt32 length, const void *data, KCItemRef *item );
The type of keychain item that you wish to
create. See “Keychain Item Type Constants” for a description of possible
values and a description of the KCItemClass data
type.
The creator code of the application that owns this item.
The length of the data to be stored in this item.
A pointer to a buffer containing the data
to be stored in this item. Before calling KCNewItem,
allocate enough memory for the buffer to hold the data you want
to store.
On return, a pointer to a reference to the newly-created item.
A result
code. See “Keychain Manager Result Codes.” The Memory Manager
result code memFullErr indicates
that you did not allocate enough memory in the current heap to create
the item.
After calling the KCNewItem function,
you should call the function KCAddItem if
you wish to permanently store a password or other keychain item.
Note that a copy of the data buffer pointed to by the data parameter
is stored in the newly-created item.
When you are done with a keychain item, you should call the
function KCReleaseItem to release
its memory. You should not use the item after its memory has been
deallocated.
Available beginning with KeychainLib 1.0.
Use the SecKeychainItemCreateFromContent function
in Keychain Services instead.
KeychainCore.hDisposes of the memory occupied by a keychain item reference. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCReleaseItem ( KCItemRef *item );
A pointer to a keychain item reference. Pass
the keychain item reference whose memory you want to release. On
return, the reference is set to NULL and
should not be used again.
A result code. See “Keychain Manager Result Codes.”
You should call the KCReleaseItem function
to release the memory occupied by a keychain item reference when
you are finished with it.
Available beginning with KeychainLib 1.0
Use the CFRelease function instead.
KeychainCore.hDisposes of the memory associated with a keychain reference. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCReleaseKeychain ( KCRef *keychain );
A pointer to a keychain reference. Pass the
keychain reference whose memory you want to release. On return,
the reference is set to NULL and should
not be used again.
A result code. See “Keychain Manager Result Codes.”
You should call the KCReleaseKeychain function
to release the memory occupied by a keychain reference when you
are finished with it. You should not use the reference after it has
been released.
Available beginning with KeychainLib 2.0.
Use the CFRelease function instead.
KeychainCore.hDisposes of the memory occupied by a search criteria reference. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCReleaseSearch ( KCSearchRef *search );
A pointer to a search criteria reference.
Pass the search criteria reference whose memory you want to release.
On return, the reference is set to NULL and
should not be used again.
A result
code. See “Keychain Manager Result Codes.” The result code errKCInvalidSearchRef indicates
that the specified search reference was invalid.
You should call the KCReleaseSearch function
to release the memory occupied by a search criteria reference when
you are completely finished with a search performed by calling the functions KCFindFirstItem or KCFindNextItem.
Available beginning with KeychainLib 1.0
Use the CFRelease function instead.
KeychainCore.hUnregisters your keychain event callback function. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCRemoveCallback ( KCCallbackUPP callbackProc );
A Universal Procedure Pointer (UPP) to your
keychain event callback function that was previously registered
with the function KCAddCallback.
A result
code. See “Keychain Manager Result Codes.” The result code errKCInvalidCallback indicates
that the callback function was not previously registered.
After you pass a UPP to your keychain event callback function
to the KCRemoveCallback function,
it will no longer be called by the Keychain Manager.
After calling KCRemoveCallback,
you should call the function DisposeKCCallbackUPP to dispose
of the UPP to your callback function.
Available beginning with KeychainLib 1.0.
Use the SecKeychainRemoveCalllback function
in Keychain Services instead.
KeychainCore.hSets or edits keychain item data using a keychain item attribute structure. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCSetAttribute ( KCItemRef item, KCAttribute *attr );
A reference to the keychain item whose data you wish to set or edit.
A pointer to a structure of type KCAttribute containing
keychain item data you want to set. Before calling the function KCSetAttribute,
fill in the tag, length,
and data fields of this
structure with the tag identifying the attribute you wish to modify
or set, the length of the attribute data you wish to set, and a
pointer to that data, respectively.
A result
code. See “Keychain Manager Result Codes.” The result code errKCInvalidItemRef indicates
that the keychain item reference was invalid. The result code errKCNoSuchAttr indicates
that the item attribute you wish to set is undefined for the specified
item. The result code errKCDataTooLarge indicates
that more data was supplied than is allowed for this attribute.
You can call the KCSetAttribute function
or the function KCSetData to
set or modify keychain item data. The difference between the functions
is that the KCSetData function requires
that you pass the length of the data and a pointer to that data
as separate parameters rather than fields in a keychain item attribute
structure.
If the keychain that contains the item is locked, before calling
the KCSetAttribute function you
should call the function KCUnlock to
prompt the user to unlock the keychain. The keychain must permit
read/write access in order to modify keychain item data.
You can only set or modify standard item attributes identified
by the tag constants kDescriptionKCItemAttr, kCommentKCItemAttr, kLabelKCItemAttr, kCreatorKCItemAttr, kTypeKCItemAttr,
and kCustomIconKCItemAttr.
In addition, each class of keychain item has attributes specific
to that class which may be set or modified. See “Keychain Item Attribute Tag Constants” for
more information.
Available beginning with KeychainLib 1.0.
Use the SecKeychainItemModifyAttributesAndData function
in Keychain Services instead.
KeychainCore.hSets or edits keychain item data. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCSetData ( KCItemRef item, UInt32 length, const void *data );
A reference to the keychain item whose data you wish to set.
The length of the data buffer pointed to by
the data parameter.
A pointer to a buffer containing the data
to be stored in this item. Before calling the KCSetData function,
allocate enough memory for the buffer to hold the data you want
to store.
A result
code. See “Keychain Manager Result Codes.” The result code errKCInvalidItemRef indicates
that the specified keychain item reference was invalid. The result
code errKCDataTooLarge indicates
that the data was too large for the supplied buffer. The result
code errKCDataNotModifiable indicates
that the data cannot be set for this item.
You can call the function KCSetData or
the function KCSetAttribute to
set or modify keychain item data. The difference between the functions
is that the function KCSetAttribute requires
that you pass the length of the data buffer as a field in a keychain item
attribute structure rather than as a separate parameter.
If the keychain that contains the item is locked, before calling
the KCSetData function
you should call the function KCUnlock to
prompt the user to unlock the keychain. The keychain must permit
read/write access in order to modify keychain item data.
You can set or edit any of the standard item attributes identified
by the following tag constants: kDescriptionKCItemAttr, kCommentKCItemAttr, kLabelKCItemAttr, kCreatorKCItemAttr, kTypeKCItemAttr,
and kCustomIconKCItemAttr.
There is additional data you can set, depending upon the type of
keychain item whose data you are manipulating. See “Keychain Item Attribute Tag Constants” for more information.
Available beginning with KeychainLib 1.0.
Use the SecKeychainItemModifyContent function
in Keychain Services instead.
KeychainCore.hSets the default keychain. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCSetDefaultKeychain ( KCRef keychain );
A reference to the keychain you wish to make the default.
A result
code. See “Keychain Manager Result Codes.” The result code errKCNoSuchKeychain indicates
that the specified keychain could not be found. The result code errKCInvalidKeychain indicates
that the specified keychain is invalid.
In most cases, your application should not need to set the
default keychain, because this is a choice normally made by the
user. You should call the KCSetDefaultKeychain function
to change where a password or other keychain items are added.
The KCSetDefaultKeychain function
sets the default keychain regardless of whether the keychain is
currently locked.
Available beginning with KeychainLib 2.0.
Use the SecKeychainSetDefault function
in Keychain Services instead.
KeychainCore.hEnables or disables Keychain Manager functions that display a user interface. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCSetInteractionAllowed ( Boolean state );
A flag that indicates whether the Keychain
Manager will display a user interface. If you pass true,
user interaction is allowed. This is the default value. If false,
Keychain Manager functions that normally display a user interface
will instead return an error.
A result code. See “Keychain Manager Result Codes.”
The KCSetInteractionAllowed function
enables you to control whether the functions KCLock, KCUnlock, and KCChangeSettings display a user interface.
Note that failure to re-enable user interaction will affect other
clients of the Keychain Manager. By default, user interaction is
permitted.
Available beginning with KeychainLib 2.0.
Use the SecKeychainSetUserInteractionAllowed function
in Keychain Services instead.
KeychainCore.hDisplays a dialog box that prompts the user for a password before unlocking a keychain. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCUnlock ( KCRef keychain, StringPtr password );
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, the function KCUnlock displays
the Unlock Keychain dialog box and the keychain appears as the chosen
menu item in the keychain popup menu. If the default keychain is
currently unlocked, the Unlock Keychain dialog box is not displayed
and the KCUnlock function
returns noErr.
A pointer to a Pascal string representing
the password string for this keychain. Pass NULL if
the user password is unknown. In this case, The KCUnlock function
displays the Unlock Keychain dialog box, and the authentication
user interface associated with the keychain about to be unlocked.
If you specify an invalid password, you will not be able to unlock the
keychain with a specified password until the machine is rebooted.
In this case, the KCUnlock function
returns errKCInteractionRequired.
A result
code. See “Keychain Manager Result Codes.” The result code noErr does
not guarantee that the specified keychain is unlocked, because the
user can select any available keychain and unlock it. The result
code userCanceledErr indicates
that the user pressed the Cancel button in the Unlock Keychain dialog
box. The result code errKCAuthFailed indicates
that authentication failed because of too many unsuccessful retries.
The result code errKCInteractionRequired indicates
that user interaction is required to unlock the keychain. In this
case, you will not be able to unlock the keychain with that password
until the machine is rebooted.
In most cases, your application does not need to call the KCUnlock function
directly, since most Keychain Manager functions that require an
unlocked keychain call KCUnlock automatically.
If your application needs to verify that a keychain is unlocked,
call the function KCGetStatus.
You can also call the function kcunlock to
display a user interface prompting the user to unlock a keychain.
The kcunlock function
requires that you pass a pointer to a C string instead of a pointer
to a Pascal string in the password parameter.
It is recommended that the KCUnlock function
not be explicitly called by applications. Most functions that require
an unlocked keychain call the KCUnlock function
for you.
The memory that the keychain reference occupies must be released
by calling the function KCReleaseKeychain when
you are finished with it.
The KCUnlock function
replaces the function KCUnlockKeychain,
which was available in KeychainLib 1.0.
Use the SecKeychainUnlock function
in Keychain Services instead.
KeychainHI.h(Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus kcunlock ( KCRef keychain, const char *password );
This function is available for convenience only and may be
removed. Use the function KCUnlock instead.
Use the SecKeychainUnlock function
in Keychain Services instead.
KeychainHI.hUpdates a password or other keychain item. (Deprecated in Mac OS X v10.6.)
Not recommended
OSStatus KCUpdateItem ( KCItemRef item );
A reference to the keychain item whose data
you wish to update. If you pass an item that has not been previously
added to the keychain, the KCUpdateItem function
does nothing and returns noErr.
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.
You can use the KCUpdateItem function
to update a password or other keychain item in a keychain’s permanent
data store after changing its data. The function KCUpdateItem automatically
calls the function KCUnlock to
display the Unlock Keychain dialog box if the keychain containing
the item is currently locked.
Available beginning with KeychainLib 1.0.
Use the SecKeychainItemModifyContent function
in Keychain Services instead.
KeychainCore.hCreates a UPP to your keychain event callback. (Deprecated in Mac OS X v10.6.)
Not recommended
KCCallbackUPP NewKCCallbackUPP ( KCCallbackProcPtr userRoutine );
A pointer to your keychain event callback
function. For information on how to create a keychain event callback,
see KCCallbackProcPtr.
A UPP to your callback
function. You can register your callback function by passing this
UPP in the callbackProc parameter
of the function KCAddCallback. See the description of the KCCallbackUPP data type.
The NewKCCallbackUPP function
creates a pointer to your keychain event callback function. You
pass a pointer to your callback function in the callbackProc parameter
of the function KCAddCallback if
you want your application to receive data transfer events.
When you are finished with a UPP to your keychain event callback
function, you should dispose of it by calling the function DisposeKCCallbackUPP.
There is no replacement function available.
KeychainCore.hLast updated: 2005-07-07
