Inherits from NSObject
Declared in WSCKeychain.h
WSCKeychain.m

Overview

A keychain is an encrypted container that holds passphrases for multiple applications and secure services.

Keychains are secure storage containers, which means that when the keychain is locked, no one can access its protected contents. In OS X, users can unlock a keychain—thus providing trusted applications access to the contents—by entering a single master passphrase.

The above encrypted container which is called “keychain” is represented by WSCKeychain object in WaxSealCore framework and SecKeychainRef in Keychain Services API.

Tasks

Properties

Creating Keychains

Comparing Keychains

Creating and Managing Keychain Items

Keychain Services Bridge

Properties

URL

The URL for the receiver. (read-only)

@property (retain, readonly) NSURL *URL

Return Value

The URL for the receiver.

Declared In

WSCKeychain.h

enableLockOnSleep

A BOOL value indicating whether the keychain locks when the system sleeps.

@property (assign, readwrite) BOOL enableLockOnSleep

Discussion

Bug: So far this API doesn’t work properly due to the bug of underlying Keychain Services or my mistake, FIGHT ON!

Declared In

WSCKeychain.h

isDefault

Default state of receiver. (read-only)

@property (assign, readonly) BOOL isDefault

Discussion

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.

Declared In

WSCKeychain.h

isLocked

BOOL value that indicates whether the receiver is currently locked. (read-only)

@property (assign, readonly) BOOL isLocked

Discussion

YES if the receiver is currently locked, otherwise, NO.

Declared In

WSCKeychain.h

isReadable

BOOL value that indicates whether the receiver is readable. (read-only)

@property (assign, readonly) BOOL isReadable

Discussion

YES if the receiver is readable, otherwise, NO.

Declared In

WSCKeychain.h

isValid

BOOL value that indicates whether the receiver is currently valid. (read-only)

@property (assign, readonly) BOOL isValid

Discussion

YES if the receiver is still capable of referring to a valid keychain file; otherwise, NO.

Declared In

WSCKeychain.h

isWritable

BOOL value that indicates whether the receiver is writable. (read-only)

@property (assign, readonly) BOOL isWritable

Discussion

YES if the receiver is writable, otherwise, NO.

Declared In

WSCKeychain.h

secKeychain

The reference of the SecKeychain opaque object, which wrapped by WSCKeychain object.

@property (unsafe_unretained, readonly) SecKeychainRef secKeychain

Discussion

If you are familiar with the underlying Keychain Services API, you can move freely back and forth between WaxSealCore framework and Keychain Services API with this property.

Declared In

WSCKeychain.h

Class Methods

keychainWithSecKeychainRef:

Creates and returns a WSCKeychain object using the given reference to the instance of SecKeychain opaque type.

+ (instancetype)keychainWithSecKeychainRef:(SecKeychainRef)_SecKeychainRef

Parameters

_SecKeychainRef

A reference to the instance of SecKeychain opaque type.

Return Value

A WSCKeychain object initialized with the given reference to the instance of SecKeychain opaque type. Return nil if _SecKeychainRef is nil or an error occured.

Discussion

If you are familiar with the underlying Keychain Services API, you can move freely back and forth between WaxSealCore framework and Keychain Services API with this class method.

Warning: This method is just used for bridge between WaxSealCore framework and Keychain Services API.

Instead of invoking this method, you should construct a WSCKeychain object by invoking:

Declared In

WSCKeychain.h

login

Opens and returns a WSCKeychain object representing the login.keychain for current user.

+ (instancetype)login

Return Value

A WSCKeychain object representing the login.keychain for current user

Discussion

This method will search for the login.keychain at ~/Library/Keychains, if there is not a login.keychain, nil returned.

See Also

Declared In

WSCKeychain.h

system

Opens and returns a WSCKeychain object representing the System.keychain for current user.

+ (instancetype)system

Return Value

A WSCKeychain object representing the System.keychain.

Discussion

This method will search for the System.keychain at /Library/Keychains, if there is not a System.keychain, nil returned.

See Also

Declared In

WSCKeychain.h

Instance Methods

addApplicationPassphraseWithServiceName:accountName:passphrase:error:

Adds a new application passphrase to the keychain represented by receiver.

- (WSCPassphraseItem *)addApplicationPassphraseWithServiceName:(NSString *)_ServiceName accountName:(NSString *)_AccountName passphrase:(NSString *)_Passphrase error:(NSError **)_Error

Parameters

_ServiceName

An NSString object representing the service name.

_AccountName

An NSString object representing the account name.

_Passphrase

An NSString object representing the passphrase.

_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 WSCPassphraseItem object representing the new keychain item. Returns nil if an error occurs.

Discussion

This method adds a new application passphrase to the keychain represented by receiver. Required parameters to identify the passphrase are _ServiceName and _AccountName, which are application-defined strings. This method returns a newly added item represented by a WSCKeychainItem object.

You can use this method to add passphrases for accounts other than the Internet. For example, you might add Evernote or IRC Client passphrases, or passphrases for your database or scheduling programs.

This method sets the initial access rights for the new keychain item so that the application creating the item is given trusted access.

This method automatically calls the unlockKeychainWithUserInteraction:error: method to display the Unlock Keychain dialog box if the keychain is currently locked.

Declared In

WSCKeychain.h

addInternetPassphraseWithServerName:URLRelativePath:accountName:protocol:passphrase:error:

Adds a new Internet passphrase to the keychain represented by receiver.

- (WSCPassphraseItem *)addInternetPassphraseWithServerName:(NSString *)_ServerName URLRelativePath:(NSString *)_URLRelativePath accountName:(NSString *)_AccountName protocol:(WSCInternetProtocolType)_Protocol passphrase:(NSString *)_Passphrase error:(NSError **)_Error

Parameters

_ServerName

An NSString object representing the server name.

_URLRelativePath

An NSString object representing the the path.

_AccountName

An NSString object representing the account name.

_Protocol

The protocol associated with this passphrase. See “WaxSealCore Internet Protocol Type Constants” for a description of possible values.

_Passphrase

An NSString object containing the passphrase.

_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 WSCPassphraseItem object representing the new keychain item. Returns nil if an error occurs.

Discussion

This method adds a new Internet server passphrase to the specified keychain. Required parameters to identify the passphrase are _ServerName and _AccountName (you cannot pass nil for both parameters). In addition, some protocols may require an optional _SecurityDomain when authentication is requested. This method returns a newly added item represented by a WSCKeychainItem object.

This method sets the initial access rights for the new keychain item so that the application creating the item is given trusted access.

This method automatically calls the unlockKeychainWithUserInteraction:error: method to display the Unlock Keychain dialog box if the keychain is currently locked.

Declared In

WSCKeychain.h

allApplicationPassphraseItems

Retrieve all the application passphrase items stored in the keychain represented by receiver.

- (NSSet *)allApplicationPassphraseItems

Return Value

An NSSet object containing all the application passphrase items stored in the keychain represented by receiver. Returns an empty set if there is not any application passphrase item in the keychain. Returns nil if an error occured.

Discussion

Warning: After invoking this method, the passphrase item stored in the returned set may become invalid (perhaps it has been deleted or modified by user or by other applications), you should check the validity of each passphrase item before using it.

Declared In

WSCKeychain.h

allCertificateItems

Retrieve all the X.509 certificates stored in the keychain represented by receiver.

- (NSSet *)allCertificateItems

Return Value

An NSSet object containing all the certificate items stored in the keychain represented by receiver. Returns an empty set if there is not any certificate item in the keychain. Returns nil if an error occured.

Discussion

Warning: After invoking this method, the certificate item stored in the returned set may become invalid (perhaps it has been deleted or modified by user or by other applications), you should check the validity of each passphrase item before using it.

Declared In

WSCKeychain.h

allInternetPassphraseItems

Retrieve all the Internet passphrase items stored in the keychain represented by receiver.

- (NSSet *)allInternetPassphraseItems

Return Value

An NSSet object containing all the Internet passphrase items stored in the keychain represented by receiver. Returns an empty set if there is not any Internet passphrase item in the keychain. Returns nil if an error occured.

Discussion

Warning: After invoking this method, the passphrase item stored in the returned set may become invalid (perhaps it has been deleted or modified by user or by other applications), you should check the validity of each passphrase item before using it.

Declared In

WSCKeychain.h

deleteKeychainItem:error:

Deletes a keychain item from the permanent data store of the keychain represented by receiver.

- (BOOL)deleteKeychainItem:(WSCKeychainItem *)_KeychainItem error:(NSError **)_Error

Parameters

_KeychainItem

The keychain item to be deleted. After the delete operation, this keychain item will become invalid.

_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 delete operation is successful; otherwise, NO.

Discussion

If the keychain item has not previously been added to the keychain, this method does nothing and returns YES.

Do not delete a keychain item and recreate it in order to modify it; instead, use the read-write properties to modify an existing keychain item. When you delete a keychain item, you lose any access controls and trust settings added by the user or by other applications.

Declared In

WSCKeychain.h

findAllKeychainItemsSatisfyingSearchCriteria:itemClass:error:

Find all the keychain items satisfying the given search criteria contained in _SearchCriteriaDict dictionary.

- (NSSet *)findAllKeychainItemsSatisfyingSearchCriteria:(NSDictionary *)_SearchCriteriaDict itemClass:(WSCKeychainItemClass)_ItemClass error:(NSError **)_Error

Parameters

_SearchCriteriaDict

The NSDictionary object containing the search criteria. For the valid search keys, please see the discussion section of findFirstKeychainItemSatisfyingSearchCriteria:itemClass:error: method.

_ItemClass

The value of type WSCKeychainItemClass, it identifies the type of keychain item we want to find.

_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

An NSSet object containing the keychain items satisfying the given search criteria. Returns an empty set if there is not any keychan item satisfying the given search criteria. Returns nil if an error occurs.

Discussion

Warning: After invoking this method, the passphrase item stored in the returned set may become invalid (perhaps it has been deleted or modified by user or by other applications), you should check the validity of each passphrase item before using it.

See Also

Declared In

WSCKeychain.h

findFirstKeychainItemSatisfyingSearchCriteria:itemClass:error:

Find the first keychain item which satisfies the given search criteria contained in _SearchCriteriaDict dictionary.

- (WSCKeychainItem *)findFirstKeychainItemSatisfyingSearchCriteria:(NSDictionary *)_SearchCriteriaDict itemClass:(WSCKeychainItemClass)_ItemClass error:(NSError **)_Error

Parameters

_SearchCriteriaDict

The NSDictionary object containing the search criteria. For the valid search keys, see the discussion section.

_ItemClass

The value of type WSCKeychainItemClass, it identifies the type of keychain item we want to find.

_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 WSCKeychainItem object representing the keychain item satisfying the given search criteria. Returns nil if an error occurs or there is not any keychan item satisfying the given search criteria.

Discussion

The valid search keys:

Common Attributes:

  • WSCKeychainItemAttributeCreationDate The corresponding value is an NSDate object that identifies the creation date of a keychain item.

  • WSCKeychainItemAttributeModificationDate The corresponding value is an NSDate object that identifies the modification date of a keychain item.

  • WSCKeychainItemAttributeKindDescription The corresponding value is an NSString object that identifies the comment of a keychain item.

  • WSCKeychainItemAttributeComment The corresponding value is an NSString object that identifies the kind description of a keychain item.

  • WSCKeychainItemAttributeLabel The corresponding value is an NSString object that identifies the label of a keychain item.

  • WSCKeychainItemAttributeInvisible The corresponding value is a BOOL value that indicates whether the item is invisible.

  • WSCKeychainItemAttributeNegative The corresponding value is a BOOL value that indicates whether there is a valid passphrase associated with this keychain item.

  • WSCKeychainItemAttributeAccount The corresponding value is an NSString object that identifies the user account of a passphrase item. It also applies to application, Internet passphrase items.

Unique to the Internet Passphrase Items:

  • WSCKeychainItemAttributeHostName The corresponding value is an NSString object that identifies the Internet server’s domain name or IP address of an Internet passphrase. This search key is unique to the Internet passphrase item.

  • WSCKeychainItemAttributeAuthenticationType The corresponding value is an NSValue object that encapsulates a value of type WSCInternetAuthenticationType that identifies the authentication type of an Internet passphrase. You can get the correct NSValue object that encapsulates the given value of type WSCInternetAuthenticationType by invoking WSCAuthenticationTypeCocoaValue(). This search key is unique to the Internet passphrase item.

  • WSCKeychainItemAttributePort The corresponding value is an NSNumber object that identifies the port number of an Internet passphrase item. This search key is unique to the Internet passphrase item.

  • WSCKeychainItemAttributeRelativePath The corresponding value is an NSString object that identifies the relative path of a URL conforming to RFC 1808 of an Internet passphrase. For example: in the URL “https://github.com/TongG/WaxSealCore”, the relative URL path is “/TongG/WaxSealCore”. This search key is unique to the Internet passphrase item.

  • WSCKeychainItemAttributeProtocol The corresponding value is an NSValue object that encapsulates a value of type WSCInternetProtocolType that identifies the Internet protocol of an Internet passphrase. You can get the correct NSValue object that encapsulates the given value of type WSCInternetProtocolType by invoking WSCInternetProtocolCocoaValue(). This search key is unique to the Internet passphrase item.

Unique to the Application Passphrase Items:

  • WSCKeychainItemAttributeServiceName The corresponding value is an NSString object that identifies the value of untyped bytes that represents a user-defined data. This search key is unique to the application passphrase item.

  • WSCKeychainItemAttributeUserDefinedDataAttribute The corresponding value is an NSData object that identifies the service name of an application passphrase item. For example, “WaxSeal”. This search key is unique to the application passphrase item.

Unique to the Application Passphrase Items:

  • WSCKeychainItemAttributeCertificateType

Warning: After invoking this method, the passphrase item returned by this method may become invalid (perhaps it has been deleted or modified by user or by other applications), you should check the validity of it before using it.

See Also

Declared In

WSCKeychain.h

isEqualToKeychain:

Returns a BOOL value that indicates whether a given keychain is equal to receiver using an URL comparision.

- (BOOL)isEqualToKeychain:(WSCKeychain *)_AnotherKeychain

Parameters

_AnotherKeychain

The keychain with which to compare the receiver.

Return Value

YES if _AnotherKeychain is equivalent to receiver (if they have the same URL); otherwise NO.

One more thing

When you know both objects are keychains, this method is a faster way to check equality than method isEqual:.

Declared In

WSCKeychain.h