pq_crypto-seal 0.1.0

data/lib/pq_crypto/seal/format.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+module PQCrypto
+  module Seal
+    module Format
+      MAGIC = "PQCSEAL1".b
+      VERSION = 1
+      CONTENT_SUITE_AEGIS256 = 1
+      WRAP_SUITE_MLKEM768_X25519_AEGIS256 = 1
+      LOOKUP_HINT = 1
+      FLAGS = 0
+      INNER_VERSION = 1
+      INNER_FLAGS = 0
+
+      PADDING_NONE = 0
+      PADDING_PADME = 1
+      PADDING_FIXED = 2
+      PADDING_BUCKETS = 3
+      PADDING_POLICY_IDS = {
+        PADDING_NONE => true,
+        PADDING_PADME => true,
+        PADDING_FIXED => true,
+        PADDING_BUCKETS => true
+      }.freeze
+      PADDING_POLICY_BY_SYMBOL = {
+        nil => PADDING_NONE,
+        :none => PADDING_NONE,
+        :padme => PADDING_PADME
+      }.freeze
+
+      PAYLOAD_ID_BYTES = 32
+      NONCE_BYTES = 32
+      TAG_BYTES = 32
+      HINT_BYTES = 32
+      SECTION_ID_BYTES = 32
+
+      XWING_PUBLIC_KEY_BYTES = 1216
+      XWING_CIPHERTEXT_BYTES = 1120
+      XWING_SHARED_SECRET_BYTES = 32
+
+      DEK_BYTES = 32
+      STANZA_BYTES = HINT_BYTES + XWING_CIPHERTEXT_BYTES + NONCE_BYTES + DEK_BYTES + TAG_BYTES
+      DEFAULT_SLOT_SIZE = 2048
+      MIN_SLOT_SIZE = 2048
+      MAX_SLOT_SIZE = 8192
+      SLOT_GRANULARITY = 256
+      DEFAULT_RECIPIENT_CAPACITY = 4
+      MAX_RECIPIENT_CAPACITY = 32
+      MAX_PUBLIC_METADATA_BYTES = 1 * 1024 * 1024
+      MAX_PRIVATE_METADATA_BYTES = 16 * 1024 * 1024
+      MAX_HEADER_BYTES = 2 * 1024 * 1024
+
+      DEFAULT_MAX_PLAINTEXT_BYTES = 1 * 1024 * 1024 * 1024
+      DEFAULT_MAX_STAGING_BYTES = DEFAULT_MAX_PLAINTEXT_BYTES + MAX_PRIVATE_METADATA_BYTES + 64
+      DEFAULT_MAX_ENVELOPE_BYTES =
+        MAX_HEADER_BYTES +
+        (2 + SECTION_ID_BYTES + MAX_RECIPIENT_CAPACITY * MAX_SLOT_SIZE) +
+        DEFAULT_MAX_STAGING_BYTES +
+        TAG_BYTES
+
+      LIMIT_DEFAULTS = {
+        max_staging_bytes: DEFAULT_MAX_STAGING_BYTES,
+        max_plaintext_bytes: DEFAULT_MAX_PLAINTEXT_BYTES,
+        max_envelope_bytes: DEFAULT_MAX_ENVELOPE_BYTES
+      }.freeze
+
+      Header = Struct.new(
+        :raw, :content_suite_id, :lookup_mode, :flags, :padding_policy_id,
+        :payload_id, :payload_nonce, :recipient_capacity, :slot_size,
+        :padded_inner_length, :public_metadata,
+        keyword_init: true
+      )
+      Section = Struct.new(:wrap_suite_id, :section_id, :raw, :slots_offset, :slots_length, keyword_init: true)
+
+      SLOT_FIELDS = [
+        [:hint, HINT_BYTES],
+        [:kem_ciphertext, XWING_CIPHERTEXT_BYTES],
+        [:wrap_nonce, NONCE_BYTES],
+        [:wrapped_dek, DEK_BYTES],
+        [:wrap_tag, TAG_BYTES]
+      ].freeze
+
+      module_function
+
+      def validate_slot_size!(slot_size, error: InvalidConfigurationError)
+        n = Integer(slot_size)
+        unless n.between?(MIN_SLOT_SIZE, MAX_SLOT_SIZE) && (n % SLOT_GRANULARITY).zero?
+          raise error, "slot_size must be #{MIN_SLOT_SIZE}..#{MAX_SLOT_SIZE} and divisible by #{SLOT_GRANULARITY}"
+        end
+        raise error, "slot_size is too small for current wrap suite" if n < STANZA_BYTES
+        n
+      end
+
+      def validate_capacity!(capacity, recipient_count = nil, error: InvalidConfigurationError)
+        n = Integer(capacity)
+        unless n.between?(1, MAX_RECIPIENT_CAPACITY)
+          raise error, "recipient_capacity must be 1..#{MAX_RECIPIENT_CAPACITY}"
+        end
+        if recipient_count && recipient_count > n
+          raise RecipientCapacityExceeded, "#{recipient_count} recipients do not fit capacity #{n}"
+        end
+        n
+      end
+
+      def validate_slot_size_from_wire!(slot_size)
+        validate_slot_size!(slot_size, error: FormatError)
+      end
+
+      def validate_capacity_from_wire!(capacity)
+        validate_capacity!(capacity, error: FormatError)
+      end
+
+      def validate_padding_policy_id!(policy_id)
+        n = Integer(policy_id)
+        raise FormatError, "unsupported padding policy id #{n}" unless PADDING_POLICY_IDS.key?(n)
+        n
+      end
+
+      def padding_policy_id_for(policy)
+        return PADDING_POLICY_BY_SYMBOL.fetch(policy) if PADDING_POLICY_BY_SYMBOL.key?(policy)
+        case policy
+        when :preserve
+          raise InvalidConfigurationError, "padding: :preserve is only valid for rotate_dek"
+        when Hash
+          return PADDING_FIXED if policy.key?(:to)
+          return PADDING_BUCKETS if policy.key?(:buckets)
+          raise InvalidConfigurationError, "padding hash must contain :to or :buckets"
+        else
+          raise InvalidConfigurationError, "unsupported padding policy: #{policy.inspect}"
+        end
+      end
+
+      def build_header(payload_id:, payload_nonce:, recipient_capacity:, slot_size:,
+                       padded_inner_length:, public_metadata:, padding_policy_id:)
+        public_metadata = String(public_metadata).b
+        raise InvalidConfigurationError, "public metadata is too large" if public_metadata.bytesize > MAX_PUBLIC_METADATA_BYTES
+        raise InvalidConfigurationError, "invalid payload_id" unless payload_id.bytesize == PAYLOAD_ID_BYTES
+        raise InvalidConfigurationError, "invalid payload nonce" unless payload_nonce.bytesize == NONCE_BYTES
+        validate_padding_policy_id!(padding_policy_id)
+
+        body = +"".b
+        body << Binary.u16(CONTENT_SUITE_AEGIS256)
+        body << Binary.u8(LOOKUP_HINT)
+        body << Binary.u16(FLAGS)
+        body << Binary.u8(Integer(padding_policy_id))
+        body << payload_id
+        body << payload_nonce
+        body << Binary.u16(recipient_capacity)
+        body << Binary.u16(slot_size)
+        body << Binary.u64(padded_inner_length)
+        body << Binary.u32(public_metadata.bytesize)
+        body << public_metadata
+        header = MAGIC + Binary.u8(VERSION) + Binary.u32(MAGIC.bytesize + 1 + 4 + body.bytesize) + body
+        raise InvalidConfigurationError, "header is too large" if header.bytesize > MAX_HEADER_BYTES
+        header
+      end
+
+      def parse_header(bytes)
+        bytes = String(bytes).b
+        offset = 0
+        magic, offset = Binary.read_bytes(bytes, offset, MAGIC.bytesize)
+        raise FormatError, "invalid envelope magic" unless magic == MAGIC
+        version, offset = Binary.read_u8(bytes, offset)
+        raise FormatError, "unsupported format version #{version}" unless version == VERSION
+        header_length, offset = Binary.read_u32(bytes, offset)
+        raise FormatError, "invalid header length" if header_length < offset || header_length > MAX_HEADER_BYTES
+        Binary.ensure_available!(bytes, 0, header_length)
+        raw = bytes.byteslice(0, header_length).b
+
+        content_suite, offset = Binary.read_u16(raw, offset)
+        raise UnsupportedSuiteError, "unsupported content suite #{content_suite}" unless content_suite == CONTENT_SUITE_AEGIS256
+        lookup_mode, offset = Binary.read_u8(raw, offset)
+        raise UnsupportedSuiteError, "unsupported lookup mode #{lookup_mode}" unless lookup_mode == LOOKUP_HINT
+        flags, offset = Binary.read_u16(raw, offset)
+        raise FormatError, "unknown header flags" unless flags == FLAGS
+        padding_policy_id, offset = Binary.read_u8(raw, offset)
+        validate_padding_policy_id!(padding_policy_id)
+        payload_id, offset = Binary.read_bytes(raw, offset, PAYLOAD_ID_BYTES)
+        payload_nonce, offset = Binary.read_bytes(raw, offset, NONCE_BYTES)
+        capacity, offset = Binary.read_u16(raw, offset)
+        validate_capacity_from_wire!(capacity)
+        slot_size, offset = Binary.read_u16(raw, offset)
+        validate_slot_size_from_wire!(slot_size)
+        padded_inner_length, offset = Binary.read_u64(raw, offset)
+        raise FormatError, "padded inner frame is too short" if padded_inner_length < 14
+        public_length, offset = Binary.read_u32(raw, offset)
+        raise FormatError, "public metadata is too large" if public_length > MAX_PUBLIC_METADATA_BYTES
+        public_metadata, offset = Binary.read_bytes(raw, offset, public_length)
+        raise FormatError, "non-canonical header length" unless offset == raw.bytesize
+
+        Header.new(
+          raw: raw, content_suite_id: content_suite, lookup_mode: lookup_mode,
+          flags: flags, padding_policy_id: padding_policy_id,
+          payload_id: payload_id, payload_nonce: payload_nonce,
+          recipient_capacity: capacity, slot_size: slot_size,
+          padded_inner_length: padded_inner_length, public_metadata: public_metadata
+        )
+      end
+
+      def section_length(header)
+        section_length_for(header.recipient_capacity, header.slot_size)
+      end
+
+      def section_length_for(capacity, slot_size)
+        2 + SECTION_ID_BYTES + Integer(capacity) * Integer(slot_size)
+      end
+
+      def split_slot(slot, slot_size)
+        fields = {}
+        offset = 0
+        SLOT_FIELDS.each do |name, length|
+          fields[name] = slot.byteslice(offset, length)
+          offset += length
+        end
+        fields[:padding] = slot.byteslice(offset, slot_size - offset)
+        fields
+      end
+
+      def parse_section(bytes, offset, header)
+        length = section_length(header)
+        raw, = Binary.read_bytes(bytes, offset, length)
+        wrap_suite, slot_offset = Binary.read_u16(raw, 0)
+        section_id, slot_offset = Binary.read_bytes(raw, slot_offset, SECTION_ID_BYTES)
+        unless wrap_suite == WRAP_SUITE_MLKEM768_X25519_AEGIS256
+          raise UnsupportedSuiteError, "unsupported wrap suite #{wrap_suite}"
+        end
+        Section.new(
+          wrap_suite_id: wrap_suite, section_id: section_id, raw: raw,
+          slots_offset: slot_offset, slots_length: raw.bytesize - slot_offset
+        )
+      end
+
+      def inner_prefix(content_length, private_metadata_length)
+        Binary.u8(INNER_VERSION) + Binary.u8(INNER_FLAGS) +
+          Binary.u64(content_length) + Binary.u32(private_metadata_length)
+      end
+
+      def parse_verified_inner(bytes)
+        bytes = String(bytes).b
+        offset = 0
+        version, offset = Binary.read_u8(bytes, offset)
+        raise FormatError, "unsupported inner version" unless version == INNER_VERSION
+        flags, offset = Binary.read_u8(bytes, offset)
+        raise FormatError, "unknown inner flags" unless flags == INNER_FLAGS
+        content_length, offset = Binary.read_u64(bytes, offset)
+        metadata_length, offset = Binary.read_u32(bytes, offset)
+        raise FormatError, "private metadata is too large" if metadata_length > MAX_PRIVATE_METADATA_BYTES
+        metadata, offset = Binary.read_bytes(bytes, offset, metadata_length)
+        content, offset = Binary.read_bytes(bytes, offset, content_length)
+        [content, metadata, bytes.bytesize - offset]
+      end
+
+      def check_resource_limits!(padded_inner_length:, envelope_bytes: nil,
+                                 max_staging_bytes: DEFAULT_MAX_STAGING_BYTES,
+                                 max_envelope_bytes: DEFAULT_MAX_ENVELOPE_BYTES)
+        if padded_inner_length > Integer(max_staging_bytes)
+          raise ResourceLimitError,
+                "padded_inner_length #{padded_inner_length} exceeds max_staging_bytes #{max_staging_bytes}"
+        end
+        if envelope_bytes && envelope_bytes > Integer(max_envelope_bytes)
+          raise ResourceLimitError,
+                "envelope #{envelope_bytes} exceeds max_envelope_bytes #{max_envelope_bytes}"
+        end
+        true
+      end
+
+      def pre_auth_limits(limits)
+        {
+          max_staging_bytes: limits.fetch(:max_staging_bytes, DEFAULT_MAX_STAGING_BYTES),
+          max_envelope_bytes: limits.fetch(:max_envelope_bytes, DEFAULT_MAX_ENVELOPE_BYTES)
+        }
+      end
+    end
+  end
+end

data/lib/pq_crypto/seal/io.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "fileutils"
+
+module PQCrypto
+  module Seal
+    module IOAPI
+      DEFAULT_CHUNK_SIZE = 1024 * 1024
+      module_function
+
+      def encrypt_io(input, output, size:, to:, metadata: "".b, public_metadata: "".b,
+                     recipient_capacity: Format::DEFAULT_RECIPIENT_CAPACITY,
+                     slot_size: Format::DEFAULT_SLOT_SIZE, padding: :padme,
+                     chunk_size: DEFAULT_CHUNK_SIZE, strict_size: true)
+        content_size = Integer(size)
+        raise ArgumentError, "size must be non-negative" if content_size.negative?
+        metadata = String(metadata).b
+        seal(:validate_private_metadata!, metadata)
+        recipients = seal(:normalize_public_keys, to)
+        capacity = Format.validate_capacity!(recipient_capacity, recipients.length)
+        slot_size = Format.validate_slot_size!(slot_size)
+        chunk_size = validate_chunk_size(chunk_size)
+
+        parts = nil
+        parts = seal(
+          :materialize_crypto_parts,
+          recipients: recipients, capacity: capacity, slot_size: slot_size,
+          padding: padding, public_metadata: public_metadata,
+          content_size: content_size, metadata_size: metadata.bytesize
+        )
+        output.write(parts[:header])
+        output.write(parts[:section])
+        encryptor = Native::Encryptor.new(parts[:dek], parts[:payload_nonce], parts[:header_hash])
+        output.write(encryptor.update(parts[:inner_prefix]))
+        output.write(encryptor.update(metadata)) unless metadata.empty?
+        copied = copy_exact_encrypted(input, output, encryptor, content_size, chunk_size)
+        raise EOFError, "input ended after #{copied} of #{content_size} bytes" unless copied == content_size
+        if strict_size
+          raise ArgumentError, "input contains more bytes than declared size" unless input.read(1).nil?
+        end
+        write_random_encrypted(output, encryptor, parts[:padded_inner_length] - parts[:raw_inner_length], chunk_size)
+        output.write(encryptor.final)
+        output
+      ensure
+        seal(:wipe_string!, parts[:dek]) if parts
+        seal(:wipe_string!, metadata) if metadata.is_a?(String) && !metadata.frozen?
+      end
+
+      def decrypt_io(input, output, with:, staging_directory: nil, chunk_size: DEFAULT_CHUNK_SIZE,
+                     strict_eof: true, **limits)
+        limits = Format::LIMIT_DEFAULTS.merge(limits)
+        chunk_size = validate_chunk_size(chunk_size)
+        staging = new_staging("pqcrypto-seal-inner", staging_directory)
+        opened = decrypt_to_staging(
+          input, staging, with: with, chunk_size: chunk_size, strict_eof: strict_eof, **limits
+        )
+        staging.flush
+        staging.rewind
+        content_offset, content_length, metadata = parse_verified_staging(staging, opened[:header].padded_inner_length)
+        if content_length > Integer(limits[:max_plaintext_bytes])
+          seal(:wipe_string!, metadata)
+          raise ResourceLimitError,
+                "plaintext #{content_length} exceeds max_plaintext_bytes #{limits[:max_plaintext_bytes]}"
+        end
+        staging.seek(content_offset, ::IO::SEEK_SET)
+        copy_exact(staging, output, content_length, chunk_size)
+        Opened.from_header(opened[:header], opened[:section], data: nil, metadata: metadata)
+      ensure
+        staging.close! if defined?(staging) && staging
+      end
+
+      def decrypt_frame_io(input, output, with:, **options)
+        decrypt_io(input, output, with: with, strict_eof: false, **options)
+      end
+
+      def encrypt_frame_io(input, output, size:, to:, **options)
+        encrypt_io(input, output, size: size, to: to, strict_size: false, **options)
+      end
+
+      def encrypt_file(source, destination, **options)
+        File.open(source, "rb") do |input|
+          size = input.stat.size
+          atomic_destination(destination) do |tmp|
+            encrypt_io(input, tmp, size: size, strict_size: true, **options)
+          end
+        end
+        destination
+      end
+
+      def decrypt_file(source, destination, with:, staging_directory: nil,
+                       chunk_size: DEFAULT_CHUNK_SIZE, **limits)
+        File.open(source, "rb") do |input|
+          atomic_destination(destination) do |tmp|
+            decrypt_io(
+              input, tmp, with: with, staging_directory: staging_directory,
+              chunk_size: chunk_size, strict_eof: true, **limits
+            )
+          end
+        end
+        destination
+      end
+
+      def rebuild_recipients_file(source, destination, with:, recipients:, chunk_size: DEFAULT_CHUNK_SIZE)
+        chunk_size = validate_chunk_size(chunk_size)
+        File.open(source, "rb") do |input|
+          header = read_header(input)
+          old_section = Format.parse_section(read_exact(input, Format.section_length(header)), 0, header)
+          dek = seal(:unwrap_dek, header, old_section, with)
+          public_keys = seal(:normalize_public_keys, recipients)
+          Format.validate_capacity!(header.recipient_capacity, public_keys.length)
+          new_section = seal(
+            :build_recipient_section,
+            recipients: public_keys, capacity: header.recipient_capacity,
+            slot_size: header.slot_size, payload_id: header.payload_id,
+            header_hash: Native.sha256(header.raw), dek: dek,
+            wrap_suite_id: Format::WRAP_SUITE_MLKEM768_X25519_AEGIS256
+          )
+          atomic_destination(destination) do |tmp|
+            tmp.write(header.raw)
+            tmp.write(new_section)
+            verifier = Native::Decryptor.new(dek, header.payload_nonce, Native.sha256(header.raw))
+            remaining = header.padded_inner_length
+            while remaining.positive?
+              take = [remaining, chunk_size].min
+              ciphertext_chunk = read_exact(input, take)
+              tmp.write(ciphertext_chunk)
+              seal(:wipe_string!, verifier.update(ciphertext_chunk))
+              remaining -= take
+            end
+            payload_tag = read_exact(input, Format::TAG_BYTES)
+            raise FormatError, "trailing bytes after envelope" unless input.read(1).nil?
+            verifier.final(payload_tag)
+            tmp.write(payload_tag)
+          end
+        ensure
+          seal(:wipe_string!, dek) if defined?(dek)
+        end
+        destination
+      end
+
+      def add_recipient_file(source, destination, with:, recipient:, current_recipients:, **options)
+        rebuild_recipients_file(
+          source, destination, with: with,
+          recipients: Array(current_recipients) + [recipient], **options
+        )
+      end
+
+      def drop_recipient_stanza_file(source, destination, with:, remaining_recipients:, **options)
+        rebuild_recipients_file(source, destination, with: with, recipients: remaining_recipients, **options)
+      end
+
+      def rotate_dek_file(source, destination, with:, recipients:, padding: :preserve,
+                          staging_directory: nil, chunk_size: DEFAULT_CHUNK_SIZE)
+        plaintext = new_staging("pqcrypto-seal-rotation", staging_directory)
+        opened = nil
+        File.open(source, "rb") do |input|
+          opened = decrypt_io(input, plaintext, with: with,
+                              staging_directory: staging_directory, chunk_size: chunk_size, strict_eof: true)
+        end
+        plaintext.flush
+        plaintext.rewind
+        info = inspect_file(source)
+        padding = { to: info.envelope_bytes } if padding == :preserve
+        atomic_destination(destination) do |tmp|
+          encrypt_io(
+            plaintext, tmp, size: plaintext.stat.size, to: recipients,
+            metadata: opened.metadata, public_metadata: opened.public_metadata,
+            recipient_capacity: info.recipient_capacity, slot_size: info.slot_size,
+            padding: padding, chunk_size: chunk_size, strict_size: true
+          )
+        end
+        destination
+      ensure
+        plaintext.close! if defined?(plaintext) && plaintext
+        seal(:wipe_string!, opened.metadata) if defined?(opened) && opened && opened.metadata
+      end
+
+      def inspect_file(source)
+        File.open(source, "rb") do |input|
+          header = read_header(input)
+          section = Format.parse_section(read_exact(input, Format.section_length(header)), 0, header)
+          total = header.raw.bytesize + section.raw.bytesize + header.padded_inner_length + Format::TAG_BYTES
+          raise FormatError, "file length does not match envelope" unless File.size(source) == total
+          Inspection.from_header(header, section, envelope_bytes: total)
+        end
+      end
+
+      def decrypt_to_staging(input, staging, with:, chunk_size:, strict_eof:, **limits)
+        limits = Format::LIMIT_DEFAULTS.merge(limits)
+        header = read_header(input)
+        Format.check_resource_limits!(
+          padded_inner_length: header.padded_inner_length, **Format.pre_auth_limits(limits)
+        )
+        section = Format.parse_section(read_exact(input, Format.section_length(header)), 0, header)
+        estimated = header.raw.bytesize + section.raw.bytesize + header.padded_inner_length + Format::TAG_BYTES
+        Format.check_resource_limits!(
+          padded_inner_length: header.padded_inner_length,
+          envelope_bytes: estimated, **Format.pre_auth_limits(limits)
+        )
+        dek = seal(:unwrap_dek, header, section, with)
+        decryptor = Native::Decryptor.new(dek, header.payload_nonce, Native.sha256(header.raw))
+        remaining = header.padded_inner_length
+        while remaining.positive?
+          take = [remaining, chunk_size].min
+          staging.write(decryptor.update(read_exact(input, take)))
+          remaining -= take
+        end
+        tag = read_exact(input, Format::TAG_BYTES)
+        raise FormatError, "trailing bytes after envelope" if strict_eof && !input.read(1).nil?
+        decryptor.final(tag)
+        { header: header, section: section }
+      ensure
+        seal(:wipe_string!, dek) if defined?(dek)
+      end
+
+      def parse_verified_staging(staging, expected_size)
+        raise FormatError, "staging size mismatch" unless staging.stat.size == expected_size
+        staging.rewind
+        prefix = read_exact(staging, 14)
+        version = prefix.getbyte(0)
+        flags = prefix.getbyte(1)
+        raise FormatError, "unsupported inner version" unless version == Format::INNER_VERSION
+        raise FormatError, "unknown inner flags" unless flags == Format::INNER_FLAGS
+        hi, lo, metadata_length = prefix.byteslice(2, 12).unpack("NNN")
+        content_length = (hi << 32) | lo
+        raise FormatError, "private metadata is too large" if metadata_length > Format::MAX_PRIVATE_METADATA_BYTES
+        minimum = 14 + metadata_length + content_length
+        raise FormatError, "inner lengths exceed authenticated frame" if minimum > expected_size
+        metadata = read_exact(staging, metadata_length)
+        [14 + metadata_length, content_length, metadata]
+      end
+
+      def read_header(input)
+        prefix_len = Format::MAGIC.bytesize + 1 + 4
+        initial = read_exact(input, prefix_len)
+        header_length = initial.byteslice(Format::MAGIC.bytesize + 1, 4).unpack1("N")
+        raise FormatError, "invalid header length" if header_length < initial.bytesize || header_length > Format::MAX_HEADER_BYTES
+        Format.parse_header(initial + read_exact(input, header_length - initial.bytesize))
+      end
+
+      def seal(name, *args, **kwargs)
+        Seal.send(name, *args, **kwargs)
+      end
+
+      def atomic_destination(destination)
+        path = File.expand_path(destination)
+        directory = File.dirname(path)
+        FileUtils.mkdir_p(directory)
+        temp = Tempfile.new([".#{File.basename(path)}.", ".pqcseal"], directory)
+        temp.binmode
+        temp.chmod(0o600)
+        begin
+          yield temp
+          temp.flush
+          temp.fsync
+          temp.close
+          File.rename(temp.path, path)
+          fsync_directory(directory)
+        ensure
+          temp.close! rescue nil
+        end
+      end
+
+      def fsync_directory(directory)
+        File.open(directory, "r") { |dir| dir.fsync }
+      rescue SystemCallError, IOError
+        nil
+      end
+
+      def copy_exact_encrypted(input, output, encryptor, length, chunk_size)
+        copied = 0
+        while copied < length
+          chunk = input.read([chunk_size, length - copied].min)
+          break unless chunk && !chunk.empty?
+          chunk = chunk.b
+          output.write(encryptor.update(chunk))
+          copied += chunk.bytesize
+        end
+        copied
+      end
+
+      def write_random_encrypted(output, encryptor, length, chunk_size)
+        remaining = length
+        while remaining.positive?
+          take = [remaining, chunk_size].min
+          random = Native.random_bytes(take)
+          output.write(encryptor.update(random))
+          seal(:wipe_string!, random)
+          remaining -= take
+        end
+      end
+
+      def copy_exact(input, output, length, chunk_size)
+        remaining = length
+        while remaining.positive?
+          chunk = input.read([remaining, chunk_size].min)
+          raise EOFError, "staging input is truncated" unless chunk && !chunk.empty?
+          output.write(chunk)
+          remaining -= chunk.bytesize
+        end
+      end
+
+      def read_exact(io, length)
+        return "".b if length.zero?
+        buffer = +"".b
+        while buffer.bytesize < length
+          chunk = io.read(length - buffer.bytesize)
+          raise EOFError, "truncated envelope" unless chunk && !chunk.empty?
+          buffer << chunk.b
+        end
+        buffer
+      end
+
+      def new_staging(prefix, staging_directory)
+        tempfile = Tempfile.new([prefix, ".bin"], staging_directory)
+        tempfile.binmode
+        tempfile.chmod(0o600)
+        unlink_open_tempfile(tempfile)
+        tempfile
+      end
+
+      def unlink_open_tempfile(tempfile)
+        tempfile.unlink
+      rescue SystemCallError, IOError, NotImplementedError
+        nil
+      end
+
+      def validate_chunk_size(value)
+        size = Integer(value)
+        raise ArgumentError, "chunk_size must be positive" unless size.positive?
+        size
+      end
+    end
+  end
+end

data/lib/pq_crypto/seal/native.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "pq_crypto/seal/pq_crypto_seal"
+
+module PQCrypto
+  module Seal
+    module Native
+      KEY_BYTES = 32
+      NONCE_BYTES = 32
+      TAG_BYTES = 32
+    end
+  end
+end

data/lib/pq_crypto/seal/padding.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module PQCrypto
+  module Seal
+    module Padding
+      module_function
+
+      def padme_target(length)
+        n = Integer(length)
+        raise ArgumentError, "length must be non-negative" if n.negative?
+        return n if n <= 1
+
+        exponent = n.bit_length - 1
+        significant = exponent.bit_length
+        low_bits = exponent - significant
+        return n if low_bits <= 0
+
+        mask = (1 << low_bits) - 1
+        (n + mask) & ~mask
+      end
+
+      def target(base_length, policy)
+        case policy
+        when nil, :none then base_length
+        when :padme then padme_target(base_length)
+        when Hash then fixed_or_buckets(base_length, policy)
+        else
+          raise InvalidConfigurationError, "unsupported padding policy: #{policy.inspect}"
+        end
+      end
+
+      def fixed_or_buckets(base_length, policy)
+        if policy.key?(:to)
+          target = Integer(policy.fetch(:to))
+          raise InvalidConfigurationError, "padding target is smaller than envelope" if target < base_length
+          target
+        elsif policy.key?(:buckets)
+          bucket = Array(policy.fetch(:buckets)).map { |n| Integer(n) }.sort.find { |n| n >= base_length }
+          raise InvalidConfigurationError, "no padding bucket can hold envelope" unless bucket
+          bucket
+        else
+          raise InvalidConfigurationError, "padding hash must contain :to or :buckets"
+        end
+      end
+    end
+  end
+end

data/lib/pq_crypto/seal/version.rb

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