epics 2.9.0 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc38fae79ba6b5ebcbafa535bfd7b4364b708deff8d1d45caa44ed9273a338e1
-  data.tar.gz: 3a54d33face295d3f0718baeb6343d8aff05946b27aaf11f9df0871869e266bf
+  metadata.gz: 1a9354e4e83108afe41607057bd8ce1fcba27fc03476a521269911f1f1fea57f
+  data.tar.gz: 82333eed938cdb0a31fcb54b206a6c5653eef950ee7b120f9487de012e4b22f0
 SHA512:
-  metadata.gz: 3827df11227abf25613c8b27356cbb45465d2be54b58421725bb9625338be4c1bedab8683c3b0f9e9630bc3a63700bfcc897fff130baae465475e53f5112aa43
-  data.tar.gz: 168a79d4581dcc1053a130081d70bf08741f7d7f96582863963653aab189f866c303b6c582d15584851443d5c65756139b3956ca81c3dfbf0715afc5ba3040ae
+  metadata.gz: 9d74d5100f8698e179df3d9b7eb3f3b3154d64313b975e6645b99ebdfd389e6b1695021640f39b753c685d47055216bf2ecda404c01b1c32f049f16b4caae769
+  data.tar.gz: 3d79c5800b76e7dfbe259e27e8ae1d1f14a77dc99a5b676603bd184a3cff5d3780682f13b14c796a0f92182805cec119ddf4dd585977b4b81f2c0195df00cd2d

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ### Unreleased
 
+### 2.11.0
+
+- [ENHANCEMENT] Added FUL order type (thanks to @scollon-pl)
+
+### 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

@@ -10,7 +10,7 @@ It supports EBICS 2.5.
 
 The client supports the complete initialization process comprising INI, HIA and HPB including the
 INI letter generation. It offers support for the most common download and upload order types
-(STA HAA HTD HPD PTK HAC HKD BKA C52 C53 C54 CD1 CDB CDD CCT VMK FDL).
+(STA HAA HTD HPD PTK HAC HKD BKA C52 C53 C54 CD1 CDB CDD CCT VMK FDL FUL).
 
 ## Installation
 
@@ -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
@@ -185,6 +193,10 @@ class Epics::Client
     upload(Epics::XCT, document)
   end
 
+  def FUL(document)
+    upload(Epics::FUL, document)
+  end
+
   def STA(from = nil, to = nil)
     download(Epics::STA, from: from, to: to)
   end
@@ -225,6 +237,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 +289,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 +342,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/ful.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class Epics::FUL < Epics::GenericUploadRequest
+  def header
+    ful_order_params = Hash.new.tap do |params|
+      params[:FileFormat] = options[:file_format]
+    end
+
+    client.header_request.build(
+      nonce: nonce,
+      timestamp: timestamp,
+      order_type: 'FUL',
+      order_attribute: 'DZHNN',
+      custom_order_params: { FULOrderParams: ful_order_params },
+      mutable: { TransactionPhase: 'Initialisation' }
+    )
+  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.11.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

@@ -26,12 +26,14 @@ require "epics/htd"
 require "epics/haa"
 require "epics/sta"
 require "epics/fdl"
+require "epics/ful"
 require "epics/vmk"
 require "epics/bka"
 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 +60,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')]