SAMKeychain

Complete API reference for the SAMKeychain class

Simple wrapper for accessing accounts, getting passwords, setting passwords, and deleting passwords using the system Keychain on Mac OS X and iOS.

Class Methods

passwordForService: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.

+ (nullable NSString *)passwordForService:(NSString *)serviceName 
                                  account:(NSString *)account;

serviceName · NSString * · required

The service for which to return the corresponding password.

account · NSString * · required

The account for which to return the corresponding password.

return · NSString *

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.

Example:

NSString *password = [SAMKeychain passwordForService:@"MyService" 
                                             account:@"[e-mail]"];
if (password) {
    NSLog(@"Password retrieved: %@", password);
}

passwordForService:account:error:

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. Populates an error object if an error occurs.

+ (nullable NSString *)passwordForService:(NSString *)serviceName 
                                  account:(NSString *)account 
                                    error:(NSError **)error;

serviceName · NSString * · required

The service for which to return the corresponding password.

account · NSString * · required

The account for which to return the corresponding password.

error · NSError **

Populated should an error occur.

return · NSString *

Returns a string containing the password, or nil if an error occurs.

Example:

NSError *error = nil;
NSString *password = [SAMKeychain passwordForService:@"MyService" 
                                             account:@"[e-mail]" 
                                               error:&error];
if (error) {
    NSLog(@"Error retrieving password: %@", error);
}

passwordDataForService:account:

Returns NSData containing the password for a given account and service, or nil if the Keychain doesn’t have a password for the given parameters.

+ (nullable NSData *)passwordDataForService:(NSString *)serviceName 
                                    account:(NSString *)account;

serviceName · NSString * · required

The service for which to return the corresponding password.

account · NSString * · required

The account for which to return the corresponding password.

return · NSData *

Returns NSData containing the password for a given account and service, or nil if the Keychain doesn’t have a password for the given parameters.

Example:

NSData *passwordData = [SAMKeychain passwordDataForService:@"MyService" 
                                                   account:@"[e-mail]"];
if (passwordData) {
    NSLog(@"Password data retrieved: %lu bytes", (unsigned long)passwordData.length);
}

passwordDataForService:account:error:

Returns NSData containing the password for a given account and service, or nil if the Keychain doesn’t have a password for the given parameters. Populates an error object if an error occurs.

+ (nullable NSData *)passwordDataForService:(NSString *)serviceName 
                                    account:(NSString *)account 
                                      error:(NSError **)error;

serviceName · NSString * · required

The service for which to return the corresponding password.

account · NSString * · required

The account for which to return the corresponding password.

error · NSError **

Populated should an error occur.

return · NSData *

Returns NSData containing the password, or nil if an error occurs.

Example:

NSError *error = nil;
NSData *passwordData = [SAMKeychain passwordDataForService:@"MyService" 
                                                   account:@"[e-mail]" 
                                                     error:&error];
if (error) {
    NSLog(@"Error retrieving password data: %@", error);
}

deletePasswordForService:account:

Deletes a password from the Keychain.

+ (BOOL)deletePasswordForService:(NSString *)serviceName 
                         account:(NSString *)account;

serviceName · NSString * · required

The service for which to delete the corresponding password.

account · NSString * · required

The account for which to delete the corresponding password.

return · BOOL

Returns YES on success, or NO on failure.

Example:

BOOL success = [SAMKeychain deletePasswordForService:@"MyService" 
                                             account:@"[e-mail]"];
if (success) {
    NSLog(@"Password deleted successfully");
}

deletePasswordForService:account:error:

Deletes a password from the Keychain. Populates an error object if an error occurs.

+ (BOOL)deletePasswordForService:(NSString *)serviceName 
                         account:(NSString *)account 
                           error:(NSError **)error;

serviceName · NSString * · required

The service for which to delete the corresponding password.

account · NSString * · required

The account for which to delete the corresponding password.

error · NSError **

Populated should an error occur.

return · BOOL

Returns YES on success, or NO on failure.

Example:

NSError *error = nil;
BOOL success = [SAMKeychain deletePasswordForService:@"MyService" 
                                             account:@"[e-mail]" 
                                               error:&error];
if (!success) {
    NSLog(@"Error deleting password: %@", error);
}

setPassword:forService:account:

Sets a password in the Keychain.

+ (BOOL)setPassword:(NSString *)password 
         forService:(NSString *)serviceName 
            account:(NSString *)account;

password · NSString * · required

The password to store in the Keychain.

serviceName · NSString * · required

The service for which to set the corresponding password.

account · NSString * · required

The account for which to set the corresponding password.

return · BOOL

Returns YES on success, or NO on failure.

Example:

BOOL success = [SAMKeychain setPassword:@"mySecurePassword" 
                             forService:@"MyService" 
                                account:@"[e-mail]"];
if (success) {
    NSLog(@"Password saved successfully");
}

setPassword:forService:account:error:

Sets a password in the Keychain. Populates an error object if an error occurs.

+ (BOOL)setPassword:(NSString *)password 
         forService:(NSString *)serviceName 
            account:(NSString *)account 
              error:(NSError **)error;

password · NSString * · required

The password to store in the Keychain.

serviceName · NSString * · required

The service for which to set the corresponding password.

account · NSString * · required

The account for which to set the corresponding password.

error · NSError **

Populated should an error occur.

return · BOOL

Returns YES on success, or NO on failure.

Example:

NSError *error = nil;
BOOL success = [SAMKeychain setPassword:@"mySecurePassword" 
                             forService:@"MyService" 
                                account:@"[e-mail]" 
                                  error:&error];
if (!success) {
    NSLog(@"Error saving password: %@", error);
}

setPasswordData:forService:account:

Sets a password in the Keychain using NSData.

+ (BOOL)setPasswordData:(NSData *)password 
             forService:(NSString *)serviceName 
                account:(NSString *)account;

password · NSData * · required

The password to store in the Keychain.

serviceName · NSString * · required

The service for which to set the corresponding password.

account · NSString * · required

The account for which to set the corresponding password.

return · BOOL

Returns YES on success, or NO on failure.

Example:

NSData *passwordData = [@"mySecurePassword" dataUsingEncoding:NSUTF8StringEncoding];
BOOL success = [SAMKeychain setPasswordData:passwordData 
                                 forService:@"MyService" 
                                    account:@"[e-mail]"];
if (success) {
    NSLog(@"Password data saved successfully");
}

setPasswordData:forService:account:error:

Sets a password in the Keychain using NSData. Populates an error object if an error occurs.

+ (BOOL)setPasswordData:(NSData *)password 
             forService:(NSString *)serviceName 
                account:(NSString *)account 
                  error:(NSError **)error;

password · NSData * · required

The password to store in the Keychain.

serviceName · NSString * · required

The service for which to set the corresponding password.

account · NSString * · required

The account for which to set the corresponding password.

error · NSError **

Populated should an error occur.

return · BOOL

Returns YES on success, or NO on failure.

Example:

NSData *passwordData = [@"mySecurePassword" dataUsingEncoding:NSUTF8StringEncoding];
NSError *error = nil;
BOOL success = [SAMKeychain setPasswordData:passwordData 
                                 forService:@"MyService" 
                                    account:@"[e-mail]" 
                                      error:&error];
if (!success) {
    NSLog(@"Error saving password data: %@", error);
}

allAccounts

Returns an array containing the Keychain’s accounts, or nil if the Keychain has no accounts.

+ (nullable NSArray<NSDictionary<NSString *, id> *> *)allAccounts;

return · NSArray<NSDictionary<NSString *, id> *> *

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.

Example:

NSArray *accounts = [SAMKeychain allAccounts];
for (NSDictionary *account in accounts) {
    NSString *accountName = account[kSAMKeychainAccountKey];
    NSLog(@"Account: %@", accountName);
}

See the NSString constants declared in SAMKeychain.h for a list of keys that can be used when accessing the dictionaries returned by this method.

allAccounts:

Returns an array containing the Keychain’s accounts, or nil if the Keychain has no accounts. Populates an error object if an error occurs.

+ (nullable NSArray<NSDictionary<NSString *, id> *> *)allAccounts:(NSError **)error;

error · NSError **

Populated should an error occur.

return · NSArray<NSDictionary<NSString *, id> *> *

An array of dictionaries containing the Keychain’s accounts, or nil if an error occurs. The order of the objects in the array isn’t defined.

Example:

NSError *error = nil;
NSArray *accounts = [SAMKeychain allAccounts:&error];
if (error) {
    NSLog(@"Error retrieving accounts: %@", error);
} else {
    for (NSDictionary *account in accounts) {
        NSString *accountName = account[kSAMKeychainAccountKey];
        NSLog(@"Account: %@", accountName);
    }
}

accountsForService:

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.

+ (nullable NSArray<NSDictionary<NSString *, id> *> *)accountsForService:(nullable NSString *)serviceName;

serviceName · NSString *

The service for which to return the corresponding accounts.

return · NSArray<NSDictionary<NSString *, id> *> *

An array of dictionaries containing the Keychain’s accounts for 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.

Example:

NSArray *accounts = [SAMKeychain accountsForService:@"MyService"];
for (NSDictionary *account in accounts) {
    NSString *accountName = account[kSAMKeychainAccountKey];
    NSLog(@"Account for MyService: %@", accountName);
}

See the NSString constants declared in SAMKeychain.h for a list of keys that can be used when accessing the dictionaries returned by this method.

accountsForService: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. Populates an error object if an error occurs.

+ (nullable NSArray<NSDictionary<NSString *, id> *> *)accountsForService:(nullable NSString *)serviceName 
                                                                   error:(NSError **)error;

serviceName · NSString *

The service for which to return the corresponding accounts.

error · NSError **

Populated should an error occur.

return · NSArray<NSDictionary<NSString *, id> *> *

An array of dictionaries containing the Keychain’s accounts for a given serviceName, or nil if an error occurs. The order of the objects in the array isn’t defined.

Example:

NSError *error = nil;
NSArray *accounts = [SAMKeychain accountsForService:@"MyService" error:&error];
if (error) {
    NSLog(@"Error retrieving accounts: %@", error);
} else {
    for (NSDictionary *account in accounts) {
        NSString *accountName = account[kSAMKeychainAccountKey];
        NSLog(@"Account for MyService: %@", accountName);
    }
}

accessibilityType (iOS only)

Returns the accessibility type for all future passwords saved to the Keychain.

+ (CFTypeRef)accessibilityType;

return · CFTypeRef

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.

Example:

CFTypeRef accessibility = [SAMKeychain accessibilityType];
if (accessibility == kSecAttrAccessibleWhenUnlocked) {
    NSLog(@"Keychain items are accessible when unlocked");
}

This method is only available on iOS 4.0 and later.

setAccessibilityType: (iOS only)

Sets the accessibility type for all future passwords saved to the Keychain.

+ (void)setAccessibilityType:(CFTypeRef)accessibilityType;

accessibilityType · CFTypeRef · required

One of the “Keychain Item Accessibility Constants” used for determining when a keychain item should be readable.

Example:

[SAMKeychain setAccessibilityType:kSecAttrAccessibleWhenUnlocked];

If the value is NULL (the default), the Keychain default will be used which is highly insecure. You really should use at least kSecAttrAccessibleAfterFirstUnlock for background applications or kSecAttrAccessibleWhenUnlocked for all other applications.

This method is only available on iOS 4.0 and later.

Constants

Error Domain

kSAMKeychainErrorDomain

extern NSString *const kSAMKeychainErrorDomain;

SAMKeychain error domain used in NSError objects.

Example:

if ([error.domain isEqualToString:kSAMKeychainErrorDomain]) {
    // Handle SAMKeychain-specific error
}

Dictionary Keys

These constants are used as keys in the dictionaries returned by allAccounts, allAccounts:, accountsForService:, and accountsForService:error:.

kSAMKeychainAccountKey

extern NSString *const kSAMKeychainAccountKey;

Account name key.

Example:

NSArray *accounts = [SAMKeychain allAccounts];
for (NSDictionary *account in accounts) {
    NSString *accountName = account[kSAMKeychainAccountKey];
}

kSAMKeychainCreatedAtKey

extern NSString *const kSAMKeychainCreatedAtKey;

Time the item was created. The value will be a string.

Example:

NSArray *accounts = [SAMKeychain allAccounts];
for (NSDictionary *account in accounts) {
    NSString *createdAt = account[kSAMKeychainCreatedAtKey];
    NSLog(@"Created at: %@", createdAt);
}

kSAMKeychainClassKey

extern NSString *const kSAMKeychainClassKey;

Item class key.

Example:

NSArray *accounts = [SAMKeychain allAccounts];
for (NSDictionary *account in accounts) {
    NSString *itemClass = account[kSAMKeychainClassKey];
}

kSAMKeychainDescriptionKey

extern NSString *const kSAMKeychainDescriptionKey;

Item description key.

Example:

NSArray *accounts = [SAMKeychain allAccounts];
for (NSDictionary *account in accounts) {
    NSString *description = account[kSAMKeychainDescriptionKey];
}

kSAMKeychainLabelKey

extern NSString *const kSAMKeychainLabelKey;

Item label key.

Example:

NSArray *accounts = [SAMKeychain allAccounts];
for (NSDictionary *account in accounts) {
    NSString *label = account[kSAMKeychainLabelKey];
}

kSAMKeychainLastModifiedKey

extern NSString *const kSAMKeychainLastModifiedKey;

Time the item was last modified. The value will be a string.

Example:

NSArray *accounts = [SAMKeychain allAccounts];
for (NSDictionary *account in accounts) {
    NSString *lastModified = account[kSAMKeychainLastModifiedKey];
    NSLog(@"Last modified: %@", lastModified);
}

kSAMKeychainWhereKey

extern NSString *const kSAMKeychainWhereKey;

Where the item was created key.

Example:

NSArray *accounts = [SAMKeychain allAccounts];
for (NSDictionary *account in accounts) {
    NSString *where = account[kSAMKeychainWhereKey];
}

Error Codes

SAMKeychainErrorCode

Error codes specific to SAMKeychain that can be returned in NSError objects.

typedef NS_ENUM(OSStatus, SAMKeychainErrorCode) {
    SAMKeychainErrorBadArguments = -1001,
};

SAMKeychainErrorBadArguments

Some of the arguments were invalid.

Example:

NSError *error = nil;
BOOL success = [SAMKeychain setPassword:@"password" 
                             forService:nil 
                                account:@"[e-mail]" 
                                  error:&error];
if (error && error.code == SAMKeychainErrorBadArguments) {
    NSLog(@"Invalid arguments provided");
}

For error codes returned by the operating system, refer to SecBase.h for your platform.