Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: 69019d81e6
Fetching contributors…

Cannot retrieve contributors at this time

358 lines (235 sloc) 11.928 kb
//
// SSKeychain.h
// SSToolkit
//
// Created by Sam Soffes on 5/19/10.
// Copyright (c) 2009-2011 Sam Soffes. All rights reserved.
//
#import <Foundation/Foundation.h>
#import <Security/Security.h>
/** Error codes that can be returned in NSError objects. */
typedef enum {
/** No error. */
SSKeychainErrorNone = noErr,
/** Some of the arguments were invalid. */
SSKeychainErrorBadArguments = -1001,
/** There was no password. */
SSKeychainErrorNoPassword = -1002,
/** One or more parameters passed internally were not valid. */
SSKeychainErrorInvalidParameter = errSecParam,
/** Failed to allocate memory. */
SSKeychainErrorFailedToAllocated = errSecAllocate,
/** No trust results are available. */
SSKeychainErrorNotAvailable = errSecNotAvailable,
/** Authorization/Authentication failed. */
SSKeychainErrorAuthorizationFailed = errSecAuthFailed,
/** The item already exists. */
SSKeychainErrorDuplicatedItem = errSecDuplicateItem,
/** The item cannot be found.*/
SSKeychainErrorNotFound = errSecItemNotFound,
/** Interaction with the Security Server is not allowed. */
SSKeychainErrorInteractionNotAllowed = errSecInteractionNotAllowed,
/** Unable to decode the provided data. */
SSKeychainErrorFailedToDecode = errSecDecode
} SSKeychainErrorCode;
extern NSString *const kSSKeychainErrorDomain;
/** Account name. */
extern NSString *const kSSKeychainAccountKey;
/**
Time the item was created.
The value will be a string.
*/
extern NSString *const kSSKeychainCreatedAtKey;
/** Item class. */
extern NSString *const kSSKeychainClassKey;
/** Item description. */
extern NSString *const kSSKeychainDescriptionKey;
/** Item label. */
extern NSString *const kSSKeychainLabelKey;
/** Time the item was last modified.
The value will be a string.
*/
extern NSString *const kSSKeychainLastModifiedKey;
/** Where the item was created. */
extern NSString *const kSSKeychainWhereKey;
/**
Simple wrapper for accessing accounts, getting passwords, setting passwords, and deleting passwords using the system
Keychain on Mac OS X and iOS.
This was originally inspired by EMKeychain and SDKeychain (both of which are now gone). Thanks to the authors.
SSKeychain has since switched to a simpler implementation that was abstracted from [SSToolkit](http://sstoolk.it).
*/
@interface SSKeychain : NSObject
///-----------------------
/// @name Getting Accounts
///-----------------------
/**
Returns an array containing the Keychain's accounts, or `nil` if the Keychain has no accounts.
See the `NSString` constants declared in SSKeychain.h for a list of keys that can be used when accessing the
dictionaries returned by this method.
@return An array of dictionaries containing the Keychain's accounts, or `nil` if the Keychain doesn't have any
accounts. The order of the objects in the array isn't defined.
@see allAccounts:
*/
+ (NSArray *)allAccounts;
/**
Returns an array containing the Keychain's accounts, or `nil` if the Keychain doesn't have any
accounts.
See the `NSString` constants declared in SSKeychain.h for a list of keys that can be used when accessing the
dictionaries returned by this method.
@param error If accessing the accounts fails, upon return contains an error that describes the problem.
@return An array of dictionaries containing the Keychain's accounts, or `nil` if the Keychain doesn't have any
accounts. The order of the objects in the array isn't defined.
@see allAccounts
*/
+ (NSArray *)allAccounts:(NSError **)error;
/**
Returns an array containing the Keychain's accounts for a given service, or `nil` if the Keychain doesn't have any
accounts for the given service.
See the `NSString` constants declared in SSKeychain.h for a list of keys that can be used when accessing the
dictionaries returned by this method.
@param serviceName The service for which to return the corresponding accounts.
@return An array of dictionaries containing the Keychain's accountsfor a given `serviceName`, or `nil` if the Keychain
doesn't have any accounts for the given `serviceName`. The order of the objects in the array isn't defined.
@see accountsForService:error:
*/
+ (NSArray *)accountsForService:(NSString *)serviceName;
/**
Returns an array containing the Keychain's accounts for a given service, or `nil` if the Keychain doesn't have any
accounts for the given service.
@param serviceName The service for which to return the corresponding accounts.
@param error If accessing the accounts fails, upon return contains an error that describes the problem.
@return An array of dictionaries containing the Keychain's accountsfor a given `serviceName`, or `nil` if the Keychain
doesn't have any accounts for the given `serviceName`. The order of the objects in the array isn't defined.
@see accountsForService:
*/
+ (NSArray *)accountsForService:(NSString *)serviceName error:(NSError **)error;
///------------------------
/// @name Getting Passwords
///------------------------
/**
Returns a string containing the password for a given account and service, or `nil` if the Keychain doesn't have a
password for the given parameters.
@param serviceName The service for which to return the corresponding password.
@param account The account for which to return the corresponding password.
@return Returns a string containing the password for a given account and service, or `nil` if the Keychain doesn't
have a password for the given parameters.
@see passwordForService:account:error:
*/
+ (NSString *)passwordForService:(NSString *)serviceName account:(NSString *)account;
/**
Returns a string containing the password for a given account and service, or `nil` if the Keychain doesn't have a
password for the given parameters.
@param serviceName The service for which to return the corresponding password.
@param account The account for which to return the corresponding password.
@param error If accessing the password fails, upon return contains an error that describes the problem.
@return Returns a string containing the password for a given account and service, or `nil` if the Keychain doesn't
have a password for the given parameters.
@see passwordForService:account:
*/
+ (NSString *)passwordForService:(NSString *)serviceName account:(NSString *)account error:(NSError **)error;
/**
Returns the password data for a given account and service, or `nil` if the Keychain doesn't have data
for the given parameters.
@param serviceName The service for which to return the corresponding password.
@param account The account for which to return the corresponding password.
@param error If accessing the password fails, upon return contains an error that describes the problem.
@return Returns a the password data for the given account and service, or `nil` if the Keychain doesn't
have data for the given parameters.
@see passwordDataForService:account:error:
*/
+ (NSData *)passwordDataForService:(NSString *)serviceName account:(NSString *)account;
/**
Returns the password data for a given account and service, or `nil` if the Keychain doesn't have data
for the given parameters.
@param serviceName The service for which to return the corresponding password.
@param account The account for which to return the corresponding password.
@param error If accessing the password fails, upon return contains an error that describes the problem.
@return Returns a the password data for the given account and service, or `nil` if the Keychain doesn't
have a password for the given parameters.
@see passwordDataForService:account:
*/
+ (NSData *)passwordDataForService:(NSString *)serviceName account:(NSString *)account error:(NSError **)error;
///-------------------------
/// @name Deleting Passwords
///-------------------------
/**
Deletes a password from the Keychain.
@param serviceName The service for which to delete the corresponding password.
@param account The account for which to delete the corresponding password.
@return Returns `YES` on success, or `NO` on failure.
@see deletePasswordForService:account:error:
*/
+ (BOOL)deletePasswordForService:(NSString *)serviceName account:(NSString *)account;
/**
Deletes a password from the Keychain.
@param serviceName The service for which to delete the corresponding password.
@param account The account for which to delete the corresponding password.
@param error If deleting the password fails, upon return contains an error that describes the problem.
@return Returns `YES` on success, or `NO` on failure.
@see deletePasswordForService:account:
*/
+ (BOOL)deletePasswordForService:(NSString *)serviceName account:(NSString *)account error:(NSError **)error;
///------------------------
/// @name Setting Passwords
///------------------------
/**
Sets a password in the Keychain.
@param password The password to store in the Keychain.
@param serviceName The service for which to set the corresponding password.
@param account The account for which to set the corresponding password.
@return Returns `YES` on success, or `NO` on failure.
@see setPassword:forService:account:error:
*/
+ (BOOL)setPassword:(NSString *)password forService:(NSString *)serviceName account:(NSString *)account;
/**
Sets a password in the Keychain.
@param password The password to store in the Keychain.
@param serviceName The service for which to set the corresponding password.
@param account The account for which to set the corresponding password.
@param error If setting the password fails, upon return contains an error that describes the problem.
@return Returns `YES` on success, or `NO` on failure.
@see setPassword:forService:account:
*/
+ (BOOL)setPassword:(NSString *)password forService:(NSString *)serviceName account:(NSString *)account error:(NSError **)error;
/**
Sets arbirary data in the Keychain.
@param password The data to store in the Keychain.
@param serviceName The service for which to set the corresponding password.
@param account The account for which to set the corresponding password.
@param error If setting the password fails, upon return contains an error that describes the problem.
@return Returns `YES` on success, or `NO` on failure.
@see setPasswordData:forService:account:error:
*/
+ (BOOL)setPasswordData:(NSData *)password forService:(NSString *)serviceName account:(NSString *)account;
/**
Sets arbirary data in the Keychain.
@param password The data to store in the Keychain.
@param serviceName The service for which to set the corresponding password.
@param account The account for which to set the corresponding password.
@param error If setting the password fails, upon return contains an error that describes the problem.
@return Returns `YES` on success, or `NO` on failure.
@see setPasswordData:forService:account:
*/
+ (BOOL)setPasswordData:(NSData *)password forService:(NSString *)serviceName account:(NSString *)account error:(NSError **)error;
///--------------------
/// @name Configuration
///--------------------
#if __IPHONE_4_0 && TARGET_OS_IPHONE
/**
Returns the accessibility type for all future passwords saved to the Keychain.
@return Returns the accessibility type.
The return value will be `NULL` or one of the "Keychain Item Accessibility Constants" used for determining when a
keychain item should be readable.
@see accessibilityType
*/
+ (CFTypeRef)accessibilityType;
/**
Sets the accessibility type for all future passwords saved to the Keychain.
@param accessibilityType One of the "Keychain Item Accessibility Constants" used for determining when a keychain item
should be readable.
If the value is `NULL` (the default), the Keychain default will be used.
@see accessibilityType
*/
+ (void)setAccessibilityType:(CFTypeRef)accessibilityType;
#endif
@end
Jump to Line
Something went wrong with that request. Please try again.