EE-ID-verification 0.1.0

data/lib/ee_id_verification/models.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module EeIdVerification
+  # Authentication session model for Estonian ID card authentication workflow.
+  #
+  # This class represents an active authentication session during the two-phase
+  # authentication process used by Estonian ID cards. The authentication workflow
+  # is designed to be secure and user-friendly:
+  #
+  # 1. Session Creation: When authentication starts, a session is created with
+  #    a unique ID and initial status of :waiting_for_pin
+  # 2. PIN Entry: User provides PIN1 which is verified directly on the card
+  # 3. Session Completion: Upon successful PIN verification, session status
+  #    changes to :completed and personal data is extracted
+  #
+  # The session-based approach provides several benefits:
+  # - Separation of concerns between session management and authentication logic
+  # - Timeout handling to prevent indefinite waiting for PIN entry
+  # - State tracking for complex authentication workflows
+  # - Security through session expiration and cleanup
+  #
+  # Session states:
+  # - :waiting_for_pin - Session created, waiting for user PIN input
+  # - :completed - Authentication successful, personal data available
+  # - :failed - Authentication failed (wrong PIN, card error, etc.)
+  # - :expired - Session timed out waiting for PIN entry
+  #
+  # @example Creating and managing a session
+  #   session = AuthenticationSession.new(
+  #     id: SecureRandom.uuid,
+  #     method: :digidoc_local,
+  #     status: :waiting_for_pin,
+  #     created_at: Time.now,
+  #     expires_at: Time.now + 300  # 5 minutes
+  #   )
+  #   
+  #   # Check if session is still valid
+  #   if session.expired?
+  #     puts "Session expired, please try again"
+  #   end
+  class AuthenticationSession
+    # Session attributes for tracking authentication state
+    # @!attribute [rw] id
+    #   @return [String] Unique session identifier (typically UUID)
+    # @!attribute [rw] method  
+    #   @return [Symbol] Authentication method used (:digidoc_local)
+    # @!attribute [rw] status
+    #   @return [Symbol] Current session status (:waiting_for_pin, :completed, :failed, :expired)
+    # @!attribute [rw] created_at
+    #   @return [Time] When the session was created
+    # @!attribute [rw] expires_at
+    #   @return [Time, nil] When the session expires (nil for no expiration)
+    attr_accessor :id, :method, :status, :created_at, :expires_at
+
+    # Initialize a new authentication session with the provided attributes.
+    #
+    # This constructor uses a flexible attribute assignment approach that allows
+    # setting any of the session attributes through a hash. This pattern provides
+    # flexibility for different authentication scenarios while maintaining a
+    # clean interface.
+    #
+    # @param attributes [Hash] Session attributes to set
+    # @option attributes [String] :id Unique session identifier
+    # @option attributes [Symbol] :method Authentication method
+    # @option attributes [Symbol] :status Initial session status
+    # @option attributes [Time] :created_at Session creation time
+    # @option attributes [Time] :expires_at Session expiration time
+    # @example
+    #   session = AuthenticationSession.new(
+    #     id: "auth-123",
+    #     status: :waiting_for_pin,
+    #     created_at: Time.now
+    #   )
+    def initialize(attributes = {})
+      # Dynamically set attributes using setter methods
+      # This approach ensures only valid attributes are set and leverages
+      # any custom setter logic that might be added in the future
+      attributes.each do |key, value|
+        send("#{key}=", value) if respond_to?("#{key}=")
+      end
+    end
+
+    # Check if the authentication session has expired.
+    #
+    # Sessions expire to prevent security issues from long-lived authentication
+    # attempts and to free up system resources. An expired session cannot be
+    # used to complete authentication and should be discarded.
+    #
+    # The expiration check handles cases where no expiration time is set
+    # (nil expires_at means the session never expires automatically).
+    #
+    # @return [Boolean] true if session has expired, false otherwise
+    # @example
+    #   session = AuthenticationSession.new(expires_at: Time.now - 60)
+    #   puts "Expired!" if session.expired?
+    def expired?
+      expires_at && expires_at < Time.now
+    end
+  end
+
+  # Authentication result model containing the outcome of Estonian ID card authentication.
+  #
+  # This class encapsulates all information returned from a completed (or failed)
+  # authentication attempt. It provides a comprehensive view of the authentication
+  # outcome including:
+  #
+  # - Authentication status and success/failure indicators
+  # - Personal information extracted from the ID card certificate
+  # - Error information if authentication failed
+  # - Convenient methods for checking authentication state
+  #
+  # The result object serves as the primary interface between the authentication
+  # system and consuming applications, providing all necessary information to
+  # make authorization decisions and display user information.
+  #
+  # Personal data fields match those available in Estonian ID card certificates:
+  # - personal_code: 11-digit Estonian personal identification code
+  # - given_name: User's first/given name(s)
+  # - surname: User's family/last name
+  # - country: Country code (always "EE" for Estonian cards)
+  #
+  # @example Successful authentication result
+  #   result = AuthenticationResult.new(
+  #     session_id: "auth-123",
+  #     status: :completed,
+  #     authenticated: true,
+  #     personal_code: "38001010008",
+  #     given_name: "MARI",
+  #     surname: "MAASIKAS",
+  #     country: "EE"
+  #   )
+  #   
+  #   if result.success?
+  #     puts "Welcome, #{result.full_name}!"
+  #     log_successful_login(result.personal_code)
+  #   end
+  #
+  # @example Failed authentication result
+  #   result = AuthenticationResult.new(
+  #     session_id: "auth-456", 
+  #     status: :failed,
+  #     authenticated: false,
+  #     error: "Invalid PIN1"
+  #   )
+  #   
+  #   if result.failure?
+  #     puts "Authentication failed: #{result.error}"
+  #   end
+  class AuthenticationResult
+    # Result attributes containing authentication outcome and personal data
+    # @!attribute [rw] session_id
+    #   @return [String] ID of the session this result belongs to
+    # @!attribute [rw] status
+    #   @return [Symbol] Final authentication status (:completed, :failed, etc.)
+    # @!attribute [rw] authenticated
+    #   @return [Boolean] Whether authentication was successful
+    # @!attribute [rw] error
+    #   @return [String, nil] Error message if authentication failed
+    # @!attribute [rw] personal_code
+    #   @return [String, nil] Estonian 11-digit personal identification code
+    # @!attribute [rw] given_name
+    #   @return [String, nil] User's first/given name from certificate
+    # @!attribute [rw] surname  
+    #   @return [String, nil] User's family/last name from certificate
+    # @!attribute [rw] country
+    #   @return [String, nil] Country code from certificate (typically "EE")
+    attr_accessor :session_id, :status, :authenticated, :error,
+                  :personal_code, :given_name, :surname, :country
+
+    # Initialize a new authentication result with the provided attributes.
+    #
+    # Similar to AuthenticationSession, this uses flexible attribute assignment
+    # to allow setting result fields through a hash. The authenticated flag
+    # defaults to false to ensure secure defaults - authentication must be
+    # explicitly marked as successful.
+    #
+    # @param attributes [Hash] Result attributes to set
+    # @option attributes [String] :session_id Associated session ID
+    # @option attributes [Symbol] :status Authentication status
+    # @option attributes [Boolean] :authenticated Success flag
+    # @option attributes [String] :error Error message for failures
+    # @option attributes [String] :personal_code Estonian personal code
+    # @option attributes [String] :given_name User's first name
+    # @option attributes [String] :surname User's last name
+    # @option attributes [String] :country Country code
+    # @example
+    #   result = AuthenticationResult.new(
+    #     authenticated: true,
+    #     personal_code: "38001010008"
+    #   )
+    def initialize(attributes = {})
+      # Set provided attributes using dynamic attribute assignment
+      attributes.each do |key, value|
+        send("#{key}=", value) if respond_to?("#{key}=")
+      end
+      
+      # Ensure authenticated defaults to false for security
+      # Authentication must be explicitly set to true to be considered successful
+      @authenticated ||= false
+    end
+
+    # Check if the user was successfully authenticated.
+    #
+    # This is the primary method for determining authentication success.
+    # It directly returns the authenticated flag which should only be true
+    # if PIN verification succeeded and personal data was extracted.
+    #
+    # @return [Boolean] true if authentication was successful
+    def authenticated?
+      @authenticated
+    end
+
+    # Check if authentication was successful and no errors occurred.
+    #
+    # This method provides a more comprehensive success check than authenticated?
+    # by also ensuring no error occurred during the process. This catches cases
+    # where authentication might be marked as successful but an error was
+    # encountered during personal data extraction.
+    #
+    # @return [Boolean] true if authenticated and no error present
+    # @example
+    #   if result.success?
+    #     grant_access(result.personal_code)
+    #   else
+    #     show_error_message(result.error)
+    #   end
+    def success?
+      authenticated? && !error
+    end
+
+    # Check if authentication failed or encountered an error.
+    #
+    # This is the inverse of success? and provides a convenient way to check
+    # for any kind of authentication failure. Useful for error handling and
+    # conditional logic in authentication flows.
+    #
+    # @return [Boolean] true if authentication failed or error occurred
+    def failure?
+      !success?
+    end
+
+    # Get the user's full name by combining given name and surname.
+    #
+    # Estonian ID certificates store names in separate fields (given name and
+    # surname) following international X.509 certificate standards. This method
+    # provides a convenient way to get the complete name for display purposes.
+    #
+    # The method handles various edge cases:
+    # - Missing given name or surname (returns partial name)
+    # - Both names missing (returns nil)
+    # - Extra whitespace (cleaned up by join)
+    #
+    # @return [String, nil] Full name or nil if no name components available
+    # @example
+    #   result.given_name = "MARI"
+    #   result.surname = "MAASIKAS"  
+    #   puts result.full_name  # => "MARI MAASIKAS"
+    #   
+    #   result.given_name = nil
+    #   result.surname = "MAASIKAS"
+    #   puts result.full_name  # => "MAASIKAS"
+    def full_name
+      # Return nil if neither name component is available
+      return nil unless given_name || surname
+
+      # Combine available name components, filtering out nil values
+      # compact removes nil values, join combines with space
+      [given_name, surname].compact.join(" ")
+    end
+  end
+end

data/lib/ee_id_verification/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EeIdVerification
+  VERSION = "0.1.0"
+end

data/lib/ee_id_verification.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "ee_id_verification/version"
+require_relative "ee_id_verification/certificate_reader"
+require_relative "ee_id_verification/models"
+
+# Estonian ID card authentication library.
+#
+# Simple Ruby interface for authenticating users with Estonian ID cards
+# using local card readers. Focuses on DigiDoc Local authentication only.
+#
+# ## Basic Usage
+#
+#     require 'ee_id_verification'
+#
+#     # Create verifier
+#     verifier = EeIdVerification.new
+#
+#     # Check if ID card is available
+#     if verifier.available?
+#       # Authenticate user
+#       session = verifier.authenticate
+#       puts "Enter PIN1: "
+#       pin = gets.chomp
+#
+#       result = verifier.complete_authentication(session, pin)
+#       puts "Welcome #{result.full_name}!" if result.success?
+#     end
+#
+module EeIdVerification
+  # Generic error class for the gem.
+  class Error < StandardError; end
+
+  # Main verifier class
+  class Verifier
+    # Initialize the verifier
+    def initialize
+      @reader = CertificateReader.new
+      @sessions = {}
+    end
+
+    # Check if Estonian ID card authentication is available
+    # @return [Boolean] true if card and reader are present
+    def available?
+      @reader.card_present?
+    end
+
+    # Start authentication process
+    # @return [AuthenticationSession] session for PIN completion
+    def authenticate
+      raise Error, "No Estonian ID card detected" unless available?
+
+      session = AuthenticationSession.new(
+        id: SecureRandom.hex(16),
+        method: :digidoc_local,
+        status: :waiting_for_pin,
+        created_at: Time.now,
+        expires_at: Time.now + 300
+      )
+
+      @sessions[session.id] = session
+      session
+    end
+
+    # Complete authentication with PIN
+    # @param session [AuthenticationSession] session from authenticate
+    # @param pin [String] user's PIN1
+    # @return [AuthenticationResult] final result
+    def complete_authentication(session, pin)
+      stored_session = @sessions[session.id]
+      return failed_result(session.id, "Session not found") unless stored_session
+      return failed_result(session.id, "Session expired") if session.expired?
+
+      begin
+        @reader.connect
+        cert = @reader.read_auth_certificate(pin)
+        personal_data = @reader.extract_personal_data(cert)
+
+        @sessions.delete(session.id)
+
+        AuthenticationResult.new(
+          session_id: session.id,
+          status: :completed,
+          authenticated: true,
+          personal_code: personal_data[:personal_code],
+          given_name: personal_data[:given_name],
+          surname: personal_data[:surname],
+          country: personal_data[:country]
+        )
+      rescue StandardError => e
+        failed_result(session.id, e.message)
+      ensure
+        begin
+          @reader.disconnect
+        rescue StandardError
+          nil
+        end
+      end
+    end
+
+    private
+
+    def failed_result(session_id, error_message)
+      AuthenticationResult.new(
+        session_id: session_id,
+        status: :failed,
+        authenticated: false,
+        error: error_message
+      )
+    end
+  end
+
+  # Module-level convenience method
+  def self.new
+    Verifier.new
+  end
+end

data/script/test_id_card.rb

@@ -0,0 +1,255 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/ee_id_verification"
+require "openssl"
+
+def print_section(title)
+  puts "\n#{title}"
+  puts "=" * title.length
+end
+
+def print_subsection(title)
+  puts "\n#{title}:"
+  puts "-" * (title.length + 1)
+end
+
+def format_certificate_field(name, value)
+  if value.nil? || value.to_s.strip.empty?
+    puts "   #{name}: (not available)"
+  else
+    puts "   #{name}: #{value}"
+  end
+end
+
+def get_card_hardware_info
+  begin
+    # Get PKCS#11 library and slots directly
+    library = EeIdVerification::CertificateReader.shared_pkcs11_library
+    return { error: "PKCS#11 library not available" } unless library
+    
+    slots = library.slots(true)
+    esteid_slots = slots.select do |slot|
+      begin
+        token_info = slot.token_info
+        label = token_info.label.strip
+        manufacturer = token_info.manufacturerID.strip
+        
+        label.include?("ESTEID") ||
+          manufacturer.include?("SK") ||
+          label.match?(/PIN[12]/) ||
+          label.include?("Isikutuvastus")
+      rescue
+        false
+      end
+    end
+    
+    return { error: "No Estonian ID card slots found" } if esteid_slots.empty?
+    
+    slot = esteid_slots.first
+    token_info = slot.token_info
+    
+    {
+      token_label: token_info.label.strip,
+      token_manufacturer: token_info.manufacturerID.strip,
+      token_model: token_info.model.strip,
+      token_serial: token_info.serialNumber.strip,
+      slot_description: "Slot #{slot}"
+    }
+  rescue => e
+    { error: e.message }
+  end
+end
+
+puts "Estonian ID Card Test & Information Export"
+puts "=========================================="
+
+verifier = EeIdVerification.new
+reader = EeIdVerification::CertificateReader.new
+
+unless verifier.available?
+  puts "❌ No Estonian ID card detected"
+  puts "Please insert your ID card and ensure reader is connected"
+  exit 1
+end
+
+puts "✅ Estonian ID card detected"
+
+# Get hardware information before authentication
+print_section("Card Reader & Hardware Information")
+hardware_info = get_card_hardware_info
+
+if hardware_info[:error]
+  puts "⚠️  Could not retrieve hardware info: #{hardware_info[:error]}"
+else
+  format_certificate_field("Token Label", hardware_info[:token_label])
+  format_certificate_field("Token Manufacturer", hardware_info[:token_manufacturer])
+  format_certificate_field("Token Model", hardware_info[:token_model])
+  format_certificate_field("Token Serial Number", hardware_info[:token_serial])
+  format_certificate_field("Slot Description", hardware_info[:slot_description])
+end
+
+# Proceed with authentication
+session = verifier.authenticate
+puts "\n🔑 Enter your PIN1: "
+pin = gets.chomp
+
+result = verifier.complete_authentication(session, pin)
+
+if result.success?
+  print_section("🎉 Authentication Successful!")
+  
+  print_subsection("Basic Identity Information")
+  format_certificate_field("Full Name", result.full_name)
+  format_certificate_field("Given Name", result.given_name)
+  format_certificate_field("Surname", result.surname)
+  format_certificate_field("Personal Code", result.personal_code)
+  format_certificate_field("Country", result.country)
+  
+  # Parse personal code for detailed demographics
+  if result.personal_code
+    personal_info = reader.parse_personal_code(result.personal_code)
+    
+    if personal_info && !personal_info.empty?
+      print_subsection("Demographic Information")
+      format_certificate_field("Birth Date", personal_info[:birth_date])
+      format_certificate_field("Gender", personal_info[:gender])
+      format_certificate_field("Age", "#{personal_info[:age]} years")
+      
+      # Calculate additional demographics
+      if personal_info[:birth_date]
+        birth_year = personal_info[:birth_date].year
+        generation = case birth_year
+                    when 1946..1964 then "Baby Boomer"
+                    when 1965..1980 then "Generation X"
+                    when 1981..1996 then "Millennial"
+                    when 1997..2012 then "Generation Z"
+                    else "Generation Alpha"
+                    end
+        format_certificate_field("Generation", generation)
+        
+        # Century calculation
+        century_code = result.personal_code[0].to_i
+        century_info = case century_code
+                      when 1, 2 then "19th century (1800-1899)"
+                      when 3, 4 then "20th century (1900-1999)"
+                      when 5, 6 then "21st century (2000-2099)"
+                      when 7, 8 then "22nd century (2100-2199)"
+                      else "Unknown century"
+                      end
+        format_certificate_field("Birth Century", century_info)
+      end
+    end
+  end
+  
+  # Get detailed certificate information
+  begin
+    reader.connect
+    certificate = reader.read_auth_certificate(pin)
+    
+    print_subsection("Certificate Details")
+    format_certificate_field("Certificate Type", "Authentication Certificate (PIN1)")
+    format_certificate_field("Serial Number", certificate.serial.to_s)
+    format_certificate_field("Version", "v#{certificate.version}")
+    format_certificate_field("Valid From", certificate.not_before.strftime("%Y-%m-%d %H:%M:%S UTC"))
+    format_certificate_field("Valid Until", certificate.not_after.strftime("%Y-%m-%d %H:%M:%S UTC"))
+    
+    # Check if certificate is still valid
+    now = Time.now
+    if now < certificate.not_before
+      format_certificate_field("Status", "⚠️  Not yet valid")
+    elsif now > certificate.not_after
+      format_certificate_field("Status", "❌ Expired")
+    else
+      days_until_expiry = ((certificate.not_after - now) / (24 * 60 * 60)).to_i
+      format_certificate_field("Status", "✅ Valid (expires in #{days_until_expiry} days)")
+    end
+    
+    print_subsection("Certificate Issuer")
+    issuer_parts = certificate.issuer.to_a.to_h { |part| [part[0], part[1]] }
+    format_certificate_field("Common Name", issuer_parts["CN"])
+    format_certificate_field("Organization", issuer_parts["O"])
+    format_certificate_field("Country", issuer_parts["C"])
+    format_certificate_field("Email", issuer_parts["emailAddress"])
+    
+    print_subsection("Certificate Subject")
+    subject_parts = certificate.subject.to_a.to_h { |part| [part[0], part[1]] }
+    format_certificate_field("Common Name", subject_parts["CN"])
+    format_certificate_field("Given Name", subject_parts["GN"] || subject_parts["givenName"])
+    format_certificate_field("Surname", subject_parts["SN"] || subject_parts["surname"])
+    format_certificate_field("Serial Number", subject_parts["serialNumber"])
+    format_certificate_field("Country", subject_parts["C"])
+    format_certificate_field("Organization", subject_parts["O"])
+    format_certificate_field("Organizational Unit", subject_parts["OU"])
+    
+    print_subsection("Cryptographic Information")
+    public_key = certificate.public_key
+    format_certificate_field("Algorithm", certificate.signature_algorithm)
+    format_certificate_field("Public Key Type", public_key.class.name.split("::").last)
+    
+    if public_key.respond_to?(:n) # RSA key
+      key_size = public_key.n.to_s(2).length
+      format_certificate_field("Key Size", "#{key_size} bits")
+      format_certificate_field("Exponent", public_key.e.to_s)
+    end
+    
+    print_subsection("Certificate Extensions")
+    certificate.extensions.each do |ext|
+      case ext.oid
+      when "keyUsage"
+        format_certificate_field("Key Usage", ext.value)
+      when "extendedKeyUsage"
+        format_certificate_field("Extended Key Usage", ext.value)
+      when "subjectKeyIdentifier"
+        format_certificate_field("Subject Key ID", ext.value.gsub(":", " "))
+      when "authorityKeyIdentifier"
+        # Parse the authority key identifier
+        aki_value = ext.value.gsub("keyid:", "").split("\n").first
+        format_certificate_field("Authority Key ID", aki_value.gsub(":", " "))
+      when "certificatePolicies"
+        format_certificate_field("Certificate Policies", ext.value)
+      when "crlDistributionPoints"
+        format_certificate_field("CRL Distribution", ext.value.split("\n").join(", "))
+      when "authorityInfoAccess"
+        format_certificate_field("Authority Info Access", ext.value.split("\n").join(", "))
+      else
+        format_certificate_field(ext.oid, ext.value) if ext.value.length < 100
+      end
+    end
+    
+    print_subsection("Certificate Fingerprints")
+    cert_der = certificate.to_der
+    format_certificate_field("SHA-1", OpenSSL::Digest::SHA1.hexdigest(cert_der).upcase.scan(/.{2}/).join(":"))
+    format_certificate_field("SHA-256", OpenSSL::Digest::SHA256.hexdigest(cert_der).upcase.scan(/.{2}/).join(":"))
+    format_certificate_field("MD5", OpenSSL::Digest::MD5.hexdigest(cert_der).upcase.scan(/.{2}/).join(":"))
+    
+  rescue => e
+    puts "\n⚠️  Could not retrieve detailed certificate information: #{e.message}"
+  ensure
+    reader.disconnect rescue nil
+  end
+  
+else
+  puts "\n❌ Authentication failed: #{result.error}"
+  
+  # Provide helpful error guidance
+  case result.error
+  when /PIN/i
+    puts "\nTroubleshooting:"
+    puts "- Verify you're using PIN1 (not PIN2 for signing)"
+    puts "- Check if PIN is blocked (3 failed attempts)"
+    puts "- Use DigiDoc4 client to unblock PIN if needed"
+  when /card/i
+    puts "\nTroubleshooting:"
+    puts "- Ensure card is properly inserted"
+    puts "- Check card reader connection"
+    puts "- Try removing and reinserting the card"
+  when /certificate/i
+    puts "\nTroubleshooting:"
+    puts "- Your card may be expired or damaged"
+    puts "- Contact Estonian ID-card support: +372 677 3377"
+  end
+end
+
+puts "\n" + "=" * 50
+puts "Test completed at #{Time.now.strftime('%Y-%m-%d %H:%M:%S')}"