ruby-keychain 0.1.0

data/LICENSE

@@ -0,0 +1,8 @@
+The MIT License
+Copyright (c) 2012 Frederick Cheung
+
+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

@@ -0,0 +1,90 @@
+A set of ruby bindings for the OS X keychain, written using ffi
+
+Introduction
+============
+
+The keychain is OS X's secure credential storage mechanism. This library allows access to internet passwords (typically specified as a combination of host, protocol, account (optionally port)) and generic passwords (identified by a service and account).
+
+
+Working with keychains
+==================
+
+Most operations will act on either the default keychain, or the default keychain search list. You can obtain specific keychains with
+
+    Keychain.default #the default keychain, usually /Users/<username>/Library/Keychains/<username>.keychain
+    Keychain.open(path) #opens a keychain file
+    Keychain.create(path, password) #creates a new keychain at the specified path
+
+
+
+Searching for Keychain Items
+=========
+
+The top level constant `Keychain` as well as individual keychain objects have two methods `internet_passwords` and `generic_passwords` that return scope like objects. You can do
+
+    Keychain.internet_passwords.where(:server => 'example.com').all
+
+to return Keychain::Item objects for that server
+
+    Keychain.internet_passwords.where(:server => 'example.com').first
+
+to return the first Keychain::Item for that server or
+
+    Keychain.internet_passwords.where(:server => 'example.com').limit(4).all
+
+to return up to 4 Keychain::Item for that server.
+
+`generic_passwords` behaves similarly but searches the keychain for genereric passwords
+
+You can restrict the search to a specific keychain with
+
+    some_keychain.internet_passwords.where(:server => 'example.com').all
+
+returns matching `Keychain::Item` from the specified keychain.
+
+or to an arbitrary list of keychains with
+
+    Keychain.internet_passwords.in(keychain_1, keychain2).all
+
+
+Finding a Keychain::Item won't prompt the user for a password if the keychain is unlocked. Calling the password accessor method of the item may prompt the user for their password depending on the keychain item access settings.
+
+If you call `where` multiple times, each successive invocation merges its conditions with the previous set of conditions
+
+
+Creating keychain items
+=========================
+
+In the default keychain:
+
+    Keychain.internet_passwords.create(:server => 'example.com', :protocol => Keychain::Protocols::HTTP, :password => 'secret', :account => 'bob')
+
+    or
+
+    Keychain.generic_passwords.create(:service => 'AWS', :password => 'secret', :account => 'bob')
+
+In a specific keychain
+
+    some_keychain.internet_passwords.create(...)
+
+by default keychain items are only readable by the application that created them, however when running a ruby script the application is ruby: by default other ruby scripts will be able to read the items (if the keychain is unlocked).
+
+Using keychain items
+=====================
+
+The `Keychain::Item` class has accessors for all its attributes, for the full list of attributes see `Sec::ATTR_MAP`
+
+All strings returned are utf-8 encoded. Be careful not to set attribute values to strings with the ASCII_8BIT encoding as this will cause them to be treated as raw data rather than string. The exception to this is password data which the keychain api defines as being arbitrary binary data. When storing an actual password it is customary to use utf-8. The password data will always be returned as raw binary data
+
+
+Error Handling
+==============
+
+Failed operations will result in `Keychain::Error` being raised. The original error code is available as the `code` attribute of the exception. When attempting to insert a duplicate item, `Keychain::DuplicateItemError` (a subclass of `Keychain::Error`) is raised instead
+
+
+Compatibility
+=============
+Requires ruby 1.9 due to use of encoding related methods. Should work in MRI and jruby. Not compatible with rubinius due to rubinius' ffi implemenation
+not supporting certain features
+

data/lib/keychain.rb

@@ -0,0 +1,72 @@
+require 'ffi'
+require 'corefoundation'
+require 'keychain/sec'
+require 'keychain/keychain'
+require 'keychain/error'
+require 'keychain/item'
+require 'keychain/scope'
+require 'keychain/protocols'
+# top level constant for this library
+module Keychain
+  class << self
+    # creates a new keychain file and adds it to the keychain search path ( SecKeychainCreate )
+    #
+    # See https://developer.apple.com/library/mac/documentation/security/Reference/keychainservices/Reference/reference.html#//apple_ref/c/func/SecKeychainCreate
+    # @param [String] path The path to the keychain file to create
+    #   If it is not absolute it is interpreted relative to ~/Library/Keychains
+    # @param [String] password The password to use for the keychain
+    # @return [Keychain::Keychain] a keychain object representing the newly created keychain
+
+    def create(path, password)
+      password = password.encode(Encoding::UTF_8)
+      path = path.encode(Encoding::UTF_8)
+
+      out_buffer = FFI::MemoryPointer.new(:pointer)
+      status = Sec.SecKeychainCreate(path, password.bytesize, FFI::MemoryPointer.from_string(password), 0,
+                                          nil, out_buffer)
+
+      Sec.check_osstatus(status)
+      Keychain.new(out_buffer.read_pointer).release_on_gc
+    end
+
+    # Gets the default keychain object ( SecKeychainCopyDefault )
+    #
+    # See https://developer.apple.com/library/mac/documentation/security/Reference/keychainservices/Reference/reference.html#//apple_ref/c/func/SecKeychainCopyDefault
+    # @return [Keychain::Keychain] a keychain object
+    def default
+      out_buffer = FFI::MemoryPointer.new(:pointer)
+      status = Sec.SecKeychainCopyDefault(out_buffer);
+      Sec.check_osstatus(status)
+
+      Keychain.new(out_buffer.read_pointer).release_on_gc
+    end
+
+    # Opens the keychain file at the specified path and adds it to the keychain search path ( SecKeychainOpen )
+    #
+    # Will succeed even if the file doesn't exists (however most operations on the keychain will then fail)
+    #
+    # See https://developer.apple.com/library/mac/documentation/security/Reference/keychainservices/Reference/reference.html#//apple_ref/c/func/SecKeychainCopyDefault
+    # @param [String] path Path to the keychain file
+    # @return [Keychain::Keychain] a keychain object
+    def open(path)
+      out_buffer = FFI::MemoryPointer.new(:pointer)
+      status = Sec.SecKeychainOpen(path,out_buffer);
+      Sec.check_osstatus(status)
+      Keychain.new(out_buffer.read_pointer).release_on_gc
+    end
+
+    # Returns a scope for internet passwords contained in all keychains
+    #
+    # @return [Keychain::Scope] a new scope object
+    def internet_passwords
+      Scope.new(Sec::Classes::INTERNET)
+    end
+
+    # Returns a scope for generic passwords in all keychains
+    #
+    # @return [Keychain::Scope] a new scope object
+    def generic_passwords
+      Scope.new(Sec::Classes::GENERIC)
+    end
+  end
+end

data/lib/keychain/error.rb

@@ -0,0 +1,34 @@
+
+module Sec
+  attach_function 'SecCopyErrorMessageString', [:osstatus, :pointer], :pointer
+end
+
+# The base class of all keychain related errors
+#
+# The original error code is available as `code`
+class Keychain::Error < StandardError
+  attr_accessor :code
+  def initialize(code)
+    self.code = code
+    description = Sec.SecCopyErrorMessageString(code, nil)
+    if description.null?
+      super("Sec Error #{code}")
+    else
+      description = CF::Base.typecast(description)
+      super("#{description.to_s} (#{code})")
+    end
+  end
+end
+
+# Raised when saving or updating an item
+# fails because an existing item is already in the keychain
+class Keychain::DuplicateItemError < Keychain::Error; end
+# Raised when an operation that requires a password fails,
+# for example unlocking a keychain
+class Keychain::AuthFailedError < Keychain::Error; end
+# Raised when an action that requires user interaction 
+# (such as decrypting as password) is cancelled by the user
+class Keychain::UserCancelledError < Keychain::Error; end
+# Raised when an action fails because the underlying keychain
+# does not exist
+class Keychain::NoSuchKeychainError < Keychain::Error; end

data/lib/keychain/item.rb

@@ -0,0 +1,188 @@
+
+module Sec
+  attach_function 'SecKeychainItemDelete', [:pointer], :osstatus
+  attach_function 'SecItemAdd', [:pointer, :pointer], :osstatus
+  attach_function 'SecItemUpdate', [:pointer, :pointer], :osstatus
+  attach_function 'SecKeychainItemCopyKeychain', [:pointer, :pointer], :osstatus
+
+end
+
+# An individual item from the keychain. Individual accessors are generated for the items attributes
+#
+#
+class Keychain::Item < Sec::Base
+  attr_accessor :attributes
+  register_type 'SecKeychainItem'
+
+  # returns a programmer friendly description of the item
+  # @return [String]
+  def inspect
+    "<SecKeychainItem 0x#{@ptr.address.to_s(16)} #{service ? "service: #{service}" : "server: #{server}"} account: #{account}>"
+  end
+
+  Sec::ATTR_MAP.values.each do |ruby_name|
+    unless method_defined?(ruby_name)
+      define_method ruby_name do
+        @attributes[ruby_name]
+      end
+      define_method ruby_name.to_s+'=' do |value|
+        @attributes[ruby_name] = value
+      end
+    end
+  end
+
+  # Creates a new keychain item either from an FFI::Pointer or a hash of attributes
+  #
+  # @param [FFI::Pointer, Hash] attrs_or_pointer Either an FFI::Pointer to an existing 
+  #   SecKeychainItemRef to wrap or hash of attributes to create a new, unsaved Keychain::Item from
+  #   see {Keychain::Scope#create}
+  #  
+  def self.new(attrs_or_pointer)
+    if attrs_or_pointer.is_a? Hash
+      super(0).tap do |result|
+        attrs_or_pointer.each {|k,v| result.send("#{k}=", v)}
+      end
+    else
+      super
+    end
+  end
+
+  # @private
+  def initialize(*args)
+    super
+    @attributes = {}
+  end
+
+  # Removes the item from the associated keychain
+  #
+  def delete
+    status = Sec.SecKeychainItemDelete(self)
+    Sec.check_osstatus(status)
+    self
+  end
+
+  # Set a new password for the item
+  # @note The new password is not saved into the keychain until you call {Keychain::Item#save!}
+  # @param [String] value The new value for the password
+  # @return [String] The set value
+  def password=(value)
+    @unsaved_password = value
+  end
+
+  # Returns the keychain the item is in
+  #
+  # @return [Keychain::Keychain]
+  def keychain
+    out = FFI::MemoryPointer.new :pointer
+    status = Sec.SecKeychainItemCopyKeychain(self,out)
+    Sec.check_osstatus(status)
+    CF::Base.new(out.read_pointer).release_on_gc
+  end
+
+  # Fetches the password data associated with the item. This may cause the user to be asked for access
+  # @return [String] The password data, an ASCII_8BIT encoded string
+  def password
+    return @unsaved_password if @unsaved_password
+    out_buffer = FFI::MemoryPointer.new(:pointer)
+    status = Sec.SecItemCopyMatching({Sec::Query::ITEM_LIST => CF::Array.immutable([self]),
+                             Sec::Query::CLASS => klass, 
+                             Sec::Query::RETURN_DATA => true}.to_cf, out_buffer)
+    Sec.check_osstatus(status)
+    CF::Base.typecast(out_buffer.read_pointer).to_s
+  end
+
+  # Attempts to update the keychain with any changes made to the item
+  # or saves a previously unpersisted item
+  # @param [optional, Hash] options extra options when saving the item
+  # @option options [Keychain::Keychain] :keychain when saving an unsaved item, they keychain to save it in
+  # @return [Keychain::Item] returns the item
+  def save!(options={})
+    if persisted?
+      cf_dict = update
+    else
+      cf_dict = create(options)
+    end    
+    @unsaved_password = nil
+    update_self_from_dictionary(cf_dict)
+    cf_dict.release
+    self
+  end
+
+  # @private
+  def self.from_dictionary_of_attributes(cf_dict)
+    new(0).tap {|item| item.send :update_self_from_dictionary, cf_dict}
+  end
+
+  # Whether the item has been persisted to the keychain
+  # @return [Boolean]
+  def persisted?
+    !@ptr.null?
+  end
+
+  private
+
+  def create(options)
+    result = FFI::MemoryPointer.new :pointer
+    query = build_create_query(options)
+    query.merge!(build_new_attributes)
+    status = Sec.SecItemAdd(query, result);
+    Sec.check_osstatus(status)
+    cf_dict = CF::Base.typecast(result.read_pointer)
+  end
+
+  def update
+    status = Sec.SecItemUpdate({Sec::Query::ITEM_LIST => [self], Sec::INVERSE_ATTR_MAP[:klass] => klass}.to_cf, build_new_attributes);
+    Sec.check_osstatus(status)
+
+    result = FFI::MemoryPointer.new :pointer
+    query = build_refresh_query
+    status = Sec.SecItemCopyMatching(query, result);
+    Sec.check_osstatus(status)
+    cf_dict = CF::Base.typecast(result.read_pointer)
+  end
+    
+
+
+  def update_self_from_dictionary(cf_dict)
+    if !persisted?
+      self.ptr = cf_dict[Sec::Value::REF].to_ptr
+      self.retain.release_on_gc
+    end
+    @attributes = cf_dict.inject({}) do |memo, (k,v)|
+      if ruby_name = Sec::ATTR_MAP[k]
+        memo[ruby_name] = v.to_ruby
+      end
+      memo
+    end
+  end
+
+  def build_create_query options
+    query = CF::Dictionary.mutable
+    query[Sec::Value::DATA] = CF::Data.from_string(@unsaved_password) if @unsaved_password
+    query[Sec::Query::KEYCHAIN] = options[:keychain] if options[:keychain] 
+    query[Sec::Query::RETURN_ATTRIBUTES] = CF::Boolean::TRUE
+    query[Sec::Query::RETURN_REF] = CF::Boolean::TRUE
+    query
+  end
+
+  def build_refresh_query
+    query = CF::Dictionary.mutable
+    query[Sec::Query::ITEM_LIST] = CF::Array.immutable([self])
+    query[Sec::Query::RETURN_ATTRIBUTES] = CF::Boolean::TRUE
+    query[Sec::Query::RETURN_REF] = CF::Boolean::TRUE
+    query[Sec::INVERSE_ATTR_MAP[:klass]] = klass.to_cf
+    query
+  end
+
+  def build_new_attributes
+    new_attributes = CF::Dictionary.mutable
+    @attributes.each do |k,v|
+      next if k == :created_at || k == :updated_at
+      next if k == :klass && persisted?
+      k = Sec::INVERSE_ATTR_MAP[k]
+      new_attributes[k] = v.to_cf
+    end
+    new_attributes[Sec::Value::DATA] = CF::Data.from_string(@unsaved_password) if @unsaved_password
+    new_attributes
+  end
+end

data/lib/keychain/keychain.rb

@@ -0,0 +1,188 @@
+
+module Sec
+  attach_function 'SecKeychainCopyDefault', [:pointer], :osstatus
+  attach_function 'SecKeychainDelete', [:keychainref], :osstatus
+  attach_function 'SecKeychainOpen', [:string, :pointer], :osstatus
+  attach_function 'SecKeychainGetPath', [:keychainref, :pointer, :pointer], :osstatus
+
+  attach_function 'SecKeychainCreate', [:string, :uint32, :pointer, :char, :pointer, :pointer], :osstatus
+  attach_function 'SecItemCopyMatching', [:pointer, :pointer], :osstatus
+  
+  #@private
+  class KeychainSettings < FFI::Struct
+    layout  :version, :uint32,
+            :lock_on_sleep, :uchar,
+            :use_lock_interval, :uchar, #apple ignores this
+            :lock_interval, :uint32
+  end
+
+  attach_function 'SecKeychainSetSettings', [:keychainref, KeychainSettings], :osstatus
+  attach_function 'SecKeychainCopySettings', [:keychainref, KeychainSettings], :osstatus
+
+  attach_function 'SecKeychainLock', [:keychainref], :osstatus
+  attach_function 'SecKeychainUnlock', [:keychainref, :uint32, :pointer, :uchar], :osstatus
+
+  attach_function 'SecKeychainGetStatus', [:keychainref, :pointer], :osstatus
+
+  enum :keychainStatus, [
+    :kSecUnlockStateStatus, 1,
+    :kSecReadPermStatus,    2,
+    :kSecWritePermStatus,   4,
+  ]
+end
+
+module Keychain
+  # Wrapper class for individual keychains. Corresponds to a SecKeychainRef
+  #
+  class Keychain < Sec::Base
+    register_type 'SecKeychain'
+
+    # Returns whether the keychain will be locked if the machine goes to sleep
+    #
+    # @return [Boolean]
+    #
+    def lock_on_sleep?
+      get_settings[:lock_on_sleep] != 0
+    end
+
+    # Returns the duration (in seconds) after which the keychain will be locked
+    #
+    # @return [Boolean]
+    #
+    def lock_interval
+      get_settings[:lock_interval]
+    end
+
+    # Set whether the keychain will be locked if the machine goes to sleep
+    #
+    # @param [Boolean] value
+    #
+    def lock_on_sleep= value
+      put_settings(get_settings.tap {|s| s[:lock_on_sleep] = value ? 1 : 0})
+    end
+
+    # Sets the duration (in seconds) after which the keychain will be locked
+    #
+    # @param [Integer] value dutarion in seconds
+    #
+    def lock_interval= value
+      put_settings(get_settings.tap {|s| s[:lock_interval] = value})
+    end
+
+    # Returns a scope for internet passwords contained in this keychain
+    #
+    # @return [Keychain::Scope] a new scope object
+    def internet_passwords
+      Scope.new(Sec::Classes::INTERNET, self)
+    end
+
+    # Returns a scope for generic passwords contained in this keychain
+    #
+    # @return [Keychain::Scope] a new scope object
+    def generic_passwords
+      Scope.new(Sec::Classes::GENERIC, self)
+    end
+
+    # returns a description of the keychain
+    # @return [String]
+    def inspect
+      "<SecKeychain 0x#{@ptr.address.to_s(16)}: #{path}>"
+    end
+
+    # Removes the keychain from the search path and deletes the corresponding file (SecKeychainDelete)
+    #
+    # See https://developer.apple.com/library/mac/documentation/security/Reference/keychainservices/Reference/reference.html#//apple_ref/c/func/SecKeychainDelete
+    # @return self
+    def delete
+      status = Sec.SecKeychainDelete(self)
+      Sec.check_osstatus(status)
+      self
+    end
+
+    # Returns the path at which the keychain is stored
+    #
+    # See https://developer.apple.com/library/mac/documentation/security/Reference/keychainservices/Reference/reference.html#//apple_ref/c/func/SecKeychainGetPath
+    #
+    # @return [String] path to the keychain file
+    def path
+      out_buffer = FFI::MemoryPointer.new(:uchar, 2048)
+      io_size = FFI::MemoryPointer.new(:uint32)
+      io_size.put_uint32(0, out_buffer.size)
+
+      status = Sec.SecKeychainGetPath(self,io_size, out_buffer)
+      Sec.check_osstatus(status)
+
+      out_buffer.read_string(io_size.get_uint32(0)).force_encoding(Encoding::UTF_8)
+    end
+
+    # Locks the keychain
+    #
+    def lock!
+      status = Sec.SecKeychainLock(self)
+      Sec.check_osstatus status
+    end
+
+    # Unlocks the keychain
+    #
+    # @param [optional, String] password the password to unlock the keychain with. If no password is supplied the keychain will prompt the user for a password
+    def unlock! password=nil
+      if password
+        password = password.encode(Encoding::UTF_8)
+        status = Sec.SecKeychainUnlock self, password.bytesize, password, 1
+      else
+        status = Sec.SecKeychainUnlock self, 0, nil, 0
+      end
+      Sec.check_osstatus status
+    end 
+
+    # Returns whether the keychain is locked
+    # @return [Boolean]
+    def locked?
+      !status_flag?(:kSecUnlockStateStatus)
+    end
+
+    # Returns whether the keychain is readable
+    # @return [Boolean]
+    def readable?
+      status_flag?(:kSecReadPermStatus)
+    end
+
+    # Returns whether the keychain is writable
+    # @return [Boolean]
+    def writeable?
+      status_flag?(:kSecWritePermStatus)
+    end
+       
+    def exists?
+      begin
+        readable?
+        true
+      rescue NoSuchKeychainError
+        false
+      end
+    end
+
+    private
+
+    def status_flag? enum_name
+      out = FFI::MemoryPointer.new(:uint32)
+      status = Sec.SecKeychainGetStatus(self,out);
+      Sec.check_osstatus status
+      (out.get_uint32(0) & Sec.enum_value(enum_name)).nonzero?
+    end
+      
+    def get_settings
+      settings = Sec::KeychainSettings.new
+      settings[:version] = 1
+      status = Sec.SecKeychainCopySettings(self, settings)
+      Sec.check_osstatus status
+      settings
+    end
+
+    def put_settings settings
+      status = Sec.SecKeychainSetSettings(self, settings)
+      Sec.check_osstatus status
+      settings
+    end
+  end
+end