kerberos_authenticator 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c594e9c76894d762d40c03315577382a1202c241
+  data.tar.gz: 8ca589fdf26e7183cc11075e3224b7b1737b5af3
+SHA512:
+  metadata.gz: 936e9cdefd7562f35f4f583673fc8647bf07361ed934d00486a793b53cfb6b71de327ec118d9c9a0911df14e666d5311513884798e02f8c7e3bae36165b729e1
+  data.tar.gz: e54b978206b7d64df2e6dab52f441d7393db2aa4fff387ad92c3377ac8d707058f7e0fe81643f940d36b71c3316122b320322c6616966c0adf095b94c46456b1

data/lib/kerberos_authenticator.rb

@@ -0,0 +1,118 @@
+require 'base64'
+require 'tempfile'
+
+require 'kerberos_authenticator/error'
+require 'kerberos_authenticator/krb5'
+
+module KerberosAuthenticator
+  # @return [Krb5]
+  def self.krb5
+    Krb5
+  end
+
+  # Supports setting KerberosAuthenticator up using a block.
+  def self.setup
+    yield self
+  end
+
+  # Authenticates a user using their password.
+  # @param username [String] a string representation of the user's principal
+  # @param password [String] the user's password
+  # @raise [Error] if Kerberos can't understand the principal or contact any KDCs for the principal's realm
+  # @raise [Error] if preauthentication fails (usually meaning that the user's password was incorrect)
+  # @raise [Error] if the KDC cannot find the user
+  # @return [TrueClass] always returns true if authentication succeeds without any error
+  # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/init_creds.html Initial credentials
+  def self.authenticate!(username, password)
+    user = Krb5::Principal.new_with_name(username)
+    creds = user.initial_creds_with_password(password, service)
+
+    with_keytab do |kt|
+      creds.verify!(server_princ, kt)
+    end
+
+    true
+  end
+
+  # @!attribute [rw] server
+  #   @return [String] the server principal name to use when verifying the identity the KDC
+
+  # @!attribute [rw] service
+  #   @return [String] the service principal name to request a ticket for when obtaining a user's credentials
+
+  # @!attribute [rw] keytab_base64
+  #   @return [String] the keytab to use when verifying the identity the KDC represented as a Base64 encoded string (overrides keytab_path)
+
+  # @!attribute [rw] keytab_path
+  #   @return [String] the path to the keytab to use when verifying the identity the KDC
+
+  @service = nil
+
+  def self.service
+    @service
+  end
+
+  def self.service=(v)
+    @service = v
+  end
+
+  @server = nil
+
+  def self.server
+    @server
+  end
+
+  def self.server=(v)
+    @server = v
+  end
+
+  @keytab_base64 = nil
+  @keytab_path = nil
+
+  def self.keytab_base64
+    @keytab_base64
+  end
+
+  def self.keytab_base64=(v)
+    @keytab_base64 = v
+  end
+
+  def self.keytab_path
+    @keytab_path
+  end
+
+  def self.keytab_path=(v)
+    @keytab_path = v
+  end
+
+  def self.server_princ
+    server ? Krb5::Principal.new_with_name(server) : nil
+  end
+
+  def self.new_kt_tmp_file
+    return nil unless keytab_base64
+
+    kt_tmp_file = Tempfile.new('krb5_kt', encoding: 'ascii-8bit')
+    kt_tmp_file.write(Base64.decode64(keytab_base64))
+    kt_tmp_file.close
+
+    kt_tmp_file
+  end
+
+  def self.with_keytab
+    if keytab_base64
+      kt_tmp_file = new_kt_tmp_file
+      kt = Krb5::Keytab.new_with_name("FILE:#{kt_tmp_file.path}")
+    elsif keytab_path
+      kt = Krb5::Keytab.new_with_name("FILE:#{keytab_path}")
+    end
+
+    begin
+      yield kt
+    ensure
+      kt_tmp_file.close! if kt_tmp_file
+    end
+  end
+
+  private_class_method :server_princ, :new_kt_tmp_file, :with_keytab
+end

data/lib/kerberos_authenticator/error.rb

@@ -0,0 +1,4 @@
+module KerberosAuthenticator
+  class Error < StandardError; end
+  class StandardError < Error; end
+end

data/lib/kerberos_authenticator/krb5.rb

@@ -0,0 +1,35 @@
+require 'ffi'
+
+module KerberosAuthenticator
+  # An FFI wrapper around the Kerberos 5 library.
+  # Use the environmental variable FFI_KRB5_LIBRARY_NAME to override the library loaded.
+  module Krb5
+    extend FFI::Library
+
+    if ENV['FFI_KRB5_LIBRARY_NAME']
+      ffi_lib ENV['FFI_KRB5_LIBRARY_NAME']
+    else
+      ffi_lib 'krb5'
+    end
+
+    # @!attribute [rw] use_secure_context
+    #   @return [Boolean] if Context.context should ignore environmental variables when returning a library context
+
+    @use_secure_context = true
+
+    def self.use_secure_context
+      @use_secure_context
+    end
+
+    def self.use_secure_context=(v)
+      @use_secure_context = v
+    end
+  end
+end
+
+require 'kerberos_authenticator/krb5/attach_function'
+require 'kerberos_authenticator/krb5/error'
+require 'kerberos_authenticator/krb5/context'
+require 'kerberos_authenticator/krb5/principal'
+require 'kerberos_authenticator/krb5/creds'
+require 'kerberos_authenticator/krb5/keytab'

data/lib/kerberos_authenticator/krb5/attach_function.rb

@@ -0,0 +1,32 @@
+module KerberosAuthenticator
+  module 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
+    def self.attach_function(c_name, params, returns, options = {})
+      ruby_name = c_name.to_s.gsub(/^krb5_/, '').to_sym
+
+      super(ruby_name, c_name, params, returns, options)
+
+      if returns == :krb5_error_code
+        no_check_name = "#{ruby_name}_without_catching_error"
+
+        alias_method(no_check_name, ruby_name)
+
+        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) }
+          end
+        else
+          define_method(ruby_name) do |*args, &block|
+            Krb5::Error.raise_if_error(nil) { public_send(no_check_name, *args, &block) }
+          end
+        end
+
+        module_function no_check_name
+      end
+
+      module_function ruby_name
+    end
+  end
+end

data/lib/kerberos_authenticator/krb5/context.rb

@@ -0,0 +1,54 @@
+module KerberosAuthenticator
+  module Krb5
+    typedef :pointer, :krb5_context
+
+    attach_function :krb5_init_context, [:buffer_out], :krb5_error_code
+    attach_function :krb5_free_context, [:krb5_context], :void
+
+    begin
+      attach_function :krb5_init_secure_context, [:buffer_out], :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)
+      alias_method(:init_secure_context, :init_context)
+      module_function :init_secure_context
+    end
+
+    # A Kerberos context, holding all per-thread state.
+    class Context
+      # @return [Context] a fibre-local Context
+      def self.context
+        if Krb5.use_secure_context
+          Thread.current[:krb5_secure_context] ||= new(true)
+        else
+          Thread.current[:krb5_context] ||= new
+        end
+      end
+
+      # @param secure [Boolean] whether to ignore environmental variables when constructing a library context
+      # @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
+
+        if secure
+          Krb5::Error.raise_if_error { Krb5.init_secure_context(@buffer) }
+        else
+          Krb5::Error.raise_if_error { Krb5.init_context(@buffer) }
+        end
+
+        ObjectSpace.define_finalizer(self, self.class.finalize(@buffer))
+        self
+      end
+
+      def ptr
+        @buffer.get_pointer(0)
+      end
+
+      # @api private
+      def self.finalize(buffer)
+        proc { Krb5.free_context(buffer.get_pointer(0)) }
+      end
+    end
+  end
+end

data/lib/kerberos_authenticator/krb5/creds.rb

@@ -0,0 +1,89 @@
+module KerberosAuthenticator
+  module Krb5
+    typedef :pointer, :krb5_creds
+
+    attach_function :krb5_get_init_creds_password, [:krb5_context, :krb5_creds, :krb5_principal, :string, :pointer, :pointer, :int, :string, :pointer], :krb5_error_code
+    attach_function :krb5_verify_init_creds, [:krb5_context, :krb5_creds, :krb5_principal, :pointer, :pointer, :pointer], :krb5_error_code
+
+    attach_function :krb5_verify_init_creds_opt_init, [:pointer], :void
+    attach_function :krb5_verify_init_creds_opt_set_ap_req_nofail, [:pointer, :bool], :void
+
+    attach_function :krb5_free_creds, [:krb5_context, :krb5_creds], :void
+    attach_function :krb5_get_init_creds_opt_free, [:krb5_context, :pointer], :void
+
+    # Credentials, or tickets, provided by a KDC for a user.
+    class Creds
+      attr_reader :context, :ptr
+
+      # Requests initial credentials for principal using password from a KDC.
+      # @param principal [Principal] the user's Principal
+      # @param password [String] the user's password
+      # @param service [String] the service name used when requesting the credentials
+      # @return [Creds]
+      # @raise [Error] if a KDC for the principal can't be contacted
+      # @raise [Error] if preauthentication fails
+      # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/api/krb5_get_init_creds_password.html krb5_get_init_creds_password
+      # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/init_creds.html Initial credentials
+      def self.initial_creds_for_principal_with_a_password(principal, password, service = nil)
+        raise ArgumentError, 'expected Principal' unless principal.is_a? Principal
+
+        context = principal.context
+        ptr = FFI::MemoryPointer.new :char, 120
+
+        Krb5.get_init_creds_password(context.ptr, ptr, principal.ptr, password, nil, nil, 0, service, nil)
+
+        new(context, ptr)
+      end
+
+      def initialize(context, ptr)
+        @context = context
+        @ptr = ptr
+
+        @ptr.autorelease = false
+        ObjectSpace.define_finalizer(self, self.class.finalize(context, ptr))
+
+        self
+      end
+
+      # Calls #verify with nofail as true.
+      # @see #verify
+      def verify!(server_principal = nil, keytab = nil)
+        verify(true, server_principal, keytab)
+      end
+
+      # Attempt 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
+      # @raise [Error] if nofail is true and no keytab information is available
+      # @raise [Error] if the KDC did not have knowledge of the key requested
+      # @return [TrueClass] always returns true if no error was raised
+      # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/api/krb5_verify_init_creds.html krb5_verify_init_creds
+      # @see http://web.mit.edu/kerberos/krb5-1.14/doc/appdev/refs/api/krb5_verify_init_creds_opt_set_ap_req_nofail.html krb5_verify_init_creds_opt_set_ap_req_nofail
+      def verify(nofail = false, server_principal = nil, keytab = nil)
+        verify_creds_opt = FFI::MemoryPointer.new :int, 2
+
+        Krb5.verify_init_creds_opt_init(verify_creds_opt)
+        verify_creds_opt.autorelease = false
+
+        begin
+          Krb5.verify_init_creds_opt_set_ap_req_nofail(verify_creds_opt, nofail)
+
+          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)
+        ensure
+          Krb5.get_init_creds_opt_free(context.ptr, verify_creds_opt)
+        end
+
+        true
+      end
+
+      # @api private
+      def self.finalize(context, ptr)
+        proc { Krb5.free_creds(context.ptr, ptr) }
+      end
+    end
+  end
+end

data/lib/kerberos_authenticator/krb5/error.rb

@@ -0,0 +1,23 @@
+module KerberosAuthenticator
+  module Krb5
+    typedef :int, :krb5_error_code
+    attach_function :krb5_get_error_message, [:pointer, :krb5_error_code], :string
+
+    # A Kerberos library error
+    class Error < StandardError
+      attr_reader :error_code
+
+      # @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
+        super(Krb5.get_error_message(context_ptr, krb5_error_code))
+      end
+
+      def self.raise_if_error(context_ptr = nil)
+        err = yield
+        return 0 if err == 0
+        raise Krb5::Error.new(context_ptr, err)
+      end
+    end
+  end
+end

data/lib/kerberos_authenticator/krb5/keytab.rb

@@ -0,0 +1,45 @@
+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_close, [:krb5_context, :krb5_keytab], :krb5_error_code
+    attach_function :krb5_kt_get_type, [:krb5_context, :krb5_keytab], :string
+
+    # Storage for locally-stored keys.
+    class Keytab
+      attr_reader :context
+
+      # @param name [String] a name of the form 'type:residual', where usually type is 'FILE' and residual the path to that file
+      # @return [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)
+
+        new(context, buffer)
+      end
+
+      def initialize(context, buffer)
+        @context = context
+        @buffer = buffer
+
+        ObjectSpace.define_finalizer(self, self.class.finalize(context, buffer))
+        self
+      end
+
+      def ptr
+        @buffer.get_pointer(0)
+      end
+
+      def type
+        Krb5.kt_get_type(context.ptr, ptr)
+      end
+
+      # @api private
+      def self.finalize(context, buffer)
+        proc { Krb5.kt_close(context.ptr, buffer.get_pointer(0)) }
+      end
+    end
+  end
+end

data/lib/kerberos_authenticator/krb5/principal.rb

@@ -0,0 +1,69 @@
+module KerberosAuthenticator
+  module Krb5
+    typedef :pointer, :krb5_principal
+
+    attach_function :krb5_parse_name, [:krb5_context, :string, :krb5_principal], :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
+    attach_function :krb5_free_unparsed_name, [:krb5_context, :pointer], :void
+
+    # A Kerberos principal identifying a user, service or machine.
+    class Principal
+      attr_reader :context
+
+      # 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)
+        raise ArgumentError, 'name cannot be empty' if name.empty?
+
+        buffer = FFI::Buffer.new :pointer
+        Krb5.parse_name(context.ptr, name, buffer)
+        new(context, buffer)
+      end
+
+      def initialize(context, buffer)
+        @context = context
+        @buffer = buffer
+
+        ObjectSpace.define_finalizer(self, self.class.finalize(context, buffer))
+
+        self
+      end
+
+      # @param password [String]
+      # @param service [String]
+      # @return [Creds]
+      # @see Creds.initial_creds_for_principal_with_a_password
+      def initial_creds_with_password(password, service = nil)
+        Creds.initial_creds_for_principal_with_a_password(self, password, service)
+      end
+
+      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)
+
+        str_ptr = out_ptr.read_pointer
+        copy = String.new(str_ptr.read_string)
+
+        Krb5.free_unparsed_name(context.ptr, str_ptr)
+
+        copy
+      end
+
+      # @api private
+      def self.finalize(context, buffer)
+        proc { Krb5.free_principal(context.ptr, buffer.get_pointer(0)) }
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: kerberos_authenticator
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Adam Watkins
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-04-09 00:00:00.000000000 Z
+dependencies: []
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/kerberos_authenticator.rb
+- lib/kerberos_authenticator/error.rb
+- lib/kerberos_authenticator/krb5.rb
+- lib/kerberos_authenticator/krb5/attach_function.rb
+- lib/kerberos_authenticator/krb5/context.rb
+- lib/kerberos_authenticator/krb5/creds.rb
+- lib/kerberos_authenticator/krb5/error.rb
+- lib/kerberos_authenticator/krb5/keytab.rb
+- lib/kerberos_authenticator/krb5/principal.rb
+homepage: https://github.com/stupidpupil/kerberos_authenticator
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements:
+- A Kerberos 5 library
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: An FFI library to support Kerberos authentication of a user, with a password,
+  and of the KDC, with a keytab
+test_files: []
+has_rdoc: