generate-http-message-signature

#!/usr/bin/env ruby
#
# OVERVIEW
# --------
#
#   Generate signature metadata, signature base, and a signature
#   that comply with RFC 9421 HTTP Message Signatures.
#
# USAGE
# -----
#
#   generate-http-message-signature
#       --key FILE              # Private key in the JWK format.
#       [--alg ALG]             # Algorithm (RFC 9421 Section 3.3)
#       [--baseline BASELINE]   # signature-base-line (RFC 9421 Section 2.5)
#       [--created TIME]        # TIME is seconds since epoch, or 'now'.
#       [--expires TIME]        # TIME is seconds since epoch, or '+{seconds}'
#       [--keyid KEYID]         # Key ID
#       [--nonce NONCE]         # Nonce
#       [--tag TAG]             # Tag
#       [--print-all]
#       [--[no-]print-signature]
#       [--[no-]print-signature-base]
#       [--[no-]print-signature-metadata]
#
# EXAMPLE
# -------
#
#   TARGET_URI=https://trial.authlete.net/api/userinfo
#   KEYID=ScIdKFzAj93vywpwjrfi3wrj5oHmHbHfmPT5IPTLmVc
#   CREATED=$((`date +%s` - 10))
#
#   (1) signature
#
#     generate-http-message-signature \
#         --key request-signing.jwk \
#         --baseline "\"@method\": GET" \
#         --baseline "\"@target-uri\": ${TARGET_URI}" \
#         --baseline "\"authorization\": Bearer ${ACCESS_TOKEN}" \
#         --created ${CREATED} \
#         --keyid ${KEYID} \
#         --tag fapi-2-request \
#         --print-signature
#
#     output:
#       cviJgxadN66Ycd+O/TYp9eTu1FGWIFkw8ti3LjAGsFmbwp5E5yTGiILUPNegcKPFNUgwKkUtVJorFUfavcfg5g==
#
#   (2) signature base
#
#     generate-http-message-signature \
#         --key request-signing.jwk \
#         --baseline "\"@method\": GET" \
#         --baseline "\"@target-uri\": ${TARGET_URI}" \
#         --baseline "\"authorization\": Bearer ${ACCESS_TOKEN}" \
#         --created ${CREATED} \
#         --keyid ${KEYID} \
#         --tag fapi-2-request \
#         --print-signature-base
#
#     output:
#       "@method": GET
#       "@target-uri": https://trial.authlete.net/api/userinfo
#       "authorization": Bearer 4rSgHO6sdlBL4z_1l4bAmED2CG40zblXlc3YDqrqdu8
#       "@signature-params": ("@method" "@target-uri" "authorization");created=1728051074;keyid="ScIdKFzAj93vywpwjrfi3wrj5oHmHbHfmPT5IPTLmVc";tag="fapi-2-request"
#
#   (3) signature metadata
#
#     generate-http-message-signature \
#         --key request-signing.jwk \
#         --baseline "\"@method\": GET" \
#         --baseline "\"@target-uri\": ${TARGET_URI}" \
#         --baseline "\"authorization\": Bearer ${ACCESS_TOKEN}" \
#         --created ${CREATED} \
#         --keyid ${KEYID} \
#         --tag fapi-2-request \
#         --print-signature-metadata
#
#     output:
#       ("@method" "@target-uri" "authorization");created=1728051074;keyid="ScIdKFzAj93vywpwjrfi3wrj5oHmHbHfmPT5IPTLmVc";tag="fapi-2-request"
#


require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'json-jwt'
  gem 'optparse'
end

require 'base64'
require 'time'


#------------------------------------------------------------
# main
#------------------------------------------------------------
def main(args)
  # Process the command line options.
  options = Options.process(args)

  # Build signature metadata.
  signature_metadata = build_signature_metadata(options)

  # Build a signature-params-line.
  signature_params_line = build_signature_params_line(options, signature_metadata)

  # Build a signature base.
  signature_base = build_signature_base(options, signature_params_line)

  # Build a signature.
  signature = build_signature(options, signature_base)

  # Signature
  if options.print_signature
    puts signature
  end

  # Signature Base
  if options.print_signature_base
    puts signature_base
  end

  # Signature Metadata
  if options.print_signature_metadata
    puts signature_metadata
  end
end


#------------------------------------------------------------
# Command line options
#------------------------------------------------------------
class Options < OptionParser
  DESC_ALG      = "specifies the 'alg' parameter."
  DESC_BASELINE = "specifies a signature-base-line (RFC 9421 Section 2.5)"
  DESC_CREATED  = "specifies the 'created' parameter. TIME is seconds since epoch, or 'now'."
  DESC_EXPIRES  = "specifies the 'expires' parameter. TIME is seconds since epoch, or '+{seconds}'."
  DESC_KEY      = "specifies a file containing a private key in the JWK format."
  DESC_KEYID    = "specifies the 'keyid' parameter."
  DESC_NONCE    = "specifies the 'nonce' parameter."
  DESC_TAG      = "specifies the 'tag' parameter."

  attr_reader :alg, :baselines, :created, :expires, :key, :keyid, :nonce, :tag
  attr_reader :print_signature_base, :print_signature_metadata
  attr_accessor :print_signature

  def initialize
    super

    @alg       = nil
    @baselines = []
    @created   = nil
    @expires   = nil
    @key       = nil
    @keyid     = nil
    @nonce     = nil
    @tag       = nil

    @print_signature          = false
    @print_signature_base     = false
    @print_signature_metadata = false

    # For the 'tag' parameter.
    self.on('--alg ALG', DESC_ALG) do |alg|
      @alg = alg
    end

    # For signature-base-line's.
    self.on('--baseline BASELINE', DESC_BASELINE) do |baseline|
      @baselines << baseline
    end

    # For the 'created' parameter.
    self.on('--created TIME', DESC_CREATED) do |time|
      # If the specified value is 'now' (string)
      if time == 'now'
        # The current time is used as the creation time.
        @created = Time.now.to_i
      else
        # The value is interpreted as seconds since the Unix epoch.
        @created = time.to_i
      end
    end

    # For the 'expires' parameter.
    self.on('--expires TIME', DESC_EXPIRES) do |time|
      if time.start_with?('+')
        # Convert the substring after '+' to an integer.
        seconds = time[1 .. -1].to_i

        # If the --created option has already been used.
        if @created.nil?
          # The specified value is interpreted as a difference from the current time.
          @expires = Time.now.to_i + seconds
        else
          # The specified value is interpreted as a difference from the creation time.
          @expires = @created + seconds
        end
      else
        # The value is interpreted as seconds since the Unix epoch.
        @expires = time.to_i
      end
    end

    # Private key for signing.
    self.on('--key FILE', DESC_KEY) do |file|
      @key = read_jwk(file)
    end

    # For the 'keyid' parameter.
    self.on('--keyid KEYID', DESC_KEYID) do |id|
      @keyid = id
    end

    # For the 'nonce' parameter.
    self.on('--nonce NONCE', DESC_NONCE) do |nonce|
      @nonce = nonce
    end

    # For the 'tag' parameter.
    self.on('--tag TAG', DESC_TAG) do |tag|
      @tag = tag
    end

    # Print the signature, signature base, and signature metadata.
    self.on('--print-all') do
      @print_signature          = true
      @print_signature_base     = true
      @print_signature_metadata = true
    end

    # Whether to print the signature.
    self.on('--[no-]print-signature') do |bool|
      @print_signature = bool
    end

    # Whether to print the signature base.
    self.on('--[no-]print-signature-base') do |bool|
      @print_signature_base = bool
    end

    # Whether to print the signature metadata.
    self.on('--[no-]print-signature-metadata') do |bool|
      @print_signature_metadata = bool
    end
  end

  private

  def read_jwk(file)
    json = File.read(file)
    hash = JSON.parse(json, {symbolize_names: true})
    JSON::JWK.new(hash)
  end

  def error_if_missing(value, option)
    if value.nil?
      raise OptionParser::ParseError.new "'#{option}' is missing."
    end
  end

  public

  def verify
    error_if_missing(@key, '--key FILE')
  end

  def self.process(args)
    options = Options.new
    options.parse(args)
    options.verify()

    # If none of the '--print-*' options has been given.
    if !options.print_signature &&
       !options.print_signature_base &&
       !options.print_signature_metadata
      # Turn on '--print-signature'.
      options.print_signature = true
    end

    return options
  end
end


#------------------------------------------------------------
# signature metadata
#------------------------------------------------------------
def build_signature_metadata(options)
  metadata = '('

  # Extract component identifiers from the baselines.
  component_identifiers = options.baselines.map { |s| s.split(':')[0] }
  metadata << component_identifiers.join(' ')

  metadata << ')'

  # alg
  if !options.alg.nil?
    metadata << ";alg=\"#{options.alg}\""
  end

  # created
  if !options.created.nil?
    metadata << ";created=#{options.created}"
  end

  # expires
  if !options.expires.nil?
    metadata << ";expires=#{options.expires}"
  end

  # keyid
  if !options.keyid.nil?
    metadata << ";keyid=\"#{options.keyid}\""
  end

  # nonce
  if !options.nonce.nil?
    metadata << ";nonce=\"#{options.nonce}\""
  end

  # tag
  if !options.tag.nil?
    metadata << ";tag=\"#{options.tag}\""
  end

  return metadata
end


#------------------------------------------------------------
# signature-params-line
#------------------------------------------------------------
def build_signature_params_line(options, signature_metadata)
  # RFC 9421 HTTP Message Signatures
  # 2.5. Creating the Signature Base
  #
  #   signature-params-line = DQUOTE "@signature-params" DQUOTE
  #        ":" SP inner-list
  #
  "\"@signature-params\": #{signature_metadata}"
end


#------------------------------------------------------------
# signature-base
#------------------------------------------------------------
def build_signature_base(options, signature_params_line)
  # RFC 9421 HTTP Message Signatures
  # 2.5. Creating the Signature Base
  #
  #   signature-base = *( signature-base-line LF ) signature-params-line
  #

  base = ''

  options.baselines.each do |baseline|
    base << baseline
    base << "\n"
  end

  base << signature_params_line

  return base
end


#------------------------------------------------------------
# signature
#------------------------------------------------------------
def build_signature(options, signature_base)
  # Sign the signature base with the private key.
  signature = HttpSigner.new(options.key).http_sign(signature_base)

  # Base64
  Base64.strict_encode64(signature)
end


#------------------------------------------------------------
# HTTP Signer
#------------------------------------------------------------
class HttpSigner < JSON::JWS
  def initialize(private_key)
    self.alg     = autodetected_algorithm_from(private_key)
    @private_key = private_key
  end

  def http_sign(signature_base)
    # RFC 9421 HTTP Message Signatures
    # 3.3.7. JSON Web Signature (JWS) Algorithms
    #
    #   For both signing and verification, the HTTP message's
    #   signature base (Section 2.5) is used as the entire
    #   "JWS Signing Input". The JOSE Header [JWS] [RFC7517]
    #   is not used, and the signature base is not first
    #   encoded in Base64 before applying the algorithm.
    #   The output of the JWS Signature is taken as a byte
    #   array prior to the Base64url encoding used in JOSE.
    #

    # Call the private 'sign' method.
    sign signature_base, @private_key
  end
end


#------------------------------------------------------------
# Entry Point
#------------------------------------------------------------
main(ARGV)