easy_code_sign 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 795cefa5ad0f01177caeb61d8aaa3c910e6796a5d0f7caad13653a762ada80c1
+  data.tar.gz: 4a65763e2aa2e0396c285c5bf3d75e3dc36697cf4e5f50b4489403a4e0789489
+SHA512:
+  metadata.gz: 0ceaf7fcd326449fd314d493828ed33ca12b4c004f86e08cef72ab1f22212ce92525a4d9ee1aeed5f421dc8636c0504e7b78e75bb5530ef6da1e8aeda929002e
+  data.tar.gz: 0e59683b775e2809b102022b0f16dd3ed142e1fdb1296c83162e1f2fc0747b75440189ea43372f07518f99d7e95e2040af19713ea79fecaf47f03bd011c0fbf3

data/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **PDF Document Signing**
+  - Sign PDF documents (.pdf) with PKCS#7 digital signatures
+  - Visible signature annotations with customizable position (top-left, top-right, bottom-left, bottom-right)
+  - Signature metadata (reason, location, contact info)
+  - Page selection for signature placement
+  - RFC 3161 timestamp embedding in PDF signatures
+  - ByteRange-based signing for PDF incremental updates
+
+- **PDF Verification**
+  - Verify signed PDF documents
+  - ByteRange integrity checking
+  - Extract and display PDF signature metadata
+
+- **CLI Enhancements for PDF**
+  - `--visible-signature` - Add visible signature annotation
+  - `--signature-page` - Select page for signature
+  - `--signature-position` - Position preset (top_left, top_right, bottom_left, bottom_right)
+  - `--signature-reason` - Reason for signing
+  - `--signature-location` - Signing location
+
+### Dependencies
+
+- Added HexaPDF (~> 1.0) for PDF manipulation and signing
+
+## [0.1.0] - 2025-01-06
+
+### Added
+
+- **Core Signing Functionality**
+  - Sign Ruby gems (.gem) with PKCS#7 detached signatures compatible with `gem cert`
+  - Sign ZIP archives (.zip, .jar, .apk, .war, .ear) using JAR-style signing with META-INF manifest
+  - Batch signing support for multiple files in a single token session
+
+- **Hardware Token Support**
+  - SafeNet eToken integration via PKCS#11
+  - Extensible provider architecture for future HSM support
+  - Automatic PKCS#11 library detection on macOS, Linux, and Windows
+  - Secure PIN entry via interactive prompt (never passed as CLI argument)
+  - Token slot listing and management
+
+- **RFC 3161 Timestamping**
+  - Full RFC 3161 timestamp protocol support
+  - Compatible with common TSAs (DigiCert, GlobalSign, Sectigo, SSL.com)
+  - Timestamp verification with certificate chain validation
+  - Configurable hash algorithms (SHA-256, SHA-384, SHA-512)
+
+- **Signature Verification**
+  - Cryptographic signature validation
+  - File integrity checking (tamper detection)
+  - Certificate validity and expiration checking
+  - Certificate chain validation
+  - Trust anchor verification using system CA store or custom trust stores
+  - Timestamp validation for point-in-time verification
+  - Certificate revocation checking (OCSP with CRL fallback)
+
+- **Command-Line Interface**
+  - `easysign sign` - Sign files with hardware token
+  - `easysign verify` - Verify signed files with detailed output
+  - `easysign list-slots` - List available token slots
+  - `easysign info` - Display signature information
+  - JSON output option for scripting and automation
+  - Verbose and quiet modes
+
+- **Ruby API**
+  - Simple high-level API (`EasyCodeSign.sign`, `EasyCodeSign.verify`)
+  - Comprehensive configuration system
+  - Custom trust store support
+  - PIN callback for programmatic secure PIN entry
+  - Detailed result objects with structured error reporting
+
+- **Error Handling**
+  - 18 specific error types for clear diagnostics
+  - Hierarchical error classes for flexible rescue
+  - PIN retry tracking with lockout warnings
+  - Network timeout handling for TSA requests
+
+### Security
+
+- PINs are never logged, stored, or passed as command-line arguments
+- Secure interactive PIN prompt using `noecho` to prevent display
+- Private keys never leave the hardware token
+- Certificate revocation checking enabled by default
+
+[0.1.0]: https://github.com/mpantel/easy_code_sign/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 michail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,331 @@
+# EasyCodeSign
+
+A Ruby gem for signing and verifying Ruby gems, ZIP files, and PDF documents using hardware security tokens (HSM/smart cards). Currently supports SafeNet eToken with plans for additional providers.
+
+## Features
+
+- **Sign Ruby gems** (.gem) - Creates PKCS#7 signatures compatible with `gem cert`
+- **Sign ZIP archives** (.zip, .jar, .apk, .war, .ear) - JAR-style signing with META-INF manifest
+- **Sign PDF documents** (.pdf) - Digital signatures with optional visible annotations
+- **Hardware token support** - SafeNet eToken via PKCS#11 (extensible for other HSMs)
+- **RFC 3161 timestamping** - Proves signature existed at a specific time
+- **Full verification** - Signature, certificate chain, trust, and timestamp validation
+- **Certificate revocation checking** - OCSP and CRL support
+- **Command-line interface** - Easy-to-use CLI for signing and verification
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'easy_code_sign'
+```
+
+Or install directly:
+
+```bash
+gem install easy_code_sign
+```
+
+### Prerequisites
+
+- Ruby 3.2+
+- SafeNet eToken drivers and PKCS#11 library installed
+- Hardware token with code signing certificate
+
+## Command-Line Usage
+
+### Sign a file
+
+```bash
+# Basic signing (will prompt for PIN securely)
+easysign sign my_gem-1.0.0.gem
+
+# Sign with timestamp
+easysign sign my_gem-1.0.0.gem --timestamp --tsa http://timestamp.digicert.com
+
+# Sign with custom output path
+easysign sign archive.zip --output signed_archive.zip
+
+# Use specific PKCS#11 library
+easysign sign my_gem.gem --library /path/to/libeToken.dylib
+```
+
+### Sign a PDF
+
+```bash
+# Basic PDF signing (invisible signature)
+easysign sign document.pdf
+
+# PDF with visible signature annotation
+easysign sign document.pdf --visible-signature --signature-position bottom-right
+
+# PDF with timestamp and metadata
+easysign sign document.pdf -t --visible-signature --signature-reason "Approved" --signature-location "New York"
+
+# PDF signing on specific page
+easysign sign document.pdf --visible-signature --signature-page 2
+```
+
+> **Security Note:** The PIN is always entered interactively via a secure prompt.
+> It is never passed as a command-line argument to prevent exposure in shell
+> history, process listings, or log files.
+
+### Verify a signature
+
+```bash
+# Basic verification
+easysign verify signed.gem
+
+# Output as JSON
+easysign verify signed.gem --json
+
+# Use custom trust store
+easysign verify signed.gem --trust-store /path/to/ca-certs/
+```
+
+### List available tokens
+
+```bash
+easysign list-slots
+```
+
+### Show signature information
+
+```bash
+easysign info signed.gem
+```
+
+## Ruby API
+
+### Configuration
+
+```ruby
+require 'easy_code_sign'
+
+EasyCodeSign.configure do |config|
+  # Token provider (:safenet is currently supported)
+  config.provider = :safenet
+
+  # Path to PKCS#11 library (auto-detected if not specified)
+  config.pkcs11_library = '/usr/local/lib/libeToken.dylib'
+
+  # Token slot index (default: 0)
+  config.slot_index = 0
+
+  # Timestamp authority URL (optional)
+  config.timestamp_authority = 'http://timestamp.digicert.com'
+
+  # Hash algorithm for timestamps (default: :sha256)
+  config.timestamp_hash_algorithm = :sha256
+
+  # Require timestamp for all signatures (default: false)
+  config.require_timestamp = false
+
+  # Check certificate revocation during verification (default: true)
+  config.check_revocation = true
+
+  # Network timeout in seconds (default: 30)
+  config.network_timeout = 30
+
+  # Custom trust store path for verification (optional)
+  config.trust_store_path = '/path/to/custom/ca-certs'
+
+  # PIN callback for interactive PIN entry
+  config.pin_callback = ->(slot_info) {
+    print "Enter PIN for #{slot_info[:slot_index]}: "
+    $stdin.noecho(&:gets).chomp
+  }
+end
+```
+
+### Signing
+
+```ruby
+# Sign a gem
+result = EasyCodeSign.sign('my_gem-1.0.0.gem', pin: '1234')
+puts "Signed: #{result.file_path}"
+puts "Signer: #{result.signer_name}"
+
+# Sign with timestamp
+result = EasyCodeSign.sign('my_gem-1.0.0.gem',
+  pin: '1234',
+  timestamp: true
+)
+puts "Timestamp: #{result.timestamp}"
+
+# Sign with custom output path
+result = EasyCodeSign.sign('archive.zip',
+  pin: '1234',
+  output_path: 'signed_archive.zip',
+  algorithm: :sha256_rsa
+)
+
+# Batch signing (single token session)
+signer = EasyCodeSign.signer
+results = signer.sign_batch(
+  ['gem1.gem', 'gem2.gem', 'archive.zip'],
+  pin: '1234'
+)
+```
+
+### Verification
+
+```ruby
+# Verify a signed file
+result = EasyCodeSign.verify('signed.gem')
+
+if result.valid?
+  puts "Signature is valid!"
+  puts "Signed by: #{result.signer_name}"
+  puts "Organization: #{result.signer_organization}"
+
+  if result.timestamped?
+    puts "Timestamp: #{result.timestamp}"
+    puts "TSA: #{result.timestamp_authority}"
+  end
+else
+  puts "Verification failed:"
+  result.errors.each { |e| puts "  - #{e}" }
+end
+
+# Detailed verification status
+puts "Signature valid: #{result.signature_valid?}"
+puts "Integrity valid: #{result.integrity_valid?}"
+puts "Certificate valid: #{result.certificate_valid?}"
+puts "Chain valid: #{result.chain_valid?}"
+puts "Trusted: #{result.trusted?}"
+
+# Get full result as hash
+puts result.to_h
+
+# Use custom trust store
+trust_store = EasyCodeSign::Verification::TrustStore.new
+trust_store.add_file('/path/to/custom_ca.pem')
+result = EasyCodeSign.verify('signed.gem', trust_store: trust_store)
+
+# Batch verification
+verifier = EasyCodeSign.verifier
+results = verifier.verify_batch(['file1.gem', 'file2.zip'])
+results.each do |path, result|
+  puts "#{path}: #{result.valid? ? 'VALID' : 'INVALID'}"
+end
+```
+
+### Working with Tokens
+
+```ruby
+# List available token slots
+slots = EasyCodeSign.list_slots
+slots.each do |slot|
+  puts "Slot #{slot[:index]}: #{slot[:token_label]}"
+  puts "  Serial: #{slot[:serial]}"
+end
+
+# Direct provider access
+provider = EasyCodeSign.provider
+provider.with_session(pin: '1234') do |session|
+  cert = session.certificate
+  puts "Certificate: #{cert.subject}"
+  puts "Expires: #{cert.not_after}"
+
+  chain = session.certificate_chain
+  puts "Chain length: #{chain.length}"
+end
+```
+
+## Supported Timestamp Authorities
+
+Common free TSA endpoints:
+
+| Provider | URL |
+|----------|-----|
+| DigiCert | `http://timestamp.digicert.com` |
+| GlobalSign | `http://timestamp.globalsign.com/tsa/r6advanced1` |
+| Sectigo | `http://timestamp.sectigo.com` |
+| SSL.com | `http://ts.ssl.com` |
+
+## Error Handling
+
+```ruby
+begin
+  EasyCodeSign.sign('file.gem', pin: '1234')
+rescue EasyCodeSign::TokenNotFoundError
+  puts "Hardware token not connected"
+rescue EasyCodeSign::PinError => e
+  puts "PIN error: #{e.message}"
+  puts "Retries remaining: #{e.retries_remaining}" if e.retries_remaining
+rescue EasyCodeSign::TokenLockedError
+  puts "Token is locked - contact your administrator"
+rescue EasyCodeSign::TimestampAuthorityError => e
+  puts "Timestamp failed: #{e.message}"
+  puts "HTTP status: #{e.http_status}" if e.http_status
+rescue EasyCodeSign::InvalidFileError => e
+  puts "Invalid file: #{e.message}"
+rescue EasyCodeSign::Error => e
+  puts "Signing error: #{e.message}"
+end
+```
+
+## Architecture
+
+```
+EasyCodeSign
+├── Providers           # Hardware token abstraction
+│   ├── Base            # Abstract provider interface
+│   ├── Pkcs11Base      # Shared PKCS#11 functionality
+│   └── Safenet         # SafeNet eToken implementation
+├── Signable            # File type handlers
+│   ├── Base            # Abstract signable interface
+│   ├── GemFile         # Ruby gem signing
+│   └── ZipFile         # JAR-style ZIP signing
+├── Timestamp           # RFC 3161 timestamping
+│   ├── Client          # TSA HTTP client
+│   ├── Request         # TimeStampReq builder
+│   ├── Response        # TimeStampResp parser
+│   └── Verifier        # Timestamp verification
+├── Verification        # Signature verification
+│   ├── Result          # Verification result
+│   ├── TrustStore      # CA certificate management
+│   ├── CertificateChain# Chain validation
+│   └── SignatureChecker# Cryptographic verification
+├── Signer              # Signing orchestrator
+├── Verifier            # Verification orchestrator
+└── CLI                 # Command-line interface
+```
+
+## Security Considerations
+
+- **PINs are never passed as CLI arguments** - Always entered via secure interactive prompt
+- **PINs are never logged or stored** - Use `pin_callback` for programmatic secure entry
+- **Hardware tokens protect private keys** - Keys never leave the HSM
+- **Timestamps provide non-repudiation** - Signatures remain valid after certificate expiry
+- **Certificate revocation is checked** - OCSP (real-time) with CRL fallback
+- **System CA store is used by default** - Custom trust stores supported
+
+## Development
+
+```bash
+# Install dependencies
+bin/setup
+
+# Run tests
+bundle exec rake test
+
+# Run linter
+bundle exec rubocop
+
+# Interactive console
+bin/console
+
+# Install locally
+bundle exec rake install
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mpantel/easy_code_sign.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/exe/easysign

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "easy_code_sign"
+require "easy_code_sign/cli"
+
+EasyCodeSign::CLI.start(ARGV)