pq_crypto-seal 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f0508e0149f076a9f8d6c9a829b516a41e2998dc5af916db9d0d4696349d36c
-  data.tar.gz: ce0dd7ba92b94ae212f22ea73cc9754b2028da7037a46539c5408dd60bae961b
+  metadata.gz: aa301e0c50869cf3f9e1fec6924920573f895a4aa3ba9cf66cf63675a1ed0f60
+  data.tar.gz: 73f8cb33894474e63326d0ad43cad5e4e230c4c3050f5e145a7e67e9966ca027
 SHA512:
-  metadata.gz: 248f9187168dd55054827e08dbfcf771555101e00f748cdcef55dbaed31ba4c4fb98ce6f6017c05c00bc5f78de23cfcd4c457541eda93cc2537be8be749711e6
-  data.tar.gz: b96cd381d599e6e9a52e0eba84de72500e6746e744183c5d383ed61d31305874393d640c8a1a79dbf288c7db1daeb1379ffc3c125443b5c0c4b2a39b14088402
+  metadata.gz: 6749ce2e5b6e26d85bf33cd0aa93a4ce82b8fb710bbfc550404551567eab4006649e03f14088cc266786dbc9a6eb358367605eaf1145c6482857c0f6be1ba595
+  data.tar.gz: 61fbbb576c26adb08279357ed800d5245e80d3e6b264992e4afcc7a30972b8fdeae9621fd30bc9a5fcac407d004d72a07925c26e0614cfaaa38e2d504e3d5bf6

data/CHANGELOG.md

@@ -1,7 +1,37 @@
 # Changelog
 
+## 0.1.1
+
+- Release hygiene: CI Actions pinned by commit SHA, `permissions: contents: read`,
+  fuzz + gem-smoke + `release_contract_check` jobs; ignore `.DS_Store` / binaries.
+- Aggressive internal refactor: parsing, recipient wrapping, one-shot operations,
+  streaming, atomic files, padding policies, and resource limits now live in
+  focused objects instead of large branching methods. Public API and wire v1
+  remain unchanged.
+- Padding enforcement now validates both policy id and the canonical target;
+  parameterized fixed/bucket requirements cannot masquerade as one another.
+- Added exact deterministic envelope/stream equivalence, official X-Wing
+  draft-10 decapsulation KATs, partial-read/write regression tests, and a
+  release-contract checker.
+- Release gem contains production code plus only the AEGIS-256 sources needed
+  to compile; tests, CI, fuzz harnesses, RAF, and unused AEGIS families stay out.
+- CI restores pinned Actions, sanitizer fuzz smoke, and isolated built-gem E2E.
+
+- IO: all output paths use `write_all` (reject silent partial writes).
+- Decrypt APIs accept `required_padding:` and can enforce Padmé / none / fixed /
+  buckets after successful AEAD (wire format unchanged).
+- Runtime dependency pinned to `pq_crypto = 0.6.4`.
+- Resource limits applied to `inspect_envelope`, `rebuild_recipients`,
+  `rotate_dek`, and `rebuild_recipients_file`.
+- Default one-shot limits lowered to 64 MiB (use file/IO APIs for larger docs).
+- Document that `rotate_dek` allocates a new `payload_id`.
+- CI: Actions pinned by commit SHA; `permissions: contents: read`; fuzz and
+  gem-smoke jobs restored.
+- Repository hygiene: ignore `.DS_Store` and built binaries.
+
 ## 0.1.0
 
+
 - AEGIS streaming state rejects `update`/`final` before `initialize` (`mode` guard).
 - Encrypt path wipes the internal plaintext copy in `ensure` (caller buffers unchanged).
 - CI: Actions pinned by commit SHA, `permissions: contents: read`, fuzz + gem-smoke jobs.

data/FORMAT.md

@@ -131,9 +131,18 @@ slot_size:          2048 bytes (configurable 2048..8192, multiple of 256)
 recipient_capacity: 4 (maximum 32; never derived automatically from ACL size)
 padding:            Padmé over the complete final envelope size
 max_staging_bytes:  ~1 GiB + private-metadata ceiling
-max_plaintext_bytes:~1 GiB
+max_plaintext_bytes:64 MiB by default
 ```
 
 Parsers reject trailing bytes on the one-shot and default IO paths. Framed
 stream consumers that intentionally embed one envelope inside a larger stream
 must use `encrypt_frame_io` / `decrypt_frame_io`.
+
+
+## Receiver-side padding checks (0.1.1+)
+
+`padding_policy_id` is authenticated but does not by itself encode fixed targets
+or bucket lists. Decryptors that need enforcement pass `required_padding:`. The
+receiver verifies the authenticated policy id and recomputes the canonical target
+from the authenticated inner lengths. Fixed and bucket policies require the
+expected target or bucket list from the application.

data/GET_STARTED.md

@@ -28,3 +28,13 @@ Recipient-section rebuilds always require the application's complete,
 authoritative public-key ACL. They do not revoke access to plaintext or old
 envelope copies. Use `rotate_dek`/`rotate_dek_file` when a new payload key and
 full re-encryption are required.
+
+## Large documents
+
+Default one-shot limits are 64 MiB (`max_plaintext_bytes` / related staging and
+envelope ceilings). For larger objects use `encrypt_file` / `decrypt_file` or
+`encrypt_io` / `decrypt_io` and raise the limits explicitly, for example:
+
+```ruby
+PQCrypto::Seal.decrypt_file(src, dst, with: credentials, max_plaintext_bytes: 512 * 1024 * 1024)
+```

data/README.md

@@ -12,10 +12,10 @@ random DEK → AEGIS-256 → document
 `libaegis` 0.10.3 is vendored and compiled into the extension. The existing
 `pq_crypto` gem supplies the hybrid KEM and OpenSSL-backed primitives.
 
-> **Status:** 0.1.0 is experimental cryptographic software; format v1; not
+> **Status:** 0.1.1 is experimental cryptographic software; format v1; not
 > independently audited. Read `SECURITY.md` before using it for irreplaceable data.
 >
-> `wrap_suite_id = 1` is pinned to `:ml_kem_768_x25519_xwing` and `pq_crypto ~> 0.6.4`.
+> `wrap_suite_id = 1` is pinned to `:ml_kem_768_x25519_xwing` and `pq_crypto = 0.6.4`.
 
 ## Installation
 
@@ -129,7 +129,7 @@ rotated = PQCrypto::Seal.rotate_dek(
 
 `rebuild_recipients` preserves the DEK and encrypted payload. It is an
 operational migration of the current canonical copy, not protection against old
-saved envelopes. `rotate_dek` creates a new DEK and re-encrypts the payload; it
+saved envelopes. `rotate_dek` creates a new DEK, a **new payload_id**, and re-encrypts the payload; it
 still cannot erase knowledge from prior copies. Rotation preserves the current
 final envelope size by default (`padding: :preserve`); pass `:padme`, `:none`, or
 an explicit padding policy to recalculate it.
@@ -213,3 +213,19 @@ Set `PQC_SEAL_SANITIZE=1` when compiling under ASan/UBSan. The suite covers
 AEGIS one-shot/incremental equivalence, tampering, multi-recipient opening,
 full-envelope padding, recipient rebuilds, staged file publication, and parser
 limits.
+
+
+## Padding enforcement on decrypt
+
+After AEAD verification you may require a padding policy:
+
+```ruby
+PQCrypto::Seal.decrypt(envelope, with: credentials, required_padding: :padme)
+PQCrypto::Seal.decrypt(envelope, with: credentials, required_padding: :from_header)
+PQCrypto::Seal.decrypt(envelope, with: credentials, required_padding: { to: 4096 })
+```
+
+Omitting `required_padding` keeps padding enforcement optional. When supplied,
+the decryptor verifies both the authenticated policy id and the canonical target
+computed from the authenticated content and metadata lengths. Fixed and bucket
+policies require the expected target or bucket list from the application.

data/RELEASING.md

@@ -1,7 +1,7 @@
 # Releasing
 
 1. Run `bundle exec ruby script/vendor_libs.rb --check`.
-2. Confirm `pq_crypto` dependency remains `~> 0.6.4` and `WRAP_KEM_ALGORITHM`
+2. Confirm `pq_crypto` dependency remains `= 0.6.4` and `WRAP_KEM_ALGORITHM`
    is still `:ml_kem_768_x25519_xwing` with the documented sizes.
 3. Run the full CI matrix and sanitizer job.
 4. Build with `gem build pq_crypto-seal.gemspec`.

data/SECURITY.md

@@ -1,7 +1,7 @@
 # Security
 
 This project has not received an independent cryptographic or implementation
-audit. Do not treat version 0.1.0 as a substitute for a reviewed storage design.
+audit. Do not treat version 0.1.1 as a substitute for a reviewed storage design.
 
 Experimental cryptographic software; format v1; not independently audited.
 
@@ -44,6 +44,22 @@ callers that need residual-data hygiene must clear their own buffers.
 `Opened#data` / `Opened#metadata` returned from `open` are the caller's
 responsibility after use.
 
+
+## payload_id stability
+
+`payload_id` is stable across `rebuild_recipients` / add / drop operations.
+`rotate_dek` re-encrypts the payload with a fresh DEK and **allocates a new
+`payload_id`** — treat the result as a new document identity. Applications that
+need a stable external id across DEK rotation must track it outside the envelope.
+
+## Padding policy enforcement
+
+The authenticated header carries `padding_policy_id` only. Receivers that require
+a specific length-hiding policy should pass `required_padding:` to decrypt/open
+(for example `required_padding: :padme` or `required_padding: :from_header`).
+The receiver then checks both the policy id and the canonical target computed from
+authenticated inner lengths. Without that argument the field is informational.
+
 ## Envelope digests
 
 `Seal.digest` hashes the complete envelope, including the mutable recipient
@@ -77,7 +93,7 @@ forensics may still retain remnants; use a suitably protected staging filesystem
 
 `wrap_suite_id = 1` is permanently bound to MLKEM768-X25519 / X-Wing (draft-10
 compatible) with fixed public-key (1216), ciphertext (1120), and shared-secret
-(32) sizes, as implemented by `pq_crypto ~> 0.6.4`. Seal does not follow
+(32) sizes, as implemented by `pq_crypto = 0.6.4`. Seal does not follow
 `HybridKEM::CANONICAL_ALGORITHM`; a future change of that constant must not
 alter suite 1 wire bytes. Always generate keys with
 `PQCrypto::HybridKEM.generate(PQCrypto::Seal::WRAP_KEM_ALGORITHM)`.

data/VENDORING.md

@@ -12,3 +12,9 @@ libaegis 0.10.3.
 The complete source snapshot is retained, while the Ruby extension compiles only the AEGIS-256 and common implementation files it exposes. No system libaegis is
 loaded at runtime. Update the version, archive checksum, source snapshot, KATs,
 and cross-backend tests together.
+
+The git tree keeps the full upstream snapshot so `script/vendor_libs.rb --check`
+can prove byte-identity against the audited archive. The published gem package
+ships only the AEGIS-256 family plus shared `common`/`include` sources required
+to compile the extension (see `pq_crypto-seal.gemspec`); unused families and RAF
+remain in the repository for provenance and are not loaded at runtime.

data/lib/pq_crypto/seal/binary.rb

@@ -3,59 +3,68 @@
 module PQCrypto
   module Seal
     module Binary
-      module_function
+      INTEGER_TYPES = {
+        u8: [1, "C", 0xff],
+        u16: [2, "n", 0xffff],
+        u32: [4, "N", 0xffff_ffff],
+        u64: [8, "Q>", 0xffff_ffff_ffff_ffff]
+      }.freeze
 
-      def u8(value)
-        [integer!(value, 0xff)].pack("C")
-      end
+      class Reader
+        attr_reader :offset
 
-      def u16(value)
-        [integer!(value, 0xffff)].pack("n")
-      end
+        def initialize(bytes, offset = 0)
+          @bytes = String(bytes).b
+          @offset = Integer(offset)
+        end
 
-      def u32(value)
-        [integer!(value, 0xffff_ffff)].pack("N")
-      end
+        INTEGER_TYPES.each do |name, (length, directive, _max)|
+          define_method(name) { bytes(length).unpack1(directive) }
+        end
 
-      def u64(value)
-        [integer!(value, 0xffff_ffff_ffff_ffff)].pack("Q>")
-      end
+        def bytes(length)
+          length = Integer(length)
+          Binary.ensure_available!(@bytes, offset, length)
+          value = @bytes.byteslice(offset, length).b
+          @offset += length
+          value
+        end
 
-      def read_u8(bytes, offset)
-        ensure_available!(bytes, offset, 1)
-        [bytes.getbyte(offset), offset + 1]
+        def finished?
+          offset == @bytes.bytesize
+        end
       end
 
-      def read_u16(bytes, offset)
-        ensure_available!(bytes, offset, 2)
-        [bytes.byteslice(offset, 2).unpack1("n"), offset + 2]
-      end
+      class << self
+        INTEGER_TYPES.each do |name, (_length, directive, max)|
+          define_method(name) { |value| [integer!(value, max)].pack(directive) }
+          define_method("read_#{name}") { |bytes, offset| read_with(bytes, offset, &name) }
+        end
 
-      def read_u32(bytes, offset)
-        ensure_available!(bytes, offset, 4)
-        [bytes.byteslice(offset, 4).unpack1("N"), offset + 4]
-      end
+        def read_bytes(bytes, offset, length)
+          read_with(bytes, offset) { |reader| reader.bytes(length) }
+        end
 
-      def read_u64(bytes, offset)
-        ensure_available!(bytes, offset, 8)
-        [bytes.byteslice(offset, 8).unpack1("Q>"), offset + 8]
-      end
+        def ensure_available!(bytes, offset, length)
+          offset, length = Integer(offset), Integer(length)
 
-      def read_bytes(bytes, offset, length)
-        raise FormatError, "negative length" if length.negative?
-        ensure_available!(bytes, offset, length)
-        [bytes.byteslice(offset, length).b, offset + length]
-      end
+          raise FormatError, "invalid offset" if offset.negative? || length.negative?
+          raise FormatError, "truncated envelope" if offset > bytes.bytesize || length > bytes.bytesize - offset
+        end
 
-      def ensure_available!(bytes, offset, length)
-        raise FormatError, "invalid offset" if offset.negative? || length.negative?
-        raise FormatError, "truncated envelope" if offset > bytes.bytesize || length > bytes.bytesize - offset
-      end
+        def integer!(value, max)
+          number = Integer(value)
+          raise RangeError, "integer is out of range" if number.negative? || number > max
+
+          number
+        end
+
+        private
 
-      def integer!(value, max)
-        number = Integer(value)
-        raise RangeError, "integer is out of range" if number.negative? || number > max
-        number
+        def read_with(bytes, offset)
+          reader = Reader.new(bytes, offset)
+          [yield(reader), reader.offset]
+        end
       end
     end
   end