ssh-tresor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8e23a140ad7fd2c6f75c86669822b89e3cb5a640e099af9994dcd6b9acc4812f
+  data.tar.gz: 1012f7b0f6fb6dc97ead863eee8d0ae52857ff39edbd0ea7b3a41da403cc2c97
+SHA512:
+  metadata.gz: ae65b38efa4debb392042bd0476d63ecebe08971fb33555fef4c0e01ac8333eaacb05832f0fdbd1089f226d471308709d3e80cfaed3def793aeebc8ff5609e3e
+  data.tar.gz: c972fb2e7d43e58c862501f4e9dc74383f7b68feac777bac3c8b676a3c2f17a0063d28e2bb82a651fffe6ae76835401d3f24c092c26b2bb4bba52f0f57af3dcc

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 ssh-tresor-ruby contributors
+
+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,63 @@
+# ssh-tresor-ruby
+
+`ssh-tresor` encrypts and decrypts secrets using keys available through
+`ssh-agent`.
+
+The private key never leaves the SSH agent. Encryption creates a random master
+key, asks the agent to sign random per-key challenges, derives slot keys with
+HKDF-SHA256, and stores an AES-256-GCM encrypted master key slot for each SSH
+key. Decryption works when one matching SSH key is loaded locally or forwarded
+with `ssh -A`.
+
+It is freely inspired by the [`ssh-tresor`][1] project but doesn't depend
+on it.
+
+[1]: https://github.com/haraldh/ssh-tresor
+
+## Usage
+
+```sh
+ssh-tresor list-keys
+echo -n "secret" | ssh-tresor encrypt -a > secret.tresor
+ssh-tresor decrypt secret.tresor
+ssh-tresor list-slots secret.tresor
+ssh-tresor add-key -k SHA256:abc < secret.tresor > updated.tresor
+ssh-tresor remove-key -k SHA256:abc < updated.tresor > reduced.tresor
+```
+
+## Library API
+
+Other gems can depend on `ssh-tresor-ruby` and call it directly:
+
+```ruby
+require "ssh_tresor"
+
+vault = SshTresor::Vault.new
+
+encrypted = vault.encrypt("secret", armor: true)
+plaintext = vault.decrypt(encrypted)
+
+updated = vault.add_key(encrypted, fingerprint: "SHA256:abc", armor: true)
+slots = vault.list_slots(updated)
+keys = vault.list_keys
+```
+
+The `Vault` instance connects to `SSH_AUTH_SOCK` by default. You can inject a
+custom agent object for tests or alternate transports:
+
+```ruby
+vault = SshTresor::Vault.new(agent: my_agent)
+```
+
+The lower-level `SshTresor::TresorBlob` parser and `SshTresor::Tresor` module
+remain available if you need direct access to parsed slots.
+
+## Wire Format
+
+The implementation writes and reads the `SSHTRESR` v3 format:
+
+```text
+Header:  SSHTRESR (8) + version (1) + slot_count (1)
+Slot:    fingerprint (32) + challenge (32) + nonce (12) + encrypted_key (48)
+Data:    nonce (12) + ciphertext including 16-byte AES-GCM auth tag
+```

data/exe/ssh-tresor

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ssh_tresor/cli"
+
+exit SshTresor::CLI.new(ARGV).run
+

data/lib/ssh_tresor/agent.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "base64"
+require "digest"
+require "socket"
+
+require_relative "error"
+require_relative "ssh_encoding"
+
+module SshTresor
+  AgentKey = Struct.new(:blob, :comment, keyword_init: true) do
+    def fingerprint_bytes
+      @fingerprint_bytes ||= Digest::SHA256.digest(blob)
+    end
+
+    def fingerprint
+      "SHA256:#{Base64.strict_encode64(fingerprint_bytes).delete("=")}"
+    end
+
+    def md5_fingerprint
+      Digest::MD5.digest(blob).bytes.map { |byte| "%02x" % byte }.join(":")
+    end
+
+    def ssh_type
+      @ssh_type ||= SSHEncoding::Reader.new(blob).string
+    end
+
+    def key_type
+      @key_type ||= Agent.format_key_type(blob)
+    end
+
+    def security_key?
+      ssh_type.start_with?("sk-")
+    end
+
+    def matches_fingerprint?(prefix)
+      normalized_prefix = prefix.delete_prefix("SHA256:")
+      normalized_fingerprint = fingerprint.delete_prefix("SHA256:")
+      normalized_fingerprint.start_with?(normalized_prefix)
+    end
+
+    def to_s
+      "#{fingerprint} #{key_type} #{comment}"
+    end
+  end
+
+  class Agent
+    SSH_AGENT_FAILURE = 5
+    SSH_AGENTC_REQUEST_IDENTITIES = 11
+    SSH_AGENT_IDENTITIES_ANSWER = 12
+    SSH_AGENTC_SIGN_REQUEST = 13
+    SSH_AGENT_SIGN_RESPONSE = 14
+    SSH_AGENT_SIGN_REQUEST_RSA_SHA2_256 = 2
+
+    def self.connect
+      socket_path = ENV["SSH_AUTH_SOCK"]
+      raise AgentError, "SSH agent not available\nHint: Is SSH_AUTH_SOCK set? Try running: eval $(ssh-agent) && ssh-add" if socket_path.nil? || socket_path.empty?
+
+      new(UNIXSocket.new(socket_path))
+    rescue SystemCallError => e
+      raise AgentError, "Failed to connect to SSH agent: #{e.message}"
+    end
+
+    def self.format_key_type(blob)
+      reader = SSHEncoding::Reader.new(blob)
+      type = reader.string
+
+      case type
+      when "ssh-ed25519"
+        "ED25519"
+      when "ssh-rsa"
+        reader.string
+        n = reader.string
+        "RSA-#{bit_length(n)}"
+      when /\Aecdsa-sha2-/
+        curve = reader.string
+        "ECDSA-#{curve.delete_prefix("nistp")}"
+      when "sk-ssh-ed25519@openssh.com"
+        "SK-ED25519"
+      when "sk-ecdsa-sha2-nistp256@openssh.com"
+        "SK-ECDSA-256"
+      else
+        type.upcase
+      end
+    rescue Error
+      "UNKNOWN"
+    end
+
+    def self.bit_length(bytes)
+      trimmed = bytes.b.sub(/\A\x00+/n, "")
+      return 0 if trimmed.empty?
+
+      ((trimmed.bytesize - 1) * 8) + trimmed.getbyte(0).bit_length
+    end
+
+    def initialize(socket)
+      @socket = socket
+    end
+
+    def list_keys
+      response = request(SSHEncoding.byte(SSH_AGENTC_REQUEST_IDENTITIES))
+      reader = SSHEncoding::Reader.new(response)
+      type = reader.byte
+      raise AgentError, "SSH agent refused identity request" if type == SSH_AGENT_FAILURE
+      raise AgentError, "Unexpected SSH agent response type #{type}" unless type == SSH_AGENT_IDENTITIES_ANSWER
+
+      count = reader.uint32
+      Array.new(count) do
+        blob = reader.string
+        comment = reader.string.force_encoding(Encoding::UTF_8)
+        comment = comment.valid_encoding? ? comment : comment.b.inspect
+        AgentKey.new(blob: blob, comment: comment)
+      end
+    end
+
+    def first_key
+      list_keys.first || raise(KeyNotFound, "No keys available in SSH agent\nHint: Try running: ssh-add")
+    end
+
+    def find_key(fingerprint)
+      matches = list_keys.select { |key| key.matches_fingerprint?(fingerprint) }
+
+      case matches.length
+      when 0
+        raise KeyNotFound, "Key not found: #{fingerprint}\nHint: Use 'ssh-tresor list-keys' to see available keys"
+      when 1
+        matches.first
+      else
+        raise KeyNotFound, "Key not found: #{fingerprint} (ambiguous: #{matches.length} keys match this prefix, please be more specific)"
+      end
+    end
+
+    def find_key_by_fingerprint_bytes(fingerprint_bytes)
+      list_keys.find { |key| key.fingerprint_bytes == fingerprint_bytes } ||
+        raise(KeyNotFound, "Key not found: SHA256:#{Base64.strict_encode64(fingerprint_bytes).delete("=")}")
+    end
+
+    def sign(key, data)
+      flags = key.ssh_type == "ssh-rsa" ? SSH_AGENT_SIGN_REQUEST_RSA_SHA2_256 : 0
+      payload = SSHEncoding.byte(SSH_AGENTC_SIGN_REQUEST) +
+                SSHEncoding.string(key.blob) +
+                SSHEncoding.string(data) +
+                SSHEncoding.uint32(flags)
+
+      response = request(payload)
+      reader = SSHEncoding::Reader.new(response)
+      type = reader.byte
+      raise AgentError, "SSH agent refused signing request" if type == SSH_AGENT_FAILURE
+      raise AgentError, "Unexpected SSH agent response type #{type}" unless type == SSH_AGENT_SIGN_RESPONSE
+
+      signature_blob = reader.string
+      signature_reader = SSHEncoding::Reader.new(signature_blob)
+      signature_reader.string
+      signature_reader.string
+    end
+
+    private
+
+    def request(payload)
+      @socket.write(SSHEncoding.uint32(payload.bytesize))
+      @socket.write(payload)
+
+      length = read_exact(4).unpack1("N")
+      read_exact(length)
+    rescue IOError, SystemCallError => e
+      raise AgentError, "SSH agent communication failed: #{e.message}"
+    end
+
+    def read_exact(length)
+      buffer = +"".b
+      while buffer.bytesize < length
+        chunk = @socket.read(length - buffer.bytesize)
+        raise AgentError, "SSH agent closed connection" if chunk.nil?
+
+        buffer << chunk
+      end
+      buffer
+    end
+  end
+end
+

data/lib/ssh_tresor/cli.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "base64"
+require "optparse"
+
+require_relative "../ssh_tresor"
+
+module SshTresor
+  class CLI
+    def initialize(argv)
+      @argv = argv.dup
+    end
+
+    def run
+      command = @argv.shift
+      return help if command.nil? || %w[-h --help help].include?(command)
+      return version if %w[-v --version version].include?(command)
+
+      case command
+      when "encrypt"
+        encrypt_command
+      when "decrypt"
+        decrypt_command
+      when "add-key"
+        add_key_command
+      when "remove-key"
+        remove_key_command
+      when "list-slots"
+        list_slots_command
+      when "list-keys"
+        list_keys_command
+      else
+        warn "Unknown command: #{command}"
+        help(1)
+      end
+    rescue Error => e
+      warn "Error: #{e.message}"
+      e.exit_code
+    rescue OptionParser::ParseError => e
+      warn "Error: #{e.message}"
+      Error::EXIT_GENERAL_ERROR
+    end
+
+    private
+
+    def help(exit_code = 0)
+      io = exit_code.zero? ? $stdout : $stderr
+      io.puts <<~HELP
+        Usage: ssh-tresor <command> [options]
+
+        Commands:
+          encrypt       Encrypt data using SSH keys from the agent
+          decrypt       Decrypt data using an SSH key from the agent
+          add-key       Add a key to an existing tresor
+          remove-key    Remove a key from an existing tresor
+          list-slots    List key slots in a tresor
+          list-keys     List available keys in the SSH agent
+      HELP
+      exit_code
+    end
+
+    def version
+      puts SshTresor::VERSION
+      0
+    end
+
+    def encrypt_command
+      options = { fingerprints: [], armor: false }
+      parser = OptionParser.new do |opts|
+        opts.on("-k", "--key FINGERPRINT") { |value| options[:fingerprints] << value }
+        opts.on("-o", "--output FILE") { |value| options[:output] = value }
+        opts.on("-a", "--armor") { options[:armor] = true }
+      end
+      parser.parse!(@argv)
+
+      plaintext = read_input(@argv.shift)
+      blob = Tresor.encrypt(plaintext, fingerprints: options[:fingerprints])
+      output = options[:armor] ? blob.to_armored : blob.to_bytes
+      write_output(options[:output], output)
+      0
+    end
+
+    def decrypt_command
+      options = {}
+      parser = OptionParser.new do |opts|
+        opts.on("-o", "--output FILE") { |value| options[:output] = value }
+      end
+      parser.parse!(@argv)
+
+      encrypted = read_input(@argv.shift)
+      blob = TresorBlob.from_bytes(encrypted)
+      write_output(options[:output], Tresor.decrypt(blob))
+      0
+    end
+
+    def add_key_command
+      options = { all: false, armor: false, in_place: false }
+      parser = OptionParser.new do |opts|
+        opts.on("-k", "--key FINGERPRINT") { |value| options[:fingerprint] = value }
+        opts.on("-a", "--all") { options[:all] = true }
+        opts.on("-i", "--in-place") { options[:in_place] = true }
+        opts.on("-o", "--output FILE") { |value| options[:output] = value }
+        opts.on("--armor") { options[:armor] = true }
+      end
+      parser.parse!(@argv)
+
+      raise Error, "Invalid arguments: either --key or --all must be specified" if options[:fingerprint].nil? && !options[:all]
+      raise Error, "Invalid arguments: --key and --all are mutually exclusive" if options[:fingerprint] && options[:all]
+
+      input = @argv.shift
+      encrypted = read_input(input)
+      was_armored = armored?(encrypted)
+      blob = TresorBlob.from_bytes(encrypted)
+
+      updated = if options[:all]
+                  new_blob, added = Tresor.add_all_keys(blob)
+                  warn(added.zero? ? "No new keys added (all keys already present or unavailable)" : "Added #{added} key(s)")
+                  new_blob
+                else
+                  Tresor.add_key(blob, options[:fingerprint])
+                end
+
+      output = serialize(updated, options[:armor] || was_armored)
+      write_output(options[:in_place] ? input : options[:output], output)
+      0
+    end
+
+    def remove_key_command
+      options = { armor: false, in_place: false }
+      parser = OptionParser.new do |opts|
+        opts.on("-k", "--key FINGERPRINT") { |value| options[:fingerprint] = value }
+        opts.on("-i", "--in-place") { options[:in_place] = true }
+        opts.on("-o", "--output FILE") { |value| options[:output] = value }
+        opts.on("--armor") { options[:armor] = true }
+      end
+      parser.parse!(@argv)
+
+      raise Error, "Invalid arguments: --key is required" if options[:fingerprint].nil?
+
+      input = @argv.shift
+      encrypted = read_input(input)
+      was_armored = armored?(encrypted)
+      blob = TresorBlob.from_bytes(encrypted)
+      updated = Tresor.remove_key(blob, options[:fingerprint])
+      output = serialize(updated, options[:armor] || was_armored)
+      write_output(options[:in_place] ? input : options[:output], output)
+      0
+    end
+
+    def list_slots_command
+      encrypted = read_input(@argv.shift)
+      blob = TresorBlob.from_bytes(encrypted)
+      agent_keys = begin
+        Tresor.list_keys
+      rescue AgentError
+        []
+      end
+
+      puts "Tresor contains #{blob.slots.length} key slot(s):"
+      blob.slot_fingerprints.each_with_index do |fingerprint, index|
+        fingerprint_text = "SHA256:#{Base64.strict_encode64(fingerprint).delete("=")}"
+        key = agent_keys.find { |agent_key| agent_key.fingerprint_bytes == fingerprint }
+        availability = key ? " #{key.key_type} #{key.comment} [AVAILABLE]" : ""
+        puts "  Slot #{index + 1}: #{fingerprint_text}#{availability}"
+      end
+      0
+    end
+
+    def list_keys_command
+      options = { md5: false }
+      parser = OptionParser.new do |opts|
+        opts.on("--md5") { options[:md5] = true }
+      end
+      parser.parse!(@argv)
+
+      keys = Tresor.list_keys
+      raise KeyNotFound, "No keys available in SSH agent\nHint: Try running: ssh-add" if keys.empty?
+
+      keys.each do |key|
+        puts(options[:md5] ? "#{key.md5_fingerprint} #{key.key_type} #{key.comment}" : key.to_s)
+      end
+      0
+    end
+
+    def read_input(path)
+      bytes = if path.nil? || path == "-"
+                $stdin.binmode.read
+              else
+                File.binread(path)
+              end
+
+      if bytes.bytesize > TresorBlob::MAX_TRESOR_SIZE
+        raise Error, "Invalid tresor format: input too large: #{bytes.bytesize} bytes, maximum #{TresorBlob::MAX_TRESOR_SIZE} bytes"
+      end
+
+      bytes
+    end
+
+    def write_output(path, data)
+      if path.nil?
+        $stdout.binmode.write(data)
+      else
+        File.binwrite(path, data)
+      end
+    end
+
+    def armored?(data)
+      data.b.strip.start_with?(TresorBlob::ARMOR_BEGIN)
+    end
+
+    def serialize(blob, armor)
+      armor ? blob.to_armored : blob.to_bytes
+    end
+  end
+end

data/lib/ssh_tresor/crypto.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+require_relative "error"
+
+module SshTresor
+  module Crypto
+    CHALLENGE_SIZE = 32
+    MASTER_KEY_SIZE = 32
+    NONCE_SIZE = 12
+    AUTH_TAG_SIZE = 16
+
+    module_function
+
+    def random_challenge
+      SecureRandom.random_bytes(CHALLENGE_SIZE)
+    end
+
+    def random_master_key
+      SecureRandom.random_bytes(MASTER_KEY_SIZE)
+    end
+
+    def random_nonce
+      SecureRandom.random_bytes(NONCE_SIZE)
+    end
+
+    def derive_key(signature)
+      OpenSSL::KDF.hkdf(
+        signature,
+        salt: "ssh-tresor-v3",
+        info: "slot-key-derivation",
+        length: 32,
+        hash: "SHA256"
+      )
+    end
+
+    def encrypt(key, nonce, plaintext)
+      cipher = OpenSSL::Cipher.new("aes-256-gcm")
+      cipher.encrypt
+      cipher.key = key
+      cipher.iv = nonce
+      cipher.auth_data = "".b
+
+      ciphertext = cipher.update(plaintext.b) + cipher.final
+      ciphertext + cipher.auth_tag
+    rescue OpenSSL::Cipher::CipherError => e
+      raise Error, "Encryption failed: AES-GCM encryption failed: #{e.message}"
+    end
+
+    def decrypt(key, nonce, ciphertext_with_tag)
+      raise DecryptionError, "ciphertext too short" if ciphertext_with_tag.bytesize < AUTH_TAG_SIZE
+
+      ciphertext = ciphertext_with_tag.byteslice(0, ciphertext_with_tag.bytesize - AUTH_TAG_SIZE)
+      tag = ciphertext_with_tag.byteslice(-AUTH_TAG_SIZE, AUTH_TAG_SIZE)
+
+      cipher = OpenSSL::Cipher.new("aes-256-gcm")
+      cipher.decrypt
+      cipher.key = key
+      cipher.iv = nonce
+      cipher.auth_tag = tag
+      cipher.auth_data = "".b
+
+      cipher.update(ciphertext) + cipher.final
+    rescue OpenSSL::Cipher::CipherError
+      raise DecryptionError, "authentication failed - wrong key or corrupted data"
+    end
+  end
+end
+

data/lib/ssh_tresor/error.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module SshTresor
+  class Error < StandardError
+    EXIT_GENERAL_ERROR = 1
+    EXIT_AGENT_CONNECTION_FAILED = 2
+    EXIT_KEY_NOT_FOUND = 3
+    EXIT_DECRYPTION_FAILED = 4
+
+    attr_reader :exit_code
+
+    def initialize(message, exit_code: EXIT_GENERAL_ERROR)
+      super(message)
+      @exit_code = exit_code
+    end
+  end
+
+  class AgentError < Error
+    def initialize(message)
+      super(message, exit_code: EXIT_AGENT_CONNECTION_FAILED)
+    end
+  end
+
+  class KeyNotFound < Error
+    def initialize(message)
+      super(message, exit_code: EXIT_KEY_NOT_FOUND)
+    end
+  end
+
+  class NoMatchingSlot < Error
+    def initialize
+      super(
+        "No matching slot found\nHint: None of the keys in your SSH agent can decrypt this tresor",
+        exit_code: EXIT_KEY_NOT_FOUND
+      )
+    end
+  end
+
+  class DecryptionError < Error
+    def initialize(message)
+      super("Decryption failed: #{message}", exit_code: EXIT_DECRYPTION_FAILED)
+    end
+  end
+end
+

data/lib/ssh_tresor/format.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "base64"
+
+require_relative "crypto"
+require_relative "error"
+
+module SshTresor
+  Slot = Struct.new(:fingerprint, :challenge, :nonce, :encrypted_key, keyword_init: true) do
+    def to_bytes
+      fingerprint + challenge + nonce + encrypted_key
+    end
+  end
+
+  class TresorBlob
+    MAGIC = "SSHTRESR".b
+    VERSION = 0x03
+    FINGERPRINT_SIZE = 32
+    CHALLENGE_SIZE = 32
+    NONCE_SIZE = 12
+    AUTH_TAG_SIZE = 16
+    MASTER_KEY_SIZE = 32
+    ENCRYPTED_KEY_SIZE = MASTER_KEY_SIZE + AUTH_TAG_SIZE
+    SLOT_SIZE = FINGERPRINT_SIZE + CHALLENGE_SIZE + NONCE_SIZE + ENCRYPTED_KEY_SIZE
+    HEADER_SIZE = 10
+    MAX_TRESOR_SIZE = 100 * 1024 * 1024
+    ARMOR_BEGIN = "-----BEGIN SSH TRESOR-----"
+    ARMOR_END = "-----END SSH TRESOR-----"
+
+    attr_reader :slots, :data_nonce, :ciphertext
+
+    def self.from_bytes(data)
+      bytes = data.b
+      if bytes.valid_encoding? && bytes.strip.start_with?(ARMOR_BEGIN)
+        from_armored(bytes)
+      else
+        from_binary(bytes)
+      end
+    end
+
+    def self.from_armored(text)
+      start = text.index(ARMOR_BEGIN)
+      finish = text.index(ARMOR_END)
+      raise Error, "Invalid tresor format: missing BEGIN header" if start.nil?
+      raise Error, "Invalid tresor format: missing END footer" if finish.nil?
+      raise Error, "Invalid tresor format: invalid armor structure" if start >= finish
+
+      base64 = text[(start + ARMOR_BEGIN.length)...finish].chars.reject { |char| char =~ /\s/ }.join
+      from_binary(Base64.strict_decode64(base64))
+    rescue ArgumentError => e
+      raise Error, "Invalid tresor format: base64 decoding failed: #{e.message}"
+    end
+
+    def self.from_binary(data)
+      min_size = HEADER_SIZE + SLOT_SIZE + NONCE_SIZE + AUTH_TAG_SIZE
+      raise Error, "Invalid tresor format: data too short: #{data.bytesize} bytes, minimum #{min_size} required" if data.bytesize < min_size
+      raise Error, "Invalid tresor format: invalid magic header" unless data.byteslice(0, 8) == MAGIC
+
+      version = data.getbyte(8)
+      raise Error, "Invalid tresor format: unsupported version: #{version}, expected #{VERSION}" unless version == VERSION
+
+      slot_count = data.getbyte(9)
+      raise Error, "Invalid tresor format: tresor has no key slots" if slot_count.zero?
+
+      slots_end = HEADER_SIZE + (slot_count * SLOT_SIZE)
+      raise Error, "Invalid tresor format: data too short for #{slot_count} slots" if data.bytesize < slots_end + NONCE_SIZE + AUTH_TAG_SIZE
+
+      slots = Array.new(slot_count) do |index|
+        offset = HEADER_SIZE + (index * SLOT_SIZE)
+        parse_slot(data.byteslice(offset, SLOT_SIZE))
+      end
+
+      data_nonce = data.byteslice(slots_end, NONCE_SIZE)
+      ciphertext = data.byteslice(slots_end + NONCE_SIZE, data.bytesize - slots_end - NONCE_SIZE)
+
+      new(slots: slots, data_nonce: data_nonce, ciphertext: ciphertext)
+    end
+
+    def self.parse_slot(bytes)
+      raise Error, "Invalid tresor format: slot data too short" if bytes.bytesize < SLOT_SIZE
+
+      offset = 0
+      fingerprint = bytes.byteslice(offset, FINGERPRINT_SIZE)
+      offset += FINGERPRINT_SIZE
+      challenge = bytes.byteslice(offset, CHALLENGE_SIZE)
+      offset += CHALLENGE_SIZE
+      nonce = bytes.byteslice(offset, NONCE_SIZE)
+      offset += NONCE_SIZE
+      encrypted_key = bytes.byteslice(offset, ENCRYPTED_KEY_SIZE)
+
+      Slot.new(
+        fingerprint: fingerprint,
+        challenge: challenge,
+        nonce: nonce,
+        encrypted_key: encrypted_key
+      )
+    end
+
+    def initialize(slots:, data_nonce:, ciphertext:)
+      @slots = slots
+      @data_nonce = data_nonce
+      @ciphertext = ciphertext
+    end
+
+    def to_bytes
+      raise Error, "Invalid tresor format: tresor has no key slots" if slots.empty?
+      raise Error, "Invalid tresor format: tresor has too many slots (max 255)" if slots.length > 255
+
+      MAGIC + [VERSION, slots.length].pack("CC") + slots.map(&:to_bytes).join.b + data_nonce + ciphertext
+    end
+
+    def to_armored
+      encoded = Base64.strict_encode64(to_bytes)
+      wrapped = encoded.scan(/.{1,64}/).join("\n")
+      "#{ARMOR_BEGIN}\n#{wrapped}\n#{ARMOR_END}\n"
+    end
+
+    def find_slot(fingerprint)
+      slots.find { |slot| slot.fingerprint == fingerprint }
+    end
+
+    def slot_fingerprints
+      slots.map(&:fingerprint)
+    end
+  end
+end
+

data/lib/ssh_tresor/ssh_encoding.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module SshTresor
+  module SSHEncoding
+    module_function
+
+    def byte(value)
+      value.chr.b
+    end
+
+    def uint32(value)
+      [value].pack("N")
+    end
+
+    def string(value)
+      bytes = value.b
+      uint32(bytes.bytesize) + bytes
+    end
+
+    class Reader
+      def initialize(data)
+        @data = data.b
+        @offset = 0
+      end
+
+      def byte
+        read(1).getbyte(0)
+      end
+
+      def uint32
+        read(4).unpack1("N")
+      end
+
+      def string
+        length = uint32
+        read(length)
+      end
+
+      def eof?
+        @offset == @data.bytesize
+      end
+
+      private
+
+      def read(length)
+        raise Error, "Invalid SSH wire data: short read" if @offset + length > @data.bytesize
+
+        bytes = @data.byteslice(@offset, length)
+        @offset += length
+        bytes
+      end
+    end
+  end
+end
+

data/lib/ssh_tresor/tresor.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "agent"
+require_relative "crypto"
+require_relative "format"
+require "base64"
+
+module SshTresor
+  module Tresor
+    module_function
+
+    def encrypt(plaintext, fingerprints: [])
+      encrypt_with_agent(Agent.connect, plaintext, fingerprints: fingerprints)
+    end
+
+    def encrypt_with_agent(agent, plaintext, fingerprints: [])
+      keys = if fingerprints.empty?
+               [agent.first_key]
+             else
+               fingerprints.map { |fingerprint| agent.find_key(fingerprint) }
+             end
+
+      encrypt_with_keys(agent, keys, plaintext)
+    end
+
+    def decrypt(blob)
+      decrypt_with_agent(Agent.connect, blob)
+    end
+
+    def decrypt_with_agent(agent, blob)
+      keys = agent.list_keys.sort_by(&:security_key?)
+
+      keys.each do |key|
+        slot = blob.find_slot(key.fingerprint_bytes)
+        next if slot.nil?
+
+        begin
+          return decrypt_with_slot(agent, key, slot, blob)
+        rescue DecryptionError
+          next
+        end
+      end
+
+      raise NoMatchingSlot
+    end
+
+    def add_key(blob, fingerprint)
+      add_key_with_agent(Agent.connect, blob, fingerprint)
+    end
+
+    def add_key_with_agent(agent, blob, fingerprint)
+      master_key = recover_master_key(agent, blob)
+      new_key = agent.find_key(fingerprint)
+
+      raise Error, "Invalid tresor format: key already exists in tresor" if blob.find_slot(new_key.fingerprint_bytes)
+
+      TresorBlob.new(
+        slots: blob.slots + [create_slot(agent, new_key, master_key)],
+        data_nonce: blob.data_nonce,
+        ciphertext: blob.ciphertext
+      )
+    end
+
+    def add_all_keys(blob)
+      add_all_keys_with_agent(Agent.connect, blob)
+    end
+
+    def add_all_keys_with_agent(agent, blob)
+      master_key = recover_master_key(agent, blob)
+      new_slots = blob.slots.dup
+      added = 0
+
+      agent.list_keys.each do |key|
+        next if blob.find_slot(key.fingerprint_bytes)
+
+        begin
+          new_slots << create_slot(agent, key, master_key)
+          added += 1
+        rescue Error
+          next
+        end
+      end
+
+      [TresorBlob.new(slots: new_slots, data_nonce: blob.data_nonce, ciphertext: blob.ciphertext), added]
+    end
+
+    def remove_key(blob, fingerprint)
+      raise Error, "Invalid tresor format: cannot remove the last key from tresor" if blob.slots.length == 1
+
+      fingerprint_bytes = resolve_slot_fingerprint(blob, fingerprint)
+      new_slots = blob.slots.reject { |slot| slot.fingerprint == fingerprint_bytes }
+
+      raise KeyNotFound, "Key not found: #{fingerprint}" if new_slots.length == blob.slots.length
+
+      TresorBlob.new(slots: new_slots, data_nonce: blob.data_nonce, ciphertext: blob.ciphertext)
+    end
+
+    def list_keys
+      Agent.connect.list_keys
+    end
+
+    def list_slots(blob)
+      blob.slot_fingerprints
+    end
+
+    def encrypt_with_keys(agent, keys, plaintext)
+      master_key = Crypto.random_master_key
+      slots = keys.map { |key| create_slot(agent, key, master_key) }
+      data_nonce = Crypto.random_nonce
+      ciphertext = Crypto.encrypt(master_key, data_nonce, plaintext)
+
+      TresorBlob.new(slots: slots, data_nonce: data_nonce, ciphertext: ciphertext)
+    end
+
+    def create_slot(agent, key, master_key)
+      challenge = Crypto.random_challenge
+      signature = agent.sign(key, challenge)
+      slot_key = Crypto.derive_key(signature)
+      nonce = Crypto.random_nonce
+      encrypted_key = Crypto.encrypt(slot_key, nonce, master_key)
+
+      Slot.new(
+        fingerprint: key.fingerprint_bytes,
+        challenge: challenge,
+        nonce: nonce,
+        encrypted_key: encrypted_key
+      )
+    end
+
+    def decrypt_with_slot(agent, key, slot, blob)
+      signature = agent.sign(key, slot.challenge)
+      slot_key = Crypto.derive_key(signature)
+      master_key = Crypto.decrypt(slot_key, slot.nonce, slot.encrypted_key)
+      Crypto.decrypt(master_key, blob.data_nonce, blob.ciphertext)
+    end
+
+    def recover_master_key(agent, blob)
+      agent.list_keys.each do |key|
+        slot = blob.find_slot(key.fingerprint_bytes)
+        next if slot.nil?
+
+        begin
+          signature = agent.sign(key, slot.challenge)
+          slot_key = Crypto.derive_key(signature)
+          return Crypto.decrypt(slot_key, slot.nonce, slot.encrypted_key)
+        rescue DecryptionError
+          next
+        end
+      end
+
+      raise NoMatchingSlot
+    end
+
+    def resolve_slot_fingerprint(blob, fingerprint)
+      normalized = fingerprint.delete_prefix("SHA256:")
+      matches = blob.slot_fingerprints.select do |slot_fingerprint|
+        Base64.strict_encode64(slot_fingerprint).delete("=").start_with?(normalized)
+      end
+
+      case matches.length
+      when 0
+        raise KeyNotFound, "Key not found: #{fingerprint}"
+      when 1
+        matches.first
+      else
+        raise KeyNotFound, "Key not found: #{fingerprint} (ambiguous: #{matches.length} slots match this prefix, please be more specific)"
+      end
+    end
+  end
+end

data/lib/ssh_tresor/vault.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require_relative "format"
+require_relative "tresor"
+
+module SshTresor
+  # Public high-level API for encrypting and decrypting tresors from another Ruby
+  # application or gem.
+  #
+  # `Vault` is intentionally a small facade over the lower-level SSH agent,
+  # crypto, and wire-format objects. It connects to `SSH_AUTH_SOCK` by default,
+  # but accepts an injected agent object for tests or alternate transports.
+  #
+  # @example Encrypt and decrypt using the current SSH agent
+  #   vault = SshTresor::Vault.new
+  #   encrypted = vault.encrypt("secret", armor: true)
+  #   plaintext = vault.decrypt(encrypted)
+  #
+  # @example Inject a custom agent implementation
+  #   vault = SshTresor::Vault.new(agent: my_agent)
+  #
+  # @see SshTresor::Tresor
+  # @see SshTresor::TresorBlob
+  class Vault
+    # Creates a vault bound to an SSH agent.
+    #
+    # The default agent is opened from `ENV["SSH_AUTH_SOCK"]`. The injected agent
+    # must implement the subset of {SshTresor::Agent} used by the high-level
+    # operations: `first_key`, `find_key`, `list_keys`, and `sign`.
+    #
+    # @param agent [#first_key, #find_key, #list_keys, #sign] SSH agent-like object.
+    # @raise [SshTresor::AgentError] when the default SSH agent cannot be reached.
+    # @return [SshTresor::Vault]
+    def initialize(agent: Agent.connect)
+      @agent = agent
+    end
+
+    # Encrypts plaintext for one or more keys available in the SSH agent.
+    #
+    # When no fingerprints are given, the first key returned by the agent is
+    # used. Fingerprints may be full `SHA256:...` values or unambiguous prefixes.
+    #
+    # @param plaintext [String] Plaintext bytes to encrypt.
+    # @param fingerprints [Array<String>] SSH key fingerprints to encrypt for.
+    # @param armor [Boolean] Whether to return base64 armor instead of binary format.
+    # @return [String] Encrypted tresor bytes or armored text.
+    # @raise [SshTresor::KeyNotFound] when a requested key is unavailable.
+    # @raise [SshTresor::AgentError] when agent signing fails.
+    def encrypt(plaintext, fingerprints: [], armor: false)
+      blob = Tresor.encrypt_with_agent(@agent, plaintext, fingerprints: fingerprints)
+      armor ? blob.to_armored : blob.to_bytes
+    end
+
+    # Decrypts an encrypted tresor using any matching key in the SSH agent.
+    #
+    # The input may be binary `SSHTRESR` v3 data or armored text. The agent is
+    # asked to sign the stored slot challenge for matching key fingerprints.
+    #
+    # @param encrypted [String] Binary or armored tresor content.
+    # @return [String] Decrypted plaintext bytes.
+    # @raise [SshTresor::NoMatchingSlot] when no loaded agent key can decrypt it.
+    # @raise [SshTresor::DecryptionError] when authentication/decryption fails.
+    # @raise [SshTresor::Error] when the tresor format is invalid.
+    def decrypt(encrypted)
+      Tresor.decrypt_with_agent(@agent, TresorBlob.from_bytes(encrypted))
+    end
+
+    # Adds one SSH key slot to an existing tresor.
+    #
+    # The current agent must be able to decrypt an existing slot before adding a
+    # new one, because the master key must be recovered and re-wrapped for the
+    # new key.
+    #
+    # @param encrypted [String] Binary or armored tresor content.
+    # @param fingerprint [String] Fingerprint or unambiguous prefix of the key to add.
+    # @param armor [Boolean, nil] Output armor mode. `nil` preserves input format.
+    # @return [String] Updated encrypted tresor content.
+    # @raise [SshTresor::NoMatchingSlot] when the current agent cannot unlock the tresor.
+    # @raise [SshTresor::KeyNotFound] when the new key is unavailable.
+    def add_key(encrypted, fingerprint:, armor: nil)
+      input_was_armored = armored?(encrypted)
+      blob = TresorBlob.from_bytes(encrypted)
+      updated = Tresor.add_key_with_agent(@agent, blob, fingerprint)
+      serialize(updated, armor.nil? ? input_was_armored : armor)
+    end
+
+    # Adds slots for all available SSH agent keys not already present.
+    #
+    # Keys that are already present or cannot sign are skipped.
+    #
+    # @param encrypted [String] Binary or armored tresor content.
+    # @param armor [Boolean, nil] Output armor mode. `nil` preserves input format.
+    # @return [Array(String, Integer)] Updated tresor content and number of slots added.
+    # @raise [SshTresor::NoMatchingSlot] when the current agent cannot unlock the tresor.
+    def add_all_keys(encrypted, armor: nil)
+      input_was_armored = armored?(encrypted)
+      blob = TresorBlob.from_bytes(encrypted)
+      updated, added = Tresor.add_all_keys_with_agent(@agent, blob)
+      [serialize(updated, armor.nil? ? input_was_armored : armor), added]
+    end
+
+    # Removes one key slot from an existing tresor.
+    #
+    # This operation only edits metadata and does not require the SSH agent to
+    # hold the removed key. Removing the final slot is rejected.
+    #
+    # @param encrypted [String] Binary or armored tresor content.
+    # @param fingerprint [String] Fingerprint or unambiguous prefix of the slot to remove.
+    # @param armor [Boolean, nil] Output armor mode. `nil` preserves input format.
+    # @return [String] Updated encrypted tresor content.
+    # @raise [SshTresor::KeyNotFound] when no slot matches the fingerprint.
+    # @raise [SshTresor::Error] when attempting to remove the last slot.
+    def remove_key(encrypted, fingerprint:, armor: nil)
+      input_was_armored = armored?(encrypted)
+      blob = TresorBlob.from_bytes(encrypted)
+      updated = Tresor.remove_key(blob, fingerprint)
+      serialize(updated, armor.nil? ? input_was_armored : armor)
+    end
+
+    # Lists keys currently available through the configured SSH agent.
+    #
+    # @return [Array<SshTresor::AgentKey>] Agent keys with fingerprints, type, and comments.
+    # @raise [SshTresor::AgentError] when the SSH agent cannot be queried.
+    def list_keys
+      @agent.list_keys
+    end
+
+    # Lists key slot fingerprints present in encrypted tresor content.
+    #
+    # This does not require access to an SSH agent because slot fingerprints are
+    # stored in the tresor header.
+    #
+    # @param encrypted [String] Binary or armored tresor content.
+    # @return [Array<String>] Raw 32-byte SHA-256 fingerprint bytes for each slot.
+    # @raise [SshTresor::Error] when the tresor format is invalid.
+    def list_slots(encrypted)
+      TresorBlob.from_bytes(encrypted).slot_fingerprints
+    end
+
+    private
+
+    def armored?(data)
+      data.b.strip.start_with?(TresorBlob::ARMOR_BEGIN)
+    end
+
+    def serialize(blob, armor)
+      armor ? blob.to_armored : blob.to_bytes
+    end
+  end
+end

data/lib/ssh_tresor/version.rb

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

data/lib/ssh_tresor.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "ssh_tresor/agent"
+require_relative "ssh_tresor/crypto"
+require_relative "ssh_tresor/error"
+require_relative "ssh_tresor/format"
+require_relative "ssh_tresor/tresor"
+require_relative "ssh_tresor/vault"
+require_relative "ssh_tresor/version"

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: ssh-tresor
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ronan Potage
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-05-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Independent Ruby implementation of ssh-tresor using ssh-agent signatures,
+  HKDF-SHA256, and AES-256-GCM.
+email:
+executables:
+- ssh-tresor
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/ssh-tresor
+- lib/ssh_tresor.rb
+- lib/ssh_tresor/agent.rb
+- lib/ssh_tresor/cli.rb
+- lib/ssh_tresor/crypto.rb
+- lib/ssh_tresor/error.rb
+- lib/ssh_tresor/format.rb
+- lib/ssh_tresor/ssh_encoding.rb
+- lib/ssh_tresor/tresor.rb
+- lib/ssh_tresor/vault.rb
+- lib/ssh_tresor/version.rb
+homepage: https://github.com/capripot/ssh-tresor-ruby
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: Encrypt and decrypt secrets using SSH agent keys
+test_files: []