epics 2.11.0 → 3.0.0.rc1

data/lib/epics/client.rb

@@ -1,80 +1,251 @@
 class Epics::Client
   extend Forwardable
 
-  attr_accessor :passphrase, :url, :host_id, :user_id, :partner_id, :keys, :keys_content, :locale, :product_name,
-                :x_509_certificates_content, :debug_mode
-
+  attr_accessor :passphrase, :url, :host_id, :user_id, :partner_id, :keys_content, :locale, :product_name,
+                :debug_mode
+  attr_reader :current_order_id
+  attr_reader :keyring
   attr_writer :iban, :bic, :name
-  
+
   def_delegators :connection, :post
-  
+
+  USER_AGENT = "EPICS v#{Epics::VERSION}"
+
+  # EBICS 3.0 requires at least 2048 bits.
+  DEFAULT_KEY_SIZE = 4096
+
+  # OrderIDType is `[A-Z][A-Z0-9]{3}`, i.e. base 36 from A000 to ZZZZ. Only EBICS 2.4
+  # sends an OrderID; 2.5 and 3.0 leave numbering to the bank.
+  MIN_ORDER_ID = 466_560
+  MAX_ORDER_ID = 1_679_615
+  ORDER_ID_FORMAT = /\A[A-Z][A-Z0-9]{3}\z/
+
+  # Constructor option carrying certificate content, per signature type.
+  CERTIFICATE_OPTIONS = {
+    Epics::Signature::TYPE_A => :x_509_certificate_a_content,
+    Epics::Signature::TYPE_X => :x_509_certificate_x_content,
+    Epics::Signature::TYPE_E => :x_509_certificate_e_content
+  }.freeze
+
   def initialize(keys_content, passphrase, url, host_id, user_id, partner_id, options = {})
-    self.keys_content = keys_content.respond_to?(:read) ? keys_content.read : keys_content if keys_content
-    self.passphrase = passphrase
-    self.keys = extract_keys if keys_content
-    self.url  = url
+    self.url = url
     self.host_id    = host_id
     self.user_id    = user_id
     self.partner_id = partner_id
     self.locale = options[:locale] || Epics::DEFAULT_LOCALE
     self.product_name = options[:product_name] || Epics::DEFAULT_PRODUCT_NAME
+    self.current_order_id = options[:order_id] || MIN_ORDER_ID
+    @keyring = Epics::Keyring.new(options[:version] || Epics::Keyring::VERSION_25)
+    self.keys_content = keys_content.respond_to?(:read) ? keys_content.read : keys_content if keys_content
+    self.passphrase = passphrase
     self.debug_mode = !!options[:debug_mode]
-    self.x_509_certificates_content = {
-      a: options[:x_509_certificate_a_content],
-      x: options[:x_509_certificate_x_content],
-      e: options[:x_509_certificate_e_content]
-    }
+    @certificate_contents = CERTIFICATE_OPTIONS.transform_values { |option| options[option] }
+    @certificate_subject = options[:certificate_subject]
+    @certificate_not_after = options[:certificate_not_after]
+    @generate_certificates = options.fetch(:generate_certificates, keyring.version == Epics::Keyring::VERSION_30)
+    extract_keys if keys_content
+    apply_certificates
+
+    yield self if block_given?
+  end
+
+  # Attaches the certificates passed to the constructor. `.setup` calls this again
+  # because it builds the signatures after `#initialize` has run. Only assigns where
+  # content was given, so a certificate loaded from a key file survives.
+  def apply_certificates
+    user_signatures.each do |type, signature|
+      certificate = parse_certificate(@certificate_contents[type], CERTIFICATE_OPTIONS[type])
+      signature.certificate = certificate if certificate
+    end
+
+    self
+  end
+
+  # H005 cannot be initialised without certificates, so `.setup` mints them by default.
+  def generate_certificates?
+    @generate_certificates
+  end
+
+  # Self-signed certificate for each user key that lacks one. Permitted for INI/HIA by
+  # the Swiss market practice guidelines §6.1; banks requiring CA-issued certificates
+  # should be given `x_509_certificate_*_content`, which takes precedence.
+  #
+  # Called only by `.setup`: regenerating on every `.new` would hand the bank a
+  # different fingerprint than the one on the initialisation letter.
+  def generate_certificates
+    user_signatures.each_value do |signature|
+      next if signature.certificate
+
+      signature.certificate = Epics::Crypt::X509.generate(
+        signature.key,
+        subject: certificate_subject,
+        not_after: @certificate_not_after || Epics::Crypt::X509::UNLIMITED
+      )
+    end
+
+    self
+  end
+
+  # Built as an OpenSSL::X509::Name so IDs containing `/` or `=` need no escaping.
+  def certificate_subject
+    @certificate_subject ||= OpenSSL::X509::Name.new([
+                                                       ['CN', user_id],
+                                                       ['OU', partner_id],
+                                                       ['O', host_id]
+                                                     ])
+  end
+
+  def version
+    keyring.version
+  end
+
+  def urn_schema
+    case version
+    when Epics::Keyring::VERSION_24
+      "http://www.ebics.org/#{version}"
+    when Epics::Keyring::VERSION_25, Epics::Keyring::VERSION_30
+      "urn:org:ebics:#{version}"
+    end
   end
 
   def inspect
-    "#<#{self.class}:#{self.object_id}
-     @keys=#{self.keys.keys},
-     @user_id=\"#{self.user_id}\",
-     @partner_id=\"#{self.partner_id}\""
+    "#<#{self.class}:#{object_id}
+     @version=#{keyring.version},
+     @keys=#{keys.keys},
+     @user_id=\"#{user_id}\",
+     @partner_id=\"#{partner_id}\""
+  end
+
+  # Accepts either the protocol form ('A000') or the integer it encodes, so a caller
+  # can persist whichever it has and hand it back.
+  def current_order_id=(value)
+    # String#to_i(36) is lenient, so the format is checked before converting.
+    id = value.is_a?(String) && value.match?(ORDER_ID_FORMAT) ? value.to_i(36) : value
+
+    unless id.is_a?(Integer) && id.between?(MIN_ORDER_ID, MAX_ORDER_ID)
+      raise ArgumentError,
+            "order_id must be between #{MIN_ORDER_ID.to_s(36).upcase} and " \
+            "#{MAX_ORDER_ID.to_s(36).upcase}, got #{value.inspect}"
+    end
+
+    @current_order_id = id
+  end
+
+  # Not persisted with the keys: read it after use and pass it back as `order_id:` on
+  # the next client, or EBICS 2.4 uploads replay IDs the bank has already seen.
+  def next_order_id
+    raise 'Order ID overflow' if current_order_id >= MAX_ORDER_ID
+
+    self.current_order_id += 1
+  end
+
+  def encryption_version
+    keyring.user_encryption&.version
+  end
+
+  def encryption_key
+    keyring.user_encryption&.key
+  end
+
+  def signature_version
+    keyring.user_signature&.version
+  end
+
+  def signature_key
+    keyring.user_signature&.key
+  end
+
+  def authentication_version
+    keyring.user_authentication&.version
+  end
+
+  def authentication_key
+    keyring.user_authentication&.key
   end
 
-  def e
-    keys["E002"]
+  def bank_encryption_key
+    keyring.bank_encryption&.key
   end
 
-  def a
-    keys["A006"]
+  def bank_encryption_version
+    keyring.bank_encryption&.version
   end
 
-  def x
-    keys["X002"]
+  def bank_authentication_key
+    keyring.bank_authentication&.key
   end
 
-  def bank_e
-    keys["#{host_id.upcase}.E002"]
+  def bank_authentication_version
+    keyring.bank_authentication&.version
   end
 
-  def bank_x
-    keys["#{host_id.upcase}.X002"]
+  def keys
+    user_signature = [keyring.user_signature, keyring.user_authentication,
+                      keyring.user_encryption].each_with_object({}) do |signature, keys|
+      keys[signature.version] = signature.key if signature
+    end
+    bank_signature = [keyring.bank_authentication, keyring.bank_encryption].each_with_object({}) do |signature, keys|
+      keys["#{host_id.upcase}.#{signature.version}"] = signature.key if signature
+    end
+
+    user_signature.merge(bank_signature)
   end
 
   def name
-    @name ||= (self.HTD; @name)
+    @name ||= begin
+      self.HTD
+      @name
+    end
   end
 
   def iban
-    @iban ||= (self.HTD; @iban)
+    @iban ||= begin
+      self.HTD
+      @iban
+    end
   end
 
   def bic
-    @bic ||= (self.HTD; @bic)
+    @bic ||= begin
+      self.HTD
+      @bic
+    end
   end
 
   def order_types
-    @order_types ||= (self.HTD; @order_types)
+    @order_types ||= begin
+      self.HTD
+      @order_types
+    end
   end
 
-  def self.setup(passphrase, url, host_id, user_id, partner_id, keysize = 2048, options = {})
+  # Yields after the keys and certificates exist, so the block sees a usable client.
+  def self.setup(passphrase, url, host_id, user_id, partner_id, keysize = DEFAULT_KEY_SIZE, options = {})
+    options = options.dup
+    signature_version = options.delete(:signature_version) || Epics::Signature::A_VERSION_6
     client = new(nil, passphrase, url, host_id, user_id, partner_id, options)
-    client.keys = %w(A006 X002 E002).each_with_object({}) do |type, memo|
-      memo[type] = Epics::Key.new( OpenSSL::PKey::RSA.generate(keysize) )
+    [signature_version, Epics::Signature::X_VERSION_2, Epics::Signature::E_VERSION_2].each do |version|
+      signature = case version
+                  when Epics::Signature::A_VERSION_6
+                    Epics::Signature.new(version, Epics::SignatureAlgorithm::RsaPss.new(OpenSSL::PKey::RSA.generate(keysize)))
+                  when Epics::Signature::A_VERSION_5, Epics::Signature::X_VERSION_2, Epics::Signature::E_VERSION_2
+                    Epics::Signature.new(version, Epics::SignatureAlgorithm::RsaPkcs1.new(OpenSSL::PKey::RSA.generate(keysize)))
+                  end
+
+      case signature.type
+      when Epics::Signature::TYPE_A
+        client.keyring.user_signature = signature
+      when Epics::Signature::TYPE_X
+        client.keyring.user_authentication = signature
+      when Epics::Signature::TYPE_E
+        client.keyring.user_encryption = signature
+      end
     end
 
+    client.apply_certificates
+    client.generate_certificates if client.generate_certificates?
+
+    yield client if block_given?
     client
   end
 
@@ -91,20 +262,16 @@ class Epics::Client
     path
   end
 
-  def header_request
-    @header_request ||= Epics::HeaderRequest.new(self)
-  end
-
   def credit(document)
     self.CCT(document)
   end
 
   def debit(document, type = :CDD)
-    self.public_send(type, document)
+    public_send(type, document)
   end
 
   def statements(from, to, type = :STA)
-    self.public_send(type, from: from, to: to)
+    public_send(type, from: from, to: to)
   end
 
   def HIA
@@ -117,14 +284,17 @@ class Epics::Client
 
   def HEV
     res = post(url, Epics::HEV.new(self).to_xml).body
-    res.doc.xpath("//xmlns:VersionNumber", xmlns: 'http://www.ebics.org/H000').each_with_object({}) do |node, versions|
+    res.doc.xpath('//xmlns:VersionNumber', xmlns: 'http://www.ebics.org/H000').each_with_object({}) do |node, versions|
       versions[node['ProtocolVersion']] = node.content
     end
   end
 
   def HPB
-    Nokogiri::XML(download(Epics::HPB)).xpath("//xmlns:PubKeyValue", xmlns: "urn:org:ebics:H004").each do |node|
-      type = node.parent.last_element_child.content
+    response_xml = download(Epics::HPB)
+    doc = Nokogiri::XML(response_xml)
+
+    doc.xpath('//xmlns:PubKeyValue', xmlns: urn_schema).each do |node|
+      signature_version = node.parent.last_element_child.content
 
       modulus  = Base64.decode64(node.at_xpath(".//*[local-name() = 'Modulus']").content)
       exponent = Base64.decode64(node.at_xpath(".//*[local-name() = 'Exponent']").content)
@@ -134,67 +304,118 @@ class Epics::Client
       sequence << OpenSSL::ASN1::Integer.new(OpenSSL::BN.new(exponent, 2))
 
       bank = OpenSSL::PKey::RSA.new(OpenSSL::ASN1::Sequence(sequence).to_der)
+      signature = Epics::Signature.new(
+        signature_version,
+        case signature_version
+        when Epics::Signature::E_VERSION_2, Epics::Signature::X_VERSION_2
+          Epics::SignatureAlgorithm::RsaPkcs1.new(bank)
+        end
+      )
+
+      case signature.type
+      when Epics::Signature::TYPE_E
+        keyring.bank_encryption = signature
+      when Epics::Signature::TYPE_X
+        keyring.bank_authentication = signature
+      end
+    rescue Epics::Signature::UnknownTypeError
+    rescue Epics::Signature::UnknownVersionError
+    end
 
-      self.keys["#{host_id.upcase}.#{type}"] = Epics::Key.new(bank)
+    doc.xpath('//ds:X509Certificate', xmlns: urn_schema,
+                                      ds: 'http://www.w3.org/2000/09/xmldsig#').each do |cert_node|
+      cert_pem = "-----BEGIN CERTIFICATE-----\n#{cert_node.content}\n-----END CERTIFICATE-----"
+
+      info_element = cert_node.parent&.parent
+      auth_version = info_element&.at_xpath('.//*[local-name() = "AuthenticationVersion"]')&.content
+      enc_version = info_element&.at_xpath('.//*[local-name() = "EncryptionVersion"]')&.content
+      version = auth_version || enc_version
+
+      next unless version
+
+      begin
+        cert = OpenSSL::X509::Certificate.new(cert_pem)
+
+        signature = Epics::Signature.new(
+          version,
+          Epics::SignatureAlgorithm::RsaPkcs1.new(cert.public_key)
+        )
+        signature.certificate = Epics::Crypt::X509.new(cert_pem)
+
+        case signature.type
+        when Epics::Signature::TYPE_E
+          keyring.bank_encryption = signature
+        when Epics::Signature::TYPE_X
+          keyring.bank_authentication = signature
+        end
+      rescue Epics::Signature::UnknownTypeError
+      rescue Epics::Signature::UnknownVersionError
+      rescue OpenSSL::OpenSSLError => e
+        raise Epics::InvalidCertificateError.new('the HPB response', e)
+      end
     end
 
-    [bank_x, bank_e]
+    [bank_authentication_key, bank_encryption_key]
+  end
+
+  def AZV(document, **options)
+    upload(Epics::AZV, document, **options)
   end
 
-  def AZV(document)
-    upload(Epics::AZV, document)
+  def CD1(document, **options)
+    upload(Epics::CD1, document, **options)
   end
 
-  def CD1(document)
-    upload(Epics::CD1, document)
+  def CDB(document, **options)
+    upload(Epics::CDB, document, **options)
   end
 
-  def CDB(document)
-    upload(Epics::CDB, document)
+  def C2S(document, **options)
+    upload(Epics::C2S, document, **options)
   end
 
-  def C2S(document)
-    upload(Epics::C2S, document)
+  def CDD(document, **options)
+    upload(Epics::CDD, document, **options)
   end
 
-  def CDD(document)
-    upload(Epics::CDD, document)
+  def XE2(document, **options)
+    upload(Epics::XE2, document, **options)
   end
 
-  def XE2(document)
-    upload(Epics::XE2, document)
+  def XE3(document, **options)
+    upload(Epics::XE3, document, **options)
   end
 
-  def XE3(document)
-    upload(Epics::XE3, document)
+  def CDS(document, **options)
+    upload(Epics::CDS, document, **options)
   end
 
-  def CDS(document)
-    upload(Epics::CDS, document)
+  def XDS(document, **options)
+    upload(Epics::XDS, document, **options)
   end
 
-  def XDS(document)
-    upload(Epics::XDS, document)
+  def CCT(document, **options)
+    upload(Epics::CCT, document, **options)
   end
 
-  def CCT(document)
-    upload(Epics::CCT, document)
+  def CIP(document, **options)
+    upload(Epics::CIP, document, **options)
   end
 
-  def CIP(document)
-    upload(Epics::CIP, document)
+  def CCS(document, **options)
+    upload(Epics::CCS, document, **options)
   end
 
-  def CCS(document)
-    upload(Epics::CCS, document)
+  def XCT(document, **options)
+    upload(Epics::XCT, document, **options)
   end
 
-  def XCT(document)
-    upload(Epics::XCT, document)
+  def YCT(document, **options)
+    upload(Epics::YCT, document, **options)
   end
 
-  def FUL(document)
-    upload(Epics::FUL, document)
+  def FUL(document, **options)
+    upload(Epics::FUL, document, **options)
   end
 
   def STA(from = nil, to = nil)
@@ -202,7 +423,7 @@ class Epics::Client
   end
 
   def FDL(format, from = nil, to = nil)
-    download(Epics::FDL, file_format: format, from: from, to: to )
+    download(Epics::FDL, file_format: format, from: from, to: to)
   end
 
   def VMK(from = nil, to = nil)
@@ -221,48 +442,109 @@ class Epics::Client
     download_and_unzip(Epics::BKA, from: from, to: to)
   end
 
-  def C52(from, to)
-    download_and_unzip(Epics::C52, from: from, to: to)
+  def C52(from, to, scope: nil, msg_name_version: nil, container_type: nil)
+    download_and_unzip(Epics::C52, from: from, to: to, scope: scope, msg_name_version: msg_name_version,
+                                   container_type: container_type)
   end
 
-  def C53(from, to)
-    download_and_unzip(Epics::C53, from: from, to: to)
+  def C53(from, to, scope: nil, msg_name_version: nil, container_type: nil)
+    download_and_unzip(Epics::C53, from: from, to: to, scope: scope, msg_name_version: msg_name_version,
+                                   container_type: container_type)
   end
 
-  def C54(from, to)
-    download_and_unzip(Epics::C54, from: from, to: to)
+  def C54(from, to, scope: nil, msg_name_version: nil, container_type: nil)
+    download_and_unzip(Epics::C54, from: from, to: to, scope: scope, msg_name_version: msg_name_version,
+                                   container_type: container_type)
   end
 
   def C5N(from, to)
     download_and_unzip(Epics::C5N, from: from, to: to)
   end
 
-  def Z01(from, to)
-    download_and_unzip(Epics::Z01, from: from, to: to)
+  def Z01(from, to, scope: nil, service_option: nil, msg_name_version: nil, container_type: nil)
+    download_and_unzip(Epics::Z01, from: from, to: to, scope: scope, service_option: service_option,
+                                   msg_name_version: msg_name_version, container_type: container_type)
   end
 
-  def Z52(from, to)
-    download_and_unzip(Epics::Z52, from: from, to: to)
+  def Z52(from, to, scope: nil, service_option: nil, msg_name_version: nil, container_type: nil)
+    download_and_unzip(Epics::Z52, from: from, to: to, scope: scope, service_option: service_option,
+                                   msg_name_version: msg_name_version, container_type: container_type)
   end
 
-  def Z53(from, to)
-    download_and_unzip(Epics::Z53, from: from, to: to)
+  def Z53(from, to, scope: nil, service_option: nil, msg_name_version: nil, container_type: nil)
+    download_and_unzip(Epics::Z53, from: from, to: to, scope: scope, service_option: service_option,
+                                   msg_name_version: msg_name_version, container_type: container_type)
   end
 
-  def Z54(from, to)
-    download_and_unzip(Epics::Z54, from: from, to: to)
+  def Z54(from, to, scope: nil, service_option: nil, msg_name_version: nil, container_type: nil)
+    download_and_unzip(Epics::Z54, from: from, to: to, scope: scope, service_option: service_option,
+                                   msg_name_version: msg_name_version, container_type: container_type)
+  end
+
+  def XEK(from, to, scope: nil, service_option: nil, msg_name_version: nil, container_type: nil)
+    download_and_unzip(Epics::XEK, from: from, to: to, scope: scope, service_option: service_option,
+                                   msg_name_version: msg_name_version, container_type: container_type)
+  end
+
+  def ZSR(from, to, scope: nil, service_option: nil, msg_name_version: nil, container_type: nil)
+    download_and_unzip(Epics::ZSR, from: from, to: to, scope: scope, service_option: service_option,
+                                   msg_name_version: msg_name_version, container_type: container_type)
   end
 
   def HAA
-    Nokogiri::XML(download(Epics::HAA)).at_xpath("//xmlns:OrderTypes", xmlns: "urn:org:ebics:H004").content.split(/\s/)
+    doc = Nokogiri::XML(download(Epics::HAA))
+    ns = { xmlns: urn_schema }
+
+    case version
+    when Epics::Keyring::VERSION_24, Epics::Keyring::VERSION_25
+      doc.at_xpath('//xmlns:OrderTypes', ns).content.split(/\s/)
+    when Epics::Keyring::VERSION_30
+      doc.xpath('//xmlns:Service', ns).map do |service|
+        {
+          service_name: service.at_xpath('xmlns:ServiceName', ns)&.text,
+          scope: service.at_xpath('xmlns:Scope', ns)&.text,
+          service_option: service.at_xpath('xmlns:ServiceOption', ns)&.text,
+          container: service.at_xpath('xmlns:Container', ns)&.[]('containerType'),
+          msg_name: service.at_xpath('xmlns:MsgName', ns)&.text
+        }.compact
+      end
+    end
   end
 
   def HTD
     Nokogiri::XML(download(Epics::HTD)).tap do |htd|
-      @iban        ||= htd.at_xpath("//xmlns:AccountNumber[@international='true']", xmlns: "urn:org:ebics:H004").text rescue nil
-      @bic         ||= htd.at_xpath("//xmlns:BankCode[@international='true']", xmlns: "urn:org:ebics:H004").text rescue nil
-      @name        ||= htd.at_xpath("//xmlns:Name", xmlns: "urn:org:ebics:H004").text rescue nil
-      @order_types ||= htd.search("//xmlns:OrderTypes", xmlns: "urn:org:ebics:H004").map{|o| o.content.split(/\s/) }.delete_if{|o| o == ""}.flatten
+      @iban ||= begin
+        htd.at_xpath("//xmlns:AccountNumber[@international='true']", xmlns: urn_schema).text
+      rescue StandardError
+        nil
+      end
+      @bic ||= begin
+        htd.at_xpath("//xmlns:BankCode[@international='true']", xmlns: urn_schema).text
+      rescue StandardError
+        nil
+      end
+      @name ||= begin
+        htd.at_xpath('//xmlns:Name', xmlns: urn_schema).text
+      rescue StandardError
+        nil
+      end
+      @order_types ||= case version
+                       when Epics::Keyring::VERSION_24, Epics::Keyring::VERSION_25
+                         htd.search('//xmlns:OrderTypes', xmlns: urn_schema).map do |o|
+                           o.content.split(/\s/)
+                         end.delete_if { |o| o == '' }.flatten
+                       when Epics::Keyring::VERSION_30
+                         htd.xpath('//xmlns:Service', xmlns: urn_schema).map do |service|
+                           ns = { xmlns: urn_schema }
+                           {
+                             service_name: service.at_xpath('xmlns:ServiceName', ns)&.text,
+                             scope: service.at_xpath('xmlns:Scope', ns)&.text,
+                             service_option: service.at_xpath('xmlns:ServiceOption', ns)&.text,
+                             container: service.at_xpath('xmlns:Container', ns)&.[]('containerType'),
+                             msg_name: service.at_xpath('xmlns:MsgName', ns)&.text
+                           }.compact
+                         end
+                       end
     end.to_xml
   end
 
@@ -289,32 +571,33 @@ class Epics::Client
   def save_keys(path)
     File.write(path, dump_keys)
   end
-  
-  def x_509_certificate(type)
-    content = x_509_certificates_content[type.to_sym]
-    return if content.nil? || content.empty?
-    Epics::X509Certificate.new(content)
-  end
-  
-  def x_509_certificate_hash(type)
-    content = x_509_certificates_content[type.to_sym]
-    return if content.nil? || content.empty?
-    cert = OpenSSL::X509::Certificate.new(content)
-    Digest::SHA256.hexdigest(cert.to_der).upcase
-  end
 
   private
 
-  def upload(order_type, document)
-    order = order_type.new(self, document)
-    res = post(url, order.to_xml).body
-    order.transaction_id = res.transaction_id
+  def user_signatures
+    {
+      Epics::Signature::TYPE_A => keyring.user_signature,
+      Epics::Signature::TYPE_X => keyring.user_authentication,
+      Epics::Signature::TYPE_E => keyring.user_encryption,
+    }.compact
+  end
+
+  def parse_certificate(content, option_name)
+    return if content.nil? || content.empty?
+
+    Epics::Crypt::X509.new(content)
+  rescue OpenSSL::X509::CertificateError => e
+    raise Epics::InvalidCertificateError.new(option_name, e)
+  end
 
-    order_id = res.order_id
+  def upload(order_type, document, **options)
+    order = order_type.new(self, document, **options)
+    session = post(url, order.to_xml).body
+    order.transaction_id = session.transaction_id
 
     res = post(url, order.to_transfer_xml).body
 
-    return res.transaction_id, [res.order_id, order_id].detect { |id| id.to_s.chars.any? }
+    [res.transaction_id, [res.order_id, session.order_id].detect { |id| id.to_s.chars.any? }]
   end
 
   def download(order_type, *args, **options)
@@ -322,9 +605,7 @@ class Epics::Client
     res = post(url, document.to_xml).body
     document.transaction_id = res.transaction_id
 
-    if res.segmented? && res.last_segment?
-      post(url, document.to_receipt_xml).body
-    end
+    post(url, document.to_receipt_xml).body if res.segmented? && res.last_segment?
 
     res.order_data
   end
@@ -338,22 +619,99 @@ class Epics::Client
   end
 
   def connection
-    @connection ||= Faraday.new(headers: { 'Content-Type' => 'text/xml', user_agent: "EPICS v#{Epics::VERSION}"}, ssl: { verify: verify_ssl? }) do |faraday|
-      faraday.use Epics::XMLSIG, { client: self }
-      faraday.use Epics::ParseEbics, { client: self}
+    @connection ||= Faraday.new(headers: { 'Content-Type' => 'text/xml', user_agent: USER_AGENT },
+                                ssl: { verify: verify_ssl? }) do |faraday|
+      faraday.use Epics::ParseEbics, { client: self }
       # faraday.use MyAdapter
       faraday.response :logger, ::Logger.new(STDOUT), bodies: true if debug_mode # log requests/response to STDOUT
     end
   end
 
   def extract_keys
-    JSON.load(self.keys_content).each_with_object({}) do |(type, key), memo|
-      memo[type] = Epics::Key.new(decrypt(key)) if key
+    @unmapped_keys = {}
+
+    JSON.load(keys_content).each do |signature_version, value|
+      next unless value
+
+      entry_name = signature_version
+
+      # Handle new format: { "key" => "...", "cert" => "..." }
+      if value.is_a?(Hash)
+        key_pem = decrypt(value['key'])
+        cert_pem = value['cert'] ? decrypt(value['cert']) : nil
+      else
+        key_pem = decrypt(value)
+        cert_pem = nil
+      end
+
+      is_bank_key = signature_version.start_with?("#{host_id.upcase}.")
+      signature_version = signature_version.sub("#{host_id.upcase}.", '') if is_bank_key
+
+      signature = Epics::Signature.new(
+        signature_version,
+        case signature_version
+        when Epics::Signature::A_VERSION_6
+          Epics::SignatureAlgorithm::RsaPss.new(key_pem)
+        when Epics::Signature::A_VERSION_5, Epics::Signature::E_VERSION_2, Epics::Signature::X_VERSION_2
+          Epics::SignatureAlgorithm::RsaPkcs1.new(key_pem)
+        end
+      )
+
+      signature.certificate = Epics::Crypt::X509.new(cert_pem) if cert_pem
+
+      if is_bank_key
+        case signature.type
+        when Epics::Signature::TYPE_X
+          keyring.bank_authentication = signature
+        when Epics::Signature::TYPE_E
+          keyring.bank_encryption = signature
+        end
+      else
+        case signature.type
+        when Epics::Signature::TYPE_A
+          keyring.user_signature = signature
+        when Epics::Signature::TYPE_X
+          keyring.user_authentication = signature
+        when Epics::Signature::TYPE_E
+          keyring.user_encryption = signature
+        end
+      end
+    rescue Epics::Signature::UnknownTypeError, Epics::Signature::UnknownVersionError => e
+      # Kept verbatim so save_keys cannot drop it. A bank key whose prefix does not
+      # match host_id lands here, as does a key of a version this gem does not know.
+      @unmapped_keys[entry_name] = value
+      warn "[epics] WARNING: keeping #{entry_name.inspect} in the key file unchanged: #{e.message}"
     end
   end
 
   def dump_keys
-    JSON.dump(keys.each_with_object({}) {|(k,v),m| m[k]= encrypt(v.key.to_pem)})
+    # Entries extract_keys could not place are carried through, so saving never
+    # discards part of the key file.
+    data = (@unmapped_keys || {}).dup
+
+    [keyring.user_signature, keyring.user_authentication,
+     keyring.user_encryption].each do |sig|
+      next if !sig
+
+      data[sig.version] = dump_signature(sig)
+    end
+
+    [keyring.bank_authentication, keyring.bank_encryption].each do |sig|
+      next if !sig
+
+      data["#{host_id.upcase}.#{sig.version}"] = dump_signature(sig)
+    end
+
+    JSON.pretty_generate(data, JSON.dump_default_options)
+  end
+
+  # Keys without a certificate keep the bare-string form so key files stay readable by
+  # older versions of the gem.
+  def dump_signature(signature)
+    key = encrypt(signature.key.key.to_pem)
+    return key if !signature.certificate
+
+    { 'key' => key, 'cert' => encrypt(signature.certificate.to_pem) }
   end
 
   def new_cipher
@@ -365,17 +723,23 @@ class Epics::Client
   def encrypt(data)
     salt = OpenSSL::Random.random_bytes(8)
 
-    cipher = setup_cipher(:encrypt, self.passphrase, salt)
+    cipher = setup_cipher(:encrypt, passphrase, salt)
     Base64.strict_encode64([salt, cipher.update(data) + cipher.final].join)
   end
 
+  # Every value in a key file is a PEM. A wrong passphrase normally fails the padding
+  # check, but about one time in 256 it decrypts to garbage that happens to be padded
+  # correctly; without this check that surfaces later as an unrelated key parse error.
   def decrypt(data)
     data = Base64.strict_decode64(data)
     salt = data[0..7]
     data = data[8..-1]
 
-    cipher = setup_cipher(:decrypt, self.passphrase, salt)
-    cipher.update(data) + cipher.final
+    cipher = setup_cipher(:decrypt, passphrase, salt)
+    plaintext = cipher.update(data) + cipher.final
+    raise OpenSSL::Cipher::CipherError, 'cipher final failed: wrong passphrase' if !plaintext.start_with?('-----BEGIN')
+
+    plaintext
   end
 
   def setup_cipher(method, passphrase, salt)