Module: Keychain

Defined in:
lib/mr_keychain.rb,
lib/mr_keychain/item.rb,
lib/mr_keychain/version.rb,
lib/mr_keychain/keychain.rb,
lib/mr_keychain/keychain_exception.rb

Overview

Classes, modules, methods, and constants relevant to working with the Mac OS X keychain.

Defined Under Namespace

Classes: Item, KeychainException

Constant Summary

VERSION = 
'0.1.1'

Class Method Summary (collapse)

Class Method Details

+ (Object) create_search_dict(override, enforce, user, return_type) (private) 



107
108
109
110
111
112
113
 
# File 'lib/mr_keychain/keychain.rb', line 107

def create_search_dict override, enforce, user, return_type
  dict = override.merge(user).merge(enforce)
  for key in [KSecReturnAttributes, KSecReturnData, KSecReturnRef, KSecReturnPersistentRef]
    dict.delete key
  end
  dict.merge!( return_type => true )
end

+ (Keychain::Item?) item(search_dict)

Note:

This method asks only for the metadata and should never need user authorization.

Returns a Item if an item is found, otherwise returns nil.

The hash argument for this method is constructed exactly the same as with item_exists?, with the same default values given.

Parameters:

  • search_dict (Hash)

Returns:

Raises:



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/mr_keychain/keychain.rb', line 55

def item search_dict
  dict = create_search_dict( { KSecClass => KSecClassInternetPassword },
                             { KSecMatchLimit => KSecMatchLimitOne },
                             search_dict,
                             KSecReturnAttributes )

  result = Pointer.new(:id)
  error_code = SecItemCopyMatching( dict, result )

  case error_code
  when ErrSecSuccess      then Item.new(result[0])
  when ErrSecItemNotFound then nil
  else
    raise KeychainException.new( 'Looking up item', error_code )
  end
end

+ (Boolean) item_exists?(search_dict)

Note:

This method asks only for the metadata and should never need user authorization.

Returns true if there is at least one item matching the given attributes and search parameters.

This method provides a default class, and enforces a return type and match limit; the default key/value pairs:

  • KSecClass => KSecClassInternetPassword
  • KSecMatchLimit => KSecMatchLimitOne
  • KSecReturnAttributes => true

The class can be overridden, but the match limit and return type cannot. You can add as many attributes and/or search parameters as you like, they are listed under "Attribute Item Keys and Values" or "Search Keys" in Apple's documentation.

Parameters:

  • search_dict (Hash)

Returns:

  • (Boolean)

Raises:



26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/mr_keychain/keychain.rb', line 26

def item_exists? search_dict
  dict = create_search_dict( { KSecClass => KSecClassInternetPassword },
                             { KSecMatchLimit => KSecMatchLimitOne },
                             search_dict,
                             KSecReturnAttributes )

  result     = Pointer.new(:id)
  error_code = SecItemCopyMatching( dict, result )

  case error_code
  when ErrSecSuccess      then true
  when ErrSecItemNotFound then false
  else
    raise KeychainException.new( 'Checking item existence', error_code )
  end
end

+ (Array<Keychain::Item>) items(search_dict)

Note:

This method asks only for the metadata and should never need user authorization.

Returns an array Item objects, possibly empty.

The hash argument for this method is constructed exactly the same as with item_exists?, the only default key/value pair that is:

  • KSecMatchLimit => KSecMatchLimitAll

Parameters:

  • search_dict (Hash)

Returns:

Raises:



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/mr_keychain/keychain.rb', line 87

def items search_dict
  dict = create_search_dict( { KSecClass => KSecClassInternetPassword },
                             { KSecMatchLimit => KSecMatchLimitAll },
                             search_dict,
                             KSecReturnAttributes )

  result = Pointer.new(:id)
  error_code = SecItemCopyMatching( dict, result )

  case error_code
  when ErrSecSuccess      then result[0].map { |item| Item.new(item) }
  when ErrSecItemNotFound then []
  else
    raise KeychainException.new( 'Looking up item', error_code )
  end
end