easy_code_sign 0.1.0

data/lib/easy_code_sign/errors.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module EasyCodeSign
+  # Base error class for all EasyCodeSign errors
+  class Error < StandardError; end
+
+  # Raised when configuration is invalid or incomplete
+  class ConfigurationError < Error; end
+
+  # Base class for all token-related errors
+  class TokenError < Error; end
+
+  # Raised when the hardware token is not found or not connected
+  class TokenNotFoundError < TokenError; end
+
+  # Raised when PIN entry fails (wrong PIN, locked, etc.)
+  class PinError < TokenError
+    attr_reader :retries_remaining
+
+    def initialize(message = "PIN verification failed", retries_remaining: nil)
+      @retries_remaining = retries_remaining
+      super(message)
+    end
+  end
+
+  # Raised when the token is locked due to too many failed PIN attempts
+  class TokenLockedError < TokenError; end
+
+  # Raised when the requested certificate/key is not found on the token
+  class KeyNotFoundError < TokenError; end
+
+  # Raised when a PKCS#11 operation fails
+  class Pkcs11Error < TokenError
+    attr_reader :pkcs11_error_code
+
+    def initialize(message, pkcs11_error_code: nil)
+      @pkcs11_error_code = pkcs11_error_code
+      super(message)
+    end
+  end
+
+  # Base class for signing-related errors
+  class SigningError < Error; end
+
+  # Raised when the file to be signed cannot be read or is invalid
+  class InvalidFileError < SigningError; end
+
+  # Raised when signature generation fails
+  class SignatureGenerationError < SigningError; end
+
+  # Base class for verification-related errors
+  class VerificationError < Error; end
+
+  # Raised when signature verification fails cryptographically
+  class InvalidSignatureError < VerificationError; end
+
+  # Raised when the signed file has been tampered with
+  class TamperedFileError < VerificationError; end
+
+  # Raised when certificate chain validation fails
+  class CertificateChainError < VerificationError
+    attr_reader :certificate, :reason
+
+    def initialize(message, certificate: nil, reason: nil)
+      @certificate = certificate
+      @reason = reason
+      super(message)
+    end
+  end
+
+  # Raised when a certificate has been revoked
+  class CertificateRevokedError < CertificateChainError; end
+
+  # Raised when a certificate has expired
+  class CertificateExpiredError < CertificateChainError; end
+
+  # Raised when the signing certificate is not trusted
+  class UntrustedCertificateError < CertificateChainError; end
+
+  # Base class for timestamp-related errors
+  class TimestampError < Error; end
+
+  # Raised when communication with the TSA fails
+  class TimestampAuthorityError < TimestampError
+    attr_reader :http_status
+
+    def initialize(message, http_status: nil)
+      @http_status = http_status
+      super(message)
+    end
+  end
+
+  # Raised when the TSA response is invalid or verification fails
+  class InvalidTimestampError < TimestampError; end
+
+  # Raised when a required timestamp is missing
+  class MissingTimestampError < TimestampError; end
+
+  # Base class for PDF-related errors
+  class PdfError < SigningError; end
+
+  # Raised when the PDF file is invalid or cannot be parsed
+  class InvalidPdfError < PdfError; end
+
+  # Raised when PDF signature operations fail
+  class PdfSignatureError < PdfError; end
+
+  # Raised when ByteRange calculation or verification fails
+  class ByteRangeError < PdfError; end
+
+  # Raised when deferred (two-phase) PDF signing fails
+  class DeferredSigningError < PdfError; end
+end

data/lib/easy_code_sign/pdf/appearance_builder.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module EasyCodeSign
+  module Pdf
+    # Builds visible signature appearance for PDF signatures
+    #
+    # Creates an appearance stream that displays signature information
+    # in the PDF document (signer name, date, reason, etc.)
+    #
+    class AppearanceBuilder
+      POSITIONS = {
+        top_left: ->(box) { [36, box.height - 36 - 50, 236, box.height - 36] },
+        top_right: ->(box) { [box.width - 236, box.height - 36 - 50, box.width - 36, box.height - 36] },
+        bottom_left: ->(box) { [36, 36, 236, 86] },
+        bottom_right: ->(box) { [box.width - 236, 36, box.width - 36, 86] }
+      }.freeze
+
+      def initialize(document, config, certificate)
+        @document = document
+        @config = config
+        @certificate = certificate
+      end
+
+      # Build appearance stream for visible signature
+      # @param widget [HexaPDF::Type::Annotations::Widget] the signature widget
+      # @return [void]
+      def build_appearance(widget)
+        rect = widget[:Rect].value
+        width = rect[2] - rect[0]
+        height = rect[3] - rect[1]
+
+        # Create appearance form XObject
+        form = @document.add({ Type: :XObject, Subtype: :Form, BBox: [0, 0, width, height] })
+        canvas = form.canvas
+
+        # Draw border
+        canvas.stroke_color(0, 0, 0)
+        canvas.line_width(1)
+        canvas.rectangle(0.5, 0.5, width - 1, height - 1)
+        canvas.stroke
+
+        # Draw text content
+        draw_signature_text(canvas, width, height)
+
+        # Set as widget's normal appearance
+        widget[:AP] = { N: form }
+      end
+
+      # Calculate signature rectangle for a given position
+      # @param page [HexaPDF::Type::Page] the page
+      # @param position [Symbol] position preset
+      # @return [Array<Numeric>] rectangle coordinates [x1, y1, x2, y2]
+      def self.calculate_rect(page, position, custom_rect: nil)
+        return custom_rect if custom_rect
+
+        box = page.box(:media)
+        calculator = POSITIONS[position.to_sym] || POSITIONS[:bottom_right]
+        calculator.call(box)
+      end
+
+      private
+
+      def draw_signature_text(canvas, width, height)
+        canvas.font("Helvetica", size: 8)
+        canvas.fill_color(0, 0, 0)
+
+        y_offset = height - 12
+        x_offset = 5
+
+        # Signer name
+        signer = extract_signer_name
+        canvas.text("Digitally signed by:", at: [x_offset, y_offset])
+        y_offset -= 10
+        canvas.text(signer, at: [x_offset, y_offset])
+        y_offset -= 12
+
+        # Reason (if provided)
+        if @config[:reason]
+          canvas.text("Reason: #{@config[:reason]}", at: [x_offset, y_offset])
+          y_offset -= 10
+        end
+
+        # Location (if provided)
+        if @config[:location]
+          canvas.text("Location: #{@config[:location]}", at: [x_offset, y_offset])
+          y_offset -= 10
+        end
+
+        # Date
+        canvas.text("Date: #{Time.now.strftime('%Y-%m-%d %H:%M:%S %Z')}", at: [x_offset, y_offset])
+      end
+
+      def extract_signer_name
+        # Try to extract CN from certificate subject
+        subject = @certificate.subject.to_a
+        cn = subject.find { |name, _, _| name == "CN" }
+        return cn[1] if cn
+
+        # Fallback to full subject
+        @certificate.subject.to_s
+      end
+    end
+  end
+end

data/lib/easy_code_sign/pdf/timestamp_handler.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module EasyCodeSign
+  module Pdf
+    # Adapts a pre-fetched timestamp token for HexaPDF's SignedDataCreator.
+    #
+    # HexaPDF's SignedDataCreator calls `timestamp_handler.sign(io, byte_range)`
+    # and embeds the return value as the id-aa-timeStampToken unsigned attribute.
+    # This handler returns the DER bytes of an already-obtained token rather than
+    # making a live TSA request.
+    #
+    # Supports both eager (TimestampToken) and lazy (Proc) modes:
+    #   - Eager: TimestampHandler.new(token)       — token already available
+    #   - Lazy:  TimestampHandler.new(-> { token }) — token resolved at sign time
+    #
+    class TimestampHandler
+      def initialize(timestamp_token)
+        @timestamp_token = timestamp_token
+      end
+
+      # Called by HexaPDF's SignedDataCreator#create_unsigned_attrs
+      # @param _io [IO] ignored — we already have the token
+      # @param _byte_range [Array] ignored
+      # @return [String, nil] DER-encoded timestamp token
+      def sign(_io, _byte_range)
+        token = @timestamp_token.respond_to?(:call) ? @timestamp_token.call : @timestamp_token
+        token&.token_der
+      end
+    end
+  end
+end

data/lib/easy_code_sign/providers/base.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module EasyCodeSign
+  module Providers
+    # Abstract base class for hardware token providers
+    #
+    # Subclasses must implement:
+    # - #connect - Establish connection to the token
+    # - #disconnect - Close connection to the token
+    # - #login(pin) - Authenticate with PIN
+    # - #logout - End authenticated session
+    # - #sign(data, algorithm:) - Sign data with the private key
+    # - #certificate - Return the signing certificate
+    # - #certificate_chain - Return the full certificate chain
+    #
+    class Base
+      attr_reader :configuration
+
+      def initialize(configuration)
+        @configuration = configuration
+        @connected = false
+        @logged_in = false
+      end
+
+      # Connect to the hardware token
+      # @raise [TokenNotFoundError] if token is not connected
+      # @return [void]
+      def connect
+        raise NotImplementedError, "#{self.class}#connect must be implemented"
+      end
+
+      # Disconnect from the hardware token
+      # @return [void]
+      def disconnect
+        raise NotImplementedError, "#{self.class}#disconnect must be implemented"
+      end
+
+      # Authenticate with PIN
+      # @param pin [String] the PIN for the token
+      # @raise [PinError] if PIN is incorrect
+      # @raise [TokenLockedError] if token is locked
+      # @return [void]
+      def login(pin)
+        raise NotImplementedError, "#{self.class}#login must be implemented"
+      end
+
+      # End authenticated session
+      # @return [void]
+      def logout
+        raise NotImplementedError, "#{self.class}#logout must be implemented"
+      end
+
+      # Sign data using the private key on the token
+      # @param data [String] the data to sign (typically a hash)
+      # @param algorithm [Symbol] signature algorithm (:sha256_rsa, :sha384_rsa, :sha512_rsa, etc.)
+      # @raise [SignatureGenerationError] if signing fails
+      # @return [String] the raw signature bytes
+      def sign(data, algorithm:)
+        raise NotImplementedError, "#{self.class}#sign must be implemented"
+      end
+
+      # Get the signing certificate from the token
+      # @raise [KeyNotFoundError] if no certificate is found
+      # @return [OpenSSL::X509::Certificate]
+      def certificate
+        raise NotImplementedError, "#{self.class}#certificate must be implemented"
+      end
+
+      # Get the full certificate chain from the token
+      # @return [Array<OpenSSL::X509::Certificate>] certificates ordered from leaf to root
+      def certificate_chain
+        raise NotImplementedError, "#{self.class}#certificate_chain must be implemented"
+      end
+
+      # Check if connected to the token
+      # @return [Boolean]
+      def connected?
+        @connected
+      end
+
+      # Check if authenticated (logged in)
+      # @return [Boolean]
+      def logged_in?
+        @logged_in
+      end
+
+      # List available slots/tokens
+      # @return [Array<Hash>] array of slot information hashes
+      def list_slots
+        raise NotImplementedError, "#{self.class}#list_slots must be implemented"
+      end
+
+      # Execute a block with automatic connect/login/logout/disconnect
+      # @param pin [String, nil] PIN for authentication (uses callback if nil)
+      # @yield [provider] yields self to the block
+      # @return [Object] result of the block
+      def with_session(pin: nil)
+        pin ||= request_pin
+        connect
+        login(pin)
+        yield self
+      ensure
+        logout if logged_in?
+        disconnect if connected?
+      end
+
+      protected
+
+      def log(level, message)
+        return unless configuration.logger
+
+        configuration.logger.send(level, "[EasyCodeSign] #{message}")
+      end
+
+      private
+
+      def request_pin
+        callback = configuration.pin_callback
+        raise ConfigurationError, "No PIN provided and no pin_callback configured" unless callback
+
+        slot_info = { slot_index: configuration.slot_index }
+        callback.call(slot_info)
+      end
+    end
+  end
+end

data/lib/easy_code_sign/providers/pkcs11_base.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "pkcs11"
+require "openssl"
+
+module EasyCodeSign
+  module Providers
+    # Base class for PKCS#11-based token providers
+    #
+    # Provides common functionality for tokens that use the PKCS#11 interface.
+    # Subclasses can override methods to handle token-specific behavior.
+    #
+    class Pkcs11Base < Base
+      # PKCS#11 mechanism mappings for signature algorithms
+      SIGNATURE_MECHANISMS = {
+        sha256_rsa: :CKM_SHA256_RSA_PKCS,
+        sha384_rsa: :CKM_SHA384_RSA_PKCS,
+        sha512_rsa: :CKM_SHA512_RSA_PKCS,
+        sha256_ecdsa: :CKM_ECDSA_SHA256,
+        sha384_ecdsa: :CKM_ECDSA_SHA384,
+        sha512_ecdsa: :CKM_ECDSA_SHA512
+      }.freeze
+
+      def initialize(configuration)
+        super
+        @pkcs11 = nil
+        @session = nil
+        @slot = nil
+      end
+
+      def connect
+        log :debug, "Loading PKCS#11 library: #{configuration.pkcs11_library}"
+        @pkcs11 = PKCS11.open(configuration.pkcs11_library)
+
+        slots = available_slots
+        raise TokenNotFoundError, "No tokens found in any slot" if slots.empty?
+
+        @slot = slots[configuration.slot_index]
+        raise TokenNotFoundError, "Slot #{configuration.slot_index} not found" unless @slot
+
+        log :debug, "Opening session on slot #{configuration.slot_index}"
+        @session = @slot.open(PKCS11::CKF_SERIAL_SESSION | PKCS11::CKF_RW_SESSION)
+        @connected = true
+      rescue PKCS11::Error => e
+        raise Pkcs11Error.new("Failed to connect: #{e.message}", pkcs11_error_code: e.error_code)
+      end
+
+      def disconnect
+        return unless @connected
+
+        log :debug, "Closing PKCS#11 session"
+        @session&.close
+        @pkcs11&.close
+        @session = nil
+        @pkcs11 = nil
+        @slot = nil
+        @connected = false
+      rescue PKCS11::Error => e
+        log :warn, "Error during disconnect: #{e.message}"
+      end
+
+      def login(pin)
+        raise TokenNotFoundError, "Not connected to token" unless @connected
+
+        log :debug, "Logging in to token"
+        @session.login(:USER, pin)
+        @logged_in = true
+      rescue PKCS11::Error => e
+        handle_login_error(e)
+      end
+
+      def logout
+        return unless @logged_in
+
+        log :debug, "Logging out from token"
+        @session&.logout
+        @logged_in = false
+      rescue PKCS11::Error => e
+        log :warn, "Error during logout: #{e.message}"
+        @logged_in = false
+      end
+
+      def sign(data, algorithm: :sha256_rsa)
+        raise TokenNotFoundError, "Not logged in" unless @logged_in
+
+        mechanism = SIGNATURE_MECHANISMS[algorithm]
+        raise SigningError, "Unsupported algorithm: #{algorithm}" unless mechanism
+
+        private_key = find_private_key
+        raise KeyNotFoundError, "No private key found on token" unless private_key
+
+        log :debug, "Signing #{data.bytesize} bytes with #{algorithm}"
+        @session.sign(mechanism, private_key, data)
+      rescue PKCS11::Error => e
+        raise SignatureGenerationError, "Signing failed: #{e.message}"
+      end
+
+      def certificate
+        @certificate ||= find_certificate
+      end
+
+      def certificate_chain
+        @certificate_chain ||= build_certificate_chain
+      end
+
+      def list_slots
+        @pkcs11 ||= PKCS11.open(configuration.pkcs11_library)
+        @pkcs11.slots.map.with_index do |slot, index|
+          token_info = begin
+            slot.token_info
+          rescue StandardError
+            nil
+          end
+
+          {
+            index: index,
+            description: slot.info.slot_description.strip,
+            token_present: token_info != nil,
+            token_label: token_info&.label&.strip,
+            manufacturer: token_info&.manufacturer_id&.strip,
+            serial: token_info&.serial_number&.strip
+          }
+        end
+      end
+
+      protected
+
+      def available_slots
+        @pkcs11.slots.select do |slot|
+          slot.token_info rescue false # Returns false if no token present
+        end
+      end
+
+      def find_private_key
+        @session.find_objects(CKA_CLASS: PKCS11::CKO_PRIVATE_KEY).first
+      end
+
+      def find_certificate
+        cert_obj = @session.find_objects(CKA_CLASS: PKCS11::CKO_CERTIFICATE).first
+        raise KeyNotFoundError, "No certificate found on token" unless cert_obj
+
+        cert_der = @session.get_attribute_value(cert_obj, :CKA_VALUE).first
+        OpenSSL::X509::Certificate.new(cert_der)
+      end
+
+      def build_certificate_chain
+        certs = @session.find_objects(CKA_CLASS: PKCS11::CKO_CERTIFICATE).map do |cert_obj|
+          cert_der = @session.get_attribute_value(cert_obj, :CKA_VALUE).first
+          OpenSSL::X509::Certificate.new(cert_der)
+        end
+
+        # Sort chain: leaf first, then intermediates, then root
+        sort_certificate_chain(certs)
+      end
+
+      def sort_certificate_chain(certs)
+        return certs if certs.size <= 1
+
+        # Find the leaf certificate (not an issuer of any other cert)
+        issuers = certs.map(&:subject).map(&:to_s)
+        leaf = certs.find { |c| !issuers.include?(c.issuer.to_s) || c.subject == c.issuer }
+
+        return certs unless leaf
+
+        # Build chain from leaf
+        chain = [leaf]
+        remaining = certs - [leaf]
+
+        while remaining.any?
+          current = chain.last
+          issuer = remaining.find { |c| c.subject.to_s == current.issuer.to_s }
+          break unless issuer
+
+          chain << issuer
+          remaining.delete(issuer)
+        end
+
+        chain
+      end
+
+      private
+
+      def handle_login_error(error)
+        case error.error_code
+        when PKCS11::CKR_PIN_INCORRECT
+          raise PinError, "Incorrect PIN"
+        when PKCS11::CKR_PIN_LOCKED
+          raise TokenLockedError, "Token is locked due to too many failed PIN attempts"
+        when PKCS11::CKR_PIN_EXPIRED
+          raise PinError, "PIN has expired and must be changed"
+        else
+          raise Pkcs11Error.new("Login failed: #{error.message}", pkcs11_error_code: error.error_code)
+        end
+      end
+    end
+  end
+end

data/lib/easy_code_sign/providers/safenet.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module EasyCodeSign
+  module Providers
+    # SafeNet eToken provider
+    #
+    # Implements PKCS#11 integration for SafeNet eToken hardware security tokens.
+    # These tokens are commonly used for code signing certificates.
+    #
+    # @example
+    #   provider = EasyCodeSign::Providers::Safenet.new(config)
+    #   provider.with_session(pin: "1234") do |p|
+    #     signature = p.sign(digest, algorithm: :sha256_rsa)
+    #   end
+    #
+    class Safenet < Pkcs11Base
+      # Default PKCS#11 library paths for SafeNet tokens
+      DEFAULT_LIBRARY_PATHS = {
+        darwin: [
+          "/usr/local/lib/libeToken.dylib",
+          "/Library/Frameworks/eToken.framework/Versions/Current/libeToken.dylib"
+        ],
+        linux: [
+          "/usr/lib/libeToken.so",
+          "/usr/lib/x86_64-linux-gnu/libeToken.so",
+          "/opt/safenet/eToken/lib/libeToken.so"
+        ],
+        windows: [
+          "C:\\Windows\\System32\\eToken.dll",
+          "C:\\Program Files\\SafeNet\\Authentication\\eToken PKI Client\\x64\\eToken.dll"
+        ]
+      }.freeze
+
+      def initialize(configuration)
+        super
+        auto_detect_library! if configuration.pkcs11_library.nil?
+      end
+
+      # SafeNet tokens may require specific initialization
+      def connect
+        log :info, "Connecting to SafeNet eToken"
+        super
+        log :info, "Connected to SafeNet eToken: #{token_label}"
+      end
+
+      # Get the token label/name
+      # @return [String]
+      def token_label
+        return nil unless @slot
+
+        @slot.token_info.label.strip
+      rescue PKCS11::Error
+        nil
+      end
+
+      # Get token serial number
+      # @return [String]
+      def serial_number
+        return nil unless @slot
+
+        @slot.token_info.serial_number.strip
+      rescue PKCS11::Error
+        nil
+      end
+
+      # Check if token requires PIN change
+      # @return [Boolean]
+      def pin_change_required?
+        return false unless @slot
+
+        flags = @slot.token_info.flags
+        (flags & PKCS11::CKF_USER_PIN_TO_BE_CHANGED) != 0
+      rescue PKCS11::Error
+        false
+      end
+
+      private
+
+      def auto_detect_library!
+        platform = detect_platform
+        paths = DEFAULT_LIBRARY_PATHS[platform] || []
+
+        found = paths.find { |path| File.exist?(path) }
+
+        if found
+          log :debug, "Auto-detected SafeNet library: #{found}"
+          configuration.pkcs11_library = found
+        else
+          raise ConfigurationError,
+                "SafeNet PKCS#11 library not found. Searched: #{paths.join(', ')}. " \
+                "Please set pkcs11_library explicitly."
+        end
+      end
+
+      def detect_platform
+        case RUBY_PLATFORM
+        when /darwin/
+          :darwin
+        when /linux/
+          :linux
+        when /mswin|mingw/
+          :windows
+        else
+          :linux # Default fallback
+        end
+      end
+    end
+  end
+end