Inherits from NSObject
Declared in WSCKeychainManager.h
WSCKeychainManager.m

Overview

The WSCKeychainManager class enables you to perform many generic keychain operations and insulates an app from the underlying Keychain Services.

Although most keychain operations can be performed using the shared keychain manager object, you can also create a unique instance of WSCKeychainManager in cases where you want to use a delegate object in conjunction with the keychain manager.

Tasks

Getting and Setting the Delegate

Creating Keychain Manager

Creating and Deleting Keychains

Managing Keychains

Locking and Unlocking Keychains

Searching for Keychains Items

Properties

delegate

The WSCKeychainManager object’s delegate.

@property (nonatomic, unsafe_unretained) id<WSCKeychainManagerDelegate> delegate

Declared In

WSCKeychainManager.h

Class Methods

defaultManager

Returns the shared keychain manager object for the process.

This method always returns the same keychain manager object. If you plan to use a delegate with keychain manager to receive notifications about the completion of keychain operations, you should create a new instance of WSCKeychainManager (using the init method ) rather than using the shared object.

+ (instancetype)defaultManager

Return Value

The default WSCKeychainManager object for the keychain services.

Declared In

WSCKeychainManager.h

Instance Methods

addKeychainToDefaultSearchList:error:

Addes the specified keychain to the current default search list.

- (BOOL)addKeychainToDefaultSearchList:(WSCKeychain *)_Keychain error:(NSError **)_Error

Parameters

_Keychain

The keychain you wish to add to default search list. Passing nil to this parameter returns an NSError object which encapsulated WSCCommonInvalidParametersError error code. And passing an invalid keychain to this parameter returns an NSError object which encapsulated WSCKeychainIsInvalidError error code.

_Error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information.

Return Value

YES if the specified keychain was added to current default search list successfully; otherwise, NO.

Discussion

Warning: If the specified keychain already exists in default search list, this method will do nothing.

Declared In

WSCKeychainManager.h

createKeychainWhosePassphraseWillBeObtainedFromUserWithURL:becomesDefault:error:

Creates and returns a WSCKeychain object using the given URL and interaction prompt.

- (WSCKeychain *)createKeychainWhosePassphraseWillBeObtainedFromUserWithURL:(NSURL *)_URL becomesDefault:(BOOL)_WillBecomeDefault error:(NSError **)_Error

Parameters

_URL

Specify the URL in which the new keychain should be sotred. The URL in this parameter must not be a file reference URL or an URL other than file scheme This parameter must not be nil.

_WillBecomeDefault

A BOOL value representing whether to set the new keychain as default keychain.

_Error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you don’t want the error information.

Return Value

A WSCKeychain object initialized with above parameters as well as a passphrase, which is obtained from the passphrase dialog.

Discussion

This class method creates an empty keychain. And this method will display a passphrase dialog to user. If user interaction to create a keychain is posted, the newly-created keychain is automatically unlocked after creation.

The system ensures that a default keychain is created for the user at login, thus, in most cases, you do not need to call this method yourself. Users can create additional keychains, or change the default, by using the Keychain Access application. However, a missing default keychain is not recreated automatically, and you may receive an error from other methods if a default keychain does not exist. In that case, you can use this class method with a YES value for _WillBecomeDefault parameter, to create a new default keychain. You can also call this method to create a private temporary keychain for your application’s use, in cases where no user interaction can occur.

Declared In

WSCKeychainManager.h

createKeychainWithURL:passphrase:becomesDefault:error:

Creates and returns a WSCKeychain object using the given URL and passphrase.

- (WSCKeychain *)createKeychainWithURL:(NSURL *)_URL passphrase:(NSString *)_Passphrase becomesDefault:(BOOL)_WillBecomeDefault error:(NSError **)_Error

Parameters

_URL

Specify the URL in which the new keychain should be sotred. The URL in this parameter must not be a file reference URL or an URL other than file scheme This parameter must not be nil.

_Passphrase

A NSString object containing the passphrase which is used to protect the new keychain. This parameter must not be nil.

_WillBecomeDefault

A BOOL value representing whether to set the new keychain as default keychain.

_Error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you don’t want the error information.

Return Value

A WSCKeychain object initialized with above parameters.

Discussion

This method creates an empty keychain. The _Passphrase parameter is required. If user interaction to create a keychain is posted, the newly-created keychain is automatically unlocked after creation.

The system ensures that a default keychain is created for the user at login, thus, in most cases, you do not need to call this method yourself. Users can create additional keychains, or change the default, by using the Keychain Access application. However, a missing default keychain is not recreated automatically, and you may receive an error from other methods if a default keychain does not exist. In that case, you can use this class method with a YES value for _WillBecomeDefault parameter, to create a new default keychain. You can also call this method to create a private temporary keychain for your application’s use, in cases where no user interaction can occur.

Declared In

WSCKeychainManager.h

currentDefaultKeychain:

Retrieves a WSCKeychain object represented the current default keychain.

- (WSCKeychain *)currentDefaultKeychain:(NSError **)_Error

Parameters

_Error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information.

Return Value

A WSCKeychain object represented the current default keychain.

Discussion

Return nil if there is no default keychain.

See Also

Declared In

WSCKeychainManager.h

deleteKeychain:error:

Deletes the specified keychains from the default keychain search list, and removes the keychain itself if it is a keychain file stored locally.

- (BOOL)deleteKeychain:(WSCKeychain *)_Keychain error:(NSError **)_Error

Parameters

_Keychain

A single keychain object you wish to delete. To delete more than one keychain, please use deleteKeychains:error: method. Passing nil to this parameter returns an NSError object which encapsulated WSCCommonInvalidParametersError error code.

_Error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you don’t want the error information.

Return Value

YES if the keychain was deleted successfully or if _Keychain was nil. Returns NO if an error occured. If the delegate aborts the operation for a keychain, this method returns YES.

Discussion

Prior to deleting each keychain, the keychain manager asks its delegate if it should actually do so. It does this by calling the keychainManager:shouldDeleteKeychain: method; If the delegate method returns YES, or if the delegate does not implement the appropriate methods, the keychain manager proceeds to delete the specified keychain. If there is an error deleting a keychain, the keychain manager may also call the delegate’s keychainManager:shouldProceedAfterError:deletingKeychain: method to determine how to proceed.

The keychain may be a file stored locally, a smart card, or retrieved from a network server using non-file-based database protocols. This method deletes the keychain only if it is a local file.

This method does not release the memory used by the keychain object; you must call the release method to release the keychain object when you are finished with it.

See Also

Declared In

WSCKeychainManager.h

deleteKeychains:error:

Deletes one or more keychains specified in an array from the default keychain search list, and removes the keychain itself if it is a file stored locally.

- (BOOL)deleteKeychains:(NSArray *)_Keychains error:(NSError **)_Error

Parameters

_Keychains

An array of keychains you wish to delete. To delete keychain one by one, please use deleteKeychain:error: method. This parameter must NOT be nil, passing nil to this parameter just returns an NSError object which encapsulated WSCCommonInvalidParametersError error code directly instead of calling any delegate method in WSCKeychainManagerDelegate delegate protocol.

_Error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you don’t want the error information.

Return Value

YES if the keychain was deleted successfully or if _Keychain was nil. Returns NO if an error occured. If the delegate aborts the operation for a keychain, this method returns YES.

Discussion

Prior to deleting each keychain, the keychain manager asks its delegate if it should actually do so. It does this by calling the keychainManager:shouldDeleteKeychain: method; If the delegate method returns YES, or if the delegate does not implement the appropriate methods, the keychain manager proceeds to delete the specified keychain. If there is an error deleting a keychain, the keychain manager may also call the delegate’s keychainManager:shouldProceedAfterError:deletingKeychain: method to determine how to proceed.

The keychain may be a file stored locally, a smart card, or retrieved from a network server using non-file-based database protocols. This method deletes the keychain only if it is a local file.

This method does not release the memory used by the keychain object; you must call the release method to release each keychain object when you are finished with it.

See Also

Declared In

WSCKeychainManager.h

keychainSearchList

Retrieves a keychain search list.

- (NSSet *)keychainSearchList

Return Value

The keychain search list for current user. Returns nil if an error occurs. Returns an empty set if the current keychain search list is empty.

Discussion

This method will only retrieve the valid keychains in the current keychain search list, if a certain keychain in the current search list is already invalid (perhaps it has been deleted, moved or renamed), it won’t be counted in the search list. Which is different from the SecKeychainCopySearchList() function in the Keychain Services, this function will count the invalid keychain.

See Also

Declared In

WSCKeychainManager.h

lockAllKeychains:

Locks all keychains lying in the current default search list belonging to the current user.

- (BOOL)lockAllKeychains:(NSError **)_Error

Parameters

_Error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information.

Return Value

YES if all the keychains were locked successfully; otherwise, NO.

Discussion

Prior to locking each keychain in the current default search list, the keychain manager asks its delegate if it should actually do so. It does this by calling the keychainManager:shouldLockKeychain: method; If the delegate method returns YES, or if the delegate does not implement the appropriate methods, the keychain manager proceeds to lock the specified keychain in search list. If there is an error locking current keychain, the keychain manager may also call the delegate’s keychainManager:shouldProceedAfterError:lockingKeychain: method to determine whether lock the following keychain in the search list.

Your application should not invoke this method unless you are responding the user’s request to lock the keychain. In general, you should leave the keychain unlocked so that the user does not have to unlock it again in another application.

Declared In

WSCKeychainManager.h

lockKeychain:error:

Lock the specified keychain.

- (BOOL)lockKeychain:(WSCKeychain *)_Keychain error:(NSError **)_Error

Parameters

_Keychain

The keychain you wish to lock. Passing nil to this parameter returns an NSError object which encapsulated WSCCommonInvalidParametersError error code. And passing an invalid keychain to this parameter returns an NSError object which encapsulated WSCKeychainIsInvalidError error code.

_Error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information.

Return Value

YES if the specified keychain was locked successfully; otherwise, NO.

Discussion

Prior to locking the specified keychain, the keychain manager asks its delegate if it should actually do so. It does this by calling the keychainManager:shouldLockKeychain: method; If the delegate method returns YES, or if the delegate does not implement the appropriate methods, the keychain manager proceeds to lock the specified keychain. If there is an error locking a keychain, the keychain manager may also call the delegate’s keychainManager:shouldProceedAfterError:lockingKeychain: method to determine how to proceed.

Your application should not invoke this method unless you are responding the user’s request to lock the keychain. In general, you should leave the keychain unlocked so that the user does not have to unlock it again in another application.

Declared In

WSCKeychainManager.h

openExistingKeychainAtURL:error:

Opens an existing keychain from the location specified by a given URL.

- (WSCKeychain *)openExistingKeychainAtURL:(NSURL *)_URLOfExistingKeychain error:(NSError **)_Error

Parameters

_URLOfExistingKeychain

The file URL that identifies the keychain file you want to open. The URL in this parameter must be a file reference URL. This parameter must not be nil.

_Error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you don’t want the error information.

Return Value

A WSCKeychain object represented an existing keychain located at the given URL.

Declared In

WSCKeychainManager.h

removeKeychainFromDefaultSearchList:error:

Removes the specified keychain from the current default search list.

- (BOOL)removeKeychainFromDefaultSearchList:(WSCKeychain *)_Keychain error:(NSError **)_Error

Parameters

_Keychain

The keychain you wish to remvoe from search list. Passing nil to this parameter returns an NSError object which encapsulated WSCCommonInvalidParametersError error code. And passing an invalid keychain to this parameter returns an NSError object which encapsulated WSCKeychainIsInvalidError error code.

_Error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information.

Return Value

YES if the specified keychain was removed from current default search list successfully; otherwise, NO.

Discussion

Warning: If the specified keychain does not exist in default search list, this method will do nothing.

Declared In

WSCKeychainManager.h

setDefaultKeychain:error:

Sets the specified keychain as default keychain.

In most cases, your application should not need to set the default keychain, because this is a choice normally made by the user. You may call this method to change where a passphrase or other keychain items are added, but since this is a user choice, you should set the default keychain back to the user specified keychain when you are done.

- (WSCKeychain *)setDefaultKeychain:(WSCKeychain *)_Keychain error:(NSError **)_Error

Parameters

_Keychain

The keychain you wish to make the default.

_Error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you don’t want the error information.

Return Value

The older default keychain if the specified keychain was made default successfully. If there is not an older default keychain (perhaps the older default keychain has been deleted, moved or renamed), returns nil. Returns nil if an error occured. If the delegate aborts the operation for the keychain, this method returns nil.

See Also

Declared In

WSCKeychainManager.h

setKeychainSearchList:error:

Specifies the list of keychains to use in the default keychain search list.

- (NSSet *)setKeychainSearchList:(NSSet *)_SearchList error:(NSError **)_Error

Parameters

_SearchList

A set of keychain objects (of class WSCKeychain) specifying the list of keychains to use in the new default keychain search list. Passing an empty set clears the search list. This parameter must NOT be nil.

_Error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information.

Return Value

The older default keychain search list if the current keychain search list was updated successfully. Returns nil if an error occured. If the delegate aborts the operation for the keychain, this method returns nil.

Discussion

Prior to updating the current default keychain search list, the keychain manager asks its delegate if it should actually do so. It does this by calling the keychainManager:shouldUpdateKeychainSearchList: method; If the delegate method returns YES, or if the delegate does not implement the appropriate methods, the keychain manager proceeds to update the current default keychain search list with a new list of keychains specified in _SearchList parameter. If there is an error updating search list, the keychain manager may also call the delegate’s keychainManager:shouldProceedAfterError:updatingKeychainSearchList: method to determine how to proceed.

The default keychain search list is displayed as the keychain list in the Keychain Access utility.

If you use this method to change the keychain search list, the list displayed in Keychain Access changes accordingly.

To obtain the current default keychain search list, use the keychainSearchList method.

See Also

Declared In

WSCKeychainManager.h

unlockKeychain:withPassphrase:error:

Unlocks a keychain with an explicitly provided passphrase.

- (BOOL)unlockKeychain:(WSCKeychain *)_Keychain withPassphrase:(NSString *)_Passphrase error:(NSError **)_Error

Parameters

_Keychain

The keychain you wish to unlock. Passing nil to this parameter returns an NSError object which encapsulated WSCCommonInvalidParametersError error code. And passing an invalid keychain to this parameter returns an NSError object which encapsulated WSCKeychainIsInvalidError error code.

_Passphrase

A string containing the passphrase for the specified keychain. This parameter must NOT be nil.

_Error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information.

Return Value

YES if the specified keychain was unlocked successfully; otherwise, NO.

Discussion

In most cases, your application does not need to invoke this method directly, since most WaxSealCore API and the underlying Keychain Services functions that require an unlocked keychain do so for you. If your application needs to verify that a keychain is unlocked, inspect the isLocked property.

Declared In

WSCKeychainManager.h

unlockKeychainWithUserInteraction:error:

Unlocks a keychain with the user interaction which is used to retrieve passphrase from the user.

- (BOOL)unlockKeychainWithUserInteraction:(WSCKeychain *)_Keychain error:(NSError **)_Error

Parameters

_Keychain

The keychain you wish to unlock. Passing nil to this parameter returns an NSError object which encapsulated WSCCommonInvalidParametersError error code. And passing an invalid keychain to this parameter returns an NSError object which encapsulated WSCKeychainIsInvalidError error code.

_Error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information.

Return Value

YES if the specified keychain was unlocked successfully; otherwise, NO.

Discussion

This method will display an Unlock Keychain dialog box. If the specified keychain is currently unlocked, the Unlock Keychain dialog won’t be displayed.

In most cases, your application does not need to invoke this method directly, since most WaxSealCore API and underlying Keychain Services functions that require an unlocked keychain do so for you. If your application needs to verify that a keychain is unlocked, inspect the isLocked property.

Declared In

WSCKeychainManager.h