pqc_asn1

gem "pqc_asn1"

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

# 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!

# 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)

# 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)

# 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)

case PqcAsn1::DER.parse_spki(der)
in { oid:, key: }
  store_key(oid.name, key)
end

# 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"

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

# 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)

# 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

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