pqc_asn1 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d82d0cdf76e9156af39368f55311d62bc7bf1a0f8b7c50e1a59cf8d49a90ff95
+  data.tar.gz: d922d07e2f12177fe0a0b1a88df589aa6edf9f9ff45f4ec6278a20926d628071
+SHA512:
+  metadata.gz: dd25d378e2719c6b29abbb6cb68d8c2c1e76b974b7532c97cdb4399e19f24e90aa38ff36b12bbcf2b191f7f8f5bc8207a90ed76016c5bbaafe11ae588d842082
+  data.tar.gz: f77499b592e7cd301780cf33d9a9cf5112a167a1cf4c0c624d97ebdbcc3f1e9dd30ba25cc0d9c82831f8d208faec920d89ea21740f5f12af05dc08df066b2b28

data/CHANGELOG.md

@@ -0,0 +1,116 @@
+# 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]
+
+### Fixed
+
+- `SecureBuffer#wipe!` now returns `self` instead of `nil`, enabling method
+  chaining (e.g. `buf.wipe!.frozen?`).
+- `SecureBuffer.random(n)` rejects negative values with a clear `ArgumentError`
+  instead of silently wrapping via `NUM2SIZET`.
+- `SecureBuffer#slice(offset, length)` rejects negative offset or length with
+  `ArgumentError` instead of wrapping to a huge unsigned value.
+- `DER.read_tlv` rejects negative offset with `ArgumentError`.
+- `DER::Cursor.new(data, pos)` rejects negative pos with `ArgumentError`.
+- PEM label mismatch during IO streaming now raises `PEMError` (was `ParseError`).
+- Truncated PEM over IO (BEGIN without matching END) now raises `PEMError`
+  with code `:pem_no_markers` instead of silently dropping the block.
+- `DER.build_encrypted_pkcs8` raises `ArgumentError` when either argument is
+  `nil` instead of a confusing `NoMethodError`.
+
+### Changed
+
+- `check_input_size!` is now a private method outside of `class << self`,
+  improving readability.
+
+## [0.1.0] — 2026-03-17
+
+### Added
+
+- Algorithm-agnostic DER TLV read/write (`DER.read_tlv`, `DER.write_tlv` — private).
+- SPKI encode/decode (`DER.build_spki`, `DER.parse_spki`).
+- PKCS#8 / OneAsymmetricKey encode/decode (`DER.build_pkcs8`, `DER.parse_pkcs8`).
+- EncryptedPrivateKeyInfo encode/decode (`DER.build_encrypted_pkcs8`,
+  `DER.parse_encrypted_pkcs8`) — codec only, no encryption/decryption.
+- PEM encode/decode (`PEM.encode`, `PEM.decode`, `PEM.decode_auto`,
+  `PEM.decode_each`).
+- `PEM.decode_each` accepts IO objects (or any `#each_line` responder) in
+  addition to Strings, reading line-by-line to avoid slurping the entire stream.
+- `PEM::DecodeResult` — value object returned by `PEM.decode_auto` with
+  `#data`, `#label`, `#to_a`, `#to_h`, `#deconstruct_keys`, and `#==`.
+  Use `result.to_a` for explicit Array destructuring.
+- Base64 encode/decode (RFC 4648, strict padding validation).
+- Built-in OID constants for ML-DSA (FIPS 204), ML-KEM (FIPS 203), and
+  SLH-DSA (FIPS 205) — all 18 NIST PQC parameter sets.
+- `OID.from_dotted` / `OID.to_dotted` — convert between dotted-decimal notation
+  and DER-encoded OID TLV bytes.
+- `OID.name_for` — reverse lookup from OID to constant name.
+- `OID.register(dotted, name, key_sizes: nil)` — register custom OIDs at
+  runtime; creates a named constant under `PqcAsn1::OID` and optionally extends
+  key size validation.
+- `DER::KeyInfo` — immutable value object returned by `parse_spki` /
+  `parse_pkcs8` with `#oid`, `#parameters`, `#key`, `#public_key`, `#format`,
+  `#algorithm`, `#to_der`, `#to_pem`, and pattern-matching support.
+- `DER::EncryptedKeyInfo` — value object for EncryptedPrivateKeyInfo structures.
+- `DER::CompositeKeyInfo` — placeholder for future composite key support
+  (raises `NotImplementedError`).
+- `DER.parse_auto` — detect SPKI vs PKCS#8 vs EncryptedPrivateKeyInfo by
+  structure and dispatch to the correct parser.
+- `DER.parse_pem` — decode a PEM string and parse the contained DER structure;
+  uses the PEM label to select the parser.
+- `DER.detect_format` — lightweight format detection returning `:spki`,
+  `:pkcs8`, `:encrypted_pkcs8`, or `nil`.
+- `DER.build_spki` and `DER.build_pkcs8` accept `validate: true` keyword to
+  check key lengths against `DER::KEY_SIZES` before encoding.
+- `DER.build_spki` and `DER.build_pkcs8` accept `parameters:` keyword for
+  AlgorithmIdentifier parameters and (PKCS#8 only) `public_key:` keyword for
+  the RFC 5958 publicKey field.
+- `DER::KEY_SIZES` — frozen Hash mapping each built-in OID to
+  `{ public:, secret: }` expected byte counts.
+- `DER::Cursor` — zero-copy DER reader as a first-class public API with
+  `#read`, `#read_raw`, `#read_sequence`, `#read_optional`, `#read_raw_optional`,
+  `#skip`, `#skip_optional`, `#peek_tag`, `#eof?`, `#remaining`, `#pos`, `#data`,
+  and convenience readers (`#read_integer`, `#read_oid`, `#read_octet_string`,
+  `#read_bit_string`).
+- `SecureBuffer` — `mmap`-backed allocation with `mlock`, `mprotect` guard
+  pages, canary integrity checking, and secure zeroing on GC.
+- `SecureBuffer#use { |bytes| }` — block-scoped access to secret key
+  bytes; the yielded String is securely zeroed after the block returns.
+- `SecureBuffer#wipe!` — eagerly zero and mark the buffer as wiped.
+- `SecureBuffer#slice(offset, length)` — extract a sub-range as a new
+  SecureBuffer.
+- `SecureBuffer#to_pem(label = "PRIVATE KEY")` — PEM-encode DER contents
+  directly from a SecureBuffer.
+- `SecureBuffer.random(n)` — fill a new buffer from the platform CSPRNG.
+- `SecureBuffer.from_string(str)` — copy a String into a SecureBuffer.
+- `SecureBuffer#==` — constant-time equality comparison.
+- `DERError`, `PEMError`, `OIDError` — fine-grained error subclasses.
+  `DERError` and `PEMError` inherit from `ParseError` (backward-compatible);
+  `OIDError` inherits from `Error`.
+- `Error#code` — fine-grained symbol (e.g. `:outer_sequence`, `:base64`)
+  identifying the exact failure point.
+- `Error#category` — coarse programmatic error category (`:malformed_input`,
+  `:malformed_encoding`, `:validation`, `:system`).
+- `Error#offset` — byte position in the input where a parse error was detected.
+- `rake vendor:verify` — checks SHA-256 of vendored C files against pinned
+  checksums; fails loudly on mismatch.
+- `rake vendor:lock` — records current SHA-256 digests after a deliberate
+  vendor upgrade.
+- `rake vendor:concat` — re-vendor from a local libpqcasn1 checkout.
+- `rake vendor:update[VERSION]` — re-vendor from a GitHub release tarball.
+- `rake fixtures:generate` — regenerates test fixtures from scratch.
+- No runtime dependencies; no OpenSSL.
+- Vendored libpqcasn1 0.1.3.
+
+### Known limitations
+
+- **No Windows support.** `SecureBuffer` uses POSIX `mmap`/`mprotect`/
+  `mlock`, which are unavailable on Windows.  The gem will not compile on
+  Windows without a compatibility layer (e.g. Cygwin/MSYS2).
+- Composite key support is not yet implemented (placeholder classes raise
+  `NotImplementedError`).

data/LICENSE

@@ -0,0 +1,14 @@
+Copyright 2026 Suleyman Musayev
+
+This project is dual-licensed. You may use, distribute, and modify it under
+the terms of either:
+
+  * the MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT), or
+  * the Apache License, Version 2.0 (LICENSE-APACHE or
+    http://www.apache.org/licenses/LICENSE-2.0)
+
+at your option.
+
+Unless you explicitly state otherwise, any Contribution intentionally submitted
+for inclusion in this project by you, as defined in the Apache-2.0 license,
+shall be dual-licensed as above, without any additional terms or conditions.

data/LICENSE-APACHE

@@ -0,0 +1,185 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and subsequently
+      incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or a Contribution
+      incorporated within the Work constitutes direct or contributory patent
+      infringement, then any patent licenses granted to You under this License
+      for that Work shall terminate as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text file
+          distributed as part of the Derivative Works; within the Source
+          form or documentation, if provided along with the Derivative
+          Works; or, within a display generated by the Derivative Works,
+          if and wherever such third-party notices normally appear. The
+          contents of the NOTICE file are for informational purposes only
+          and do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, reproduce, modify,
+      prepare Derivative Works of, publicly display, publicly perform,
+      sublicense, and distribute those modifications and additional rights
+      as a separate license, provided Your use, reproduction, modification,
+      preparation of Derivative Works, distribution, and other activities
+      remain in full compliance with the terms of this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Suleyman Musayev
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suleyman Musayev
+
+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,267 @@
+# pqc_asn1
+
+Algorithm-agnostic ASN.1/DER/PEM/Base64 codec for post-quantum cryptography key
+serialization. Implemented in C with no OpenSSL dependency.
+
+Handles SPKI (SubjectPublicKeyInfo, RFC 5480) and PKCS#8 / OneAsymmetricKey
+(RFC 5958) structures for ML-DSA, ML-KEM, SLH-DSA, and any future scheme that
+uses standard key-wrapping formats.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "pqc_asn1"
+```
+
+Or install directly:
+
+```sh
+gem install pqc_asn1
+```
+
+The gem builds a native C extension — a C compiler is required.
+
+## Usage
+
+### Public key (SPKI)
+
+```ruby
+require "pqc_asn1"
+
+# Encode
+der = PqcAsn1::DER.build_spki(PqcAsn1::OID::ML_DSA_44, public_key_bytes)
+pem = PqcAsn1::PEM.encode(der, "PUBLIC KEY")
+
+# Decode
+info = PqcAsn1::DER.parse_spki(der)
+info.algorithm  # => "ML_DSA_44"
+info.key        # => binary String (public key bytes)
+info.to_der     # => original DER bytes
+info.to_pem     # => PEM string with "PUBLIC KEY" label
+```
+
+### Private key (PKCS#8)
+
+```ruby
+# build_pkcs8 returns a SecureBuffer — memory is locked and securely zeroed on GC
+der = PqcAsn1::DER.build_pkcs8(PqcAsn1::OID::ML_DSA_44, secret_key_bytes)
+pem = PqcAsn1::PEM.encode(der, "PRIVATE KEY")
+
+# SecureBuffer convenience
+der.to_pem              # => PEM string with "PRIVATE KEY" label
+
+# Decode
+info = PqcAsn1::DER.parse_pkcs8(der)
+info.algorithm          # => "ML_DSA_44"
+
+# Use block-scoped access — bytes are securely zeroed when the block exits
+info.key.use { |bytes| sign(bytes) }
+
+# Or wipe manually
+info.key.wipe!
+```
+
+### Key size validation
+
+```ruby
+# Raises ArgumentError if the key length doesn't match the OID
+der = PqcAsn1::DER.build_spki(PqcAsn1::OID::ML_DSA_44, pk, validate: true)
+der = PqcAsn1::DER.build_pkcs8(PqcAsn1::OID::ML_DSA_44, sk, validate: true)
+```
+
+### Auto-detection
+
+```ruby
+# Detects SPKI vs PKCS#8 vs EncryptedPrivateKeyInfo automatically
+info = PqcAsn1::DER.parse_auto(der_bytes)
+info.format     # => :spki, :pkcs8, or :encrypted_pkcs8
+
+# PEM decode with auto-detection (uses PEM label to select parser)
+info = PqcAsn1::DER.parse_pem(pem_string)
+```
+
+### PEM encoding / decoding
+
+```ruby
+# Encode arbitrary bytes
+pem = PqcAsn1::PEM.encode(bytes, "PUBLIC KEY")
+
+# Decode — returns a DecodeResult
+result = PqcAsn1::PEM.decode_auto(pem)
+result.label    # => "PUBLIC KEY"
+result.data     # => DER bytes
+
+# Explicit destructuring via .to_a
+data, label = PqcAsn1::PEM.decode_auto(pem).to_a
+
+# Iterate multiple PEM blocks in a String or IO stream
+PqcAsn1::PEM.decode_each(pem_string) { |r| process(r.data, r.label) }
+
+# IO streaming — reads line-by-line without slurping the file
+File.open("keys.pem") do |f|
+  PqcAsn1::PEM.decode_each(f) { |r| process(r.data, r.label) }
+end
+
+# Without a block — returns an Enumerator
+PqcAsn1::PEM.decode_each(pem_string).map(&:data)
+```
+
+### Pattern matching (Ruby 2.7+)
+
+```ruby
+case PqcAsn1::DER.parse_spki(der)
+in { oid:, key: }
+  store_key(oid.name, key)
+end
+```
+
+### OID utilities
+
+```ruby
+# Dotted-decimal <-> DER TLV
+der_tlv = PqcAsn1::OID.from_dotted("2.16.840.1.101.3.4.3.17")
+PqcAsn1::OID.to_dotted(der_tlv)   # => "2.16.840.1.101.3.4.3.17"
+
+# Name lookup
+PqcAsn1::OID.name_for(der_tlv)    # => "ML_DSA_44"
+
+# OID value objects
+oid = PqcAsn1::OID.new("2.16.840.1.101.3.4.3.17")
+oid.name    # => "ML_DSA_44"
+oid.dotted  # => "2.16.840.1.101.3.4.3.17"
+```
+
+### Registering custom OIDs at runtime
+
+Registration is thread-safe (protected by a Mutex).
+
+```ruby
+oid = PqcAsn1::OID.register(
+  "1.3.9999.1",
+  "MY_ALGO_128",
+  key_sizes: { public: 1312, secret: 2528 }
+)
+
+# Look up by name or dotted string — no constant is defined automatically
+PqcAsn1::OID["MY_ALGO_128"]                        # => OID value object
+PqcAsn1::OID["1.3.9999.1"]                         # => same object
+PqcAsn1::DER.build_spki(oid, pk, validate: true)   # key size validation works
+
+# To define a constant, assign explicitly:
+PqcAsn1::OID::MY_ALGO_128 = oid
+```
+
+### SecureBuffer
+
+```ruby
+# Build a PKCS#8 key — returns a SecureBuffer
+der = PqcAsn1::DER.build_pkcs8(PqcAsn1::OID::ML_DSA_44, secret_key_bytes)
+
+# Block-scoped access — bytes zeroed after the block
+der.use { |bytes| sign(bytes) }
+
+# Write DER bytes directly to an IO (minimises heap exposure)
+File.open("key.der", "wb") { |f| der.write_to(f) }
+
+# PEM-encode directly to an IO
+File.open("key.pem", "w") { |f| der.to_pem_io(f) }
+
+# Wipe returns self for chaining
+der.wipe!.wiped?  # => true
+
+# Generate random secure bytes from the platform CSPRNG
+nonce = PqcAsn1::SecureBuffer.random(32)
+
+# Extract a sub-range as a new SecureBuffer
+slice = der.slice(0, 64)
+```
+
+### Input size limits
+
+```ruby
+# Default: 1 MiB — protects parse methods against oversized input
+PqcAsn1::DER.max_input_size          # => 1048576
+
+# Adjust or disable
+PqcAsn1::DER.max_input_size = 4 << 20  # 4 MiB
+PqcAsn1::DER.max_input_size = nil       # no limit
+```
+
+### Error handling
+
+```ruby
+begin
+  PqcAsn1::DER.parse_spki(bad_bytes)
+rescue PqcAsn1::DERError => e
+  # DER structure is malformed
+  puts e.category   # => :malformed_input
+  puts e.code       # => :outer_sequence (fine-grained symbol)
+  puts e.offset     # => byte position where error was detected
+rescue PqcAsn1::PEMError => e
+  # Base64 / PEM armor problem
+rescue PqcAsn1::OIDError => e
+  # Unrecognised or invalid OID
+rescue PqcAsn1::ParseError => e
+  # Catches both DERError and PEMError
+rescue PqcAsn1::Error => e
+  # Top-level catch-all
+end
+```
+
+Error categories:
+
+| Category | Meaning |
+|---|---|
+| `:malformed_input` | DER TLV structure is wrong |
+| `:malformed_encoding` | Base64 or PEM armor is invalid |
+| `:validation` | Key size or OID mismatch |
+| `:system` | Memory allocation failure |
+
+## OID constants
+
+`PqcAsn1::OID` contains value objects for all current NIST PQC algorithms:
+
+| Constant | Algorithm | OID |
+|---|---|---|
+| `ML_DSA_44` | ML-DSA (FIPS 204) | 2.16.840.1.101.3.4.3.17 |
+| `ML_DSA_65` | ML-DSA (FIPS 204) | 2.16.840.1.101.3.4.3.18 |
+| `ML_DSA_87` | ML-DSA (FIPS 204) | 2.16.840.1.101.3.4.3.19 |
+| `ML_KEM_512` | ML-KEM (FIPS 203) | 2.16.840.1.101.3.4.4.1 |
+| `ML_KEM_768` | ML-KEM (FIPS 203) | 2.16.840.1.101.3.4.4.2 |
+| `ML_KEM_1024` | ML-KEM (FIPS 203) | 2.16.840.1.101.3.4.4.3 |
+| `SLH_DSA_SHA2_128S` | SLH-DSA (FIPS 205) | 2.16.840.1.101.3.4.3.20 |
+| `SLH_DSA_SHA2_128F` | SLH-DSA (FIPS 205) | 2.16.840.1.101.3.4.3.21 |
+| `SLH_DSA_SHA2_192S` | SLH-DSA (FIPS 205) | 2.16.840.1.101.3.4.3.22 |
+| `SLH_DSA_SHA2_192F` | SLH-DSA (FIPS 205) | 2.16.840.1.101.3.4.3.23 |
+| `SLH_DSA_SHA2_256S` | SLH-DSA (FIPS 205) | 2.16.840.1.101.3.4.3.24 |
+| `SLH_DSA_SHA2_256F` | SLH-DSA (FIPS 205) | 2.16.840.1.101.3.4.3.25 |
+| `SLH_DSA_SHAKE_128S` | SLH-DSA (FIPS 205) | 2.16.840.1.101.3.4.3.26 |
+| `SLH_DSA_SHAKE_128F` | SLH-DSA (FIPS 205) | 2.16.840.1.101.3.4.3.27 |
+| `SLH_DSA_SHAKE_192S` | SLH-DSA (FIPS 205) | 2.16.840.1.101.3.4.3.28 |
+| `SLH_DSA_SHAKE_192F` | SLH-DSA (FIPS 205) | 2.16.840.1.101.3.4.3.29 |
+| `SLH_DSA_SHAKE_256S` | SLH-DSA (FIPS 205) | 2.16.840.1.101.3.4.3.30 |
+| `SLH_DSA_SHAKE_256F` | SLH-DSA (FIPS 205) | 2.16.840.1.101.3.4.3.31 |
+
+## Key size reference
+
+`PqcAsn1::DER::KEY_SIZES` maps each OID to `{ public:, secret: }` byte counts.
+Used automatically when `validate: true` is passed to `build_spki` / `build_pkcs8`.
+
+## Requirements
+
+- Ruby >= 2.7.2
+- A C compiler (the gem builds a native extension)
+- POSIX platform (Linux, macOS). Windows is not supported — `SecureBuffer`
+  requires `mmap`/`mprotect`/`mlock` which are unavailable on native Windows
+
+## License
+
+Licensed under either of
+
+- MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+
+at your option. Contributions are dual-licensed under the same terms unless
+explicitly stated otherwise.