openid4vp 0.1.0

data/lib/openid4vp/jose/jwe.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "jose"
+
+require_relative "../jose"
+require_relative "../errors"
+require_relative "../util"
+require_relative "../util/base64url"
+require_relative "algorithms"
+require_relative "jwk"
+
+module OpenID4VP
+  module JOSE
+    # JSON Web Encryption (RFC 7516), compact serialization, restricted to
+    # the ECDH-ES key management family (RFC 7518 SS4.6) used for OpenID4VP
+    # SS8.3 encrypted Authorization Responses. A thin adapter over
+    # `JOSE::JWE` (the `jose` gem), which does the actual ECDH key
+    # agreement, Concat KDF, key wrapping and content encryption.
+    module JWE
+      # A decrypted JWE. `payload` is the parsed JSON Hash when `plaintext`
+      # parses as a JSON object, otherwise nil. `key` is the JWK used.
+      Decrypted = Struct.new(:header, :plaintext, :payload, :key, keyword_init: true)
+
+      # `jose`'s ECDH-ES key agreement for OKP (X25519/X448) recipients goes
+      # through JOSE::JWA::Curve25519/448, whose only implementation that
+      # ships without an extra runtime gem dependency (rbnacl/x25519) is the
+      # pure-Ruby fallback -- WITHOUT `rbnacl` or `x25519` installed, that
+      # fallback is NOT constant-time (a timing side-channel risk for X25519/
+      # X448 key agreement specifically). EC (P-256/384/521) recipients --
+      # the default and most common case -- go through OpenSSL and are
+      # unaffected. See README "Cryptography".
+      ::JOSE.crypto_fallback = true
+
+      class << self
+        # Encrypts `payload` (a Hash, JSON-encoded; or a String, used as raw
+        # plaintext bytes) to `recipient`'s public key, returning the
+        # compact serialization.
+        def encrypt(payload, recipient:, alg: nil, enc: "A128GCM", header: {}, apu: nil, apv: nil)
+          alg ||= recipient.alg || "ECDH-ES"
+          validate_algorithms!(alg, enc)
+
+          ephemeral = ephemeral_key_for(recipient)
+          protected_header = build_header(alg, enc, header, recipient, ephemeral, apu, apv)
+
+          ::JOSE::JWE.block_encrypt(
+            [jose_jwk(recipient.to_public), jose_jwk(ephemeral)], plaintext_bytes(payload), protected_header
+          ).compact
+        rescue ArgumentError, OpenSSL::OpenSSLError => e
+          raise OpenID4VP::InvalidRequest, "jwe: #{e.message}"
+        end
+
+        # Decrypts `compact` using the first of `keys` that both matches the
+        # header (by `kid`, or by `epk`'s `crv` when no `kid` is present) and
+        # successfully decrypts. Raises OpenID4VP::VerificationError when no
+        # key succeeds, and OpenID4VP::InvalidRequest on malformed input or
+        # an unsupported/unknown alg or enc.
+        def decrypt(compact, keys:)
+          protected_b64, = split_compact(compact)
+          header = decode_header(protected_b64)
+          validate_algorithms!(header["alg"], header["enc"])
+          epk = build_epk(header)
+
+          try_candidates(candidate_keys(keys, header, epk)) do |key|
+            plaintext, = ::JOSE::JWE.block_decrypt([jose_jwk(epk), jose_jwk(key)], compact)
+            Decrypted.new(header: header, plaintext: plaintext, payload: parse_payload(plaintext), key: key)
+          end
+        end
+
+        # Parses `compact` into its protected header WITHOUT decrypting.
+        # Raises OpenID4VP::InvalidRequest on malformed input.
+        def peek(compact)
+          protected_b64, = split_compact(compact)
+          decode_header(protected_b64)
+        end
+
+        private
+
+        # -- shared ---------------------------------------------------------
+
+        def jose_jwk(our_jwk)
+          ::JOSE::JWK.from_map(our_jwk.to_h)
+        rescue ArgumentError => e
+          raise OpenID4VP::InvalidRequest, "jwe: #{e.message}"
+        end
+
+        # -- encrypt helpers ---------------------------------------------
+
+        def validate_algorithms!(alg, enc)
+          unless alg.is_a?(String) && Algorithms::KEY_MANAGEMENT.include?(alg)
+            raise OpenID4VP::InvalidRequest, "jwe: unsupported alg #{alg.inspect}"
+          end
+          unless enc.is_a?(String) && Algorithms::CONTENT_ENCRYPTION.include?(enc)
+            raise OpenID4VP::InvalidRequest, "jwe: unsupported enc #{enc.inspect}"
+          end
+
+          [alg, enc]
+        end
+
+        def ephemeral_key_for(recipient)
+          case recipient.kty
+          when "EC" then JWK.generate(:ec, crv: recipient.crv)
+          when "OKP" then JWK.generate(:okp, crv: recipient.crv)
+          else raise OpenID4VP::InvalidRequest, "jwe: unsupported recipient kty #{recipient.kty.inspect}"
+          end
+        end
+
+        def build_header(alg, enc, header, recipient, ephemeral, apu, apv)
+          protected_header = { "alg" => alg, "enc" => enc }.merge(header)
+          protected_header["kid"] = recipient.kid if recipient.kid
+          protected_header["epk"] = ephemeral.to_public.to_h
+          protected_header["apu"] = Util::Base64url.encode(apu) if apu
+          protected_header["apv"] = Util::Base64url.encode(apv) if apv
+          protected_header
+        end
+
+        def plaintext_bytes(payload)
+          payload.is_a?(String) ? payload.b : ::JSON.generate(payload).b
+        end
+
+        # -- decrypt helpers ----------------------------------------------
+
+        def split_compact(compact)
+          parts = compact.to_s.split(".", -1)
+          raise OpenID4VP::InvalidRequest, "jwe: malformed compact serialization" unless parts.size == 5
+
+          parts
+        end
+
+        def decode_header(protected_b64)
+          header = Util::Base64url.decode_json(protected_b64)
+          raise OpenID4VP::InvalidRequest, "jwe: header is not a JSON object" unless header.is_a?(Hash)
+
+          header
+        end
+
+        # Strips any private member (e.g. "d") from the header's epk before
+        # it is used for ECDH key agreement: epk is attacker-controlled
+        # (RFC 7518 SS4.6.1.1 -- it's carried in the unauthenticated JWE
+        # header), and its only legitimate role is as the sender's
+        # EPHEMERAL PUBLIC key. Passing a private member through -- even
+        # though our own private key material is what's actually used for
+        # agreement -- is needless: it should never be present, let alone
+        # echoed or relied upon.
+        def build_epk(header)
+          epk = header["epk"]
+          raise OpenID4VP::InvalidRequest, "jwe: missing epk" unless epk.is_a?(Hash)
+
+          JWK.new(epk).to_public
+        end
+
+        # Restricts candidates to those whose `kty`/`crv` are actually
+        # compatible with `epk`'s -- a `kid` match alone does not guarantee
+        # that (a misconfigured or attacker-substituted `epk` can carry any
+        # curve) -- so an incompatible key never reaches key agreement,
+        # whose failure on mismatched domain parameters `try_candidates`
+        # also rescues, as defense in depth.
+        def candidate_keys(keys, header, epk)
+          matched = header["kid"] ? keys.select { |k| k.kid == header["kid"] } : keys
+          raise OpenID4VP::VerificationError, "no key for kid" if header["kid"] && matched.empty?
+
+          matched.select { |k| k.kty == epk.kty && k.crv == epk.crv }
+        end
+
+        def try_candidates(candidates)
+          raise OpenID4VP::VerificationError, "no matching key" if candidates.empty?
+
+          candidates.each do |key|
+            return yield(key)
+          rescue OpenID4VP::VerificationError, OpenSSL::OpenSSLError, ArgumentError
+            next
+          end
+          raise OpenID4VP::VerificationError, "decryption failed"
+        end
+
+        def parse_payload(bytes)
+          parsed = ::JSON.parse(bytes)
+          parsed.is_a?(Hash) ? parsed : nil
+        rescue ::JSON::ParserError, EncodingError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/openid4vp/jose/jwk.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "jose"
+
+require_relative "../jose"
+require_relative "../errors"
+require_relative "../util/base64url"
+
+module OpenID4VP
+  module JOSE
+    # A single JSON Web Key (RFC 7517): a thin adapter over `JOSE::JWK` (the
+    # `jose` gem), which does the actual key material parsing/serialization
+    # (including ASN.1 construction) for EC and RSA. Supports EC, OKP
+    # (Ed25519/X25519/X448) and RSA keys. Instances are immutable.
+    #
+    # OKP keys are converted to/from OpenSSL directly via OpenSSL's own raw
+    # key API (`JOSE::JWK#to_key` returns a raw byte String, not an
+    # OpenSSL::PKey, for OKP kty's, so it is not useful here).
+    class JWK
+      SUPPORTED_KTYS = %w[EC OKP RSA].freeze
+
+      EC_CURVE_TO_OPENSSL = {
+        "P-256" => "prime256v1",
+        "P-384" => "secp384r1",
+        "P-521" => "secp521r1"
+      }.freeze
+
+      EC_COORD_SIZES = { "P-256" => 32, "P-384" => 48, "P-521" => 66 }.freeze
+
+      OKP_CURVES = %w[Ed25519 X25519 X448].freeze
+      OKP_OID_TO_CRV = { "ED25519" => "Ed25519", "X25519" => "X25519", "X448" => "X448" }.freeze
+      OKP_KEY_LENGTH = { "Ed25519" => 32, "X25519" => 32, "X448" => 56 }.freeze
+
+      PRIVATE_ONLY_MEMBERS = {
+        "EC" => %w[d],
+        "OKP" => %w[d],
+        "RSA" => %w[d p q dp dq qi]
+      }.freeze
+
+      %w[kty crv kid alg use].each do |member|
+        define_method(member) { @members[member] }
+      end
+
+      class << self
+        # kty is :ec, :okp or :rsa. params (kid:, use:, alg:, ...) are merged
+        # into the resulting JWK's members.
+        def generate(kty, **params)
+          case kty
+          when :ec then generate_ec(params)
+          when :okp then generate_okp(params)
+          when :rsa then from_openssl(OpenSSL::PKey::RSA.new(params.delete(:bits) || 2048), **params)
+          else raise OpenID4VP::InvalidRequest, "jwk: unsupported kty for generate #{kty.inspect}"
+          end
+        end
+
+        # Any EC members hash reaching .new (directly, or built here) must
+        # have `d` left-padded to the curve's fixed coordinate length -- see
+        # #pad_ec_d below for why; a future constructor that bypasses it
+        # would reintroduce the P-521 truncation bug it fixes.
+        def from_openssl(pkey, **params)
+          members =
+            case pkey
+            when OpenSSL::PKey::EC then pad_ec_d(::JOSE::JWK.from_key(pkey).to_map.to_h)
+            when OpenSSL::PKey::RSA then ::JOSE::JWK.from_key(pkey).to_map.to_h
+            when OpenSSL::PKey::PKey then members_from_okp(pkey)
+            else raise OpenID4VP::InvalidRequest, "jwk: unsupported OpenSSL key type #{pkey.class}"
+            end
+          params.each { |k, v| members[k.to_s] = v unless v.nil? }
+          new(members)
+        rescue ArgumentError => e
+          raise OpenID4VP::InvalidRequest, "jwk: #{e.message}"
+        end
+
+        private
+
+        # JOSE::JWK::KTY_EC#to_map encodes `d` from the raw OpenSSL::BN,
+        # which strips leading zero bytes -- pad it back to the curve's
+        # fixed coordinate size (RFC 7518 SS6.2.1) so it round-trips through
+        # #decode_fixed_length! below.
+        def pad_ec_d(members)
+          size = EC_COORD_SIZES[members["crv"]]
+          return members unless size && members["d"]
+
+          bytes = Util::Base64url.decode(members["d"])
+          members["d"] = Util::Base64url.encode(bytes.rjust(size, "\x00".b))
+          members
+        end
+
+        def generate_ec(params)
+          crv = params.delete(:crv)
+          openssl_name = EC_CURVE_TO_OPENSSL.fetch(crv) do
+            raise OpenID4VP::InvalidRequest, "jwk: unsupported EC curve #{crv.inspect}"
+          end
+          from_openssl(OpenSSL::PKey::EC.generate(openssl_name), **params)
+        end
+
+        def generate_okp(params)
+          crv = params.delete(:crv)
+          raise OpenID4VP::InvalidRequest, "jwk: unsupported OKP curve #{crv.inspect}" unless OKP_CURVES.include?(crv)
+
+          from_openssl(OpenSSL::PKey.generate_key(crv), **params)
+        end
+
+        def members_from_okp(pkey)
+          crv = OKP_OID_TO_CRV.fetch(pkey.oid) do
+            raise OpenID4VP::InvalidRequest, "jwk: unsupported OKP key #{pkey.oid}"
+          end
+          members = { "kty" => "OKP", "crv" => crv, "x" => Util::Base64url.encode(pkey.raw_public_key) }
+          begin
+            members["d"] = Util::Base64url.encode(pkey.raw_private_key)
+          rescue OpenSSL::PKey::PKeyError
+            # public-only key
+          end
+          members
+        end
+      end
+
+      # Note for callers building an EC members Hash directly (rather than
+      # via .from_openssl/.generate): `d` must be left-padded with zero
+      # bytes to the curve's fixed coordinate length (see #pad_ec_d) --
+      # JOSE::JWK::KTY_EC#to_map does not pad it, so a `d` sourced from
+      # there needs the same fixup .from_openssl already applies.
+      def initialize(members)
+        @members = members.each_with_object({}) { |(k, v), h| h[k.to_s] = v }.freeze
+        raise OpenID4VP::InvalidRequest, "jwk: missing kty" if @members["kty"].nil?
+        unless SUPPORTED_KTYS.include?(@members["kty"])
+          raise OpenID4VP::InvalidRequest, "jwk: unsupported kty #{@members['kty'].inspect}"
+        end
+
+        freeze
+      end
+
+      def private?
+        @members.key?("d")
+      end
+
+      def public?
+        !private?
+      end
+
+      def to_public
+        return self if public?
+
+        self.class.new(@members.except(*PRIVATE_ONLY_MEMBERS.fetch(kty, [])))
+      end
+
+      def to_h
+        @members.dup
+      end
+
+      def to_json(*)
+        ::JSON.generate(to_h, *)
+      end
+
+      # RFC 7638 JWK thumbprint: raw 32-byte SHA-256 digest, computed over
+      # JOSE::JWK's canonical (sorted-key) member selection for `kty`.
+      def thumbprint
+        Util.sha256(::JOSE.encode(jose_jwk.to_thumbprint_map))
+      rescue ArgumentError, OpenSSL::OpenSSLError => e
+        raise OpenID4VP::InvalidRequest, "jwk: cannot compute thumbprint for kty #{kty}: #{e.message}"
+      end
+
+      def thumbprint_b64
+        Util::Base64url.encode(thumbprint)
+      end
+
+      def to_openssl
+        case kty
+        when "EC" then openssl_ec
+        when "OKP" then openssl_okp
+        when "RSA" then openssl_via_jose("RSA")
+        else raise OpenID4VP::InvalidRequest, "jwk: cannot convert kty #{kty} to an OpenSSL key"
+        end
+      end
+
+      # Equality is by public key material (the RFC 7638 thumbprint members),
+      # not full to_public.to_h: a private key equals its own public form,
+      # and a key equals itself after a round trip through OpenSSL even
+      # though such a round trip cannot preserve metadata like kid/use/alg.
+      def ==(other)
+        other.is_a?(JWK) && kty == other.kty && thumbprint == other.thumbprint
+      rescue OpenID4VP::InvalidRequest
+        false
+      end
+      alias eql? ==
+
+      def hash
+        [kty, thumbprint].hash
+      rescue OpenID4VP::InvalidRequest
+        kty.hash
+      end
+
+      private
+
+      # JOSE::JWK.from_map itself constructs OpenSSL key material (e.g. an
+      # EC::Point for the x/y coordinates), so a structurally well-formed
+      # but invalid member (an off-curve point of valid length, say) can
+      # raise a raw OpenSSL::OpenSSLError here, not just ArgumentError.
+      def jose_jwk
+        ::JOSE::JWK.from_map(@members)
+      rescue ArgumentError, OpenSSL::OpenSSLError => e
+        raise OpenID4VP::InvalidRequest, "jwk: #{e.message}"
+      end
+
+      def openssl_via_jose(label)
+        jose_jwk.to_key
+      rescue ArgumentError, OpenSSL::OpenSSLError => e
+        raise OpenID4VP::InvalidRequest, "jwk: invalid #{label} key material: #{e.message}"
+      end
+
+      def fetch!(key)
+        @members.fetch(key) { raise OpenID4VP::InvalidRequest, "jwk: missing #{key}" }
+      end
+
+      # Raises OpenID4VP::InvalidRequest unless the decoded member is exactly
+      # `expected` bytes long, so malformed key material never reaches
+      # OpenSSL's raw key constructors as a raw ArgumentError/OpenSSLError.
+      def decode_fixed_length!(member, expected)
+        bytes = Util::Base64url.decode(fetch!(member))
+        return bytes if bytes.bytesize == expected
+
+        raise OpenID4VP::InvalidRequest,
+              "jwk: #{member} must be #{expected} bytes for #{crv}, got #{bytes.bytesize}"
+      end
+
+      # EC key material is length-checked here (rather than left to jose/
+      # OpenSSL) because OpenSSL 3 can construct an EVP_PKEY from an
+      # inconsistent SEC1 private key (wrong-length or out-of-range `d`)
+      # without raising until the key is later used, which would leak a
+      # not-yet-invalid-looking key out of this method.
+      def openssl_ec
+        size = EC_COORD_SIZES.fetch(crv) { raise OpenID4VP::InvalidRequest, "jwk: unsupported EC curve #{crv.inspect}" }
+        decode_fixed_length!("x", size)
+        decode_fixed_length!("y", size)
+        decode_fixed_length!("d", size) if @members.key?("d")
+        openssl_via_jose("EC")
+      end
+
+      def openssl_okp
+        raise OpenID4VP::InvalidRequest, "jwk: unsupported OKP curve #{crv.inspect}" unless OKP_CURVES.include?(crv)
+
+        size = OKP_KEY_LENGTH.fetch(crv)
+        if @members.key?("d")
+          OpenSSL::PKey.new_raw_private_key(crv, decode_fixed_length!("d", size))
+        else
+          OpenSSL::PKey.new_raw_public_key(crv, decode_fixed_length!("x", size))
+        end
+      rescue OpenSSL::OpenSSLError, ArgumentError => e
+        raise OpenID4VP::InvalidRequest, "jwk: invalid OKP key material: #{e.message}"
+      end
+    end
+  end
+end

data/lib/openid4vp/jose/jwk_set.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "../jose"
+require_relative "../errors"
+require_relative "jwk"
+
+module OpenID4VP
+  module JOSE
+    # A JSON Web Key Set (RFC 7517 §5): an ordered collection of JWKs.
+    class JWKSet
+      attr_reader :keys
+
+      def self.from_h(hash)
+        keys = (hash["keys"] || hash[:keys] || []).map { |member| JWK.new(member) }
+        new(keys: keys)
+      end
+
+      def initialize(keys:)
+        @keys = keys.dup.freeze
+      end
+
+      def find(kid)
+        @keys.find { |k| k.kid == kid }
+      end
+
+      def to_h
+        { "keys" => @keys.map(&:to_h) }
+      end
+
+      def to_json(*)
+        ::JSON.generate(to_h, *)
+      end
+
+      # Picks a key usable for content encryption key agreement/wrapping:
+      # keys without an `alg` are ignored, a key restricted to
+      # `supported_algs` (when given) is preferred, and a key with
+      # `use: "enc"` is preferred over the first remaining match.
+      def select_encryption_key(supported_algs: nil)
+        candidates = @keys.select do |key|
+          next false unless key.alg
+          next false if supported_algs && !supported_algs.include?(key.alg)
+
+          true
+        end
+        candidates.find { |key| key.use == "enc" } || candidates.first
+      end
+
+      # OID4VP §5.1: every JWK in a client_metadata.jwks JWK Set must carry a
+      # `kid` so it can be referenced unambiguously.
+      def require_kids!
+        return if @keys.all?(&:kid)
+
+        raise OpenID4VP::InvalidRequest, "jwks: every key must have a kid"
+      end
+    end
+  end
+end