Macintosh Key Chain Manager

Engineering Specifications

Last Modified: 1/16/1997
Version: 1.0

Contact: Vinne Moscaritolo, vinnie@vmeng.com

CONTENTS

Introduction to the Key Chain Manager

Key Chain Manager Access

Key Chain Manager Reference

Summary

Put some text here about the keychain...

Introduction to the KeyChain Manager

some text here.....

KeyChain Manager Access

some text here.....

KeyChain Manager Reference

This section discuses the data types and routines provided by the Key Chain Manager. It describes the general purpose data types Key Chain Manager defines and all the routine that relate to manipulating the Key Chain, Key Chain services, etc.

Constants

The KeyChain Manager uses the following constants: 
#define kKCInvalidKeyChainRef	((KeyChainRef)0)

Data Types

This section discuses the general-purpose data types defined for the Key Chain Manager.

Key Chain Manager uses the KeyChainRef to refer to a Key Chain. This reference is only meaningful to the Key Chain Manager 

typedef void*	KeyChainRef;

Example Usage
The following is a simple example of how the Key Chain Manager might be used. 
KeyChainRef kcRef;
OSErr       status;

status = KCOpenSystemKeyChain(&kcRef);

status = KCUnLockKeyChain(kcRef, nil);

status = KCAddKey(kcRef,locator,data,metaData);

Managing the Key Chain
This section discuses the Key Chain Manager function for manipulatingthe Key Chain. Use KCGetSystemKeyChainRef to obtain the default Key Chain reference. Use KCGetKeyChainRef to open and get a reference for another Key Chain file. Use KCLockKeyChain and KCUnlockKeyChain to change the lock state of the Key Chain. Use KCGetKeyChainLockStatus to get the determine the lock state of the Key Chain. Use KCChangeKeyChainPassword to change the Key Chain Password.

KCGetKeyChainRef

The KCGetKeyChainRef function opens a specified keychain file. Your application identifies the keychain file with a file system specification. 
pascal OSErr KCGetKeyChainRef(const FSSpec *keychainFile,
                                  KeyChainRef* kcRef);

keychainFile

Contains a pointer to the file system specification for the Key Chain file to be opened.

kcRef

Contains a pointer to a field that is to receive the keychain reference number for the opened keychain file. Your application must use this value when calling other Key Chain Manager function that work with keychain files.

DESCRIPTION

Your application must open a keychain file before reading or writing any data from it. You can open a keychain file more than once.

RESULT CODES

noErr0No Error
paramErr-50Parameter Error (unexpected nil pointer; out of range value)

KCGetSystemKeyChainRef

The KCGetSystemKeyChainRef function opens the current system keychain file. 
pascal OSErr KCGetSystemKeyChainRef(KeyChainRef* kcRef);

kcRef

Contains a pointer to a field that is to receive the keychain reference number for the opened keychain file. Your application must use this value when calling other Key Chain Manager function that work with keychain files.

DESCRIPTION

xxxx xxxx xxxxxxx xxxxxxx xxxxxxx xxxx xxxxxxx x x x xxxxxxxxxxxx x x xxxxxxxxxxxxxxxxx xxxxxxx x x x xxxxxxxxxxxx x x x xxxxxxxxxxxx xxxxxxx x x x xxxxxxxxxxxxxxx.

RESULT CODES

noErr0No Error
paramErr-50Parameter Error (unexpected nil pointer; out of range value)

KCSetSystemKeyChain

The KCSetSystemKeyChain function.......Key Chain specified by the Key Chain reference. 
pascal OSErr KCSetSystemKeyChain(KeyChainRef  kcRef);

kcRef

Specifies the Key Chain for this operation. Your application obtains this keychain reference from such functions as KCOpenSystemKeyChain and KCOpenKeyChain.

DESCRIPTION

xxxx xxxx xxxxxxx xxxxxxx xxxxxxx xxxx xxxxxxx x x x xxxxxxxxxxxx x x xxxxxxxxxxxxxxxxx xxxxxxx x x x xxxxxxxxxxxx x x x xxxxxxxxxxxx xxxxxxx x x x xxxxxxxxxxxxxxx.

RESULT CODES

noErr0No Error
paramErr-50Parameter Error (unexpected nil pointer; out of range value)
kKCRefInvalidErr-1581Key Chain reference invalid

KCDisposeKeyChainRef

The KCDisposeKeyChainRef function.......Key Chain specified by the Key Chain reference. 
pascal OSErr KCDisposeKeyChainRef(KeyChainRef  kcRef);

kcRef

Specifies the Key Chain for this operation. Your application obtains this keychain reference from such functions as KCOpenSystemKeyChain and KCOpenKeyChain.

DESCRIPTION

xxxx xxxx xxxxxxx xxxxxxx xxxxxxx xxxx xxxxxxx x x x xxxxxxxxxxxx x x xxxxxxxxxxxxxxxxx xxxxxxx x x x xxxxxxxxxxxx x x x xxxxxxxxxxxx xxxxxxx x x x xxxxxxxxxxxxxxx.

RESULT CODES

noErr0No Error
paramErr-50Parameter Error (unexpected nil pointer; out of range value)
kKCRefInvalidErr-1581Key Chain reference invalid

KCUnlockKeyChain

The KCLockKeyChain function unlocks the Key Chain specified by the Key Chain reference. 
pascal OSErr KCUnlockKeyChain(KeyChainRef  kcRef,
                              ConstTextObject password);

kcRef

Specifies the Key Chain for this operation. Your application obtains this keychain reference from such functions as KCOpenSystemKeyChain and KCOpenKeyChain.

password

Password with with to unlock the Key Chain.

DESCRIPTION

xxxx xxxx xxxxxxx xxxxxxx xxxxxxx xxxx xxxxxxx x x x xxxxxxxxxxxx x x xxxxxxxxxxxxxxxxx xxxxxxx x x x xxxxxxxxxxxx x x x xxxxxxxxxxxx xxxxxxx x x x xxxxxxxxxxxxxxx.

SPECIAL CONSIDERATIONS

If the Key Chain specified was already unlocked, KCLockKeyChain returns an kKCAlreadyUnlockedErr error. This is because if a user attemost to unlock the Key Chain with a bad password, it is unclear whether the Key Chain should remain unlocked or should become locked.

RESULT CODES

noErr0No Error
paramErr-50Parameter Error (unexpected nil pointer; out of range value)
kKCPasswordBadErr-1580Password invalid
kKCRefInvalidErr-1581Key Chain reference invalid
kKCAlreadyUnlockedErr-1595Key Chain is already unlocked

KCLockKeyChain

The KCLockKeyChain function locks the Key Chain specified by the Key Chain reference. 
pascal OSErr KCLockKeyChain(KeyChainRef  kcRef);

kcRef

Specifies the Key Chain for this operation. Your application obtains this keychain reference from such functions as KCOpenSystemKeyChain and KCOpenKeyChain.

DESCRIPTION

xxxx xxxx xxxxxxx xxxxxxx xxxxxxx xxxx xxxxxxx x x x xxxxxxxxxxxx x x xxxxxxxxxxxxxxxxx xxxxxxx x x x xxxxxxxxxxxx x x x xxxxxxxxxxxx xxxxxxx x x x xxxxxxxxxxxxxxx.

RESULT CODES

noErr0No Error
paramErr-50Parameter Error (unexpected nil pointer; out of range value)
kKCRefInvalidErr-1581Key Chain reference invalid

KCGetKeyChainLockStatus

The KCGetKeyChainLockStatus function allows you to query the lock status of the Key Chain specified by the Key Chain reference. 
pascal OSErr KCGetKeyChainLockStatus(KeyChainRef  kcRef,
                                     KeyChainLockStatus* status);

kcRef

Specifies the Key Chain for this operation. Your application obtains this keychain reference from such functions as KCOpenSystemKeyChain and KCOpenKeyChain.

status

Contains a pointer to a field that is to receive the Key Chain lock status. The status parameter can have any of the following values:

kKCLocked - The Key Chain is locked.
kKCUnlocked - The Key Chain is not locked.

DESCRIPTION

xxxx xxxx xxxxxxx xxxxxxx xxxxxxx xxxx xxxxxxx x x x xxxxxxxxxxxx x x xxxxxxxxxxxxxxxxx xxxxxxx x x x xxxxxxxxxxxx x x x xxxxxxxxxxxx xxxxxxx x x x xxxxxxxxxxxxxxx.

RESULT CODES

noErr0No Error
paramErr-50Parameter Error (unexpected nil pointer; out of range value)
kKCRefInvalidErr-1581Key Chain reference invalid

KCChangeKeyChainPassword

The KCChangeKeyChainPassword function changes the Key Chain password to the value in specified in newPassword. This function checks the value of oldPassword and fails if you do not provide the current Key Chain password. 
pascal OSErr KCChangeKeyChainPassword(KeyChainRef  kcRef,
                                      ConstTextObject oldPassword,
                                      ConstTextObject newPassword));

kcRef

Specifies the Key Chain for this operation. Your application obtains this keychain reference from such functions as KCOpenSystemKeyChain and KCOpenKeyChain.

password

Password with with to unlock the Key Chain.

DESCRIPTION

xxxx xxxx xxxxxxx xxxxxxx xxxxxxx xxxx xxxxxxx x x x xxxxxxxxxxxx x x xxxxxxxxxxxxxxxxx xxxxxxx x x x xxxxxxxxxxxx x x x xxxxxxxxxxxx xxxxxxx x x x xxxxxxxxxxxxxxx.

RESULT CODES

noErr0No Error
paramErr-50Parameter Error (unexpected nil pointer; out of range value)
kKCPasswordBadErr-1580Password invalid
kKCRefInvalidErr-1581Key Chain reference invalid
kKCLockedErr-1583Password can not be changed when Key Chain is Locked

Summary of the KeyChain Manager

C Summary

Constants

#define kKCInvalidKeyChainRef   ((KeyChainRef)0)        /* Invalid Key Chain Reference */

enum {
      kKCLocked = 0,       // Key Chain is locked
      kKCUnlocked = 1      // Key Chain is not locked
      };   // KeyChainLockStatus

      
      
 enum {
      kKCLockHard = 0,     // Service is only accessable when KeyChain is unlocked
      kKCLockNever = 1     // Service is accessable independant of lock state
      };   // KeyChainLockOptions
Data Types
 
typedef struct OpaqueKeyChainRef* KeyChainRef;     

typedef UInt32 KeyChainLockStatus;
typedef UInt32 KeyChainLockOptions;
Key Chain Management Routines

Managing the Key Chain

pascal OSErr KCGetKeyChainRef    (const FSSpec*  keychainFile, 
                                        KeyChainRef*  kcRef,
                                            Boolean   createKeyChain);

pascal OSErr KCGetSystemKeyChainRef   (KeyChainRef* kcRef);

pascal OSErr KCSetSystemKeyChain      (KeyChainRef  kcRef);

pascal OSErr KCDisposeKeyChainRef     (KeyChainRef  kcRef);

pascal OSErr KCLockKeyChain           (KeyChainRef  kcRef);

pascal OSErr KCUnLockKeyChain         (KeyChainRef  kcRef, ConstTextObject password);

pascal OSErr KCGetKeyChainLockStatus  (KeyChainRef  kcRef, KeyChainLockStatus* status);

pascal OSErr KCChangeKeyChainPassword (KeyChainRef* kcRef, ConstTextObject oldPassword,
                                       ConstTextObject newPassword);

Service Management Routines

pascal OSErr KCAddKeyChainService (KeyChainRef  kcRef,
                                    ConstTextObject  serviceName,  
                                KeyChainLockOptions  lockOpts,
                                      KCServiceRef*  sRef);

pascal OSErr KCGetKeyChainService     (KeyChainRef   kcRef,
                                    ConstTextObject  serviceName,  
                                      KCServiceRef*  sRef);

pascal OSErr KCDeleteKeyChainService  (KeyChainRef  kcRef,
                                       KCServiceRef sRef);


pascal OSErr KCGetKeyChainServiceIterator  (KeyChainRef  kcRef, metaData, kcIterator* itx);
    
pascal OSErr KCIterate                (kcIterator* itx, Locator *Locator);

pascal OSErr KCDisposeIterator        (kcIterator* itx);

Iterating through Keys

pascal OSErr KCGetIterator            (KeyChainRef  kcRef, metaData, kcIterator* itx);
    
pascal OSErr KCIterate                (kcIterator* itx, Locator *Locator);

pascal OSErr KCDisposeIterator        (kcIterator* itx);
Result Codes
noErr0No Error
paramErr-50Parameter Error (unexpected nil pointer; out of range value)
kKCPasswordBadErr-1580Password invalid
kKCRefInvalidErr-1581Key Chain reference invalid
kKCNoKeyChainErr-1582Cannot create Key Chain
kKCLockedErr-1583Key Chain Locked
kKCAlreadyUnlockedErr-1595Key Chain is already unlocked