epics 2.9.0 → 2.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc38fae79ba6b5ebcbafa535bfd7b4364b708deff8d1d45caa44ed9273a338e1
-  data.tar.gz: 3a54d33face295d3f0718baeb6343d8aff05946b27aaf11f9df0871869e266bf
+  metadata.gz: 33e735bd9012ec4df1bc24d5f1621345adfa6aeba90dbf5c3adcc9be9673c696
+  data.tar.gz: f8c5b93115aeb9b60d3be9cbcd36251b6046f5093ed92482c2b4b1d8d4555e90
 SHA512:
-  metadata.gz: 3827df11227abf25613c8b27356cbb45465d2be54b58421725bb9625338be4c1bedab8683c3b0f9e9630bc3a63700bfcc897fff130baae465475e53f5112aa43
-  data.tar.gz: 168a79d4581dcc1053a130081d70bf08741f7d7f96582863963653aab189f866c303b6c582d15584851443d5c65756139b3956ca81c3dfbf0715afc5ba3040ae
+  metadata.gz: 6021ed35c892dc544032a95e89ef5a8361f27ea022a5a2776dfea3adea1e7ebbbb2642e145a0c4efb01157c228953c171a511747d21087e520a1b59411f82f81
+  data.tar.gz: 71ef90f98028d9e4bff31aa077d52fdbd7cadc12e8126792f7e71bb6e00b4b409a1ad9e36b54e2e345115e602734a7ddaaa26f3b214e54503055929a5600f114

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ### 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)

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
@@ -225,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
@@ -273,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
 
@@ -313,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/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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Epics
-  VERSION = '2.9.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"
@@ -58,6 +59,7 @@ 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')]

data/lib/letter/ini_with_certs.erb

@@ -0,0 +1,335 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+  <meta http-equiv="content-type" content="text/html; charset=utf-8">
+  <meta charset="UTF-8" />
+  <title>EBICS ini</title>
+  <style>
+      code {
+          font-size: 0.6rem;
+          overflow-wrap: break-word;
+      }
+      .code {
+          border-style: solid;
+          border-width: 1px;
+          padding: 8px;
+          background-color: azure;
+      }
+      .strong {
+          font-weight: bold;
+      }
+      h2 {
+          text-align: center;
+      }
+      td {
+          min-width: 150px;
+      }
+      table {
+          display: flex;
+          justify-content: center;
+      }
+      .column {
+          height: 100px;
+      }
+  </style>
+</head>
+<body>
+<div>
+  <h2><%= t('initialization_letter.a') %></h2>
+  <table>
+    <tr>
+      <td>
+        <div class="column">
+          <table>
+            <tr>
+              <td class="strong">
+                <%= t('date') %> :
+              </td>
+              <td>
+                <%= Date.today.strftime('%d.%m.%Y') %>
+              </td>
+            </tr>
+            <tr>
+              <td class="strong">
+                <%= t('time') %> :
+              </td>
+              <td>
+                <%= Time.now.strftime('%H:%M:%S') %>
+              </td>
+            </tr>
+            <tr>
+              <td class="strong">
+                <%= t('recipient') %> :
+              </td>
+              <td>
+                <%= bankname %>
+              </td>
+            </tr>
+          </table>
+        </div>
+      </td>
+      <td>
+        <div class="column">
+          <table>
+            <tr>
+              <td class="strong">
+                Host-ID :
+              </td>
+              <td>
+                <%= host_id %>
+              </td>
+            </tr>
+            <tr>
+              <td class="strong">
+                User-ID :
+              </td>
+              <td>
+                <%= user_id %>
+              </td>
+            </tr>
+            <tr>
+              <td class="strong">
+                Partner-ID :
+              </td>
+              <td>
+                <%= partner_id %>
+              </td>
+            </tr>
+            <tr>
+              <td class="strong">
+                <%= t('version') %> :
+              </td>
+              <td>
+                A006
+              </td>
+            </tr>
+          </table>
+        </div>
+      </td>
+    </tr>
+  </table>
+  <p><%= t('certificate') %> :</p>
+  <pre class="code"><code><%= @client.x_509_certificates_content[:a] %></code></pre>
+  <p><%= t('hash') %> (SHA-256) :</p>
+  <p class="code"><code><%= x_509_certificate_a_hash.scan(/../).join(":") %></code></p>
+  <p><%= t('confirmation') %></p>
+  <br/>
+  <br/>
+  <br/>
+  <br/>
+  <table>
+    <tr>
+      <td>
+        _________________________
+      </td>
+      <td>
+        _________________________
+      </td>
+      <td>
+        _________________________
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <%= t('issued_in') %>
+      </td>
+      <td>
+        <%= t('name') %>
+      </td>
+      <td>
+        <%= t('signature') %>
+      </td>
+    </tr>
+  </table>
+</div>
+<div style="page-break-after:always"></div>
+<div>
+  <h2><%= t('initialization_letter.x') %></h2>
+  <table>
+    <tr>
+      <td>
+        <div class="column">
+          <table>
+            <tr>
+              <td class="strong">
+                <%= t('date') %> :
+              </td>
+              <td>
+                <%= Date.today.strftime('%d.%m.%Y') %>
+              </td>
+            </tr>
+            <tr>
+              <td class="strong">
+                <%= t('time') %> :
+              </td>
+              <td>
+                <%= Time.now.strftime('%H:%M:%S') %>
+              </td>
+            </tr>
+            <tr>
+              <td class="strong">
+                <%= t('recipient') %> :
+              </td>
+              <td>
+                <%= bankname %>
+              </td>
+            </tr>
+          </table>
+        </div>
+      </td>
+      <td>
+        <div class="column">
+          <table>
+            <tr>
+              <td class="strong">
+                Host-ID :
+              </td>
+              <td>
+                <%= host_id %>
+              </td>
+            </tr>
+            <tr>
+              <td class="strong">
+                User-ID :
+              </td>
+              <td>
+                <%= user_id %>
+              </td>
+            </tr>
+            <tr>
+              <td class="strong">
+                Partner-ID :
+              </td>
+              <td>
+                <%= partner_id %>
+              </td>
+            </tr>
+            <tr>
+              <td class="strong">
+                <%= t('version') %> :
+              </td>
+              <td>
+                X002
+              </td>
+            </tr>
+          </table>
+        </div>
+      </td>
+    </tr>
+  </table>
+  <p><%= t('certificate') %> :</p>
+  <pre class="code"><code><%= @client.x_509_certificates_content[:x] %></code></pre>
+  <p><%= t('hash') %> (SHA-256) :</p>
+  <p class="code"><code><%= x_509_certificate_x_hash.scan(/../).join(":") %></code></p>
+</div>
+<div style="page-break-after:always"></div>
+<div>
+  <h2><%= t('initialization_letter.e') %></h2>
+  <table>
+    <tr>
+      <td>
+        <div class="column">
+          <table>
+            <tr>
+              <td class="strong">
+                <%= t('date') %> :
+              </td>
+              <td>
+                <%= Date.today.strftime('%d.%m.%Y') %>
+              </td>
+            </tr>
+            <tr>
+              <td class="strong">
+                <%= t('time') %> :
+              </td>
+              <td>
+                <%= Time.now.strftime('%H:%M:%S') %>
+              </td>
+            </tr>
+            <tr>
+              <td class="strong">
+                <%= t('recipient') %> :
+              </td>
+              <td>
+                <%= bankname %>
+              </td>
+            </tr>
+          </table>
+        </div>
+      </td>
+      <td>
+        <div class="column">
+          <table>
+            <tr>
+              <td class="strong">
+                Host-ID :
+              </td>
+              <td>
+                <%= host_id %>
+              </td>
+            </tr>
+            <tr>
+              <td class="strong">
+                User-ID :
+              </td>
+              <td>
+                <%= user_id %>
+              </td>
+            </tr>
+            <tr>
+              <td class="strong">
+                Partner-ID :
+              </td>
+              <td>
+                <%= partner_id %>
+              </td>
+            </tr>
+            <tr>
+              <td class="strong">
+                <%= t('version') %> :
+              </td>
+              <td>
+                E002
+              </td>
+            </tr>
+          </table>
+        </div>
+      </td>
+    </tr>
+  </table>
+  <p><%= t('certificate') %> :</p>
+  <pre class="code"><code><%= @client.x_509_certificates_content[:e] %></code></pre>
+  <p><%= t('hash') %> (SHA-256) :</p>
+  <p class="code"><code><%= x_509_certificate_e_hash.scan(/../).join(":") %></code></p>
+  <p><%= t('confirmation') %></p>
+  <br/>
+  <br/>
+  <br/>
+  <br/>
+  <table>
+    <tr>
+      <td>
+        _________________________
+      </td>
+      <td>
+        _________________________
+      </td>
+      <td>
+        _________________________
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <%= t('issued_in') %>
+      </td>
+      <td>
+        <%= t('name') %>
+      </td>
+      <td>
+        <%= t('signature') %>
+      </td>
+    </tr>
+  </table>
+</div>
+</body>
+</html>