aspera-cli 4.21.2 → 4.23.0

data/lib/aspera/transfer/spec_doc.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'aspera/agent/base'
+
+module Aspera
+  module Transfer
+    # translate transfer specification to ascp parameter list
+    class SpecDoc
+      class << self
+        # first letter of agent name symbol
+        def agent_to_short(agent_sym)
+          agent_sym.to_sym.eql?(:direct) ? :a : agent_sym.to_s[0].to_sym
+        end
+
+        # @columns formatter [Cli::Formatter] formatter to use, methods: special_format, check_row
+        # @columns &block modify parameter info if needed
+        # @return a table suitable to display in manual
+        def man_table(formatter, cli: true)
+          col_local = agent_to_short(:direct)
+          Spec::SCHEMA['properties'].filter_map do |name, properties|
+            # manual table
+            columns = {
+              name:        name,
+              type:        properties['type'],
+              description: []
+            }
+            # replace "back solidus" HTML entity with its text value and split lines
+            columns[:description].concat(properties['description'].gsub('&bsol;', '\\').split("\n")) if properties.key?('description')
+            columns[:description].unshift("DEPRECATED: #{properties['x-deprecation']}") if properties.key?('x-deprecation')
+            # add flags for supported agents in doc
+            AGENT_LIST.each do |agent_info|
+              columns[agent_info.last] = Cli::Formatter.tick(properties['x-agents'].nil? || properties['x-agents'].include?(agent_info.first.to_s))
+            end
+            columns[col_local] = Cli::Formatter.tick(true) if properties['x-cli-option']
+            # only keep lines that are usable in supported agents
+            next false if AGENT_LIST.map(&:last).inject(true){ |memory, agent_short_sym| memory && columns[agent_short_sym].empty?}
+            columns[:description].push("Allowed values: #{properties['enum'].join(', ')}") if properties.key?('enum')
+            cli_option =
+              if properties['x-cli-switch']
+                properties['x-cli-option']
+              elsif properties['x-cli-special']
+                formatter.special_format('special')
+              elsif properties['x-cli-option']
+                arg_type = properties.key?('enum') ? '{enum}' : "{#{[properties['type']].flatten.join('|')}}"
+                conversion_tag = properties.key?('x-cli-convert') ? '(conversion)' : ''
+                sep = properties['x-cli-option'].start_with?('--') ? '=' : ' '
+                "#{properties['x-cli-option']}#{sep}#{conversion_tag}#{arg_type}"
+              end
+            cli_option = 'env:' + properties['x-cli-envvar'] if properties.key?('x-cli-envvar')
+            columns[:description].push("(#{cli_option})") if cli && !cli_option.to_s.empty?
+            formatter.check_row(columns)
+          end.sort_by{ |i| i[:name]}
+        end
+      end
+      # Agents shown in manual for parameters (sub list)
+      AGENT_LIST = Agent::Base.agent_list.map do |agent_sym|
+        [agent_sym, agent_sym.to_s.capitalize, agent_to_short(agent_sym)]
+      end.sort_by(&:last).freeze
+      TABLE_COLUMNS = (%i[name type] + AGENT_LIST.map(&:last) + %i[description]).freeze
+    end
+  end
+end

data/lib/aspera/transfer/sync.rb

@@ -5,6 +5,7 @@
 require 'aspera/command_line_builder'
 require 'aspera/ascp/installation'
 require 'aspera/agent/direct'
+require 'aspera/transfer/convert'
 require 'aspera/log'
 require 'aspera/assert'
 require 'json'
@@ -16,62 +17,18 @@ module Aspera
   module Transfer
     # builds command line arg for async and execute it
     module Sync
-      # sync direction, default is push
+      # sync direction
       DIRECTIONS = %i[push pull bidi].freeze
+      # default direction for sync
+      DEFAULT_DIRECTION = :push
       # JSON for async instance command line options
-      CMDLINE_PARAMS_INSTANCE =
-        {
-          'alt_logdir'          => { cli: { type: :opt_with_arg}, accepted_types: :string},
-          'watchd'              => { cli: { type: :opt_with_arg}, accepted_types: :string},
-          'apply_local_docroot' => { cli: { type: :opt_without_arg}},
-          'quiet'               => { cli: { type: :opt_without_arg}},
-          'ws_connect'          => { cli: { type: :opt_without_arg}}
-        }.freeze
-
-      # map sync session parameters to transfer spec: sync -> ts, true if same
-      CMDLINE_PARAMS_SESSION =
-        {
-          'name'                       => { cli: { type: :opt_with_arg}, accepted_types: :string},
-          'local_dir'                  => { cli: { type: :opt_with_arg}, accepted_types: :string},
-          'remote_dir'                 => { cli: { type: :opt_with_arg}, accepted_types: :string},
-          'local_db_dir'               => { cli: { type: :opt_with_arg}, accepted_types: :string},
-          'remote_db_dir'              => { cli: { type: :opt_with_arg}, accepted_types: :string},
-          'host'                       => { cli: { type: :opt_with_arg}, accepted_types: :string, ts: :remote_host},
-          'user'                       => { cli: { type: :opt_with_arg}, accepted_types: :string, ts: :remote_user},
-          'private_key_paths'          => { cli: { type: :opt_with_arg, switch: '--private-key-path'}, accepted_types: :array},
-          'direction'                  => { cli: { type: :opt_with_arg}, accepted_types: :string},
-          'checksum'                   => { cli: { type: :opt_with_arg}, accepted_types: :string},
-          'tags'                       => { cli: { type: :opt_with_arg, switch: '--tags64', convert: 'Aspera::Transfer::Parameters.convert_json64'},
-                                            accepted_types: :hash, ts: true},
-          'tcp_port'                   => { cli: { type: :opt_with_arg}, accepted_types: :int, ts: :ssh_port},
-          'rate_policy'                => { cli: { type: :opt_with_arg}, accepted_types: :string},
-          'target_rate'                => { cli: { type: :opt_with_arg}, accepted_types: :string},
-          'cooloff'                    => { cli: { type: :opt_with_arg}, accepted_types: :int},
-          'pending_max'                => { cli: { type: :opt_with_arg}, accepted_types: :int},
-          'scan_intensity'             => { cli: { type: :opt_with_arg}, accepted_types: :string},
-          'cipher'                     => { cli: { type: :opt_with_arg, convert: 'Aspera::Transfer::Parameters.convert_remove_hyphen'},
-                                            accepted_types: :string, ts: true},
-          'transfer_threads'           => { cli: { type: :opt_with_arg}, accepted_types: :int},
-          'preserve_time'              => { cli: { type: :opt_without_arg}, ts: :preserve_times},
-          'preserve_access_time'       => { cli: { type: :opt_without_arg}, ts: nil},
-          'preserve_modification_time' => { cli: { type: :opt_without_arg}, ts: nil},
-          'preserve_uid'               => { cli: { type: :opt_without_arg}, ts: :preserve_file_owner_uid},
-          'preserve_gid'               => { cli: { type: :opt_without_arg}, ts: :preserve_file_owner_gid},
-          'create_dir'                 => { cli: { type: :opt_without_arg}, ts: true},
-          'reset'                      => { cli: { type: :opt_without_arg}},
-          # NOTE: only one env var, but multiple sessions... could be a problem
-          'remote_password'            => { cli: { type: :envvar, variable: 'ASPERA_SCP_PASS'}, ts: true},
-          'cookie'                     => { cli: { type: :envvar, variable: 'ASPERA_SCP_COOKIE'}, ts: true},
-          'token'                      => { cli: { type: :envvar, variable: 'ASPERA_SCP_TOKEN'}, ts: true},
-          'license'                    => { cli: { type: :envvar, variable: 'ASPERA_SCP_LICENSE'}}
-        }.freeze
-
-      CommandLineBuilder.normalize_description(CMDLINE_PARAMS_INSTANCE)
-      CommandLineBuilder.normalize_description(CMDLINE_PARAMS_SESSION)
+      INSTANCE_SCHEMA = CommandLineBuilder.read_schema(__FILE__, 'instance')
+      SESSION_SCHEMA = CommandLineBuilder.read_schema(__FILE__, 'session')
 
       CMDLINE_PARAMS_KEYS = %w[instance sessions].freeze
 
       # Translation of transfer spec parameters to async v2 API (asyncs)
+      # TODO: complete this list with all transfer spec parameters or include in async json schema with x- parameters
       TSPEC_TO_ASYNC_CONF = {
         'remote_host'     => 'remote.host',
         'remote_user'     => 'remote.user',
@@ -86,10 +43,10 @@ module Aspera
 
       ASYNC_ADMIN_EXECUTABLE = 'asyncadmin'
 
-      private_constant :CMDLINE_PARAMS_INSTANCE, :CMDLINE_PARAMS_SESSION, :CMDLINE_PARAMS_KEYS, :TSPEC_TO_ASYNC_CONF, :ASYNC_ADMIN_EXECUTABLE
+      private_constant :INSTANCE_SCHEMA, :SESSION_SCHEMA, :CMDLINE_PARAMS_KEYS, :TSPEC_TO_ASYNC_CONF, :ASYNC_ADMIN_EXECUTABLE
 
       class << self
-        # Set remote_dir in sync parameters based on transfer spec
+        # Set `remote_dir` in sync parameters based on transfer spec
         # @param params [Hash] sync parameters, old or new format
         # @param remote_dir_key [String] key to update in above hash
         # @param transfer_spec [Hash] transfer spec
@@ -100,7 +57,8 @@ module Aspera
           elsif transfer_spec['cookie']&.start_with?('aspera.shares2')
             # TODO : something more generic, independent of Shares
             # in Shares, the actual folder on remote end is not always the same as the name of the share
-            actual_remote = transfer_spec['paths']&.first&.[]('source')
+            remote_key = transfer_spec['direction'].eql?('send') ? 'destination' : 'source'
+            actual_remote = transfer_spec['paths']&.first&.[](remote_key)
             sync_params[remote_dir_key] = actual_remote if actual_remote
           end
           nil
@@ -132,14 +90,19 @@ module Aspera
           return certificates_to_use
         end
 
+        # Get symbol of sync direction, defaulting to :push
+        # @param params [Hash] sync parameters, old or new format
+        # @return [Symbol] direction symbol, one of :push, :pull, :bidi
+        def direction_sym(params)
+          (params['direction'] || DEFAULT_DIRECTION).to_sym
+        end
+
         # @param sync_params [Hash] sync parameters, old or new format
-        # @param block [nil, Proc] block to generate transfer spec, takes: direction (one of DIRECTIONS), local_dir, remote_dir
-        def start(
-          sync_params,
-          &block
-        )
+        # @param &block [nil, Proc] block to generate transfer spec, takes: direction (one of DIRECTIONS), local_dir, remote_dir
+        def start(sync_params)
           Log.log.debug{Log.dump(:sync_params_initial, sync_params)}
           Aspera.assert_type(sync_params, Hash)
+          Aspera.assert(%w[local sessions].any?{ |k| sync_params.key?(k)}){'At least one of `local` or `sessions` must be present in async parameters'}
           env_args = {
             args: [],
             env:  {}
@@ -151,8 +114,8 @@ module Aspera
             Aspera.assert_type(remote, Hash){'remote'}
             Aspera.assert_type(remote['path'], String){'remote path'}
             # get transfer spec if possible, and feed back to new structure
-            if block
-              transfer_spec = yield((sync_params['direction'] || 'push').to_sym, sync_params['local']['path'], remote['path'])
+            if block_given?
+              transfer_spec = yield(direction_sym(sync_params), sync_params['local']['path'], remote['path'])
               # translate transfer spec to async parameters
               TSPEC_TO_ASYNC_CONF.each do |ts_param, sy_path|
                 next unless transfer_spec.key?(ts_param)
@@ -172,24 +135,25 @@ module Aspera
             end
             # '--exclusive-mgmt-port=12345', '--arg-err-path=-',
             env_args[:args] = ["--conf64=#{Base64.strict_encode64(JSON.generate(sync_params))}"]
-            Log.log.debug{Log.dump(:sync_params_enriched, sync_params)}
+            Log.log.debug{Log.dump(:sync_conf, sync_params)}
             agent = Agent::Direct.new
             agent.start_and_monitor_process(session: {}, name: :async, **env_args)
-          elsif sync_params.key?('sessions')
+          else
+            # key 'sessions' is present
             # ascli JSON format (cmdline)
             raise StandardError, "Only 'sessions', and optionally 'instance' keys are allowed" unless
               sync_params.keys.push('instance').uniq.sort.eql?(CMDLINE_PARAMS_KEYS)
             Aspera.assert_type(sync_params['sessions'], Array)
             Aspera.assert_type(sync_params['sessions'].first, Hash)
-            if block
+            if block_given?
               sync_params['sessions'].each do |session|
                 Aspera.assert_type(session['local_dir'], String){'local_dir'}
                 Aspera.assert_type(session['remote_dir'], String){'remote_dir'}
-                transfer_spec = yield((session['direction'] || 'push').to_sym, session['local_dir'], session['remote_dir'])
-                CMDLINE_PARAMS_SESSION.each do |async_param, behavior|
-                  if behavior.key?(:ts)
-                    tspec_param = behavior[:ts].is_a?(TrueClass) ? async_param : behavior[:ts].to_s
-                    session[async_param] ||= transfer_spec[tspec_param] if transfer_spec.key?(tspec_param)
+                transfer_spec = yield(direction_sym(session), session['local_dir'], session['remote_dir'])
+                SESSION_SCHEMA['properties'].each do |name, properties|
+                  if properties.key?('x-tspec')
+                    tspec_param = properties['x-tspec'].is_a?(TrueClass) ? name : properties['x-tspec'].to_s
+                    session[name] ||= transfer_spec[tspec_param] if transfer_spec.key?(tspec_param)
                   end
                 end
                 session['private_key_paths'] = Ascp::Installation.instance.aspera_token_ssh_key_paths(:rsa) if transfer_spec.key?('token')
@@ -198,21 +162,18 @@ module Aspera
             end
             if sync_params.key?('instance')
               Aspera.assert_type(sync_params['instance'], Hash)
-              instance_builder = CommandLineBuilder.new(sync_params['instance'], CMDLINE_PARAMS_INSTANCE)
+              instance_builder = CommandLineBuilder.new(sync_params['instance'], INSTANCE_SCHEMA, Convert)
               instance_builder.process_params
               instance_builder.add_env_args(env_args)
             end
-
             sync_params['sessions'].each do |session_params|
               Aspera.assert_type(session_params, Hash)
-              Aspera.assert(session_params.key?('name')){'session must contain at least name'}
-              session_builder = CommandLineBuilder.new(session_params, CMDLINE_PARAMS_SESSION)
+              Aspera.assert(session_params.key?('name')){'session must contain at least: name'}
+              session_builder = CommandLineBuilder.new(session_params, SESSION_SCHEMA, Convert)
               session_builder.process_params
               session_builder.add_env_args(env_args)
             end
             Environment.secure_execute(exec: Ascp::Installation.instance.path(:async), **env_args)
-          else
-            raise 'At least one of `local` or `sessions` must be present in async parameters'
           end
           return nil
         end
@@ -248,8 +209,8 @@ module Aspera
               raise 'Missing either local_db_dir or local.path'
             end
           elsif sync_params.key?('sessions')
-            session = session_name.nil? ? sync_params['sessions'].first : sync_params['sessions'].find{|s|s['name'].eql?(session_name)}
-            raise "Session #{session_name} not found in #{sync_params['sessions'].map{|s|s['name']}.join(',')}" if session.nil?
+            session = session_name.nil? ? sync_params['sessions'].first : sync_params['sessions'].find{ |s| s['name'].eql?(session_name)}
+            raise "Session #{session_name} not found in #{sync_params['sessions'].map{ |s| s['name']}.join(',')}" if session.nil?
             raise 'Missing session name' if session['name'].nil?
             arguments.push("--name=#{session['name']}")
             if session.key?('local_db_dir')

data/lib/aspera/transfer/sync_instance.schema.yaml

@@ -0,0 +1,20 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://github.com/IBM/aspera-cli/tree/main/lib/aspera/transfer/sync_instance.schema.yaml
+$comment: >-
+  `x-` fields documented in command_line_builder.rb
+  This spec is specific to ascli.
+  The native async conf format is now preferred.
+title: SyncInstanceSpec
+description: Global parameters for async.
+type: object
+properties:
+  alt_logdir:
+    type: string
+  watchd:
+    type: string
+  apply_local_docroot:
+    x-cli-switch: true
+  quiet:
+    x-cli-switch: true
+  ws_connect:
+    x-cli-switch: true

data/lib/aspera/transfer/sync_session.schema.yaml

@@ -0,0 +1,86 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://github.com/IBM/aspera-cli/tree/main/lib/aspera/transfer/sync_instance.schema.yaml
+$comment: >-
+  `x-` fields documented in command_line_builder.rb
+  This spec is specific to ascli.
+  The native async conf format is now preferred.
+title: SyncSessionSpec
+description: Sync session parameters for async.
+type: object
+properties:
+  name:
+    type: string
+  local_dir:
+    type: string
+  remote_dir:
+    type: string
+  local_db_dir:
+    type: string
+  remote_db_dir:
+    type: string
+  host:
+    type: string
+    x-tspec: remote_host
+  user:
+    type: string
+    x-tspec: remote_user
+  private_key_paths:
+    type: array
+    x-cli-option: "--private-key-path"
+  direction:
+    type: string
+  checksum:
+    type: string
+  tags:
+    type: object
+    x-cli-option: "--tags64"
+    x-cli-convert: json64
+    x-tspec: true
+  tcp_port:
+    type: integer
+    x-tspec: ssh_port
+  rate_policy:
+    type: string
+  target_rate:
+    type: string
+  cooloff:
+    type: integer
+  pending_max:
+    type: integer
+  scan_intensity:
+    type: string
+  cipher:
+    type: string
+    x-cli-convert: remove_hyphen
+    x-tspec: true
+  transfer_threads:
+    type: integer
+  preserve_time:
+    x-cli-switch: true
+    x-tspec: preserve_times
+  preserve_access_time:
+    x-cli-switch: true
+  preserve_modification_time:
+    x-cli-switch: true
+  preserve_uid:
+    x-cli-switch: true
+    x-tspec: preserve_file_owner_uid
+  preserve_gid:
+    x-cli-switch: true
+    x-tspec: preserve_file_owner_gid
+  create_dir:
+    x-cli-switch: true
+    x-tspec: true
+  reset:
+    x-cli-switch: true
+  remote_password:
+    x-cli-envvar: ASPERA_SCP_PASS
+    x-tspec: true
+  cookie:
+    x-cli-envvar: ASPERA_SCP_COOKIE
+    x-tspec: true
+  token:
+    x-cli-envvar: ASPERA_SCP_TOKEN
+    x-tspec: true
+  license:
+    x-cli-envvar: ASPERA_SCP_LICENSE

data/lib/aspera/transfer/uri.rb

@@ -4,7 +4,7 @@
 
 require 'aspera/log'
 require 'aspera/rest'
-require 'aspera/command_line_builder'
+require 'aspera/transfer/convert'
 
 module Aspera
   module Transfer
@@ -24,7 +24,7 @@ module Aspera
         result_ts['ssh_port'] = @fasp_uri.port
         result_ts['paths'] = [{'source' => URI.decode_www_form_component(@fasp_uri.path)}]
         # faspex 4 does not encode trailing base64 padding, fix that to be able to decode properly
-        fixed_query = @fasp_uri.query.gsub(/(=+)$/){|trail_equals|'%3D' * trail_equals.length}
+        fixed_query = @fasp_uri.query.gsub(/(=+)$/){ |trail_equals| '%3D' * trail_equals.length}
 
         Rest.query_to_h(fixed_query).each do |name, value|
           case name
@@ -39,10 +39,10 @@ module Aspera
           when 'bwcap'       then result_ts['target_rate_cap_kbps'] = value.to_i
           when 'enc'         then result_ts['cipher'] = value.gsub(/^aes/, 'aes-').gsub(/cfb$/, '-cfb').gsub(/gcm$/, '-gcm').gsub('--', '-')
           when 'tags64'      then result_ts['tags'] = JSON.parse(Base64.strict_decode64(value))
-          when 'createpath'  then result_ts['create_dir'] = CommandLineBuilder.yes_to_true(value)
-          when 'fallback'    then result_ts['http_fallback'] = CommandLineBuilder.yes_to_true(value)
-          when 'lockpolicy'  then result_ts['lock_rate_policy'] = CommandLineBuilder.yes_to_true(value)
-          when 'lockminrate' then result_ts['lock_min_rate'] = CommandLineBuilder.yes_to_true(value)
+          when 'createpath'  then result_ts['create_dir'] = Convert.yes_to_true(value)
+          when 'fallback'    then result_ts['http_fallback'] = Convert.yes_to_true(value)
+          when 'lockpolicy'  then result_ts['lock_rate_policy'] = Convert.yes_to_true(value)
+          when 'lockminrate' then result_ts['lock_min_rate'] = Convert.yes_to_true(value)
           when 'auth'        then Log.log.debug{"ignoring #{name}=#{value}"} # Not used (yes/no)
           when 'v'           then Log.log.debug{"ignoring #{name}=#{value}"} # rubocop:disable Lint/DuplicateBranch -- Not used (shall be 2)
           when 'protect'     then Log.log.debug{"ignoring #{name}=#{value}"} # rubocop:disable Lint/DuplicateBranch -- TODO: what is this ?

data/lib/aspera/uri_reader.rb

@@ -22,7 +22,7 @@ module Aspera
           raise 'URL shall have a path, check syntax' if local_file_path.nil?
           local_file_path = File.expand_path(local_file_path.gsub(%r{^/}, '')) if %r{^/(~|.|..)/}.match?(local_file_path)
           return File.read(local_file_path)
-        else Aspera.error_unexpected_value(uri.scheme) {"scheme for [#{uri_to_read}]"}
+        else Aspera.error_unexpected_value(uri.scheme){"scheme for [#{uri_to_read}]"}
         end
       end
 

data/lib/aspera/web_auth.rb

@@ -182,7 +182,7 @@ module Aspera
       # last argument (self) is provided to constructor of servlet
       mount(@expected_path, WebAuthServlet, self)
       # server runs in thread
-      Thread.new { start }
+      Thread.new{start}
     end
 
     # Called by web server thread on received request

data/lib/aspera/web_server_simple.rb

@@ -10,19 +10,23 @@ require 'openssl'
 module Aspera
   # Simple WEBrick server with HTTPS support
   class WebServerSimple < WEBrick::HTTPServer
-    CERT_PARAMETERS = %i[key cert chain pkcs12].freeze
+    PARAMS = %i[cert key chain].freeze
+    DEFAULT_URL = 'http://localhost:8080'
     GENERIC_ISSUER = '/C=FR/O=Test/OU=Test/CN=Test'
     ONE_YEAR_SECONDS = 365 * 24 * 60 * 60
+    PKCS12_EXT = %w[p12 pfx].map{ |i| ".#{i}"}.freeze
+    CLOCK_SKEW_OFFSET_SEC = 5
 
-    private_constant :CERT_PARAMETERS, :GENERIC_ISSUER, :ONE_YEAR_SECONDS
+    private_constant :GENERIC_ISSUER, :ONE_YEAR_SECONDS, :PKCS12_EXT, :CLOCK_SKEW_OFFSET_SEC
 
     class << self
-      # Fill and self sign provided certificate
-      def fill_self_signed_cert(cert, key, digest = 'SHA256')
+      # Generate or fill and self sign certificate
+      def self_signed_cert(private_key, digest: 'SHA256')
+        cert = OpenSSL::X509::Certificate.new
         cert.subject = cert.issuer = OpenSSL::X509::Name.parse(GENERIC_ISSUER)
-        cert.not_before = cert.not_after = Time.now
-        cert.not_after += ONE_YEAR_SECONDS
-        cert.public_key = key.public_key
+        cert.not_before = Time.now - CLOCK_SKEW_OFFSET_SEC
+        cert.not_after  = cert.not_before + ONE_YEAR_SECONDS
+        cert.public_key = private_key.public_key
         cert.serial = 0x0
         cert.version = 2
         ef = OpenSSL::X509::ExtensionFactory.new
@@ -34,68 +38,73 @@ module Aspera
           # ef.create_extension('keyUsage', 'cRLSign,keyCertSign', true),
         ]
         cert.add_extension(ef.create_extension('authorityKeyIdentifier', 'keyid:always,issuer:always'))
-        cert.sign(key, OpenSSL::Digest.new(digest))
+        cert.sign(private_key, OpenSSL::Digest.new(digest))
+        cert
+      end
+
+      # @return a list of Certificates from chain file
+      def read_chain_file(chain)
+        File.read(chain).scan(/-----BEGIN CERTIFICATE-----.*?-----END CERTIFICATE-----/m).map{ |i| OpenSSL::X509::Certificate.new(i)}
       end
     end
 
-    # @param uri [URI]
-    def initialize(uri, certificate: nil)
-      @url = uri
+    # @param url   [URI]    Local address where server will listen (use scheme, host and port only)
+    # @param cert  [String] Path to certificate file, either with extension .p12 or .pfx, else assumed PEM
+    # @param key   [String] Path to key file (PEM) or passphrase (pkcs12)
+    # @param chain [String] Path to certificate chain file (PEM only)
+    def initialize(uri, cert: nil, key: nil, chain: nil)
+      Aspera.assert_type(uri, URI)
+      @uri = uri
       # see https://www.rubydoc.info/stdlib/webrick/WEBrick/Config
       webrick_options = {
-        BindAddress: uri.host,
-        Port:        uri.port,
+        BindAddress: @uri.host,
+        Port:        @uri.port,
         Logger:      Log.log,
         AccessLog:   [[self, WEBrick::AccessLog::COMMON_LOG_FORMAT]] # replace default access log to call local method "<<" below
       }
-      case uri.scheme
+      case @uri.scheme
       when 'http'
         Log.log.debug('HTTP mode')
       when 'https'
         webrick_options[:SSLEnable] = true
-        if certificate.nil?
+        if cert.nil? && key.nil?
           webrick_options[:SSLCertName] = [['CN', WEBrick::Utils.getservername]]
+        elsif cert && PKCS12_EXT.include?(File.extname(cert).downcase)
+          # PKCS12
+          Log.log.debug('Using PKCS12 certificate')
+          raise 'PKCS12 requires a key (password)' if key.nil?
+          pkcs12 = OpenSSL::PKCS12.new(File.read(cert), key)
+          webrick_options[:SSLCertificate] = pkcs12.certificate
+          webrick_options[:SSLPrivateKey] = pkcs12.key
+          webrick_options[:SSLExtraChainCert] = pkcs12.ca_certs
         else
-          Aspera.assert_type(certificate, Hash)
-          certificate = certificate.symbolize_keys
-          raise "unexpected key in certificate config: only: #{CERT_PARAMETERS.join(', ')}" if certificate.keys.any?{|key|!CERT_PARAMETERS.include?(key)}
-          if certificate.key?(:pkcs12)
-            Log.log.debug('Using PKCS12 certificate')
-            raise 'pkcs12 requires a key (password)' unless certificate.key?(:key)
-            pkcs12 = OpenSSL::PKCS12.new(File.read(certificate[:pkcs12]), certificate[:key])
-            webrick_options[:SSLCertificate] = pkcs12.certificate
-            webrick_options[:SSLPrivateKey] = pkcs12.key
-            webrick_options[:SSLExtraChainCert] = pkcs12.ca_certs
+          Log.log.debug('Using PEM certificate')
+          webrick_options[:SSLPrivateKey] = if key.nil?
+            OpenSSL::PKey::RSA.new(4096)
+          else
+            OpenSSL::PKey::RSA.new(File.read(key))
+          end
+          webrick_options[:SSLCertificate] = if cert.nil?
+            self.class.self_signed_cert(webrick_options[:SSLPrivateKey])
           else
-            Log.log.debug('Using PEM certificate')
-            webrick_options[:SSLPrivateKey] = if certificate.key?(:key)
-              OpenSSL::PKey::RSA.new(File.read(certificate[:key]))
-            else
-              OpenSSL::PKey::RSA.new(4096)
-            end
-            if certificate.key?(:cert)
-              webrick_options[:SSLCertificate] = OpenSSL::X509::Certificate.new(File.read(certificate[:cert]))
-            else
-              webrick_options[:SSLCertificate] = OpenSSL::X509::Certificate.new
-              self.class.fill_self_signed_cert(webrick_options[:SSLCertificate], webrick_options[:SSLPrivateKey])
-            end
-            if certificate.key?(:chain)
-              webrick_options[:SSLExtraChainCert] = [OpenSSL::X509::Certificate.new(File.read(certificate[:chain]))]
-            end
+            OpenSSL::X509::Certificate.new(File.read(cert))
           end
+          webrick_options[:SSLExtraChainCert] = read_chain_file(chain) unless chain.nil?
+          raise 'key and cert do not match' unless webrick_options[:SSLCertificate].public_key.to_der == webrick_options[:SSLPrivateKey].public_key.to_der
         end
       end
       # call constructor of parent class, but capture STDERR
       # self signed certificate generates characters on STDERR
       # see create_self_signed_cert in webrick/ssl.rb
-      Log.capture_stderr { super(webrick_options) }
+      Log.capture_stderr{super(webrick_options)}
     end
 
     # blocking
     def start
-      Log.log.info{"Listening on #{@url}"}
-      # kill -HUP for graceful shutdown
-      Kernel.trap('HUP') { shutdown }
+      Log.log.info{"Listening on #{@uri}"}
+      # kill (-TERM) for graceful shutdown
+      handler = proc{shutdown}
+      %i{INT TERM}.each{ |sig| trap(sig, &handler)}
       super
     end