sdks/ios/UGAPI/SSKeychain.h - usergrid - Git at Google

 //
 //  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
	//
	// 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