smart_health_cards_test_kit 0.9.0

data/lib/smart_health_cards_test_kit/shc_signature_verification.rb

@@ -0,0 +1,95 @@
+require_relative 'utils/verifier'
+
+module SmartHealthCardsTestKit
+  class SHCSignatureVerification < Inferno::Test
+    include HealthCard
+
+    id :shc_signature_verification_test
+    title 'Verifiable Credential JWS payload has correct JWS signature'
+    description %(
+      Each public key used to verify signatures is represented as a JSON Web Key
+      (see [RFC7517](https://tools.ietf.org/html/rfc7517)), with some of its properties encoded using
+      base64url (see section 5 of [RFC4648](https://tools.ietf.org/html/rfc4648#section-5)):
+
+      * SHALL have "kty": "EC", "use": "sig", and "alg": "ES256"
+      * SHALL have "kid" equal to the base64url-encoded SHA-256 JWK Thumbprint of the key
+      (see [RFC7638](https://tools.ietf.org/html/rfc7638))
+      * SHALL have "crv": "P-256", and "x", "y" equal to the base64url-encoded values for the public Elliptic
+      Curve point coordinates (see [RFC7518](https://tools.ietf.org/html/rfc7518#section-6.2))
+      * SHALL NOT have the Elliptic Curve private key parameter "d"
+      * If the issuer has an X.509 certificate for the public key, SHALL have "x5c" equal to an array of one
+      or more base64-encoded (not base64url-encoded) DER representations of the public certificate or
+      certificate chain (see [RFC7517](https://tools.ietf.org/html/rfc7517#section-4.7)). The public key
+      listed in the first certificate in the "x5c" array SHALL match the public key specified by the "crv",
+      "x", and "y" parameters of the same JWK entry. If the issuer has more than one certificate for the same
+      public key (e.g. participation in more than one trust community), then a separate JWK entry is used for
+      each certificate with all JWK parameter values identical except "x5c".
+
+      Issuers SHALL publish their public keys as JSON Web Key Sets (see
+      [RFC7517](https://tools.ietf.org/html/rfc7517#section-4.7)), available at
+      <<iss value from JWS>> + /.well-known/jwks.json, with Cross-Origin Resource Sharing (CORS) enabled, using
+      TLS version 1.2 following the IETF BCP 195 recommendations or TLS version 1.3 (with any configuration).
+
+      The URL at <<iss value from JWS>> SHALL use the https scheme and SHALL NOT include a trailing /.
+      For example, https://smarthealth.cards/examples/issuer is a valid iss value
+      (https://smarthealth.cards/examples/issuer/ is not).
+    )
+
+    input :credential_strings
+
+    run do
+      skip_if credential_strings.blank?, 'No Verifiable Credentials received'
+
+      credential_strings.split(',').each do |credential|
+
+        jws = SmartHealthCardsTestKit::Utils::JWS.from_jws(credential)
+        payload = payload_from_jws(jws)
+        iss = payload['iss']
+
+        assert iss.present?, 'Credential contains no `iss`'
+        warning { assert iss.start_with?('https://'), "`iss` SHALL use the `https` scheme: #{iss}" }
+        assert !iss.end_with?('/'), "`iss` SHALL NOT include a trailing `/`: #{iss}"
+
+        key_set_url = "#{iss}/.well-known/jwks.json"
+
+        get(key_set_url)
+
+        assert_response_status(200)
+        assert_valid_json(response[:body])
+
+        cors_header = request.response_header('Control-Allow-Origin')
+        warning do
+          assert cors_header.present?,
+                 'No CORS header received. Issuers SHALL publish their public keys with CORS enabled'
+          assert cors_header.value == '*',
+                 "Expected CORS header value of `*`, but actual value was `#{cors_header.value}`"
+        end
+
+        key_set = JSON.parse(response[:body])
+
+        public_key = key_set['keys'].find { |key| key['kid'] == jws.kid }
+        key_object = SmartHealthCardsTestKit::Utils::Key.from_jwk(public_key)
+
+        assert public_key.present?, "Key set did not contain a key with a `kid` of #{jws.kid}"
+
+        assert public_key['kty'] == 'EC', "Key had a `kty` value of `#{public_key['kty']}` instead of `EC`"
+        assert public_key['use'] == 'sig', "Key had a `use` value of `#{public_key['use']}` instead of `sig`"
+        assert public_key['alg'] == 'ES256', "Key had an `alg` value of `#{public_key['alg']}` instead of `ES256`"
+        assert public_key['crv'] == 'P-256', "Key had a `crv` value of `#{public_key['crv']}` instead of `P-256`"
+        assert !public_key.include?('d'), 'Key SHALL NOT have the private key parameter `d`'
+        assert public_key['kid'] == key_object.kid,
+          "'kid' SHALL be equal to the base64url-encoded SHA-256 JWK Thumbprint of the key. " \
+          "Received: '#{public_key['kid']}', Expected: '#{key_object.kid}'"
+
+        verifier = SmartHealthCardsTestKit::Utils::Verifier.new(keys: key_object, resolve_keys: false)
+
+        begin
+          assert verifier.verify(jws), 'JWS signature invalid'
+        rescue StandardError => e
+          assert false, "Error decoding credential: #{e.message}"
+        end
+      end
+    end
+  end
+end
+

data/lib/smart_health_cards_test_kit/utils/chunking_utils.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module SmartHealthCardsTestKit
+  module Utils
+  # Split up a JWS into chunks if encoded size is above QR Code Size constraint
+    module ChunkingUtils
+      extend self
+      MAX_SINGLE_JWS_SIZE = 1195
+      MAX_CHUNK_SIZE = 1191
+
+      def split_jws(jws)
+        if jws.length <= MAX_SINGLE_JWS_SIZE
+          [jws]
+        else
+          chunk_count = (jws.length / MAX_CHUNK_SIZE.to_f).ceil
+          chunk_size  = (jws.length / chunk_count.to_f).ceil
+          jws.scan(/.{1,#{chunk_size}}/)
+        end
+      end
+
+      # Splits jws into chunks and converts each string into numeric
+      def jws_to_qr_chunks(jws)
+        chunks = split_jws(jws.to_s).map { |c| convert_jws_to_numeric(c) }
+
+        # if 1 chunk, attach prefix shc:/
+        # if multiple chunks, attach prefix shc:/$orderNumber/$totalChunkCount
+        if chunks.length == 1
+          chunks[0] = "shc:/#{chunks[0]}"
+        else
+          chunks.map!.with_index(1) { |ch, i| "shc:/#{i}/#{chunks.length}/#{ch}" }
+        end
+        chunks
+      end
+
+      # Assemble jws from qr code chunks
+      def qr_chunks_to_jws(qr_chunks)
+        if qr_chunks.length == 1
+          # Strip off shc:/ and convert numeric jws
+          numeric_jws = qr_chunks[0].delete_prefix('shc:/')
+          convert_numeric_jws numeric_jws
+        else
+          ordered_qr_chunks = strip_prefix_and_sort qr_chunks
+          ordered_qr_chunks.map { |c| convert_numeric_jws(c) }.join
+        end
+      end
+
+      private
+
+      # Each character "c" of the jws is converted into a sequence of two digits by taking c.ord - 45
+      def convert_jws_to_numeric(jws)
+        jws.chars.map { |c| format('%02d', c.ord - 45) }.join
+      end
+
+      def convert_numeric_jws(numeric_jws)
+        result_jws = ''.dup
+        numeric_jws.chars.each_slice(2) do |a, b|
+          result_jws << ((a + b).to_i + 45).chr
+        end
+        result_jws
+      end
+
+      def strip_prefix_and_sort(qr_chunks)
+        # Multiple QR codes are prefixed with 'shc:/C/N' where C is the index and N is the total number of chunks
+        # Sorts chunks by C
+        sorted_chunks = qr_chunks.sort_by { |c| c[%r{/(.*?)/}, 1].to_i }
+        # Strip prefix
+        sorted_chunks.map { |c| c.sub(%r{shc:/(.*?)/(.*?)/}, '') }
+      end
+    end
+  end
+end

data/lib/smart_health_cards_test_kit/utils/encoding.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module SmartHealthCardsTestKit
+  module Utils
+    # Encoding utilities for producing JWS
+    #
+    # @see https://datatracker.ietf.org/doc/html/rfc7515#appendix-A.3.1
+    module Encoding
+      # Encodes the provided data using url safe base64 without padding
+      # @param data [String] the data to be encoded
+      # @return [String] the encoded data
+      def encode(data)
+        Base64.urlsafe_encode64(data, padding: false).gsub("\n", '')
+      end
+
+      # Decodes the provided data using url safe base 64
+      # @param data [String] the data to be decoded
+      # @return [String] the decoded data
+      def decode(data)
+        Base64.urlsafe_decode64(data)
+      end
+    end
+  end
+end

data/lib/smart_health_cards_test_kit/utils/jws.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+require_relative 'encoding'
+require_relative 'private_key'
+require_relative 'public_key'
+
+module SmartHealthCardsTestKit
+  module Utils
+    # Create JWS from a payload
+    class JWS
+      class << self
+        include Encoding
+
+        # Creates a JWS from a String representation, or returns the SmartHealthCardsTestKit::Utils::JWS object
+        # that was passed in
+        # @param jws [String, SmartHealthCardsTestKit::Utils::JWS] the JWS string, or a JWS object
+        # @param public_key [SmartHealthCardsTestKit::Utils::PublicKey] the public key associated with the JWS
+        # @param key [SmartHealthCardsTestKit::Utils::PrivateKey] the private key associated with the JWS
+        # @return [SmartHealthCardsTestKit::Utils::JWS] A new JWS object, or the JWS object that was passed in
+        def from_jws(jws, public_key: nil, key: nil)
+          return jws if jws.is_a?(SmartHealthCardsTestKit::Utils::JWS) && public_key.nil? && key.nil?
+
+          unless jws.is_a?(SmartHealthCardsTestKit::Utils::JWS) || jws.is_a?(String)
+            raise ArgumentError,
+                  'Expected either a SmartHealthCardsTestKit::Utils::JWS or String'
+          end
+
+          header, payload, signature = jws.to_s.split('.').map { |entry| decode(entry) }
+          header = JSON.parse(header)
+          JWS.new(header: header, payload: payload, signature: signature,
+                  public_key: public_key, key: key)
+        end
+      end
+
+      attr_reader :key, :public_key, :payload
+      attr_writer :signature
+      attr_accessor :header
+
+      # Create a new JWS
+
+      def initialize(header: nil, payload: nil, signature: nil, key: nil, public_key: nil)
+        # Not using accessors because they reset the signature which requires both a key and a payload
+        @header = header
+        @payload = payload
+        @signature = signature if signature
+        @key = key
+        @public_key = public_key || key&.public_key
+      end
+
+      # The kid value from the JWS header, used to identify the key to use to verify
+      # @return [String]
+      def kid
+        header['kid']
+      end
+
+      # Set the private key used for signing issued health cards
+      #
+      # @param key [SmartHealthCardsTestKit::Utils::PrivateKey, nil] the private key used for signing issued health cards
+      def key=(key)
+        PrivateKey.enforce_valid_key_type!(key, allow_nil: true)
+
+        @key = key
+
+        # If it's a new private key then the public key and signature should be updated
+        return if @key.nil?
+
+        reset_signature
+        self.public_key = @key.public_key
+      end
+
+      # Set the public key used for signing issued health cards
+      #
+      # @param public_key [SmartHealthCardsTestKit::Utils::PublicKey, nil] the private key used for signing issued health cards
+      def public_key=(public_key)
+        PublicKey.enforce_valid_key_type!(public_key, allow_nil: true)
+
+        @public_key = public_key
+      end
+
+      # Set the JWS payload. Setting a new payload will result in the a new signature
+      # @param new_payload [Object]
+      def payload=(new_payload)
+        @payload = new_payload
+        reset_signature
+      end
+
+      # The signature component of the card
+      #
+      # @return [String] the unencoded signature
+      def signature
+        return @signature if @signature
+
+        raise MissingPrivateKeyError unless key
+
+        @signature ||= key.sign(jws_signing_input)
+      end
+
+      # Export the card to a JWS String
+      # @return [String] the JWS
+      def to_s
+        [JSON.generate(header), payload, signature].map { |entry| JWS.encode(entry) }.join('.')
+      end
+
+      # # Verify the digital signature on the jws
+      # #
+      # # @return [Boolean]
+      def verify
+        raise MissingPublicKeyError unless public_key
+
+        public_key.verify(jws_signing_input, signature)
+      end
+
+      private
+
+      def jws_signing_input
+        "#{JWS.encode(@header.to_json)}.#{encoded_payload}"
+      end
+
+      def encoded_payload
+        JWS.encode(payload)
+      end
+
+      # Resets the signature
+      #
+      # This method is primarily used when an attribute that affects
+      # the signature is changed (e.g. the private key changes, the payload changes)
+      def reset_signature
+        @signature = nil
+        signature if key && payload
+      end
+    end
+  end
+end

data/lib/smart_health_cards_test_kit/utils/key.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+
+module SmartHealthCardsTestKit
+  module Utils
+    # Methods to generate signing keys and jwk
+    class Key
+      BASE = { kty: 'EC', crv: 'P-256' }.freeze
+      DIGEST = OpenSSL::Digest.new('SHA256')
+
+      # Checks if obj is the the correct key type or nil
+      # @param obj Object that should be of same type as caller or nil
+      # @param allow_nil Allow/Disallow key to be nil
+      def self.enforce_valid_key_type!(obj, allow_nil: false)
+        raise InvalidKeyError.new(self, obj) unless obj.is_a?(self) || (allow_nil && obj.nil?)
+      end
+
+      # Create a key from a JWK
+      #
+      # @param jwk_key [Hash] The JWK represented by a Hash
+      # @return [SmartHealthCardsTestKit::Utils::Key] The key represented by the JWK
+      def self.from_jwk(jwk_key)
+        jwk_key = jwk_key.transform_keys(&:to_sym)
+        curvename = 'prime256v1'
+        group = OpenSSL::PKey::EC::Group.new(curvename)
+        public_key_bn = ['04'].pack('H*') + Base64.urlsafe_decode64(jwk_key[:x]) + Base64.urlsafe_decode64(jwk_key[:y])
+        point = OpenSSL::PKey::EC::Point.new(group, OpenSSL::BN.new(public_key_bn, 2))
+
+        asn1 = OpenSSL::ASN1::Sequence([
+          OpenSSL::ASN1::Sequence([
+            OpenSSL::ASN1::ObjectId("id-ecPublicKey"),
+            OpenSSL::ASN1::ObjectId(curvename)
+          ]),
+          OpenSSL::ASN1::BitString(point.to_octet_string(:uncompressed))
+        ])
+
+        key = OpenSSL::PKey::EC.new(asn1.to_der)
+        key.private_key = OpenSSL::BN.new(Base64.urlsafe_decode64(jwk_key[:d]), 2) if jwk_key[:d]
+
+        key.private_key? ? SmartHealthCardsTestKit::Utils::PrivateKey.new(key) : SmartHealthCardsTestKit::Utils::PublicKey.new(key)
+      end
+
+      def initialize(ec_key)
+        @key = ec_key
+      end
+
+      def group
+        @key.group
+      end
+
+      def to_json(*_args)
+        to_jwk.to_json
+      end
+
+      def to_jwk
+        coordinates.merge(kid: kid, use: 'sig', alg: 'ES256')
+      end
+
+      def kid
+        Base64.urlsafe_encode64(DIGEST.digest(public_coordinates.to_json), padding: false)
+      end
+
+      def public_coordinates
+        coordinates.slice(:crv, :kty, :x, :y)
+      end
+
+      def coordinates
+        return @coordinates if @coordinates
+
+        key_binary = @key.public_key.to_bn.to_s(2)
+        coords = { x: key_binary[1, key_binary.length / 2],
+                  y: key_binary[key_binary.length / 2 + 1, key_binary.length] }
+        coords[:d] = @key.private_key.to_s(2) if @key.private_key?
+        @coordinates = coords.transform_values do |val|
+          Base64.urlsafe_encode64(val, padding: false)
+        end.merge(BASE)
+      end
+    end
+  end
+end

data/lib/smart_health_cards_test_kit/utils/key_set.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module SmartHealthCardsTestKit
+  module Utils
+    # A set of keys used for signing or verifying HealthCards
+    class KeySet
+      extend Forwardable
+
+      def_delegator :keys, :empty?
+
+      # Create a KeySet from a JWKS
+      #
+      # @param jwks [String] the JWKS as a string
+      # @return [SmartHealthCardsTestKit::Utils::KeySet]
+      def self.from_jwks(jwks)
+        jwks = JSON.parse(jwks)
+        keys = jwks['keys'].map { |jwk| SmartHealthCardsTestKit::Utils::Key.from_jwk(jwk) }
+        KeySet.new(keys)
+      end
+
+      # Create a new KeySet
+      #
+      # @param keys [SmartHealthCardsTestKit::Utils::Key, Array<SmartHealthCardsTestKit::Utils::Key>, nil] the initial keys
+      def initialize(keys = nil)
+        @key_map = {}
+        add_keys(keys) unless keys.nil?
+      end
+
+      # The contained keys
+      #
+      # @return [Array]
+      def keys
+        @key_map.values
+      end
+
+      # Returns the keys as a JWK
+      #
+      # @return JSON string in JWK format
+      def to_jwk
+        { keys: keys.map(&:to_jwk) }.to_json
+      end
+
+      # Retrieves a key from the keyset with a kid
+      # that matches the parameter
+      # @param kid [String] a Base64 encoded kid from a JWS or Key
+      # @return [Payload::Key] a key with a matching kid or nil if not found
+      def find_key(kid)
+        @key_map[kid]
+      end
+
+      # Add keys to KeySet
+      #
+      # Keys are added based on the key kid
+      #
+      # @param new_keys [SmartHealthCardsTestKit::Utils::Key, Array<SmartHealthCardsTestKit::Utils::Key>, SmartHealthCardsTestKit::Utils::KeySet] the initial keys
+      def add_keys(new_keys)
+        if new_keys.is_a? KeySet
+          add_keys(new_keys.keys)
+        else
+          [*new_keys].each { |new_key| @key_map[new_key.kid] = new_key }
+        end
+      end
+
+      # Remove keys from KeySet
+      #
+      # Keys are remove based on the key kid
+      #
+      # @param new_keys [SmartHealthCardsTestKit::Utils::Key, Array<SmartHealthCardsTestKit::Utils::Key>, SmartHealthCardsTestKit::Utils::KeySet] the initial keys
+      def remove_keys(removed_keys)
+        if removed_keys.is_a? KeySet
+          remove_keys(removed_keys.keys)
+        else
+          [*removed_keys].each { |removed_key| @key_map.delete(removed_key.kid) }
+        end
+      end
+
+      # Check if key is included in the KeySet
+      #
+      # @param key [SmartHealthCardsTestKit::Utils::Key]
+      # @return [Boolean]
+      def include?(key)
+        !@key_map[key.kid].nil?
+      end
+    end
+  end
+end

data/lib/smart_health_cards_test_kit/utils/private_key.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+require_relative 'key'
+
+module SmartHealthCardsTestKit
+  module Utils
+    # A key used for signing JWS
+    class PrivateKey < Key
+      def self.from_file(path)
+        pem = OpenSSL::PKey::EC.new(File.read(path))
+        PrivateKey.new(pem)
+      end
+
+      def self.load_from_or_create_from_file(path)
+        if File.exist?(path)
+          from_file(path)
+        else
+          generate_key(file_path: path)
+        end
+      end
+
+      def self.generate_key(file_path: nil)
+        key = OpenSSL::PKey::EC.generate('prime256v1')
+        File.write(file_path, key.to_pem) if file_path
+        PrivateKey.new(key)
+      end
+
+      def sign(payload)
+        asn1_to_raw(@key.sign(OpenSSL::Digest.new('SHA256'), payload), self)
+      end
+
+      def public_key
+        return @public_key if @public_key
+
+        pub = OpenSSL::PKey::EC.new('prime256v1')
+        pub.public_key = @key.public_key
+        @public_key = PublicKey.new(pub)
+      end
+
+      private
+
+      # Convert the ASN.1 Representation into the raw signature
+      #
+      # Adapted from ruby-jwt and json-jwt gems. More info here:
+      # https://github.com/nov/json-jwt/issues/21
+      # https://github.com/jwt/ruby-jwt/pull/87
+      # https://github.com/jwt/ruby-jwt/issues/84
+      def asn1_to_raw(signature, private_key)
+        byte_size = (private_key.group.degree + 7) / 8
+        OpenSSL::ASN1.decode(signature).value.map { |value| value.value.to_s(2).rjust(byte_size, "\x00") }.join
+      end
+    end
+  end
+end

data/lib/smart_health_cards_test_kit/utils/public_key.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SmartHealthCardsTestKit
+  module Utils
+    # A key used for verifying JWS
+    class PublicKey < Key
+      def self.from_json(json)
+        # TODO
+      end
+
+      def verify(payload, signature)
+        @key.verify(OpenSSL::Digest.new('SHA256'), raw_to_asn1(signature, self), payload)
+      end
+
+      private
+
+      # Convert the raw signature into the ASN.1 Representation
+      #
+      # Adapted from ruby-jwt and json-jwt gems. More info here:
+      # https://github.com/nov/json-jwt/issues/21
+      # https://github.com/jwt/ruby-jwt/pull/87
+      # https://github.com/jwt/ruby-jwt/issues/84
+      def raw_to_asn1(signature, key)
+        byte_size = (key.group.degree + 7) / 8
+        sig_bytes = signature[0..(byte_size - 1)]
+        sig_char = signature[byte_size..] || ''
+        OpenSSL::ASN1::Sequence.new([sig_bytes, sig_char].map do |int|
+          OpenSSL::ASN1::Integer.new(OpenSSL::BN.new(int, 2))
+        end).to_der
+      end
+    end
+  end
+end

data/lib/smart_health_cards_test_kit/utils/verification.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module SmartHealthCardsTestKit
+  module Utils
+    # Logic for verifying a Payload JWS
+    module Verification
+      # Verify Health Card with given KeySet
+      #
+      # @param verifiable [SmartHealthCardsTestKit::Utils::JWS, String] the health card to verify
+      # @param key_set [SmartHealthCardsTestKit::Utils::KeySet, nil] the KeySet from which keys should be taken or added
+      # @param resolve_keys [Boolean] if keys should be resolved
+      # @return [Boolean]
+      def verify_using_key_set(verifiable, key_set = nil, resolve_keys: true)
+        jws = JWS.from_jws(verifiable)
+        key_set ||= SmartHealthCardsTestKit::Utils::KeySet.new
+        key_set.add_keys(resolve_key(jws)) if resolve_keys && key_set.find_key(jws.kid).nil?
+
+        key = key_set.find_key(jws.kid)
+        unless key
+          raise MissingPublicKeyError,
+                'Verifier does not contain public key that is able to verify this signature'
+        end
+
+        jws.public_key = key
+        jws.verify
+      end
+
+      # Resolve a key
+      # @param jws [SmartHealthCardsTestKit::Utils::JWS, String] The JWS for which to resolve keys
+      # @return [SmartHealthCardsTestKit::Utils::KeySet]
+      def resolve_key(jws)
+        jwks_uri = URI("#{HealthCard.new(jws.to_s).issuer}/.well-known/jwks.json")
+        res = Net::HTTP.get(jwks_uri)
+        SmartHealthCardsTestKit::Utils::KeySet.from_jwks(res)
+      # Handle response if key is malformed or unreachable
+      rescue StandardError => e
+        raise ArgumentError, "Unable resolve a valid key from uri #{jwks_uri}: #{e.message}"
+      end
+    end
+  end
+end