mr_keychain 0.1.0

data/.document

@@ -0,0 +1,6 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt
+README.markdown

data/.rspec

@@ -0,0 +1 @@
+--color

data/.rvmrc

@@ -0,0 +1,2 @@
+rvm use macruby-nightly@keychain --create
+

data/.yardopts

@@ -0,0 +1,4 @@
+--protected
+--private
+--no-cache
+--markup markdown

data/Gemfile

@@ -0,0 +1,10 @@
+source "http://rubygems.org"
+
+group :development do
+  gem "rspec", "~> 2.4.0"
+  gem "yard", "~> 0.6.0"
+  gem "bluecloth", "~> 2.0.0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+  gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,32 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    bluecloth (2.0.9)
+    diff-lcs (1.1.2)
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.8.7)
+    rcov (0.9.9)
+    rspec (2.4.0)
+      rspec-core (~> 2.4.0)
+      rspec-expectations (~> 2.4.0)
+      rspec-mocks (~> 2.4.0)
+    rspec-core (2.4.0)
+    rspec-expectations (2.4.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.4.0)
+    yard (0.6.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bluecloth (~> 2.0.0)
+  bundler (~> 1.0.0)
+  jeweler (~> 1.5.2)
+  rcov
+  rspec (~> 2.4.0)
+  yard (~> 0.6.0)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Mark Rada
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,67 @@
+Keychain
+========
+
+A simple class for working with the Mac OS X keychain.
+
+Reference
+=========
+
+To learn more about using the Keychain on OS X, see Apple's [Keychain Services Programming Guide](http://developer.apple.com/library/ios/#documentation/Security/Conceptual/keychainServConcepts/01introduction/introduction.html) and the [Keychain Services Reference](http://developer.apple.com/library/mac/#documentation/Security/Reference/keychainservices/Reference/reference.html).
+
+Tips
+====
+
+* You need to be careful about what key-value pairs you have stored in an item's attributes, they can sometimes mess up searches or cause unexpected failures when saving/updating a keychain item.
+
+Example Usage
+=============
+
+        # get an item
+        item = Keychain::Item.new
+
+        # add some search criteria, you need at least one, options are listed
+        # in the keychain services reference 'Attribute Item Keys and Values'
+        # section (link above)
+        item.attributes.merge!({
+                KSecAttrProtocol => KSecAttrProtocolHTTPS,
+                KSecAttrServer   => 'github.com'
+        })
+
+        # work with the entry if it exists
+        if item.exists?
+
+           # cache all the metadata and print the account name (user name)
+           puts item.metadata![KSecAttrAccount]
+
+           # print the password (needs authorization)
+           puts item.password
+
+           # change the password and check it (BE CAREFUL)
+           puts item.password = 'test'
+
+           # change the user name and save to the keychain
+           # note how you do not need authorization to change the user name
+           item.update!({ KSecAttrAccount => 'test' })
+           puts item.metadata[KSecAttrAccount]
+
+        else
+           puts 'No such item exists, maybe you need different criteria?'
+        end
+
+Contributing to keychain
+========================
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+Copyright
+=========
+
+Copyright (c) 2011 Mark Rada. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  gem.name = "mr_keychain"
+  gem.homepage = "http://github.com/ferrous26/keychain"
+  gem.license = "MIT"
+  gem.summary = %Q{Example code of how to use the Mac OS X keychain in MacRuby}
+  gem.description = %Q{Uses APIs new in Snow Leopard to create, read, and update keychain entries}
+  gem.email = "marada@uwaterloo.ca"
+  gem.authors = ["Mark Rada"]
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/mr_keychain.rb

@@ -0,0 +1,173 @@
+framework 'Foundation'
+
+# Classes, modules, methods, and constants relevant to working with the
+# Mac OS X keychain.
+module Keychain
+
+# @note Methods only need a user's explicit authorization if they want the
+#  password data, metadata does not need permission. In these cases, the OS
+#  should present an alert asking to allow, deny, or always allow the script
+#  to access. You need to be careful when using 'always allow' if you are
+#  running this code from interactive ruby or the regular interpreter because
+#  you could accidentally allow any future script to not require permission
+#  to access any password in the keychain.
+# Represents an entry in the login keychain.
+#
+# The big assumption that this class makes is that you only ever want
+# to work with a single keychain item; whether it be searching for metadata,
+# getting passwords, or adding a new entry.
+#
+# In order to be secure, this class will NEVER cache a password; any time
+# that you change a password, it will be written to the keychain immeadiately.
+
+class Item
+
+  # @return [Hash]
+  attr_accessor :attributes
+
+  # Direct access to the attributes hash of the keychain item.
+  def [] key
+    @attributes[key]
+  end
+
+  # Direct access to the attributes hash of the keychain item.
+  def []= key, value
+    @attributes[key] = value
+  end
+
+  # You should initialize objects of this class with the attributes relevant
+  # to the item you wish to work with, but you can add or remove attributes
+  # via accessors as well.
+  # @param [Hash] attributes
+  def initialize attributes = nil
+    @attributes = { KSecClass => KSecClassInternetPassword }
+    @attributes.merge! attributes if attributes
+  end
+
+  # @note This method asks only for the metadata and doesn't need authorization
+  # Returns true if there are any item matching the given attributes.
+  # @raise [KeychainException] for unexpected errors
+  # @return [true,false]
+  def exists?
+    result = Pointer.new :id
+    search = @attributes.merge({
+      KSecMatchLimit       => KSecMatchLimitOne,
+      KSecReturnAttributes => true
+    })
+
+    case (error_code = SecItemCopyMatching(search, result))
+    when ErrSecSuccess then
+      true
+    when ErrSecItemNotFound then
+      false
+    else
+      message = SecCopyErrorMessageString(error_code, nil)
+      raise KeychainException, "Error checking keychain item existence: #{message}"
+    end
+  end
+
+  # @note We ask for an NSData object here in order to get the password.
+  # Returns the password for the first match found, raises an error if
+  # no keychain item is found.
+  #
+  # Blank passwords should come back as an empty string, but that hasn't
+  # been tested.
+  # @raise [KeychainException]
+  # @return [String] UTF8 encoded password string
+  def password
+    result = Pointer.new :id
+    search = @attributes.merge({
+      KSecMatchLimit => KSecMatchLimitOne,
+      KSecReturnData => true
+    })
+
+    case (error_code = SecItemCopyMatching(search, result))
+    when ErrSecSuccess then
+      NSString.alloc.initWithData result[0], encoding:NSUTF8StringEncoding
+    else
+      message = SecCopyErrorMessageString(error_code, nil)
+      raise KeychainException, "Error getting password: #{message}"
+    end
+  end
+
+
+  # Updates the password associated with the keychain item. If the item does
+  # not exist in the keychain it will be added first.
+  # @raise [KeychainException]
+  # @param [String] new_password a UTF-8 encoded string
+  # @return [String] the saved password
+  def password= new_password
+    password_data = {
+      KSecValueData => new_password.dataUsingEncoding(NSUTF8StringEncoding)
+    }
+    if exists?
+      error_code = SecItemUpdate( @attributes, password_data )
+    else
+      error_code = SecItemAdd( @attributes.merge password_data, nil )
+    end
+
+    case error_code
+    when ErrSecSuccess then
+      password
+    else
+      message = SecCopyErrorMessageString(error_code, nil)
+      raise KeychainException, "Error updating password: #{message}"
+    end
+  end
+
+  # @todo This method does not really fit with the rest of the API.
+  # @note This method does not need authorization unless you are
+  #  updating the password.
+  # Updates attributes of the item in the keychain. If the item does not
+  # exist yet then this method will raise an exception.
+  #
+  # Use a value of nil to remove an attribute.
+  # @param [Hash] new_attributes the attributes that you want to update
+  # @return [Hash] attributes
+  def update! new_attributes
+    result = Pointer.new :id
+    query  = @attributes.merge({ KSecMatchLimit => KSecMatchLimitOne })
+
+    case (error_code = SecItemUpdate(query, new_attributes))
+    when ErrSecSuccess then
+      metadata!
+    else
+      message = SecCopyErrorMessageString(error_code, nil)
+      raise KeychainException, "Error updating keychain item: #{message}"
+    end
+  end
+
+  # Get all the metadata about a keychain item, they will be keyed
+  # according Apple's documentation.
+  # @raise [KeychainException]
+  # @return [Hash]
+  def metadata
+    result = Pointer.new :id
+    search = @attributes.merge({
+      KSecMatchLimit       => KSecMatchLimitOne,
+      KSecReturnAttributes => true
+    })
+
+    case (error_code = SecItemCopyMatching(search, result))
+    when ErrSecSuccess then
+      result[0]
+    else
+      message = SecCopyErrorMessageString(error_code, nil)
+      raise KeychainException, "Error getting metadata: #{message}"
+    end
+  end
+
+  # Update attributes to include all the metadata from the keychain.
+  # @raise [KeychainException]
+  # @return [Hash]
+  def metadata!
+    @attributes = metadata
+  end
+end
+
+# A trivial exception class that exists to help differentiate where
+# exceptions are being raised.
+class KeychainException < Exception
+end
+
+end

data/spec/keychain_spec.rb

@@ -0,0 +1,227 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+# @todo get the spec tests to use mock data
+describe 'Keychain' do
+
+  describe 'Item' do
+
+    before do
+      @item = Keychain::Item.new
+    end
+
+
+    describe 'attributes attribute' do
+      it 'is readable' do
+        @item.respond_to?(:attributes).should == true
+      end
+
+      it 'is writable' do
+        @item.respond_to?(:attributes=).should == true
+      end
+
+      it 'should be initialized with the class being set' do
+        @item.attributes[KSecClass].should_not == nil
+      end
+
+      it 'should be initialized to be of the interenet class' do
+        @item.attributes[KSecClass].should == KSecClassInternetPassword
+      end
+
+      it 'should allow the class to be overriden' do
+        @item = Keychain::Item.new({ KSecClass => 'different' })
+        @item.attributes[KSecClass].should == 'different'
+      end
+    end
+
+
+    describe '#exists?' do
+      it 'returns false if the item does not exist' do
+        @item.attributes.merge!({
+          KSecAttrProtocol => KSecAttrProtocolIRCS,
+          KSecAttrServer   => 'github.com'
+        })
+        @item.exists?.should == false
+      end
+
+      it 'returns true if the item exists' do
+        @item.attributes.merge!({
+          KSecAttrProtocol => KSecAttrProtocolHTTPS,
+          KSecAttrServer   => 'github.com'
+        })
+        @item.exists?.should == true
+      end
+
+      it 'raises an exception for unexpected error codes' do
+        @item.attributes[KSecClass] = 'made up class'
+        expect { @item.exists? }.to raise_exception(Keychain::KeychainException)
+      end
+    end
+
+
+    describe '#password' do
+      it 'should return a string with the password' do
+        @item.attributes.merge!({
+          KSecAttrProtocol => KSecAttrProtocolHTTPS,
+          KSecAttrServer   => 'github.com'
+        })
+        @item.password.class.should == String
+      end
+
+      it 'should raise an exception if no password is found' do
+        @item.attributes.merge!({
+          KSecAttrProtocol => KSecAttrProtocolIRCS,
+          KSecAttrServer   => 'github.com'
+        })
+        expect { @item.password }.to raise_exception(Keychain::KeychainException)
+      end
+    end
+
+
+    describe '#metadata' do
+      it 'should return a hash' do
+        @item.attributes.merge!({
+          KSecAttrProtocol => KSecAttrProtocolHTTPS,
+          KSecAttrServer   => 'github.com'
+        })
+        @item.metadata.class.should == Hash
+      end
+
+      it 'should raise an exception if nothing is found' do
+        @item.attributes.merge!({
+          KSecAttrProtocol => KSecAttrProtocolIRCS,
+          KSecAttrServer   => 'github.com'
+        })
+        expect { @item.metadata }.to raise_exception(Keychain::KeychainException)
+      end
+
+      # this assumes the keychain item has more metadata
+      it 'should not overwrite @attributes' do
+        @item.attributes.merge!({
+          KSecAttrProtocol => KSecAttrProtocolHTTPS,
+          KSecAttrServer   => 'github.com'
+        })
+        metadata = @item.metadata
+        @item.attributes.should_not == metadata
+      end
+    end
+
+
+    describe '#metadata!' do
+      it 'should return a hash' do
+        @item.attributes.merge!({
+          KSecAttrProtocol => KSecAttrProtocolHTTPS,
+          KSecAttrServer   => 'github.com'
+        })
+        @item.metadata.class.should == Hash
+      end
+
+      it 'should raise an exception if nothing is found' do
+        @item.attributes.merge!({
+          KSecAttrProtocol => KSecAttrProtocolIRCS,
+          KSecAttrServer   => 'github.com'
+        })
+        expect { @item.metadata }.to raise_exception(Keychain::KeychainException)
+      end
+
+      # this assumes the keychain item has more metadata
+      it 'should overwrite @attributes' do
+        @item.attributes.merge!({
+          KSecAttrProtocol => KSecAttrProtocolHTTPS,
+          KSecAttrServer   => 'github.com'
+        })
+        metadata = @item.metadata!
+        @item.attributes.should == metadata
+      end
+    end
+
+
+    describe '#[]' do
+      it 'should be equivalent to #attributes' do
+        @item.attributes[:test] = 'test'
+        @item[:test].should == 'test'
+        @item[KSecClass].should == @item.attributes[KSecClass]
+      end
+    end
+
+
+    describe '#[]=' do
+      it 'should be equivalent to #attributes=' do
+        @item[:test] = 'test'
+        @item.attributes[:test].should == 'test'
+      end
+    end
+
+
+    # describe '#password=' do
+    #   before do
+    #     @item.attributes.merge!({
+    #       KSecAttrProtocol => KSecAttrProtocolHTTPS,
+    #       KSecAttrServer   => 'github.com'
+    #     })
+    #   end
+
+    #   it 'should return the updated password' do
+    #     (@item.password = 'new password').should == 'new password'
+    #   end
+
+    #   it 'should update the password in the keychain' do
+    #     (@item.password = 'new password').should == @item.password
+    #   end
+
+    #   it 'should create entries if they do not exsit' do
+    #     @item.attributes.merge!({
+    #       KSecAttrAccount  => 'test'
+    #     })
+    #     @item.password = 'another test'
+    #     @item.exists?.should == true
+    #   end
+
+    #   after do
+    #     NSLog('I created an entry in your keychain that you should clean up')
+    #   end
+    # end
+
+
+    describe '#update!' do
+      it 'should update fields given in the persistent keychain' do
+        @item.attributes.merge!({
+          KSecAttrProtocol => KSecAttrProtocolHTTPS,
+          KSecAttrServer   => 'github.com'
+        })
+        @item.update!({ KSecAttrComment => 'test' })
+        @item.metadata[KSecAttrComment].should == 'test'
+      end
+
+      it 'should raise an exception for non-existant items' do
+        @item.attributes.merge!({
+          KSecAttrProtocol => KSecAttrProtocolIRCS,
+          KSecAttrServer   => 'github.com'
+        })
+        expect {
+          @item.update!({ KSecAttrComment => 'different test' })
+        }.to raise_exception(Keychain::KeychainException)
+      end
+
+      it 'should update @attributes' do
+        @item.attributes.merge!({
+          KSecAttrProtocol => KSecAttrProtocolHTTPS,
+          KSecAttrServer   => 'github.com'
+        })
+        @item.update!({ KSecAttrComment => 'toast' })
+        @item.attributes[KSecAttrComment].should == 'toast'
+      end
+
+      it 'should return the metadata of the keychain item' do
+        @item.attributes.merge!({
+          KSecAttrProtocol => KSecAttrProtocolHTTPS,
+          KSecAttrServer   => 'github.com'
+        })
+        @item.update!({
+                        KSecAttrComment => 'bread'
+                      })[KSecAttrComment].should == 'bread'
+      end
+    end
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rspec'
+require 'mr_keychain'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  
+end

metadata

@@ -0,0 +1,166 @@
+--- !ruby/object:Gem::Specification 
+name: mr_keychain
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Mark Rada
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-05 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 4
+        - 0
+        version: 2.4.0
+  type: :development
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: yard
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 6
+        - 0
+        version: 0.6.0
+  type: :development
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: bluecloth
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 0
+        - 0
+        version: 2.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 5
+        - 2
+        version: 1.5.2
+  type: :development
+  prerelease: false
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id006
+description: Uses APIs new in Snow Leopard to create, read, and update keychain entries
+email: marada@uwaterloo.ca
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.markdown
+files: 
+- .document
+- .rspec
+- .rvmrc
+- .yardopts
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.markdown
+- Rakefile
+- VERSION
+- lib/mr_keychain.rb
+- spec/keychain_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/ferrous26/keychain
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -1899776903697949187
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Example code of how to use the Mac OS X keychain in MacRuby
+test_files: 
+- spec/keychain_spec.rb
+- spec/spec_helper.rb