http_message_signatures 0.1.0

data/README.md

@@ -0,0 +1,288 @@
+# HTTP Message Signatures
+
+Sign and verify HTTP messages for the Fediverse.
+
+Supports [draft-cavage-http-signatures](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures)
+(the legacy standard used by Mastodon, Pleroma, PeerTube, etc.)
+and [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421.html)
+(the final HTTP Message Signatures standard).
+
+## Features
+
+- Framework agnostic — Works with any Ruby framework or plain scripts
+- Draft-Cavage       — Sign and verify using the legacy Fediverse standard
+- RFC 9421           — Sign and verify using the final standard
+- Key helpers        — Generate and parse RSA and Ed25519 keys
+- Rack middleware    — Automatic signature verification for incoming requests
+- HTTP.rb client     — Automatic signature signing for outgoing requests
+- Algorithms         — RSA-PSS-SHA512, RSA-V1.5-SHA256, HMAC-SHA256, ECDSA-P256, ECDSA-P384, Ed25519
+- Interop            — Workarounds for Pleroma, PeerTube, etc based on Mastodon's prior art
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'http_message_signatures'
+```
+
+And then execute:
+
+```sh
+bundle install
+```
+
+Or install it yourself as:
+
+```ruby
+gem install http_message_signatures
+```
+
+## Usage
+
+### Key Management
+
+Generate keys:
+
+```ruby
+# Generate an RSA key pair (default 2048-bit)
+rsa_key = HTTPMessageSignatures::Keys.generate_rsa
+
+# Generate an Ed25519 key pair
+ed_key = HTTPMessageSignatures::Keys.generate_ed25519
+```
+
+Parse PEM keys:
+
+```ruby
+private_key = HTTPMessageSignatures::Keys.parse_private_key File.read('private.pem')
+public_key  = HTTPMessageSignatures::Keys.parse_public_key  File.read('public.pem')
+```
+
+Export to PEM:
+
+```ruby
+HTTPMessageSignatures::Keys.to_pem key                    # => public PEM
+HTTPMessageSignatures::Keys.to_pem key, private_key: true # => private PEM
+```
+
+### Draft-Cavage (Legacy Fediverse)
+
+This is what Mastodon, Pleroma, PeerTube, and most Fediverse software uses today.
+
+#### Signing a request
+
+```ruby
+signer = HTTPMessageSignatures::Cavage::Signer.new(
+  key_id:      'https://example.com/users/alice#main-key',
+  private_key: private_key
+)
+
+headers = signer.sign(
+  method:  'POST',
+  path:    '/inbox',
+  headers: {
+    'Host'         => 'remote.example',
+    'Content-Type' => 'application/activity+json'
+  },
+  body:    '{"type":"Follow"}'
+)
+# Returns a new hash with Signature, Date, and Digest headers added
+```
+
+#### Verifying a request
+
+```ruby
+verifier = HTTPMessageSignatures::Cavage::Verifier.new
+
+result = verifier.verify(
+  method:  'POST',
+  path:    '/inbox',
+  headers: request_headers,
+  body:    request_body
+) { |key_id| fetch_public_key(key_id) }
+# => true or false
+```
+
+The verifier handles interop quirks:
+- Mastodon's query-string-stripping from (`request-target`)
+- Configurable clock skew (default 12 hours, `clock_skew: nil` to disable)
+- Multiple digest format parsing
+
+### RFC 9421 (Final Standard)
+
+The modern standard with broader algorithm support,
+multiple signatures, and explicit component coverage.
+
+#### Signing a request
+
+```ruby
+signer = HTTPMessageSignatures::RFC9421::Signer.new(
+  key:                private_key,
+  key_id:             'my-key-id',
+  algorithm:          'ed25519',
+  covered_components: %w[@method @authority @path content-type]
+)
+
+headers = signer.sign(
+  method:  'POST',
+  url:     'https://remote.example/inbox',
+  headers: { 'Content-Type' => 'application/activity+json' }
+)
+# Returns a new hash with Signature-Input and Signature headers added
+```
+
+Optional parameters:
+
+```ruby
+signer = HTTPMessageSignatures::RFC9421::Signer.new(
+  key:                private_key,
+  key_id:             'my-key-id',
+  algorithm:          'rsa-pss-sha512',
+  covered_components: %w[@method @authority @path],
+  label:              'my-sig',     # default: 'sig1'
+  tag:                'my-app',     # application-specific tag
+  expires_in:         300,          # seconds until expiration
+  nonce:              SecureRandom.hex(16)
+)
+```
+
+#### Signing a response
+
+```ruby
+headers = signer.sign_response(
+  status:  200,
+  headers: { 'Content-Type' => 'application/json' }
+)
+```
+
+#### Verifying a request
+
+```ruby
+verifier = HTTPMessageSignatures::RFC9421::Verifier.new
+
+result = verifier.verify(
+  method:  'POST',
+  url:     'https://example.com/inbox',
+  headers: request_headers
+) { |key_id, algorithm| fetch_public_key key_id }
+
+result.verified   # => true or false
+result.key_id     # => 'my-key-id'
+result.algorithm  # => 'ed25519'
+result.label      # => 'sig1'
+result.components # => ['@method', '@authority', ...]
+```
+
+#### Multiple signatures
+
+A message can carry multiple independent signatures:
+
+```ruby
+# Sign with two different keys
+headers = signer_one.sign method: 'POST', url: url, headers: headers
+headers = signer_two.sign method: 'POST', url: url, headers: headers
+
+# Verify all signatures at once
+results = verifier.verify_all(
+  method:  'POST',
+  url:     url,
+  headers: headers
+) { |key_id, algorithm| fetch_key key_id }
+
+results.each { puts "#{it.label}: #{it.verified}" }
+
+# Or list available labels
+verifier.labels headers # => ['sig1', 'sig2']
+```
+
+### Rack Middleware
+
+Automatically verify signatures on incoming requests:
+
+```ruby
+# config.ru
+use HTTPMessageSignatures::RackMiddleware do |key_id|
+  fetch_public_key key_id
+end
+```
+
+With options:
+
+```ruby
+use HTTPMessageSignatures::RackMiddleware,
+    paths:      ['/inbox'],
+    clock_skew: 300,
+    on_failure: ->(_env, _error) { [403, {}, ['Forbidden']] } do |key_id|
+  fetch_public_key key_id
+end
+```
+
+The middleware auto-detects the signature format (draft-cavage or RFC 9421)
+and sets `env['http_signature.verified']` on success. Unsigned requests pass
+through. Returns 401 by default on verification failure.
+
+### HTTP.rb Signing Client
+
+Automatically sign outgoing requests using the `http` gem:
+
+```ruby
+client = HTTPMessageSignatures::HTTPSigner.new(
+  key_id:      'https://example.com/users/alice#main-key',
+  private_key: private_key
+)
+
+response = client.post 'https://remote.example/inbox',
+                       headers: { 'Content-Type' => 'application/activity+json' },
+                       body:    '{"type":"Follow"}'
+```
+
+RFC 9421 mode:
+
+```ruby
+client = HTTPMessageSignatures::HTTPSigner.new(
+  key_id:      'my-key-id',
+  private_key: private_key,
+  mode:        :rfc9421,
+  algorithm:   'ed25519'
+)
+```
+
+Supports `get`, `post`, `put`, `patch`, `delete`, and `head`.
+
+### Supported Algorithms
+
+| Algorithm            | Name                | Key Type      |
+|----------------------|---------------------|---------------|
+| RSA-PSS-SHA512       | `rsa-pss-sha512`    | RSA           |
+| RSASSA-PKCS1-v1_5    | `rsa-v1_5-sha256`   | RSA           |
+| HMAC-SHA256          | `hmac-sha256`       | Shared secret |
+| ECDSA P-256          | `ecdsa-p256-sha256` | EC P-256      |
+| ECDSA P-384          | `ecdsa-p384-sha384` | EC P-384      |
+| Ed25519              | `ed25519`           | Ed25519       |
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+bundle exec rubocop
+bundle exec rake
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/xoengineering/http_message_signatures.
+
+## License
+
+The gem is available as open source under the terms of the
+[GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl-3.0.html).
+
+## References
+
+- [HTTP Signatures (draft-cavage)](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures)
+- [RFC 9421 — HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html)
+- [RFC 8941 — Structured Field Values for HTTP](https://www.rfc-editor.org/rfc/rfc8941.html)
+- [ActivityPub](https://www.w3.org/TR/activitypub)

data/lib/http_message_signatures/cavage/signature_header.rb

@@ -0,0 +1,112 @@
+module HTTPMessageSignatures
+  module Cavage
+    # Parses and serializes draft-cavage Signature headers.
+    #
+    # The Signature header format is:
+    #   keyId="...",algorithm="...",headers="...",signature="..."
+    #
+    # @example Parsing
+    #   sig = SignatureHeader.parse(request.headers['Signature'])
+    #   sig.key_id    # => "https://example.com/users/alice#main-key"
+    #   sig.algorithm # => "rsa-sha256"
+    #   sig.headers   # => ["(request-target)", "host", "date"]
+    #   sig.signature # => "base64..."
+    #
+    # @example Building
+    #   sig = SignatureHeader.new(key_id: "...", algorithm: "rsa-sha256", headers: [...], signature: "...")
+    #   sig.to_s # => 'keyId="...",algorithm="...",headers="...",signature="..."'
+    class SignatureHeader
+      attr_reader :algorithm, :headers, :key_id, :signature
+
+      def initialize algorithm:, headers:, key_id:, signature:
+        @algorithm = algorithm
+        @headers   = headers
+        @key_id    = key_id
+        @signature = signature
+      end
+
+      # Parse a Signature header string into a SignatureHeader object.
+      #
+      # @param header [String] the raw Signature header value
+      # @return [SignatureHeader]
+      # @raise [ParseError] if the header is missing required fields
+      def self.parse header
+        raise ParseError, 'Signature header is empty' if header.nil? || header.strip.empty?
+
+        params = parse_params header.delete_prefix('Signature ')
+
+        raise ParseError, 'Missing required field: keyId' unless params.key? 'keyId'
+        raise ParseError, 'Missing required field: signature' unless params.key? 'signature'
+
+        new(
+          key_id:    params['keyId'],
+          algorithm: params.fetch('algorithm', 'hs2019'),
+          headers:   params.key?('headers') ? params['headers'].split : ['date'],
+          signature: params['signature']
+        )
+      end
+
+      # Serialize to a Signature header string.
+      #
+      # @return [String]
+      def to_s
+        format(
+          'keyId="%<key_id>s",algorithm="%<algorithm>s",headers="%<headers>s",signature="%<signature>s"',
+          key_id:    @key_id,
+          algorithm: @algorithm,
+          headers:   @headers.join(' '),
+          signature: @signature
+        )
+      end
+
+      class << self
+        private
+
+        # Parse key="value" pairs, handling commas inside quoted values.
+        def parse_params header
+          params = {}
+          scanner = StringScanner.new header.strip
+
+          until scanner.eos?
+            scanner.skip(/\s*,?\s*/)
+            break if scanner.eos?
+
+            key = scan_key scanner
+            scanner.skip(/\s*=\s*/)
+            value = scan_quoted_value scanner, key
+
+            params[key] = value
+          end
+
+          params
+        end
+
+        def scan_key scanner
+          key = scanner.scan(/[a-zA-Z]+/)
+          raise ParseError, "Expected parameter name at position #{scanner.pos}" unless key
+
+          key
+        end
+
+        def scan_quoted_value scanner, key
+          raise ParseError, "Expected quoted value for #{key} at position #{scanner.pos}" unless scanner.skip(/"/)
+
+          value = +''
+          until scanner.eos?
+            chunk = scanner.scan(/[^"\\]+/)
+            value << chunk if chunk
+
+            if scanner.peek(1) == '\\'
+              scanner.getch
+              value << scanner.getch
+            elsif scanner.peek(1) == '"'
+              scanner.getch
+              break
+            end
+          end
+          value
+        end
+      end
+    end
+  end
+end

data/lib/http_message_signatures/cavage/signer.rb

@@ -0,0 +1,77 @@
+require 'openssl'
+require 'base64'
+require 'time'
+
+module HTTPMessageSignatures
+  module Cavage
+    # Signs outgoing HTTP requests using draft-cavage HTTP signatures.
+    #
+    # @example
+    #   key = OpenSSL::PKey::RSA.generate(2048)
+    #   signer = Signer.new(key_id: "https://example.com/users/alice#main-key", private_key: key)
+    #   signed_headers = signer.sign(method: "POST", path: "/inbox", headers: headers, body: body)
+    class Signer
+      DEFAULT_POST_HEADERS = %w[(request-target) host date digest content-type].freeze
+      DEFAULT_GET_HEADERS  = %w[(request-target) host date].freeze
+
+      attr_reader :key_id, :private_key
+
+      def initialize key_id:, private_key:
+        @key_id      = key_id
+        @private_key = private_key
+      end
+
+      # Sign a request and return the headers with Signature added.
+      #
+      # @param headers [Hash] request headers
+      # @param method [String] HTTP method
+      # @param path [String] request path
+      # @param body [String, nil] request body
+      # @param signed_headers [Array<String>, nil] headers to sign (defaults based on method)
+      # @return [Hash] headers with Signature (and possibly Digest, Date) added
+      def sign headers:, method:, path:, body: nil, signed_headers: nil
+        result = headers.dup
+        result['Date'] ||= Time.now.httpdate
+
+        add_digest result, body
+
+        signed_headers ||= default_signed_headers method, body
+        signing_string = SigningString.build(method: method, path: path, signed_headers: signed_headers, headers: result)
+        signature = compute_signature signing_string
+
+        sig_header = SignatureHeader.new(
+          key_id:    @key_id,
+          algorithm: 'rsa-sha256',
+          headers:   signed_headers,
+          signature: signature
+        )
+
+        result['Signature'] = sig_header.to_s
+        result
+      end
+
+      private
+
+      def add_digest headers, body
+        return if body.nil? || body.empty?
+        return if headers.key? 'Digest'
+
+        digest = OpenSSL::Digest::SHA256.digest body
+        headers['Digest'] = "SHA-256=#{Base64.strict_encode64(digest)}"
+      end
+
+      def compute_signature signing_string
+        raw = @private_key.sign 'SHA256', signing_string
+        Base64.strict_encode64 raw
+      end
+
+      def default_signed_headers method, body
+        if body && !body.empty? && method.upcase == 'POST'
+          DEFAULT_POST_HEADERS
+        else
+          DEFAULT_GET_HEADERS
+        end
+      end
+    end
+  end
+end

data/lib/http_message_signatures/cavage/signing_string.rb

@@ -0,0 +1,56 @@
+module HTTPMessageSignatures
+  module Cavage
+    # Builds the signing string for draft-cavage HTTP signatures.
+    #
+    # The signing string is a newline-separated list of "header: value" lines,
+    # where the special pseudo-header `(request-target)` is the lowercase method
+    # followed by a space and the request path.
+    #
+    # @example
+    #   SigningString.build(
+    #     method: "post",
+    #     path: "/inbox",
+    #     signed_headers: ["(request-target)", "host", "date"],
+    #     headers: { "Host" => "example.com", "Date" => "Sun, 09 Feb 2025 07:30:00 GMT" }
+    #   )
+    #   # => "(request-target): post /inbox\nhost: example.com\ndate: Sun, 09 Feb 2025 07:30:00 GMT"
+    module SigningString
+      class << self
+        # Build the signing string from the given request components.
+        #
+        # @param headers [Hash] the request headers
+        # @param method [String] HTTP method
+        # @param path [String] request path (e.g. "/inbox")
+        # @param signed_headers [Array<String>] list of headers to include
+        # @return [String] the signing string
+        # @raise [SigningError] if a required header is missing
+        def build headers:, method:, path:, signed_headers:
+          normalized = normalize_headers headers
+
+          signed_headers.map do |name|
+            resolve_header name, method, path, normalized
+          end.join("\n")
+        end
+
+        private
+
+        def normalize_headers headers
+          headers.transform_keys(&:downcase)
+        end
+
+        def resolve_header name, method, path, normalized_headers
+          lowered = name.downcase
+
+          if lowered == '(request-target)'
+            "(request-target): #{method.downcase} #{path}"
+          else
+            value = normalized_headers[lowered]
+            raise SigningError, "Missing required header: #{name}" unless value
+
+            "#{lowered}: #{value}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/http_message_signatures/cavage/verifier.rb

@@ -0,0 +1,127 @@
+require 'openssl'
+require 'base64'
+require 'time'
+
+module HTTPMessageSignatures
+  module Cavage
+    # Verifies incoming HTTP request signatures using draft-cavage.
+    #
+    # @example Basic usage
+    #   verifier = Verifier.new
+    #   verifier.verify(method: "POST", path: "/inbox", headers: headers, body: body) do |key_id|
+    #     fetch_public_key(key_id) # return an OpenSSL::PKey
+    #   end
+    #   # => true or false
+    #
+    # @example Custom clock skew window (5 minutes)
+    #   verifier = Verifier.new(clock_skew: 300)
+    #
+    # @example Disable Date freshness check
+    #   verifier = Verifier.new(clock_skew: nil)
+    class Verifier
+      DEFAULT_CLOCK_SKEW = 43_200 # 12 hours in seconds
+
+      # @param clock_skew [Integer, nil] max allowed age of Date header in seconds (default 12h, nil to disable)
+      def initialize clock_skew: DEFAULT_CLOCK_SKEW
+        @clock_skew = clock_skew
+      end
+
+      # Verify a request signature. Returns true/false.
+      #
+      # @param headers [Hash] request headers (must include Signature)
+      # @param method [String] HTTP method
+      # @param path [String] request path
+      # @param body [String, nil] request body
+      # @yield [key_id] block that resolves a key_id to an OpenSSL public key
+      # @return [Boolean]
+      # @raise [VerificationError] if the Signature header is missing
+      # @raise [KeyError] if the key resolver returns nil
+      def verify headers:, method:, path:, body: nil
+        sig = parse_signature headers
+        return false unless digest_valid? headers, body
+        return false unless date_fresh? headers
+
+        public_key = resolve_key(sig.key_id) { yield sig.key_id }
+        raw_signature = Base64.strict_decode64 sig.signature
+        algorithm = algorithm_for sig.algorithm
+
+        # Try verification with the full path first, then fall back to path
+        # without query string. Mastodon and some other implementations omit
+        # the query string from (request-target) when signing.
+        paths_to_try(path).any? do |candidate_path|
+          signing_string = SigningString.build(
+            method:         method,
+            path:           candidate_path,
+            signed_headers: sig.headers,
+            headers:        headers
+          )
+          public_key.verify algorithm, raw_signature, signing_string
+        end
+      end
+
+      # Verify a request signature. Raises on failure.
+      #
+      # @raise [VerificationError] if the signature is invalid
+      def verify!(**, &)
+        return true if verify(**, &)
+
+        raise VerificationError, 'Invalid signature: verification failed'
+      end
+
+      private
+
+      def parse_signature headers
+        raw = headers['Signature'] || headers['signature']
+        raise VerificationError, 'Missing Signature header' unless raw
+
+        SignatureHeader.parse raw
+      end
+
+      def resolve_key key_id
+        public_key = yield key_id
+        raise KeyError, "Could not resolve public key for key_id: #{key_id}" unless public_key
+
+        public_key
+      end
+
+      def digest_valid? headers, body
+        digest_header = headers['Digest'] || headers['digest']
+        return true unless digest_header
+        return true if body.nil?
+
+        expected = Base64.strict_encode64(OpenSSL::Digest::SHA256.digest(body))
+        extract_sha256(digest_header) == expected
+      end
+
+      def extract_sha256 digest_header
+        digest_header.split(',').each do |part|
+          algorithm, value = part.strip.split('=', 2)
+          return value if algorithm.casecmp('SHA-256').zero?
+        end
+        nil
+      end
+
+      def date_fresh? headers
+        return true if @clock_skew.nil?
+
+        date_value = headers['Date'] || headers['date']
+        return true unless date_value
+
+        request_time = Time.httpdate date_value
+        (Time.now - request_time).abs <= @clock_skew
+      end
+
+      def paths_to_try path
+        base = path.split('?', 2).first
+        base == path ? [path] : [path, base]
+      end
+
+      def algorithm_for algorithm
+        case algorithm
+        when 'rsa-sha256', 'hs2019' then 'SHA256'
+        when 'rsa-sha512' then 'SHA512'
+        end
+      end
+    end
+  end
+end

data/lib/http_message_signatures/errors.rb

@@ -0,0 +1,16 @@
+module HTTPMessageSignatures
+  # Base error class for all HTTP Message Signatures errors
+  class Error < StandardError; end
+
+  # Raised when signing a request fails
+  class SigningError < Error; end
+
+  # Raised when verification of a signature fails
+  class VerificationError < Error; end
+
+  # Raised when parsing a Signature header fails
+  class ParseError < Error; end
+
+  # Raised when a required key is missing or invalid
+  class KeyError < Error; end
+end