kerberos_authenticator 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d21f1ea20049f7cc581df957b1b2e738b4578cab
-  data.tar.gz: 74504aa9db7035a3935f346c2563b3ccfda586d2
+  metadata.gz: f345054a20a13a084ee6979f3f32d62a4ba2e898
+  data.tar.gz: b0909f23de117867bf9806ef63b39b3bee1e5d24
 SHA512:
-  metadata.gz: ec9e7e068cfb22395aab8865f03f8060bee9f1e5f66196518435963f13100d7953dc9013c6dd76dd9f349f6a994eba444baea344655dc3699e2c8f4717c0a666
-  data.tar.gz: 6a784a3b02dac99f4638d23da612918c89116eb55b79b88074176a99edeb826a523d5c0eb041ab1421227677743970fc0932708dabe052751cf49eaf6ef54ea8
+  metadata.gz: 624582a12b02a838f4e8d5d29f230dc6a76904e35fbbbefd4cee22e76fa1b237f54f41e35d588235717125aa4af44b964363593cb2d72850bc083c671a4f95ee
+  data.tar.gz: b7045094f0fab8ab6087c191b63288a27a9e4229206b32441444a481ea8662aece5074671a6f5e872730cea2806d2b86f483e31f8fc9cfec47dca4293a1d8df1

data/lib/kerberos_authenticator.rb

@@ -6,7 +6,6 @@ require 'kerberos_authenticator/error'
 require 'kerberos_authenticator/krb5'
 
 module KerberosAuthenticator
-
   # A convenience method to access the Krb5 module when using the setup method.
   # @return [Krb5]
   def self.krb5
@@ -37,6 +36,14 @@ module KerberosAuthenticator
     true
   end
 
+  # Change a user's password by authenticating with their current one.
+  # @raise [Error] if the attempt to change the password fails
+  # @return [TrueClass] always returns true if no error was raised
+  def self.change_password!(username, old_password, new_password)
+    user = Krb5::Principal.new_with_name(username)
+    user.change_password(old_password, new_password)
+  end
+
   # @!attribute [rw] keytab_base64
   #   @!scope class
   #   @return [String] the keytab to use when verifying the identity of the KDC represented as a Base64 encoded string (overrides keytab_path)
@@ -113,8 +120,18 @@ module KerberosAuthenticator
       kt = Krb5::Keytab.new_with_name("FILE:#{kt_tmp_file.path}")
     elsif keytab_path
       kt = Krb5::Keytab.new_with_name("FILE:#{keytab_path}")
+    else
+      kt = Krb5::Keytab.default
     end
 
+    # FIXME: This seems to protect against segfaults in OS X Kerberos as of 10.9.5
+    #   when the keytab isn't accessible or doesn't exist.
+    #   It probably indicates an underlying memory management mistake.
+    #
+    # REVIEW: It's hard to say whether calling this or leaving it out produces
+    #   better error messages.
+    kt.assert_has_content
+
     begin
       yield kt
     ensure

data/lib/kerberos_authenticator/krb5.rb

@@ -8,7 +8,7 @@ module KerberosAuthenticator
 
     # Version suffixes of the library to search for, in order:
     # - .3: MIT as of Debian 8, RHEL 7
-    # - .26: Heimdal as of Debian 8, RHEL 7 
+    # - .26: Heimdal as of Debian 8, RHEL 7
     # and then no suffix (which should pickup OS X Kerberos).
     PREFERRED_VERSIONS = ['.3', '.26', ''].freeze
 
@@ -38,6 +38,7 @@ end
 require 'kerberos_authenticator/krb5/attach_function'
 require 'kerberos_authenticator/krb5/error'
 require 'kerberos_authenticator/krb5/context'
+require 'kerberos_authenticator/krb5/data'
 require 'kerberos_authenticator/krb5/principal'
 require 'kerberos_authenticator/krb5/creds'
 require 'kerberos_authenticator/krb5/keytab'

data/lib/kerberos_authenticator/krb5/attach_function.rb

@@ -3,7 +3,7 @@ module KerberosAuthenticator
     # Attaches a Kerberos library function to Krb5.
     # Extends FFI's built-in method to:
     # - drop the krb5_ prefix from function names
-    # - wrap any call returning a krb5_error_code with Krb5::Error.raise_if_error
+    # - wrap any call returning a krb5_error_code with Krb5::LibCallError.raise_if_error
     # @api private
     # @see http://www.rubydoc.info/github/ffi/ffi/FFI/Library#attach_function-instance_method FFI::Library#attach_function
     def self.attach_function(c_name, params, returns, options = {})
@@ -18,11 +18,11 @@ module KerberosAuthenticator
 
         if params.first == :krb5_context
           define_method(ruby_name) do |*args, &block|
-            Krb5::Error.raise_if_error(args.first) { public_send(no_check_name, *args, &block) }
+            Krb5::LibCallError.raise_if_error(args.first) { public_send(no_check_name, *args, &block) }
           end
         else
           define_method(ruby_name) do |*args, &block|
-            Krb5::Error.raise_if_error(nil) { public_send(no_check_name, *args, &block) }
+            Krb5::LibCallError.raise_if_error(nil) { public_send(no_check_name, *args, &block) }
           end
         end
 

data/lib/kerberos_authenticator/krb5/context.rb

@@ -2,20 +2,42 @@ module KerberosAuthenticator
   module Krb5
     typedef :pointer, :krb5_context
 
-    attach_function :krb5_init_context, [:buffer_out], :krb5_error_code
+    attach_function :krb5_init_context, [:pointer], :krb5_error_code
     attach_function :krb5_free_context, [:krb5_context], :void
 
     begin
-      attach_function :krb5_init_secure_context, [:buffer_out], :krb5_error_code
+      attach_function :krb5_init_secure_context, [:pointer], :krb5_error_code
     rescue FFI::NotFoundError
       # Then we're probably using a version of the Heimdal library
-      # that doesn't support init_secure_context (and ignore environmental variables by default)
+      # that doesn't support init_secure_context (and ignores environmental variables by default)
       alias_method(:init_secure_context, :init_context)
       module_function :init_secure_context
     end
 
+    attach_function :krb5_get_default_realm, [:krb5_context, :pointer], :krb5_error_code
+
+    begin
+      attach_function :krb5_xfree, [:pointer], :krb5_error_code
+    rescue FFI::NotFoundError
+      # MIT
+    end
+
+    begin
+      attach_function :krb5_free_string, [:krb5_context, :pointer], :void
+    rescue FFI::NotFoundError
+      # Heimdal
+      define_method(:free_string) { |_ctx, pointer| Krb5.xfree(pointer) }
+      module_function :free_string
+    end
+
     # A Kerberos context, holding all per-thread state.
     class Context
+      # @!attribute [r] ptr
+      #   @return [FFI::Pointer] the pointer to the wrapped krb5_context struct
+
+
+      attr_reader :ptr
+
       # @return [Context] a fibre-local Context
       def self.context
         if Krb5.use_secure_context
@@ -29,30 +51,39 @@ module KerberosAuthenticator
       # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/api/krb5_init_secure_context.html krb5_init_secure_context
       # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/api/krb5_init_context.html krb5_init_context
       def initialize(secure = false)
-        @buffer = FFI::Buffer.new :pointer
+        pointer = FFI::MemoryPointer.new :pointer
 
         if secure
-          Krb5::Error.raise_if_error { Krb5.init_secure_context(@buffer) }
+          Krb5::LibCallError.raise_if_error { Krb5.init_secure_context(pointer) }
         else
-          Krb5::Error.raise_if_error { Krb5.init_context(@buffer) }
+          Krb5::LibCallError.raise_if_error { Krb5.init_context(pointer) }
         end
 
-        ObjectSpace.define_finalizer(self, self.class.finalize(@buffer))
+        @ptr = FFI::AutoPointer.new pointer.get_pointer(0), self.class.method(:release)
+
         self
       end
 
-      # @return [FFI::Pointer] the pointer to the krb5_context structure
-      # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/types/krb5_context.html krb5_context
-      def ptr
-        @buffer.get_pointer(0)
+      # Retrieves the default realm
+      # @return [String]
+      # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/api/krb5_get_default_realm.html krb5_get_default_realm
+      def default_realm
+        out_ptr = FFI::MemoryPointer.new :pointer
+        Krb5.get_default_realm(ptr, out_ptr)
+
+        str_ptr = out_ptr.read_pointer
+        copy = String.new(str_ptr.read_string).force_encoding('UTF-8')
+
+        Krb5.free_string(ptr, str_ptr)
+
+        copy
       end
 
-      # Builds a Proc to free the Context once its no longer in use.
+      # Frees a Context
       # @api private
-      # @return [Proc]
       # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/api/krb5_free_context.html krb5_free_context
-      def self.finalize(buffer)
-        proc { Krb5.free_context(buffer.get_pointer(0)) }
+      def self.release(pointer)
+        Krb5.free_context pointer
       end
     end
   end

data/lib/kerberos_authenticator/krb5/creds.rb

@@ -11,9 +11,15 @@ module KerberosAuthenticator
     attach_function :krb5_free_cred_contents, [:krb5_context, :krb5_creds], :void
     attach_function :krb5_get_init_creds_opt_free, [:krb5_context, :pointer], :void
 
+    attach_function :krb5_set_password, [:krb5_context, :krb5_creds, :string, :krb5_principal, :pointer, :pointer, :pointer], :krb5_error_code
+
     # Credentials, or tickets, provided by a KDC for a user.
     class Creds
-      attr_reader :context, :ptr
+      # @!attribute [r] ptr
+      #   @return [FFI::Pointer] the pointer to the wrapped krb5_creds struct
+
+
+      attr_reader :ptr
 
       # The size, in bytes, of the krb5_creds structure.
       # This differs between implementations and architectures.
@@ -31,26 +37,23 @@ module KerberosAuthenticator
       def self.initial_creds_for_principal_with_a_password(principal, password, service = nil)
         raise TypeError, 'expected Principal' unless principal.is_a? Principal
 
-        context = principal.context
         ptr = FFI::MemoryPointer.new :char, SIZE_OF_KRB5_CREDS
+        Krb5.get_init_creds_password(Context.context.ptr, ptr, principal.ptr, password.to_str, nil, nil, 0, service, nil)
 
-        Krb5.get_init_creds_password(context.ptr, ptr, principal.ptr, password.to_str, nil, nil, 0, service, nil)
-
-        new(context, ptr)
+        new(ptr)
       end
 
-      # Initialize a new Keytab with a pointer to a krb5_keytab structure, and define its finalizer.
-      # @param context [Context]
+      # Initialize a new Keytab with a pointer to a krb5_keytab structure.
       # @param ptr [FFI::MemoryPointer]
       # @return [Keytab]
-      def initialize(context, ptr)
-        @context = context
-        @ptr = ptr
+      def initialize(ptr)
+        # HACK: AutoPointer won't accept a MemoryPointer, only a Pointer
+        ptr.autorelease = false
+        ptr = FFI::Pointer.new(ptr)
 
-        @ptr.autorelease = false
-        ObjectSpace.define_finalizer(self, self.class.finalize(context, ptr))
+        ptr = FFI::AutoPointer.new ptr, self.class.method(:release)
 
-        self
+        @ptr = ptr
       end
 
       # Calls #verify with nofail as true.
@@ -59,7 +62,7 @@ module KerberosAuthenticator
         verify(true, server_principal, keytab)
       end
 
-      # Attempt to verify that these Creds were obtained from a KDC with knowledge of a key in keytab.
+      # Attempts to verify that these Creds were obtained from a KDC with knowledge of a key in keytab.
       # @param nofail [Boolean] whether to raise an Error if no keytab information is available
       # @param server_principal [Principal] the server principal to use choosing an entry in keytab
       # @param keytab [Keytab] the key table containing a key that the KDC should know
@@ -76,17 +79,40 @@ module KerberosAuthenticator
         server_princ_ptr = server_principal ? server_principal.ptr : nil
         keytab_ptr = keytab ? keytab.ptr : nil
 
-        Krb5.verify_init_creds(context.ptr, ptr, server_princ_ptr, keytab_ptr, nil, verify_creds_opt)
+        Krb5.verify_init_creds(Context.context.ptr, ptr, server_princ_ptr, keytab_ptr, nil, verify_creds_opt)
+
+        true
+      end
+
+      # Sets a password for a principal using these Creds.
+      # The Creds should be for the 'kadmin/changepw' service.
+      # @param newpw [String] the new password
+      # @param change_password_for [Principal] the Principal to change the password for
+      # @raise [Error] if there is a problem making the password change request
+      # @raise [Error] if server responds that the password change request failed
+      # @return [TrueClass] always returns true if no error was raised
+      # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/api/krb5_set_password.html krb5_set_password
+      def set_password(newpw, change_password_for = nil)
+        change_password_for_ptr = change_password_for ? change_password_for.ptr : nil
+
+        result_code = FFI::MemoryPointer.new :int
+        result_code_string = Data.new
+        result_string = Data.new
+
+        Krb5.set_password(Context.context.ptr, ptr, newpw, change_password_for_ptr, result_code, result_code_string.pointer, result_string.pointer)
+
+        result_code = result_code.read_uint
+        result_string = result_string.read_string.force_encoding('UTF-8')
+        raise SetPassError.new(result_code, result_string) if result_code > 0
 
         true
       end
 
-      # Builds a Proc to free the credentials once they're no longer in use.
+      # Frees the contents of the Creds structure
       # @api private
-      # @return [Proc]
       # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/api/krb5_free_cred_contents.html krb5_free_cred_contents
-      def self.finalize(context, ptr)
-        proc { Krb5.free_cred_contents(context.ptr, ptr); ptr.free }
+      def self.release(pointer)
+        Krb5.free_cred_contents(Context.context.ptr, pointer)
       end
     end
   end

data/lib/kerberos_authenticator/krb5/data.rb

@@ -0,0 +1,40 @@
+module KerberosAuthenticator
+  module Krb5
+    attach_function :krb5_free_data_contents, [:krb5_context, :pointer], :void
+
+    # Generic Kerberos library data structure.
+    # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/types/krb5_data.html krb5_data
+    class Data < FFI::ManagedStruct
+      layout :magic, :krb5_error_code, :length, :int, :data_ptr, :pointer
+
+      # Allocates and zeroes a new krb5_data struct or cast some existing memory to one.
+      # @param pointer [Pointer] a pointer to existing memory to cast to a krb5_data struct
+      # @see https://github.com/ffi/ffi/wiki/Structs Structs
+      def initialize(pointer = nil)
+        unless pointer
+          pointer = FFI::MemoryPointer.new :char, self.class.size
+
+          # HACK: AutoPointer won't accept a MemoryPointer, only a Pointer
+          pointer.autorelease = false
+          pointer = FFI::Pointer.new(pointer)
+        end
+
+        super(pointer)
+      end
+
+      # Reads the data into a string.
+      # @return [String]
+      def read_string
+        return '' if self[:length].zero?
+        self[:data_ptr].read_bytes(self[:length])
+      end
+
+      # Frees the contents of a Data struct 
+      # @api private
+      # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/api/krb5_free_data_contents.html krb5_free_data_contents
+      def self.release(pointer)
+        Krb5.free_data_contents(Context.context.ptr, pointer)
+      end
+    end
+  end
+end

data/lib/kerberos_authenticator/krb5/error.rb

@@ -4,44 +4,70 @@ module KerberosAuthenticator
     attach_function :krb5_get_error_message, [:pointer, :krb5_error_code], :strptr
     attach_function :krb5_free_error_message, [:pointer, :pointer], :void
 
-    # A Kerberos library error
-    class Error < StandardError
+    # Generic exception class
+    class Error < StandardError; end
+
+    # A Kerberos error returned from a library call as a `krb5_error_code`.
+    class LibCallError < Error
       # @!attribute [r] error_code
       #   @return [Integer] the krb5_error_code used to convey the status of a Kerberos library operation.
-      #   @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/types/krb5_error_code.html krb5_error_code 
+      #   @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/types/krb5_error_code.html krb5_error_code
 
 
       attr_reader :error_code
 
-      # Initializes a new Error using an error code and the relevant Context to provide a friendly error message.
+      # Initializes a new LibCallError using an error code and the relevant Context to provide a friendly error message.
       # @param context_ptr [FFI::Pointer] A Context's pointer
       # @param krb5_error_code [Integer] An integer used to convey a operation's status
-      # @return [Error]
+      # @return [LibCallError]
       # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/api/krb5_get_error_message.html krb5_get_error_message
       def initialize(context_ptr, krb5_error_code)
         @error_code = krb5_error_code
         error_message, error_ptr = Krb5.get_error_message(context_ptr, krb5_error_code)
-        FFI::AutoPointer.new(error_ptr, self.class.finalize(context_ptr))
-        super(String.new(error_message))
+        self.class.release(error_ptr)
+        super String.new(error_message).force_encoding('UTF-8')
       end
 
-      # Build a Proc to free the error message string once it's no longer in use.
+      # Frees an error message
       # @api private
-      # @return [Proc]
       # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/api/krb5_free_error_message.html krb5_free_error_message
-      def self.finalize(context_ptr)
-        proc { |ptr| Krb5.free_error_message(context_ptr, ptr) }
+      def self.release(pointer)
+        Krb5.free_error_message(Context.context.ptr, pointer)
       end
 
       # Used to wrap Kerberos library functions that return a krb5_error_code.
       # @return [Integer] always returns zero on success
       # @yield [] A call to a Kerberos library function
       # @yieldreturn [Integer] a krb5_error_code
-      # @raise [Error] if the krb5_error_code differed from zero
+      # @raise [LibCallError] if the krb5_error_code differed from zero
       def self.raise_if_error(context_ptr = nil)
         err = yield
-        return 0 if err == 0
-        raise Krb5::Error.new(context_ptr, err)
+        return 0 if err.zero?
+        raise self.new(context_ptr, err)
+      end
+    end
+
+    # An error indicating a failure response from a server
+    # when trying to change a password.
+    # @see https://www.ietf.org/rfc/rfc3244.txt RFC 3244
+    class SetPassError < Error
+      # @!attribute [r] result_code
+      #   @return [Integer] the result code used to convey the result of a Set Password operation.
+      # @!attribute [r] result_string
+      #   @return [String] the full result string used to convey the result of a Set Password operation.
+
+
+      attr_reader :result_code
+      attr_reader :result_string
+
+      # Initializes a new SetPassError using an RFC 3244 result code and result string supplied in a server response.
+      # @param result_code [Integer] the result code used to convey the result of a Set Password operation
+      # @param result_string [String]  the full result string used to convey the result of a Set Password operation.
+      # @return [SetPassError]
+      def initialize(result_code, result_string)
+        @result_code = result_code
+        @result_string = result_string
+        super @result_string.lines.first.to_s.strip
       end
     end
   end

data/lib/kerberos_authenticator/krb5/keytab.rb

@@ -2,54 +2,136 @@ module KerberosAuthenticator
   module Krb5
     typedef :pointer, :krb5_keytab
 
-    attach_function :krb5_kt_resolve, [:krb5_context, :string, :buffer_out], :krb5_error_code
+    attach_function :krb5_kt_resolve, [:krb5_context, :string, :pointer], :krb5_error_code
+    attach_function :krb5_kt_default, [:krb5_context, :pointer], :krb5_error_code
+
     attach_function :krb5_kt_close, [:krb5_context, :krb5_keytab], :krb5_error_code
-    attach_function :krb5_kt_get_type, [:krb5_context, :krb5_keytab], :string
+
+    begin
+      # Heimdal
+      attach_function :krb5_kt_get_full_name, [:krb5_context, :krb5_keytab, :pointer], :krb5_error_code
+    rescue FFI::NotFoundError
+      # MIT
+      attach_function :krb5_kt_get_name, [:krb5_context, :krb5_keytab, :buffer_out, :int], :krb5_error_code
+    end
+
+    begin
+      attach_function :krb5_kt_have_content, [:krb5_context, :krb5_keytab], :krb5_error_code
+    rescue FFI::NotFoundError
+      # REVIEW: Then we're probably using an old version of the library that doesn't support kt_have_content.
+    end
 
     # Storage for locally-stored keys.
     class Keytab
-      attr_reader :context
+      # @!attribute [r] ptr
+      #   @return [FFI::Pointer] the pointer to the wrapped krb5_keytab struct
+
 
+      attr_reader :ptr
+
+      # Resolves a keytab identified by name.
+      # The keytab is not opened and may not be accessible or contain any entries. (Use #has_content? to check.)
       # @param name [String] a name of the form 'type:residual', where usually type is 'FILE' and residual the path to that file
-      # @return [Keytab]
+      # @raises [Error] if the type is unknown
+      # @return [Keytab] a resolved, but not opened, keytab
       # @see http://web.mit.edu/Kerberos/krb5-1.14/doc/appdev/refs/api/krb5_kt_resolve.html krb5_kt_resolve
-      def self.new_with_name(name, context = Context.context)
-        buffer = FFI::Buffer.new :pointer
-        Krb5.kt_resolve(context.ptr, name, buffer)
+      def self.new_with_name(name)
+        pointer = FFI::MemoryPointer.new :pointer
+        Krb5.kt_resolve(Context.context.ptr, name, pointer)
+
+        new(pointer)
+      end
+
+      # Resolves the default keytab, usually the file at `/etc/krb5.keytab`.
+      # The keytab is not opened and may not be accessible or contain any entries. (Use #has_content? to check.)
+      # @return [Keytab] the default keytab
+      # @see http://web.mit.edu/Kerberos/krb5-1.14/doc/appdev/refs/api/krb5_kt_default.html krb5_kt_default
+      def self.default
+        pointer = FFI::MemoryPointer.new :pointer
+        Krb5.kt_default(Context.context.ptr, pointer)
 
-        new(context, buffer)
+        new(pointer)
       end
 
-      # Initialize a new Keytab with a buffer containing a krb5_keytab structure, and define its finalizer.
-      # @param context [Context]
-      # @param buffer [FFI::Buffer]
+      # Initializes a new Keytab with a pointer to a pointer to a krb5_keytab structure.
+      # @param pointer [FFI::Buffer]
       # @return [Keytab]
-      def initialize(context, buffer)
-        @context = context
-        @buffer = buffer
+      def initialize(pointer)
+        @ptr = FFI::AutoPointer.new pointer.get_pointer(0), self.class.method(:release)
 
-        ObjectSpace.define_finalizer(self, self.class.finalize(context, buffer))
         self
       end
 
-      # @return [FFI::Pointer] the pointer to the krb5_keytab structure
-      # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/types/krb5_keytab.html krb5_keytab
-      def ptr
-        @buffer.get_pointer(0)
+      # Checks if the underlying keytab file or other store exists and contains entries.
+      # (When `krb5_kt_have_content` isn't provided by the Kerberos library, then only some very limited checks are performed.)
+      # @return [TrueClass] if the keytab exists and contains entries
+      # @raises [Error] if there is a problem finding entries in the keytab
+      # @see http://web.mit.edu/Kerberos/krb5-1.14/doc/appdev/refs/api/krb5_kt_have_content.html krb5_kt_have_content
+      def assert_has_content
+        if defined?(Krb5.kt_have_content)
+          Krb5.kt_have_content(Context.context.ptr, ptr)
+        else # HACK
+          raise Error, "Could not read #{name}" if file? and !FileTest.readable?(path)
+        end
+        true
+      end
+
+      # @return [Boolean] whether the keytab exists and contains entries
+      def has_content?
+        assert_has_content
+        true
+      rescue Error
+        false
+      end
+
+      # The maximum length, in bytes, that can be read by #name .
+      GET_NAME_MAX_LENGTH = 512
+
+      # The seperator between the type and the residual in a keytab's name
+      FULL_NAME_DELIMITER = ':'
+
+      # @return [String] the name of the key table
+      # @see http://web.mit.edu/Kerberos/krb5-1.14/doc/appdev/refs/api/krb5_kt_get_name.html kt_get_name
+      def name
+        if defined?(Krb5.kt_get_full_name)
+          pointer = FFI::MemoryPointer.new :pointer
+          Krb5.kt_get_full_name(Context.context.ptr, ptr, pointer)
+          pointer = pointer.read_pointer
+          copy = String.new(pointer.read_string).force_encoding('UTF-8')
+          Krb5.xfree(pointer)
+          copy
+        else
+          buffer = FFI::Buffer.new :char, GET_NAME_MAX_LENGTH
+          Krb5.kt_get_name(Context.context.ptr, ptr, buffer, GET_NAME_MAX_LENGTH)
+          buffer.read_bytes(255).force_encoding('UTF-8').split("\x00", 2)[0]
+        end
       end
 
       # @return [String] the type of the key table
-      # @see http://web.mit.edu/Kerberos/krb5-1.14/doc/appdev/refs/api/krb5_kt_get_type.html kt_get_type
       def type
-        Krb5.kt_get_type(context.ptr, ptr)
+        name.split(FULL_NAME_DELIMITER, 2).first
+      end
+
+      # @return [String] the residual of the key table, which means different things depending on the type
+      def residual
+        name.split(FULL_NAME_DELIMITER, 2).last
+      end
+
+      # @return [Boolean] if the keytab has a type of 'FILE' or 'file'
+      def file?
+        type =~ /^FILE$/i
+      end
+
+      # @return [String, nil] the path to the keytab file if the keytab is a file, nil otherwise
+      def path
+        file? ? residual : nil
       end
 
-      # Builds a Proc to close the Keytab once its no longer in use.
+      # Closes a Keytab
       # @api private
-      # @return [Proc]
       # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/api/krb5_kt_close.html krb5_kt_close
-      def self.finalize(context, buffer)
-        proc { Krb5.kt_close(context.ptr, buffer.get_pointer(0)) }
+      def self.release(pointer)
+        Krb5.kt_close(Context.context.ptr, pointer)
       end
     end
   end

data/lib/kerberos_authenticator/krb5/principal.rb

@@ -2,7 +2,7 @@ module KerberosAuthenticator
   module Krb5
     typedef :pointer, :krb5_principal
 
-    attach_function :krb5_parse_name, [:krb5_context, :string, :krb5_principal], :krb5_error_code
+    attach_function :krb5_parse_name, [:krb5_context, :string, :pointer], :krb5_error_code
     attach_function :krb5_free_principal, [:krb5_context, :krb5_principal], :void
 
     attach_function :krb5_unparse_name, [:krb5_context, :krb5_principal, :pointer], :krb5_error_code
@@ -10,34 +10,34 @@ module KerberosAuthenticator
 
     # A Kerberos principal identifying a user, service or machine.
     class Principal
-      attr_reader :context
+      # @!attribute [r] ptr
+      #   @return [FFI::Pointer] the pointer to the wrapped krb5_principal struct
+
+
+      attr_reader :ptr
 
       # Convert a string representation of a principal name into a new Principal.
       # @param name [String] a string representation of a principal name
-      # @param context [Context] a Kerberos library context
       # @return [Principal]
       # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/api/krb5_parse_name.html krb5_parse_name
-      def self.new_with_name(name, context = Context.context)
+      def self.new_with_name(name)
         raise ArgumentError, 'name cannot be empty' if name.empty?
 
-        buffer = FFI::Buffer.new :pointer
-        Krb5.parse_name(context.ptr, name, buffer)
-        new(context, buffer)
+        pointer = FFI::MemoryPointer.new :pointer
+        Krb5.parse_name(Context.context.ptr, name, pointer)
+        new(pointer)
       end
 
-      # Initialize a new Principal with a buffer containing a krb5_principal structure, and define its finalizer.
-      # @param context [Context]
-      # @param buffer [FFI::Buffer]
+      # Initialize a new Principal with a pointer to a pointer to a krb5_principal structure.
+      # @param pointer [FFI::Pointer]
       # @return [Principal]
-      def initialize(context, buffer)
-        @context = context
-        @buffer = buffer
-
-        ObjectSpace.define_finalizer(self, self.class.finalize(context, buffer))
+      def initialize(pointer)
+        @ptr = FFI::AutoPointer.new pointer.get_pointer(0), self.class.method(:release)
 
         self
       end
 
+      # Calls Creds.initial_creds_for_principal_with_a_password(self, password, service)
       # @param password [String]
       # @param service [String]
       # @return [Creds]
@@ -46,32 +46,33 @@ module KerberosAuthenticator
         Creds.initial_creds_for_principal_with_a_password(self, password, service)
       end
 
-      # @return [FFI::Pointer] the pointer to the krb5_principal structure
-      # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/types/krb5_principal.html krb5_principal
-      def ptr
-        @buffer.get_pointer(0)
-      end
-
       # @return [String] a string representation of the principal's name
       # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/api/krb5_unparse_name.html krb5_unparse_name
       def name
         out_ptr = FFI::MemoryPointer.new(:pointer, 1)
-        Krb5.unparse_name(context.ptr, ptr, out_ptr)
+        Krb5.unparse_name(Context.context.ptr, ptr, out_ptr)
 
         str_ptr = out_ptr.read_pointer
-        copy = String.new(str_ptr.read_string)
+        copy = String.new(str_ptr.read_string).force_encoding('UTF-8')
 
-        Krb5.free_unparsed_name(context.ptr, str_ptr)
+        Krb5.free_unparsed_name(Context.context.ptr, str_ptr)
 
         copy
       end
 
-      # Builds a Proc to free the Principal once it's no longer in use.
+      # A convenience function to allow a Principal to change a password by authenticating themselves.
+      # @raise [Error] if the attempt to change the password fails
+      # @return [TrueClass] always returns true if no error was raised
+      def change_password(oldpw, new_pw)
+        changepw_creds = self.initial_creds_with_password(oldpw, 'kadmin/changepw')
+        changepw_creds.set_password(new_pw, self)
+      end
+
+      # Frees a Principal
       # @api private
-      # @return [Proc]
       # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/api/krb5_free_principal.html krb5_free_principal
-      def self.finalize(context, buffer)
-        proc { Krb5.free_principal(context.ptr, buffer.get_pointer(0)) }
+      def self.release(pointer)
+        Krb5.free_principal(Context.context.ptr, pointer)
       end
     end
   end

data/lib/kerberos_authenticator/version.rb

@@ -1,3 +1,3 @@
 module KerberosAuthenticator
-  VERSION = '0.0.6'
-end
+  VERSION = '0.0.7'.freeze
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kerberos_authenticator
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors:
 - Adam Watkins
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-24 00:00:00.000000000 Z
+date: 2016-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -50,6 +50,7 @@ files:
 - lib/kerberos_authenticator/krb5/attach_function.rb
 - lib/kerberos_authenticator/krb5/context.rb
 - lib/kerberos_authenticator/krb5/creds.rb
+- lib/kerberos_authenticator/krb5/data.rb
 - lib/kerberos_authenticator/krb5/error.rb
 - lib/kerberos_authenticator/krb5/keytab.rb
 - lib/kerberos_authenticator/krb5/principal.rb