epics 2.8.0 → 2.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f97fb2e1d069feca084d74aff47a5a55a4f0f8d6aa2865567544450f68cf35c8
-  data.tar.gz: 4028071efc11da0c35e2c4e1ca9997512538083fbbfeebd6eb00ce985ea76f45
+  metadata.gz: 33e735bd9012ec4df1bc24d5f1621345adfa6aeba90dbf5c3adcc9be9673c696
+  data.tar.gz: f8c5b93115aeb9b60d3be9cbcd36251b6046f5093ed92482c2b4b1d8d4555e90
 SHA512:
-  metadata.gz: 90c7e7bf8b9dd58f367a432eb8b1beec2b3faff2bde2f186575555b4098e6db494769ba0f567e2c419bb0387344d2bf6a10f6201544a2e15f09eb583bc89fe70
-  data.tar.gz: 4b9e25b55194e4a299717d8d9cd6f1296d6e0298b20e4d405518488e90d90ed9c3e5e92c9361e00e51fcb6759d366a5100d629f4a1c582f4ab242471363f9009
+  metadata.gz: 6021ed35c892dc544032a95e89ef5a8361f27ea022a5a2776dfea3adea1e7ebbbb2642e145a0c4efb01157c228953c171a511747d21087e520a1b59411f82f81
+  data.tar.gz: 71ef90f98028d9e4bff31aa077d52fdbd7cadc12e8126792f7e71bb6e00b4b409a1ad9e36b54e2e345115e602734a7ddaaa26f3b214e54503055929a5600f114

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ### Unreleased
 
+### 2.10.0
+
+- [ENHANCEMENT] Added X.509 certificates support for INI and HIA (thanks to @vnoviskyi)
+- [ENHANCEMENT] Added Z01 order type (thanks to @Nymuxyzo)
+
+### 2.9.0
+
+- [ENHANCEMENT] Added HEV order type (thanks to @jplot)
+
 ### 2.8.0
 
 - [ENHANCEMENT] Added BKA order type

data/README.md

@@ -41,7 +41,7 @@ Once the paperwork is done, your bank should provide you with:
 Take these parameters and start setting up an UserID (repeat this for every user you want to initialize):
 
 ```ruby
-e = Epics::Client.setup("my-super-secret", "https://ebics.sandbox", "EBICS_HOST_ID", "EBICS_USER_ID", "EBICS_PARTNER_ID")
+e = Epics::Client.setup("my-super-secret", "https://ebics.sandbox", "EBICS_HOST_ID", "EBICS_USER_ID", "EBICS_PARTNER_ID", 4096)
 ```
 
 To use the keys later, just store them in a file
@@ -200,6 +200,76 @@ that are hiding some strange names from you:
 If you need more sophisticated EBICS order types, please read the next section
 about the supported functionalities.
 
+### Using X.509 Certificates
+
+Epics supports using X.509 self-signed certificates for INI and HIA requests, as required by some banks. This is in addition to the classic key-based workflow.
+
+#### When to Use
+
+Some banks require X.509 certificates for EBICS initialization (INI/HIA).
+
+You can generate your own X.509 certificate using Ruby’s OpenSSL library:
+
+This examples showcases the generation of the X.509 certificate A file and can be applied the same way for the others.
+```ruby
+key = client.a.key # or e key, or x key
+name = OpenSSL::X509::Name.parse('/CN=Test Certificate/O=MyOrg/C=DE')
+cert = OpenSSL::X509::Certificate.new
+cert.version = 2
+cert.serial = SecureRandom.random_number(2**64)
+cert.subject = name
+cert.issuer = name
+cert.public_key = key.public_key
+cert.not_before = Time.current
+cert.not_after = cert.not_before + 1.year
+
+ef = OpenSSL::X509::ExtensionFactory.new
+ef.subject_certificate = cert
+ef.issuer_certificate = cert
+cert.add_extension(ef.create_extension('basicConstraints', 'CA:FALSE', true))
+cert.add_extension(ef.create_extension('keyUsage', 'digitalSignature,nonRepudiation,keyEncipherment', true))
+
+cert.sign(key, OpenSSL::Digest.new('SHA256'))
+cert
+
+# Save to file
+File.write("cert_a.pem", cert.to_pem)
+```
+You can now use the contents of the generated certificate file in PEM format as your
+`x_509_certificate_a_content`, `x_509_certificate_x_content`, or `x_509_certificate_e_content`
+in the client initialization.
+
+**Note:** For production environments, your bank may require certificates issued by a trusted authority. Be sure to confirm your bank’s requirements before proceeding.
+
+#### Initializing the Client with X.509 Certificates
+```ruby
+# Load your certificate data (PEM or DER encoded)
+certificate_a = File.read("cert_a.pem")
+certificate_x = File.read("cert_x.pem")
+certificate_e = File.read("cert_e.pem")
+
+client = Epics::Client.new(
+  keys,                # your key data as before
+  'passphrase',
+  'url',
+  'host',
+  'user',
+  'partner',
+  x_509_certificate_a_content: certificate_a,
+  x_509_certificate_x_content: certificate_x,
+  x_509_certificate_e_content: certificate_e,
+  debug_mode: true # Optional: enables verbose logging of EBICS requests/responses
+)
+```
+### Example: Generating the Initialization Letter with Certificates
+
+```ruby
+renderer = Epics::LetterRenderer.new(client)
+letter = renderer.render("Your Bank Name")
+File.write("initialization_letter.txt", letter)
+```
+If all three certificates are present, the INI letter will use certificate hashes as required for certificate-based registration.
+
 ## Issues and Feature Requests
 
 [Railslove](http://railslove.com) is commited to provide the best developer tools for integrating
@@ -258,8 +328,8 @@ EPICS_VERIFY_SSL=false
 ## Contributing
 Railslove has a [Contributor License Agreement (CLA)](https://github.com/railslove/epics/blob/master/CONTRIBUTING.md) which clarifies the intellectual property rights for contributions from individuals or entities. To ensure every developer has signed the CLA, we use [CLA  Assistant](https://cla-assistant.io/).
 
-After checking out the repo, run `bin/setup` to install dependencies. 
-Then, run `rspec` to run the tests. 
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `rspec` to run the tests.
 You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 0. Contact team@railslove.com for information about the CLA

data/lib/epics/client.rb

@@ -1,12 +1,14 @@
 class Epics::Client
   extend Forwardable
 
-  attr_accessor :passphrase, :url, :host_id, :user_id, :partner_id, :keys, :keys_content, :locale, :product_name
-  attr_writer :iban, :bic, :name
+  attr_accessor :passphrase, :url, :host_id, :user_id, :partner_id, :keys, :keys_content, :locale, :product_name,
+                :x_509_certificates_content, :debug_mode
 
+  attr_writer :iban, :bic, :name
+  
   def_delegators :connection, :post
-
-  def initialize(keys_content, passphrase, url, host_id, user_id, partner_id, locale: Epics::DEFAULT_LOCALE, product_name: Epics::DEFAULT_PRODUCT_NAME)
+  
+  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
@@ -14,8 +16,14 @@ class Epics::Client
     self.host_id    = host_id
     self.user_id    = user_id
     self.partner_id = partner_id
-    self.locale = locale
-    self.product_name = product_name
+    self.locale = options[:locale] || Epics::DEFAULT_LOCALE
+    self.product_name = options[:product_name] || Epics::DEFAULT_PRODUCT_NAME
+    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]
+    }
   end
 
   def inspect
@@ -61,8 +69,8 @@ class Epics::Client
     @order_types ||= (self.HTD; @order_types)
   end
 
-  def self.setup(passphrase, url, host_id, user_id, partner_id, keysize = 2048)
-    client = new(nil, passphrase, url, host_id, user_id, partner_id)
+  def self.setup(passphrase, url, host_id, user_id, partner_id, keysize = 2048, options = {})
+    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) )
     end
@@ -107,6 +115,13 @@ class Epics::Client
     post(url, Epics::INI.new(self).to_xml).body.ok?
   end
 
+  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|
+      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
@@ -218,6 +233,10 @@ class Epics::Client
     download_and_unzip(Epics::C5N, from: from, to: to)
   end
 
+  def Z01(from, to)
+    download_and_unzip(Epics::Z01, from: from, to: to)
+  end
+
   def Z52(from, to)
     download_and_unzip(Epics::Z52, from: from, to: to)
   end
@@ -266,6 +285,19 @@ 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
 
@@ -306,7 +338,7 @@ class Epics::Client
       faraday.use Epics::XMLSIG, { client: self }
       faraday.use Epics::ParseEbics, { client: self}
       # faraday.use MyAdapter
-      # faraday.response :logger                  # log requests to STDOUT
+      faraday.response :logger, ::Logger.new(STDOUT), bodies: true if debug_mode # log requests/response to STDOUT
     end
   end
 

data/lib/epics/generic_request.rb

@@ -105,4 +105,18 @@ class Epics::GenericRequest
       }
     end.to_xml(save_with: Nokogiri::XML::Node::SaveOptions::AS_XML, encoding: 'utf-8')
   end
+  
+  private
+  
+  def x509_data_xml(xml, x_509_certificate)
+    return unless x_509_certificate
+    
+    xml.send('ds:X509Data') do
+      xml.send('ds:X509IssuerSerial') do
+        xml.send('ds:X509IssuerName', x_509_certificate.issuer)
+        xml.send('ds:X509SerialNumber', x_509_certificate.version)
+      end
+      xml.send('ds:X509Certificate', x_509_certificate.data)
+    end
+  end
 end

data/lib/epics/hev.rb

@@ -0,0 +1,19 @@
+class Epics::HEV < Epics::GenericRequest
+  def root
+    "ebicsHEVRequest"
+  end
+
+  def body
+    Nokogiri::XML::Builder.new do |xml|
+      xml.HostID host_id
+    end.doc.root
+  end
+
+  def to_xml
+    Nokogiri::XML::Builder.new do |xml|
+      xml.send(root, 'xmlns:xsi' => 'http://www.w3.org/2001/XMLSchema-instance', 'xsi:schemaLocation' => 'http://www.ebics.org/H000 http://www.ebics.org/H000/ebics_hev.xsd', 'xmlns' => 'http://www.ebics.org/H000') {
+        xml.parent.add_child(body)
+      }
+    end.to_xml(save_with: Nokogiri::XML::Node::SaveOptions::AS_XML, encoding: 'utf-8')
+  end
+end

data/lib/epics/hia.rb

@@ -26,6 +26,7 @@ class Epics::HIA < Epics::GenericRequest
     Nokogiri::XML::Builder.new do |xml|
       xml.HIARequestOrderData('xmlns:ds' => 'http://www.w3.org/2000/09/xmldsig#', 'xmlns' => 'urn:org:ebics:H004') {
         xml.AuthenticationPubKeyInfo {
+          x509_data_xml(xml, client.x_509_certificate(:x))
           xml.PubKeyValue {
             xml.send('ds:RSAKeyValue') {
               xml.send('ds:Modulus', Base64.strict_encode64([client.x.n].pack("H*")))
@@ -35,6 +36,7 @@ class Epics::HIA < Epics::GenericRequest
           xml.AuthenticationVersion 'X002'
         }
         xml.EncryptionPubKeyInfo{
+          x509_data_xml(xml, client.x_509_certificate(:e))
           xml.PubKeyValue {
             xml.send('ds:RSAKeyValue') {
               xml.send('ds:Modulus', Base64.strict_encode64([client.e.n].pack("H*")))

data/lib/epics/ini.rb

@@ -26,6 +26,7 @@ class Epics::INI < Epics::GenericRequest
     Nokogiri::XML::Builder.new do |xml|
       xml.SignaturePubKeyOrderData('xmlns:ds' => 'http://www.w3.org/2000/09/xmldsig#', 'xmlns' => 'http://www.ebics.org/S001') {
         xml.SignaturePubKeyInfo {
+          x509_data_xml(xml, client.x_509_certificate(:a))
           xml.PubKeyValue {
             xml.send('ds:RSAKeyValue') {
               xml.send('ds:Modulus', Base64.strict_encode64([client.a.n].pack("H*")))

data/lib/epics/letter_renderer.rb

@@ -1,7 +1,6 @@
 class Epics::LetterRenderer
   extend Forwardable
 
-  TEMPLATE_PATH = File.join(File.dirname(__FILE__), '../letter/', 'ini.erb')
   I18N_SCOPE = 'epics.letter'
 
   def initialize(client)
@@ -12,11 +11,32 @@ class Epics::LetterRenderer
     I18n.translate(key, **{ locale: @client.locale, scope: I18N_SCOPE }.merge(options))
   end
 
-  alias_method :t, :translate
+  alias t translate
 
   def_delegators :@client, :host_id, :user_id, :partner_id, :a, :x, :e
 
   def render(bankname)
-    ERB.new(File.read(TEMPLATE_PATH)).result(binding)
+    template_path = File.join(File.dirname(__FILE__), '../letter/', template_filename)
+    ERB.new(File.read(template_path)).result(binding)
+  end
+
+  def template_filename
+    use_x_509_certificate_template? ? 'ini_with_certs.erb' : 'ini.erb'
+  end
+
+  def use_x_509_certificate_template?
+    x_509_certificate_a_hash && x_509_certificate_x_hash && x_509_certificate_e_hash
+  end
+  
+  def x_509_certificate_a_hash
+    @client.x_509_certificate_hash(:a)
+  end
+  
+  def x_509_certificate_x_hash
+    @client.x_509_certificate_hash(:x)
+  end
+  
+  def x_509_certificate_e_hash
+    @client.x_509_certificate_hash(:e)
   end
 end

data/lib/epics/response.rb

@@ -12,9 +12,17 @@ class Epics::Response
   end
 
   def technical_code
+    mutable_return_code.empty? ? system_return_code : mutable_return_code
+  end
+
+  def mutable_return_code
     doc.xpath("//xmlns:header/xmlns:mutable/xmlns:ReturnCode", xmlns: "urn:org:ebics:H004").text
   end
 
+  def system_return_code
+    doc.xpath("//xmlns:SystemReturnCode/xmlns:ReturnCode", xmlns: 'http://www.ebics.org/H000').text
+  end
+
   def business_error?
     !["", "000000"].include?(business_code)
   end

data/lib/epics/signer.rb

@@ -17,7 +17,7 @@ class Epics::Signer
   end
 
   def sign!
-    signature_value_node = doc.xpath("//ds:SignatureValue").first
+    signature_value_node = doc.xpath("//ds:SignatureValue", ds: "http://www.w3.org/2000/09/xmldsig#").first
 
     if signature_node
       signature_value_node.content = Base64.encode64(client.x.key.sign(digester, signature_node.canonicalize)).gsub(/\n/,'')
@@ -27,11 +27,11 @@ class Epics::Signer
   end
 
   def digest_node
-    @d ||= doc.xpath("//ds:DigestValue").first
+    @d ||= doc.xpath("//ds:DigestValue", ds: "http://www.w3.org/2000/09/xmldsig#").first
   end
 
   def signature_node
-    @s ||= doc.xpath("//ds:SignedInfo").first
+    @s ||= doc.xpath("//ds:SignedInfo", ds: "http://www.w3.org/2000/09/xmldsig#").first
   end
 
   def digester

data/lib/epics/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Epics
-  VERSION = '2.8.0'
+  VERSION = '2.10.0'
 end

data/lib/epics/x_509_certificate.rb

@@ -0,0 +1,15 @@
+class Epics::X509Certificate
+  extend Forwardable
+
+  attr_reader :certificate
+
+  def_delegators :certificate, :issuer, :version
+
+  def initialize(crt_content)
+    @certificate = OpenSSL::X509::Certificate.new(crt_content)
+  end
+
+  def data
+    Base64.strict_encode64(@certificate.to_der)
+  end
+end

data/lib/epics/z01.rb

@@ -0,0 +1,17 @@
+class Epics::Z01 < Epics::GenericRequest
+  def header
+    client.header_request.build(
+      nonce: nonce,
+      timestamp: timestamp,
+      order_type: 'Z01',
+      order_attribute: 'DZHNN',
+      order_params: {
+        DateRange: {
+          Start: options[:from],
+          End: options[:to]
+        }
+      },
+      mutable: { TransactionPhase: 'Initialisation' }
+    )
+  end
+end

data/lib/epics.rb

@@ -32,6 +32,7 @@ require "epics/c52"
 require "epics/c53"
 require "epics/c54"
 require "epics/c5n"
+require "epics/z01"
 require "epics/z52"
 require "epics/z53"
 require "epics/z54"
@@ -56,7 +57,9 @@ require "epics/crz"
 require "epics/xct"
 require "epics/hia"
 require "epics/ini"
+require "epics/hev"
 require "epics/signer"
+require "epics/x_509_certificate"
 require "epics/client"
 
 I18n.load_path += Dir[File.join(File.dirname(__FILE__), 'letter/locales', '*.yml')]