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

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

KCFindX509Certificates

Finds the certificates in a keychain that match specified search criteria.

Unsupported

OSStatus KCFindX509Certificates (
   KCRef keychain,
   CFStringRef name,
   CFStringRef emailAddress,
   KCCertSearchOptions options,
   CFMutableArrayRef *certificateItems
);

Parameters

keychain: A reference to the keychain you want to search. If the keychain is locked, the Unlock Keychain dialog box is automatically displayed.
name: A pointer to a C string containing the certificate owner's common name.
emailAddress: A pointer to a C string containing the certificate owner’s email address.
options: The search criteria you wish to use. See “Certificate Search Options” for a description of this mask.
certificateItems: On return, a pointer to a list of the matching certificates. Pass NULL if you don’t want to obtain these references.

Return Value

A result code. See “Keychain Manager Result Codes.” The result code errKCNoDefaultKeychain indicates that a default keychain was not found. The result code errKCBufferTooSmall indicates that the certificate data was too large for the supplied buffer. In this case, you should allocate a new buffer of sufficient size before calling KCFindX509Certificates again. The result code errKCItemNotFound indicates that no matching certificate was found.

Version Notes

Available beginning with KeychainLib 2.0.

Carbon Porting Notes

This function is obsolete. There is currently no replacement.

Declared In

KeychainHI.h

KCGetKeychainManagerVersion

Determines the version of the Keychain Manager installed on the user’s system.

Not Recommended

OSStatus KCGetKeychainManagerVersion (
   UInt32 *returnVers
);

Parameters

returnVers: On return, a pointer to the version number of the Keychain Manager installed on the current system.

Return Value

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

Discussion

Your application can call the KCGetKeychainManagerVersion function to find out which version of the Keychain Manager is installed on the user's system.

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 SecKeychainGetVersion function in Keychain Services instead.

Declared In

KeychainCore.h

Callbacks

KCCallbackProcPtr

Defines a pointer to your keychain event callback that handles user keychain access events.

typedef OSStatus (*KCCallbackProcPtr)
(
   KCEvent keychainEvent,
   KCCallbackInfo * info,
   void * userContext
);

If you name your function MyKCCallbackProc, you would declare it like this:

OSStatus MyKCCallbackProc (
   KCEvent keychainEvent,
   KCCallbackInfo * info,
   void * userContext
);

Parameters

keychainEvent: The keychain event that your application wishes to be notified of. See “Keychain Events Constants” for a description of possible values. The type of event that can trigger your callback depends on the bitmask you passed in the eventMask parameter of the function KCAddCallback. For more information, see the discussion.
info: A pointer to a structure of type KCCallbackInfo. On return, the structure contains information about the keychain event that occurred. The Keychain Manager passes this information to your callback function via the info parameter of the function InvokeKCCallbackUPP.
userContext: A pointer to application-defined storage that your application previously passed to the function KCAddCallback. You can use this value to perform operations such as tracking which instance of a function is operating.

Return Value

A result code. See “Keychain Manager Result Codes.” Your keychain event callback function should process the keychain event and return noErr.

Discussion

Your keychain event callback function handles those keychain events that you indicate. In order to be notified of these events, you must pass a UPP to your notification callback function in the callbackProc parameter of KCAddCallback. You indicate the type of data transfer events you want to receive via a bitmask in the eventMask parameter. When you no longer wish to receive notification of keychain events, you should call the function KCRemoveCallback to dispose of the UPP to your keychain event callback function.

Carbon Porting Notes

Use the SecKeychainCalllback function in Keychain Services instead.

Availability

Available in Mac OS X v10.0 and later.

Declared In

KeychainCore.h

Data Types

AFPServerSignature

Represents a 16-byte Apple File Protocol server signature block.

typedef UInt8 AFPServerSignature[16];

Discussion

The AFPServerSignature type represents a 16-byte Apple File Protocol server signature block. You can pass a value of this type in the serverSignature parameter of the functions KCAddAppleSharePassword and KCFindAppleSharePassword to represent an Apple File Protocol server signature. You can use a value of this type with the keychain item attribute constant kSignatureKCItemAttr to specify an Apple File Protocol server signature.

Availability

Available in Mac OS X v10.0 and later.

Declared In

KeychainCore.h

KCAttribute

Contains information about a keychain item attribute.

typedef SecKeychainAttribute KCAttribute;

Discussion

The KCAttribute type represents a structure containing information about the attribute of a keychain item. It contains a tag that identifies a particular keychain item attribute value, the length of the attribute value, and a pointer to the attribute value. You can modify attribute data for a keychain item attribute by passing a pointer to this structure in the attr parameter of the function KCSetAttribute. The function KCGetAttribute passes back a pointer to this structure in the attr parameter.

Availability

Available in Mac OS X v10.0 and later.

Declared In

KeychainCore.h

KCAttributeList

Lists attributes in a keychain item.

typedef SecKeychainAttributeList KCAttributeList;

Discussion

The KCAttributeList type represents a list of structures containing information about the attributes in a keychain item. You pass a pointer to this list of 0 or more structures in the attrList parameter of the function KCFindFirstItem to indicate the attributes to be matched.

Availability

Available in Mac OS X v10.0 and later.

Declared In

KeychainCore.h

KCAttrType

Identifies a keychain item attribute value.

typedef SecKeychainAttrType KCAttrType;

Discussion

The KCAttrType type represents a tag that identifies a keychain item attribute value. You can use this value in the tag field of the structure KCAttribute to identify the keychain item attribute value you wish to set or obtain. See Keychain Item Attribute Tag Constants for a description of the Apple-defined tag constants and the data types of the values they identify. Your application can create application-defined tags of type KCAttrType.

Availability

Available in Mac OS X v10.0 and later.

Declared In

KeychainCore.h

KCCallbackInfo

Contains information about a keychain event.

struct KCCallbackInfo {
   UInt32 version;
   KCItemRef item;
   long processID[2];
   long event[4];
   KCRef keychain;
};
typedef struct KCCallbackInfo KCCallbackInfo;

Fields

version: The version of this structure.
item: A reference to the keychain item in which the event occurred. If the event did not involve an item, this field is not valid.
processID: A 64-bit quantity containing the process serial number of the process in which the event occurred. This is not available on Mac OS X.
event: The keychain event that occurred. If the event is a system event as indicated by the constant kSystemKCEvent, the Keychain client can process events. If the event is not a system event, this field is not valid. This is not available on Mac OS X.
keychain: A reference to the keychain in which the event occurred. If the event did not involve a keychain, this field is not valid.

Discussion

The KCCallbackInfo type represents a structure that contains information about the keychain event of which your application wants to be notified. The Keychain Manager passes a pointer to this structure in the info parameter of your callback function via the function InvokeKCCallbackUPP, which invokes your callback function. For information on how to write a keychain event callback function, see KCCallbackProcPtr.

Availability

Available in Mac OS X v10.0 and later.

Declared In

KeychainCore.h

KCCallbackUPP

Defines a data type for the KCCallbackProcPtr callback pointer.

typedef KCCallbackProcPtr KCCallbackUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

KeychainCore.h

KCItemRef

Represents a reference to a keychain item.

typedef SecKeychainItemRef KCItemRef;

Discussion

The KCItemRef type represents a reference to an opaque structure that identifies a keychain item. You should call the function KCNewItem to create a keychain item reference. The function KCReleaseItem disposes of a keychain item reference when no longer needed.

Availability

Available in Mac OS X v10.0 and later.

Declared In

KeychainCore.h

KCPublicKeyHash

Represents a 20-byte public key hash.

typedef UInt8 KCPublicKeyHash[20];

Discussion

The KCPublicKeyHash type represents a hash of a public key. You can use the constant kPublicKeyHashKCItemAttr, described in Keychain Item Attribute Tag Constants, to set or retrieve a certificate attribute value of this type.

Availability

Available in Mac OS X v10.0 and later.

Declared In

KeychainCore.h

KCRef

Represents a reference to a keychain.

typedef SecKeychainRef KCRef;

Discussion

The KCRef type represents a reference to an opaque structure that identifies a keychain. You should call the function KCMakeKCRefFromFSSpec or KCMakeKCRefFromAlias to create a keychain reference. The function KCReleaseKeychain disposes of a keychain reference when no longer needed. You pass a reference of this type to Keychain Manager functions that operate on a keychain in some way.

Availability

Available in Mac OS X v10.0 and later.

Declared In

KeychainCore.h

KCSearchRef

Represents a reference to the current search criteria.

typedef SecKeychainSearchRef KCSearchRef;

Discussion

The KCSearchRef type represents a reference to an opaque structure that identifies the current search criteria. The function KCFindFirstItem passes back a reference of this type in the search parameter for subsequent calls to the function KCFindNextItem. You must release this reference when you are finished with a search by calling the function KCReleaseSearch.

Availability

Available in Mac OS X v10.0 and later.

Declared In

KeychainCore.h

KCStatus

Identifies a mask that you can use in determining the permissions that are set in a keychain.

typedef SecKeychainStatus KCStatus;

Discussion

The KCStatus enumeration defines masks your application can use to determine the read and write permissions for a keychain. The function KCGetStatus passes back this mask in the status parameter.

Availability

Available in Mac OS X v10.0 and later.

Declared In

KeychainCore.h

Constants

Authentication Type Constants

Represent the type of authentication to use in storing and retrieving Internet passwords.

enum {
   kKCAuthTypeNTLM = 'ntlm',
   kKCAuthTypeMSN = 'msna',
   kKCAuthTypeDPA = 'dpaa',
   kKCAuthTypeRPA = 'rpaa',
   kKCAuthTypeHTTPDigest = 'httd',
   kKCAuthTypeDefault = 'dflt'
};
typedef FourCharCode KCAuthType;

Constants

kKCAuthTypeNTLM

Specifies Windows NT LAN Manager authentication.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCAuthTypeMSN

Specifies Microsoft Network authentication.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCAuthTypeDPA

Specifies Distributed Password authentication.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCAuthTypeRPA

Specifies Remote Password authentication.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCAuthTypeHTTPDigest

Specifies HTTP Digest Access authentication.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCAuthTypeDefault

Specifies default authentication.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

Discussion

The KCAuthType enumeration defines constants you can use to identify the type of authentication to use in storing and retrieving Internet passwords. You can pass a constant of this type in the authType parameter of the functions KCAddInternetPassword, KCAddInternetPasswordWithPath, KCFindInternetPassword, and KCFindInternetPasswordWithPath.

Certificate Search Options

Represent a mask that specifies the search criteria to use when finding certificates.

typedef UInt32 KCCertSearchOptions;
enum {
   kCertSearchShift = 0,
   kCertSearchSigningIgnored = 0,
   kCertSearchSigningAllowed = 1 << (kCertSearchShift + 0),
   kCertSearchSigningDisallowed = 1 << (kCertSearchShift + 1),
   kCertSearchSigningMask = ((kCertSearchSigningAllowed) |
   (kCertSearchSigningDisallowed)),
   kCertSearchVerifyIgnored = 0,
   kCertSearchVerifyAllowed = 1 << (kCertSearchShift + 2),
   kCertSearchVerifyDisallowed = 1 << (kCertSearchShift + 3),
   kCertSearchVerifyMask = ((kCertSearchVerifyAllowed) |
   (kCertSearchVerifyDisallowed)),
   kCertSearchEncryptIgnored = 0,
   kCertSearchEncryptAllowed = 1 << (kCertSearchShift + 4),
   kCertSearchEncryptDisallowed = 1 << (kCertSearchShift + 5),
   kCertSearchEncryptMask = ((kCertSearchEncryptAllowed) |
   (kCertSearchEncryptDisallowed)),
   kCertSearchDecryptIgnored = 0,
   kCertSearchDecryptAllowed = 1 << (kCertSearchShift + 6),
   kCertSearchDecryptDisallowed = 1 << (kCertSearchShift + 7),
   kCertSearchDecryptMask = ((kCertSearchDecryptAllowed) |
   (kCertSearchDecryptDisallowed)),
   kCertSearchWrapIgnored = 0,
   kCertSearchWrapAllowed = 1 << (kCertSearchShift + 8),
   kCertSearchWrapDisallowed = 1 << (kCertSearchShift + 9),
   kCertSearchWrapMask = ((kCertSearchWrapAllowed) |
   (kCertSearchWrapDisallowed)),
   kCertSearchUnwrapIgnored = 0,
   kCertSearchUnwrapAllowed = 1 << (kCertSearchShift + 10),
   kCertSearchUnwrapDisallowed = 1 << (kCertSearchShift + 11),
   kCertSearchUnwrapMask = ((kCertSearchUnwrapAllowed) |
   (kCertSearchUnwrapDisallowed)),
   kCertSearchPrivKeyRequired = 1 << (kCertSearchShift + 12),
   kCertSearchAny = 0
};

Discussion

The KCCertSearchOptions enumeration defines masks that you can use in the options parameter of the function KCFindX509Certificates.

Certificate Usage Options

Represent a mask that specifies the usage options when adding certificates.

typedef UInt32 KCCertAddOptions;
enum {
   kSecOptionReserved = 0x000000FF,
   kCertUsageShift = 8,
   kCertUsageSigningAdd         = 1 << (kCertUsageShift + 0),
   kCertUsageSigningAskAndAdd = 1 << (kCertUsageShift + 1),
   
   kCertUsageVerifyAdd = 1 << (kCertUsageShift + 2),
   kCertUsageVerifyAskAndAdd = 1 << (kCertUsageShift + 3),
   kCertUsageEncryptAdd = 1 <<(kCertUsageShift + 4),
   kCertUsageEncryptAskAndAdd = 1 << (kCertUsageShift + 5),
   kCertUsageDecryptAdd = 1 << (kCertUsageShift + 6),
   kCertUsageDecryptAskAndAdd = 1 << (kCertUsageShift + 7),
   kCertUsageKeyExchAdd = 1 << (kCertUsageShift + 8),
   kCertUsageKeyExchAskAndAdd = 1 << (kCertUsageShift + 9),
   kCertUsageRootAdd = 1 << (kCertUsageShift + 10),
   kCertUsageRootAskAndAdd = 1 << (kCertUsageShift + 11),
   kCertUsageSSLAdd = 1 << (kCertUsageShift + 12),
   kCertUsageSSLAskAndAdd = 1 << (kCertUsageShift + 13),
   kCertUsageAllAdd = 0x7FFFFF00
};

Certificate Verification Criteria

Identify the verification criteria for use when displaying certificates to the user.

typedef UInt16 KCVerifyStopOn;
enum {
   kPolicyKCStopOn = 0,
   kNoneKCStopOn = 1,
   kFirstPassKCStopOn = 2,
   kFirstFailKCStopOn = 3
};

Constants

kPolicyKCStopOn

Indicates that the function KCChooseCertificate should use the trust policy options currently in effect.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kNoneKCStopOn

Indicates that the function KCChooseCertificate completes after examining all available certificates.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kFirstPassKCStopOn

Indicates that the function KCChooseCertificate when one certificate meeting the verification criteria is found.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kFirstFailKCStopOn

Specifies that the function KCChooseCertificate completes when one certificate that fails to meet the verification criteria is found.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

Discussion

The KCVerifyStopOn enumeration defines constants your application can use to identify the verification criteria to use in selecting certificates. You can pass a constant of this type in the stopOn parameter of the function KCChooseCertificate.

Default Internet Port Constant

Represent the internet ports available.

enum {
   kAnyPort = 0
};

Constants

kAnyPort

Indicates that any Internet port can be used.

Available in Mac OS X v10.1 and later.

Declared in KeychainCore.h.

Default Internet Protocol And Authentication Type Constants

Represent the internet protocols and authentication types available.

enum {
   kAnyProtocol = 0,
   kAnyAuthType = 0
};

Constants

kAnyProtocol

Indicates that any Internet protocol can be used.

Available in Mac OS X v10.1 and later.

Declared in KeychainCore.h.

kAnyAuthType

Indicates that any Internet authentication type can be used.

Available in Mac OS X v10.1 and later.

Declared in KeychainCore.h.

Keychain Events Constants

Identify keychain events.

typedef UInt16 KCEvent;
enum {
   kIdleKCEvent = 0,
   kLockKCEvent = 1,
   kUnlockKCEvent = 2,
   kAddKCEvent = 3,
   kDeleteKCEvent = 4,
   kUpdateKCEvent = 5,
   kPasswordChangedKCEvent = 6,
   kSystemKCEvent = 8,
   kDefaultChangedKCEvent = 9,
   kDataAccessKCEvent = 10,
   kKeychainListChangedKCEvent = 11
};

Constants

kIdleKCEvent

Indicates a NULL event.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kLockKCEvent

Indicates that the keychain was locked.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kUnlockKCEvent

Indicates that the keychain was unlocked.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kAddKCEvent

Indicates that an item was added to a keychain.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kDeleteKCEvent

Indicates that an item was deleted from a keychain.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kUpdateKCEvent

Indicates that a keychain item was updated.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kPasswordChangedKCEvent

Indicates that the identity of the keychain was changed.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kSystemKCEvent

Indicates that the keychain client can process events.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kDefaultChangedKCEvent

Indicates that the default keychain has changed.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kDataAccessKCEvent

Indicates that a process has called the function KCGetData to access a keychain item’s data.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKeychainListChangedKCEvent

Indicates that the list of keychains has changed.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

Discussion

The KCEvent enumeration defines constants that identify the Keychain-related events your callback function wishes to receive. The Keychain Manager tests a mask that you pass in the eventMask parameter of the function KCAddCallback to determine the data transfer events your notification callback function wishes to receive. It passes these events in the keychainEvent parameter of the function InvokeKCCallbackUPP. For a description of the Keychain-related event masks, see Keychain Events Mask.

Keychain Events Mask

Identify a mask that you can use to set the keychain events you wish to receive.

typedef UInt16 KCEventMask;
enum {
   kIdleKCEventMask = 1 << kIdleKCEvent,
   kLockKCEventMask = 1 << kLockKCEvent,
   kUnlockKCEventMask = 1 << kUnlockKCEvent,
   kAddKCEventMask = 1 << kAddKCEvent,
   kDeleteKCEventMask = 1 << kDeleteKCEvent,
   kUpdateKCEventMask = 1 << kUpdateKCEvent,
   kPasswordChangedKCEventMask = 1 << kPasswordChangedKCEvent,
   kSystemEventKCEventMask = 1 << kSystemKCEvent,
   kDefaultChangedKCEventMask = 1 << kDefaultChangedKCEvent,
   kDataAccessKCEventMask = 1 << kDataAccessKCEvent,
   kEveryKCEventMask = 0xFFFF
};

Constants

kIdleKCEventMask

If the bit specified by this mask is set, your callback function will be invoked during a NULL event.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kLockKCEventMask

If the bit specified by this mask is set, your callback function will be invoked when the keychain is locked.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kUnlockKCEventMask

If the bit specified by this mask is set, your callback function will be invoked when the keychain is unlocked.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kAddKCEventMask

If the bit specified by this mask is set, your callback function will be invoked when an item is added to the keychain.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kDeleteKCEventMask

If the bit specified by this mask is set, your callback function will be invoked when an item is removed from the keychain.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kUpdateKCEventMask

If the bit specified by this mask is set, your callback function will be invoked when a keychain item is updated.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kPasswordChangedKCEventMask

If the bit specified by this mask is set, your callback function will be invoked when the keychain identity is changed.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kSystemEventKCEventMask

If the bit specified by this mask is set, your callback function will be invoked when the keychain client processes an event.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kDefaultChangedKCEventMask

If the bit specified by this mask is set, your callback function will be invoked when the default keychain is changed.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kDataAccessKCEventMask

If the bit specified by this mask is set, your callback function will be invoked when a process calls the function KCGetData.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kEveryKCEventMask

If the bit specified by this mask is set, your callback function will be invoked when any of the above Keychain-related events occur.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

Discussion

The KCEventMask enumeration defines masks your application can use to set Keychain event bits. You pass this mask in the eventMask parameter of the function KCAddCallback, thereby defining the Keychain-related events to which your callback will respond. The Keychain Manager uses this mask to test which events your callback function will handle. It passes these events in the keychainEvent parameter of the function InvokeKCCallbackUPP. For a description of Keychain-related events, see Keychain Events Constants.

Keychain Item Attribute Tag Constants

Represent tags that identify keychain item attribute values.

enum {
   kClassKCItemAttr = 'clas',
   kCreationDateKCItemAttr = 'cdat',
   kModDateKCItemAttr = 'mdat',
   kDescriptionKCItemAttr = 'desc',
   kCommentKCItemAttr = 'icmt',
   kCreatorKCItemAttr = 'crtr',
   kTypeKCItemAttr = 'type',
   kScriptCodeKCItemAttr = 'scrp',
   kLabelKCItemAttr = 'labl',
   kInvisibleKCItemAttr = 'invi',
   kNegativeKCItemAttr = 'nega',
   kCustomIconKCItemAttr = 'cusi',
   kAccountKCItemAttr = 'acct',
   kServiceKCItemAttr = 'svce',
   kGenericKCItemAttr = 'gena',
   kSecurityDomainKCItemAttr = 'sdmn',
   kServerKCItemAttr = 'srvr',
   kAuthTypeKCItemAttr = 'atyp',
   kPortKCItemAttr = 'port',
   kPathKCItemAttr = 'path',
   kVolumeKCItemAttr = 'vlme',
   kAddressKCItemAttr = 'addr',
   kSignatureKCItemAttr = 'ssig',
   kProtocolKCItemAttr = 'ptcl',
   kSubjectKCItemAttr = 'subj',
   kCommonNameKCItemAttr = 'cn  ',
   kIssuerKCItemAttr = 'issu',
   kSerialNumberKCItemAttr = 'snbr',
   kEMailKCItemAttr = 'mail',
   kPublicKeyHashKCItemAttr = 'hpky',
   kIssuerURLKCItemAttr = 'iurl',
   kEncryptKCItemAttr = 'encr',
   kDecryptKCItemAttr = 'decr',
   kSignKCItemAttr = 'sign',
   kVerifyKCItemAttr = 'veri',
   kWrapKCItemAttr = 'wrap',
   kUnwrapKCItemAttr = 'unwr',
   kStartDateKCItemAttr = 'sdat',
   kEndDateKCItemAttr = 'edat'
};
typedef FourCharCode KCItemAttr;

Constants

kClassKCItemAttr

Identifies the class attribute. You use this tag to set or get a value of type KCItemClass that indicates whether the item is an AppleShare, Internet, or generic password, or a certificate. See “KCPublicKeyHash” for a description of possible values.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kCreationDateKCItemAttr

Identifies the creation date attribute. You use this tag to set or get a value of type UInt32 that indicates the date the item was created.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kModDateKCItemAttr

Identifies the modification date attribute. You use this tag to set or get a value of type UInt32 that indicates the last time the item was updated.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kDescriptionKCItemAttr

Identifies the description attribute. You use this tag to set or get a value of type string that represents a user-visible string describing this item.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kCommentKCItemAttr

Identifies the comment attribute. You use this tag to set or get a value of type string that represents a user-editable string containing comments for this item.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kCreatorKCItemAttr

Identifies the creator attribute. You use this tag to set or get a value of type OSType that represents the item’s creator.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kTypeKCItemAttr

Identifies the type attribute. You use this tag to set or get a value of type OSType that represents the item’s type.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kScriptCodeKCItemAttr

Identifies the script code attribute. You use this tag to set or get a value of type ScriptCode that represents the script code for all strings.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kLabelKCItemAttr

Identifies the label attribute. You use this tag to set or get a value of type string that represents a user-editable string containing the label for this item.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kInvisibleKCItemAttr

Identifies the invisible attribute. You use this tag to set or get a value of type Boolean that indicates whether the item is invisible.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kNegativeKCItemAttr

Identifies the negative attribute. You use this tag to set or get a value of type Boolean that indicates whether there is a valid password associated with this keychain item. This is useful if your application doesn't want a password for some particular service to be stored in the keychain, but prefers that it always be entered by the user. The item (typically invisible and with zero-length data) acts as a placeholder to say “don't use me.”

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kCustomIconKCItemAttr

Identifies the custom icon attribute. You use this tag to set or get a value of type Boolean that indicates whether the item has an application-specific icon. To do this, you must also set the attribute value identified by the tag kTypeKCItemAttr to a file type for which there is a corresponding icon in the desktop database, and set the attribute value identified by the tag kCreatorKCItemAttr to an appropriate application creator type. If a custom icon corresponding to the item's type and creator can be found in the desktop database, it will be displayed by Keychain Access. Otherwise, default icons are used.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kAccountKCItemAttr

Identifies the account attribute. You use this tag to set or get a value of type Str63 that represents the user account. It also applies to generic and AppleShare passwords.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kServiceKCItemAttr

Identifies the service attribute for a generic password. You use this tag to set or get a value of type Str63 that represents the service.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kGenericKCItemAttr

Identifies the generic attribute for a generic password. You use this tag to set or get a value of untyped bytes that represents a user-defined attribute.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kSecurityDomainKCItemAttr

Identifies the security domain attribute for an internet password. You use this tag to set or get a value of type Str63 that represents the Internet security domain.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kServerKCItemAttr

Identifies the server attribute for an internet password. You use this tag to set or get a value of type string that represents the Internet server’s domain name or IP address.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kAuthTypeKCItemAttr

Identifies the authentication type attribute for an internet password. You use this tag to set or get a value of type KCAuthType that represents the Internet authentication scheme.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kPortKCItemAttr

Identifies the port attribute for an internet password. You use this tag to set or get a value of type UInt16 that represents the Internet port.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kPathKCItemAttr

Identifies the path attribute for an internet password. You use this tag to set or get a value of type Str255 that represents the path.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kVolumeKCItemAttr

Identifies the volume attribute for an AppleShare password. You use this tag to set or get a value of type Str63 that represents the AppleShare volume.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kAddressKCItemAttr

Identifies the address attribute for an AppleShare password. You use this tag to set or get a value of type string that represents the zone name, or the IP or domain name that represents the server address.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kSignatureKCItemAttr

Identifies the server signature attribute for an AppleShare password. You use this tag to set or get a value of type KCPublicKeyHash that represents the server signature block.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kProtocolKCItemAttr

Identifies the protocol attribute for an AppleShare or internet password. You use this tag to set or get a value of type KCProtocolType that represents the Internet protocol.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kSubjectKCItemAttr

Identifies the subject attribute for a certificate. You use this tag to set or get DER-encoded data that represents the subject distinguished name.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kCommonNameKCItemAttr

Identifies the common name attribute for a certificate. You use this tag to set or get a UTF8-encoded string that represents the common name.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kIssuerKCItemAttr

Identifies the issuer attribute for a certificate. You use this tag to set or get a DER-encoded data that represents the issuer distinguished name.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kSerialNumberKCItemAttr

Identifies the serial number attribute for a certificate. You use this tag to set or get a DER-encoded data that represents the serial number.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kEMailKCItemAttr

Identifies the email attribute for a certificate. You use this tag to set or get an ASCII-encoded string that represents the issuer’s email address.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kPublicKeyHashKCItemAttr

Identifies the public key hash attribute for a certificate. You use this tag to set or get a value of type KCPublicKeyHash that represents the hash of the public key.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kIssuerURLKCItemAttr

Identifies the issuer URL attribute for a certificate. You use this tag to set or get an ASCII-encoded string that represents the URL of the certificate issuer.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kEncryptKCItemAttr

Identifies the encrypt attribute for a certificate or key. You use this tag to set or get a value of type Boolean that indicates whether the item can encrypt.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kDecryptKCItemAttr

Identifies the decrypt attribute for a certificate or key. You use this tag to set or get a value of type Boolean that indicates whether the item can decrypt.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kSignKCItemAttr

Identifies the sign attribute for a certificate or key. You use this tag to set or get a value of type Boolean that indicates whether the item can sign.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kVerifyKCItemAttr

Identifies the verify attribute for a certificate or key. You use this tag to set or get a value of type Boolean that indicates whether the item can verify.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kWrapKCItemAttr

Identifies the wrap attribute for a certificate or key. You use this tag to set or get a value of type Boolean that indicates whether the item can wrap.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kUnwrapKCItemAttr

Identifies the unwrap attribute for a certificate or key. You use this tag to set or get a value of type Boolean that indicates whether the item can unwrap.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kStartDateKCItemAttr

Identifies the start date attribute for a certificate or key. You use this tag to set or get a value of type UInt32 that indicates the start date.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kEndDateKCItemAttr

Identifies the end date attribute for a certificate or key. You use this tag to set or get a value of type UInt32 that indicates the end date.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

Discussion

The KCItemAttr enumeration defines the Apple-defined tag constants that identify keychain item attribute values. Your application can use one of these tags in the tag field of the structure KCAttribute to identify the keychain item attribute value you wish to set or retrieve. Your application can create application-defined tags of type KCAttrType.

Keychain Item Type Constants

Identify the type of keychain item.

enum {
   kCertificateKCItemClass = 'cert',
   kAppleSharePasswordKCItemClass = 'ashp',
   kInternetPasswordKCItemClass = 'inet',
   kGenericPasswordKCItemClass = 'genp'
};
typedef FourCharCode KCItemClass;

Constants

kCertificateKCItemClass

Specifies that the item is a digital certificate.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kAppleSharePasswordKCItemClass

Specifies that the item is an AppleShare password.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kInternetPasswordKCItemClass

Specifies that the item is an Internet password.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kGenericPasswordKCItemClass

Specifies that the item is a generic password.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

Discussion

The KCItemClass enumeration defines constants your application can use to specify the type of the keychain item you wish to create, dispose, add, delete, update, copy, or locate. You pass a constant of this type to the functions KCNewItem, KCReleaseItem, KCAddItem, KCDeleteItem, KCUpdateItem, KCCopyItem, and KCGetKeychain. You can also use these constants with the tag constant kClassKCItemAttr, described in Keychain Item Attribute Tag Constants.

Keychain Protocol Type Constants

Identify the protocol to use in storing and retrieving Internet passwords.

enum {
   kKCProtocolTypeFTP = 'ftp ',
   kKCProtocolTypeFTPAccount = 'ftpa',
   kKCProtocolTypeHTTP = 'http',
   kKCProtocolTypeIRC = 'irc ',
   kKCProtocolTypeNNTP = 'nntp',
   kKCProtocolTypePOP3 = 'pop3',
   kKCProtocolTypeSMTP = 'smtp',
   kKCProtocolTypeSOCKS = 'sox ',
   kKCProtocolTypeIMAP = 'imap',
   kKCProtocolTypeLDAP = 'ldap',
   kKCProtocolTypeAppleTalk = 'atlk',
   kKCProtocolTypeAFP = 'afp ',
   kKCProtocolTypeTelnet = 'teln'
};
typedef FourCharCode KCProtocolType;

Constants

kKCProtocolTypeFTP

Specifies the File Transfer Protocol.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCProtocolTypeFTPAccount

Specifies the File Transfer Protocol Account.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCProtocolTypeHTTP

Specifies the HyperText Transfer Protocol.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCProtocolTypeIRC

Specifies the Internet Relay Channel Protocol.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCProtocolTypeNNTP

Specifies the Network News Transfer Protocol.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCProtocolTypePOP3

Specifies the Post Office 3 Protocol.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCProtocolTypeSMTP

Specifies the Simple Mail Transfer Protocol.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCProtocolTypeSOCKS

Specifies the Secure Proxy Server Protocol.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCProtocolTypeIMAP

Specifies the Internet Message Access Protocol.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCProtocolTypeLDAP

Specifies the Lightweight Directory Access Protocol.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCProtocolTypeAppleTalk

Specifies the AppleTalk Protocol.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCProtocolTypeAFP

Specifies the AppleTalk File Protocol.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kKCProtocolTypeTelnet

Specifies the Telnet Protocol.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

Discussion

The KCProtocolType enumeration defines constants you can use to identify the type of authentication to use in storing and retrieving Internet passwords. You can pass a constant of this type in the protocol parameter of the functions KCAddInternetPassword, KCAddInternetPasswordWithPath, KCFindInternetPassword, and KCFindInternetPasswordWithPath.

Keychain Status Constants

Identify the keychain status.

enum {
   kUnlockStateKCStatus = 1,
   kRdPermKCStatus = 2,
   kWrPermKCStatus = 4
};

Constants

kUnlockStateKCStatus

If the bit specified by this mask is set (bit 0), the keychain is unlocked.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kRdPermKCStatus

If the bit specified by this mask is set (bit 1), the keychain is unlocked with read permission.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

kWrPermKCStatus

If the bit specified by this mask is set (bit 2), the keychain is unlocked with write permission.

Available in Mac OS X v10.0 and later.

Declared in KeychainCore.h.

Result Codes

The most common result codes returned by Keychain Manager are listed below.

Result Code	Value	Description
`errKCNotAvailable`	-25291	Indicates that the Keychain Manager was not loaded. Available in Mac OS X v10.0 and later.
`errKCReadOnly`	-25292	Returned by the function `KCCopyItem` to indicate that the keychain file is read-only and cannot be edited. Available in Mac OS X v10.0 and later.
`errKCAuthFailed`	-25293	Returned by the function `KCUnlock` to indicate that the authentication failed (too many unsuccessful retries). Available in Mac OS X v10.0 and later.
`errKCNoSuchKeychain`	-25294	Returned by the functions `KCUnlock`, `KCSetDefaultKeychain`, `KCGetStatus`, and `KCGetIndKeychain` to indicate that the specified keychain was not found. Available in Mac OS X v10.0 and later.
`errKCInvalidKeychain`	-25295	Returned by the functions `KCUnlock`, `KCSetDefaultKeychain`, `KCGetStatus`, `KCGetKeychainName`, `KCChangeSettings`, and `KCCreateKeychain` to indicate that the keychain is not valid. Available in Mac OS X v10.0 and later.
`errKCDuplicateKeychain`	-25296	Returned by the function `KCCreateKeychain` to indicate that your application tried to create a keychain that already exists. Available in Mac OS X v10.0 and later.
`errKCDuplicateCallback`	-25297	Returned by the function `KCAddCallback` to indicate that your callback function was already registered. Available in Mac OS X v10.0 and later.
`errKCInvalidCallback`	-25298	Returned by the function `KCRemoveCallback` to indicate that the callback function was not previously registered. Available in Mac OS X v10.0 and later.
`errKCDuplicateItem`	-25299	Returned by the functions `KCAddAppleSharePassword`, `KCAddInternetPassword`, `KCAddInternetPasswordWithPath`, `KCAddGenericPassword`, and `KCAddItem` to indicate that you tried to add an existing keychain item to the keychain. Available in Mac OS X v10.0 and later.
`errKCItemNotFound`	-25300	Returned by the functions `KCFindAppleSharePassword`, `KCFindInternetPassword`, `KCFindInternetPasswordWithPath`, `KCFindGenericPassword`, `KCFindNextItem`, and `KCFindFirstItem` to indicate that no matching item was found. Available in Mac OS X v10.0 and later.
`errKCBufferTooSmall`	-25301	Returned by the functions `KCFindAppleSharePassword`, `KCFindInternetPassword`, `KCFindInternetPasswordWithPath`, `KCFindGenericPassword`, `KCGetAttribute`, `KCGetData`, and `KCFindX509Certificates` to indicate that the buffer was not large enough to contain the password data. Available in Mac OS X v10.0 and later.
`errKCDataTooLarge`	-25302	Returned by the functions `KCAddAppleSharePassword`, `KCAddInternetPassword`, `KCAddInternetPasswordWithPath`, `KCAddGenericPassword`, `KCSetAttribute`, and `KCSetData` to indicate that the data is too large. Available in Mac OS X v10.0 and later.
`errKCNoSuchAttr`	-25303	Returned by the functions `KCSetAttribute`, `KCGetAttribute`, and `KCFindFirstItem` to indicate that no such attribute exists. Available in Mac OS X v10.0 and later.
`errKCInvalidItemRef`	-25304	Returned by the functions `KCSetAttribute`, `KCGetAttribute`, `KCSetData`, `KCGetData`, `KCAddItem`, `KCDeleteItem`, `KCUpdateItem`, `KCCopyItem`, and `KCGetKeychain` to indicate that the keychain item reference is invalid. Available in Mac OS X v10.0 and later.
`errKCInvalidSearchRef`	-25305	Returned by the functions `KCFindNextItem` and `KCReleaseSearch` to indicate that the specified search reference is invalid. Available in Mac OS X v10.0 and later.
`errKCNoSuchClass`	-25306	Returned by the function `KCCopyItem` to indicate that the item class does not exist. Available in Mac OS X v10.0 and later.
`errKCNoDefaultKeychain`	-25307	Returned by the functions `KCChangeSettings`, `KCSetDefaultKeychain`, `KCGetDefaultKeychain`, `KCAddAppleSharePassword`, `KCAddInternetPassword`, `KCAddInternetPasswordWithPath`, `KCAddGenericPassword`, `KCFindAppleSharePassword`, `KCFindInternetPassword`, `KCFindInternetPasswordWithPath`, `KCFindGenericPassword`, `KCCopyItem`, `KCAddItem`, `KCDeleteItem`, `KCUpdateItem`, `KCFindNextItem`, `KCFindFirstItem`, and `KCFindX509Certificates` to indicate that there is no default keychain. Available in Mac OS X v10.0 and later.
`errKCInteractionNotAllowed`	-25308	Returned by the functions `KCCreateKeychain`, `KCChangeSettings`, `KCUnlock`, and `KCGetData` (the latter two only when the Unlock Dialog and Allow Access dialog boxes are needed) to indicate that there is no start-up keychain. Available in Mac OS X v10.0 and later.
`errKCReadOnlyAttr`	-25309	Returned by the function `KCSetAttribute` to indicate that the keychain item attribute is read-only. Available in Mac OS X v10.0 and later.
`errKCWrongKCVersion`	-25310	Indicates that the wrong version of Keychain Manager is installed to perform this operation. Available in Mac OS X v10.0 and later.
`errKCKeySizeNotAllowed`	-25311	Indicates that the key size is illegal. Available in Mac OS X v10.0 and later.
`errKCNoStorageModule`	-25312	Returned by functions that prompts the loading of the Keychain Manager to indicate that the storage module is not found. Available in Mac OS X v10.0 and later.
`errKCNoCertificateModule`	-25313	Returned when a function is required for a certificate and the certificate module is not found. Available in Mac OS X v10.0 and later.
`errKCNoPolicyModule`	-25314	Returned when a function is required for a trust policy and the policy module is not found. Available in Mac OS X v10.0 and later.
`errKCInteractionRequired`	-25315	Returned by the function `KCUnlock` to indicate that user interaction is required for this operation. Available in Mac OS X v10.0 and later.
`errKCDataNotAvailable`	-25316	Indicates that the requested data is not available. Available in Mac OS X v10.0 and later.
`errKCDataNotModifiable`	-25317	Returned by the functions `KCSetData` and `KCGetData` to indicate that the data cannot be modified. Available in Mac OS X v10.0 and later.
`errKCCreateChainFailed`	-25318	Returned by the functions `KCChooseCertificate` and `KCFindX509Certificates` to indicate that the attempt to create a new keychain failed. Available in Mac OS X v10.0 and later.

Last updated: 2005-07-07

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.