epics 3.0.0.rc2 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d81d3bda7eef2d4468cba9327d5e72ad7222eec73e76bfe82c609765a212075
-  data.tar.gz: b49bcb37a43532a0f9d5074478e22cfa126c4b3e7bf594894f8be27e60aeca37
+  metadata.gz: f51f635b331253de3ad314121ac6e0cf657a285415ae7811e986fb6e718649a4
+  data.tar.gz: 7889e2e42721731b46886fee4e47b20bdfb0b7a1ed892aace84886aa25edaf47
 SHA512:
-  metadata.gz: '09ce2c4c8afa08bf91a00112d8a1078b388a76b40276006706f0c821a1aab7924655a9de56032956d1e74975dda1be8438e42d11211fae95b2d4aa4634b7f7f5'
-  data.tar.gz: fe3a33f8d19057cbe437189ae98b18e32eafbedde991bb12b1cf0c10a63384a5910f254272f4d9d43f972951d50fa18601bd2b521253603b2f3893e6a81c9e13
+  metadata.gz: 7a9213441874971f2d932f36eb0032ef1ecc2063bc9567f5cd036c7dca596088e1e372caf3c10eb7ce0da749015781ad2838cc458433cbf684ecfacc5cc42e3f
+  data.tar.gz: 7deab543f728a21a132d63972ef8d8dcbfb659ff22ecccbf2e89f78c1b2666814475c89caace7b485168b08132a5c400bf030e2f1d34610cc6cd25c8e76dd836

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ### Unreleased
 
+### 3.0.1
+
+- [FIX] Upload order data was transmitted with all CR and LF removed, not as given. Any
+  content hashed by the caller no longer matched, so container uploads (e.g. `CCS`, `CDS`,
+  `C2S` with a `conxml` container whose `HashValue` covers the canonical pain message) were
+  rejected by the bank, and line breaks inside text values were lost. As in 2.x, the order
+  data is now sent unchanged and CR and LF are removed only to form the ES (electronic
+  signature) hash, as EBICS specifies; the bank removes them the same way before verifying.
+  This reverts the 3.0.0.rc1 entry "Upload order data is now normalized once"
+
+### 3.0.0
+
+- [FIX] H005 uploads were sent without `SignatureFlag` in `BTUOrderParams`, although they
+  carry the user's ES (electronic signature), so banks treated them as orders
+  to be authorised outside EBICS and some rejected them with `EBICS_INVALID_ORDER_TYPE`.
+  `SignatureFlag` is now set by default, matching `OZHNN` on H004. Pass `request_eds: true`
+  to spool the order into the EDS (distributed electronic signature, German VEU)
+  when signatures are still missing, or `signature_flag: false` to omit the flag
+
+### 3.0.0.rc2
+
 - [FIX] A download spanning several segments returned only its first segment, so zipped
   downloads such as `C52` and `C53` raised `Zip::Error` and plain ones such as `STA` came
   back cut off without an error. The remaining segments are now requested in the transfer
@@ -27,6 +48,24 @@ rewrite of request building into builders/factories/handlers.
 - [BREAKING] On H005, `Client#HAA` and `Client#order_types` return an array of service
   hashes (`service_name`, `scope`, `service_option`, `container`, `msg_name`) instead of
   an array of order-type strings
+- [BREAKING] `XEK`, `YCT` and `ZSR` raise `Epics::VersionSupportError` on H003/H004
+  instead of `NotImplementedError`, matching every other version mismatch
+- [BREAKING] `order_id:` is validated against the EBICS `OrderIDType` range (`A000` to
+  `ZZZZ`). Values below `A000` rendered as e.g. `0002`, which violates the
+  `[A-Z][A-Z0-9]{3}` pattern; they now raise `ArgumentError`. The protocol form
+  (`order_id: 'A000'`) is accepted alongside the integer
+- [BREAKING] Removed `Epics::Builders::MutableBuilder#add_receipt_code`, which emitted
+  `ReceiptCode` inside `mutable` where the schema does not allow it. `ReceiptCode`
+  belongs to `TransferReceipt`, which `TransferReceiptBuilder` already builds
+- [BREAKING] Upload order data is now normalized once, on the way in, so the bytes
+  hashed for the electronic signature are the bytes transmitted. Until 3.0 the digest
+  was taken over the normalized document while the raw one was sent, which only
+  verifies against banks that normalize before checking the ES
+- [BREAKING] Passing only one date-range bound (e.g. `client.STA(from)`) silently
+  omitted the range and fetched the bank's full retention window. Both bounds are
+  mandatory within `DateRange`, so this now raises `ArgumentError`
+- [BREAKING] Removed `Epics::Services::CryptService#sign`, which had no callers and
+  disagreed with `#encrypt` on how an A005 signature is formed
 
 **Fixes**
 
@@ -41,17 +80,12 @@ rewrite of request building into builders/factories/handlers.
   when the key they need was not loaded; they now raise `Epics::MissingKeyError` naming
   it. `#digest_valid?` no longer needs a key at all — it is a plain SHA-256 over the
   authenticated nodes
-- [BREAKING] Removed `Epics::Builders::MutableBuilder#add_receipt_code`, which emitted
-  `ReceiptCode` inside `mutable` where the schema does not allow it. `ReceiptCode`
-  belongs to `TransferReceipt`, which `TransferReceiptBuilder` already builds
 - [FIX] Removed the `container_flag:` order parameter, which emitted a `ContainerFlag`
   element that exists in no EBICS schema. The container is expressed by `Container`
   with a `containerType` attribute, which `container_type:` already emits
 - [ENHANCEMENT] Added the H005-only order types `XEK` (account statements as PDF),
   `ZSR` (payment status reports) and `YCT` (multi-currency credit transfer). Their BTF
   mappings existed in the V3 factory but had no order class or client method
-- [BREAKING] `XEK`, `YCT` and `ZSR` raise `Epics::VersionSupportError` on H003/H004
-  instead of `NotImplementedError`, matching every other version mismatch
 - [ENHANCEMENT] `XEK`, `ZSR`, `Z01`, `Z52`, `Z53` and `Z54` accept `scope:`,
   `service_option:`, `msg_name_version:` and `container_type:`. Defaults are unchanged;
   Swiss market practice requires a `Scope` and only `ZSR` sent one, so a bank-specific
@@ -63,11 +97,6 @@ rewrite of request building into builders/factories/handlers.
   keyring slots, so a `host_id` that no longer matched the stored prefix destroyed the
   bank's public keys on save. Unrecognised entries are now carried through unchanged,
   and a warning names each one instead of the failure being swallowed
-- [BREAKING] `order_id:` is validated against the EBICS `OrderIDType` range (`A000` to
-  `ZZZZ`). Values below `A000` rendered as e.g. `0002`, which violates the
-  `[A-Z][A-Z0-9]{3}` pattern; they now raise `ArgumentError`. The protocol form
-  (`order_id: 'A000'`) is accepted alongside the integer
-
 - [FIX] `XCT` sent the wrong order type: `CD1` on H003/H004 and the DTAZV service on
   H005, filing credit transfers as direct debits. It now sends `XCT` on H003/H004.
   EBICS 3.0 defines no counterpart for XCT, so on H005 it raises
@@ -75,25 +104,16 @@ rewrite of request building into builders/factories/handlers.
 - [FIX] The electronic signature over order data is again formed with line separators
   removed, matching 2.x. The refactor had signed the raw document, changing the ES for
   every upload
-- [BREAKING] Upload order data is now normalized once, on the way in, so the bytes
-  hashed for the electronic signature are the bytes transmitted. Until 3.0 the digest
-  was taken over the normalized document while the raw one was sent, which only
-  verifies against banks that normalize before checking the ES
 - [FIX] H005 `DataDigest` carried an RSA-PSS signature (256 bytes, non-reproducible)
   instead of the SHA-256 hash of the order data
 - [FIX] `Response#business_error?` treated every `01`-prefixed return code as
   informational, reporting `011001` (negative acknowledgement) and `011101` (segment
   number not reached) as success. It now uses an explicit allow-list
-- [BREAKING] Passing only one date-range bound (e.g. `client.STA(from)`) silently
-  omitted the range and fetched the bank's full retention window. Both bounds are
-  mandatory within `DateRange`, so this now raises `ArgumentError`
 - [FIX] `Time` and `DateTime` passed as date-range bounds rendered an `xs:dateTime`
   with a local offset into an `xs:date` element; they are now coerced to a date
 - [FIX] `C52` requested no container on H005 while `Client#C52` always unzips the
   response, raising `Zip::Error`. `C52` and `C53` now default to a ZIP container and
   both accept `container_type:` to override it
-- [BREAKING] Removed `Epics::Services::CryptService#sign`, which had no callers and
-  disagreed with `#encrypt` on how an A005 signature is formed
 - [FIX] `Epics::Client.setup` forwarded its block to `.new`, which yields before the
   keys are generated, so the block saw an empty keyring and anything touching it —
   `ini_letter`, `save_keys`, `INI`, `HIA` — failed. It now yields once the client is

data/README.md

@@ -307,6 +307,28 @@ practice requires it to be supplied (guidelines §5.2).
 When it is absent the bank assumes a global definition.
 On EBICS 2.4/2.5 these parameters have no equivalent and are ignored.
 
+### Signatures on uploads
+
+EBICS 3.0 replaces the order attribute (`OZHNN`, `DZHNN`) with `SignatureFlag`, which tells
+the bank whether an upload carries the user's ES (electronic signature). Uploads always
+include it and send `SignatureFlag` by default, the equivalent of `OZHNN`: the bank expects
+every required signature in the request and rejects the order otherwise.
+
+```ruby
+# spool into the EDS (distributed electronic signature, German VEU) when signatures are
+# still missing, e.g. for a user who needs a second signer
+e.CCT(document, request_eds: true)
+
+# no SignatureFlag: the order is authorised outside EBICS, e.g. by an accompanying slip
+# or in online banking
+e.CCT(document, signature_flag: false)
+```
+
+`signature_flag: false` only drops the flag; the user's signature is still sent.
+
+On EBICS 2.4/2.5 both options have no effect and are silently ignored: uploads keep
+their fixed order attribute (`OZHNN` for the payment uploads).
+
 ## Features
 
 ### Initialization

data/lib/epics/builders/order_details_builder/v3.rb

@@ -32,8 +32,22 @@ class Epics::Builders::OrderDetailsBuilder::V3 < Epics::Builders::OrderDetailsBu
   end
 
   def add_btu_order_params(
-    filename:, service_name:, msg_name:, scope: nil, service_option: nil, container_type: nil, msg_name_version: nil, msg_name_variant: nil, msg_name_format: nil
+    filename:,
+    service_name:,
+    msg_name:,
+    scope: nil,
+    service_option: nil,
+    container_type: nil,
+    msg_name_version: nil,
+    msg_name_variant: nil,
+    msg_name_format: nil,
+    signature_flag: true,
+    request_eds: false
   )
+    if request_eds && !signature_flag
+      raise ArgumentError, 'request_eds requires signature_flag'
+    end
+
     @xml.BTUOrderParams fileName: filename do |xml|
       xml.Service do
         xml.ServiceName service_name
@@ -46,6 +60,16 @@ class Epics::Builders::OrderDetailsBuilder::V3 < Epics::Builders::OrderDetailsBu
         msg_name_attributes[:format] = msg_name_format if msg_name_format
         xml.MsgName msg_name, msg_name_attributes
       end
+      # Without SignatureFlag the bank treats the order as carrying no ES (electronic
+      # signature) and expects authorisation outside EBICS. requestEDS asks the bank to
+      # spool the order into the EDS (distributed electronic signature, German VEU,
+      # "Verteilte Elektronische Unterschrift") instead of rejecting it when signatures
+      # are still missing.
+      if signature_flag
+        signature_flag_attributes = {}
+        signature_flag_attributes[:requestEDS] = 'true' if request_eds
+        xml.SignatureFlag '', signature_flag_attributes
+      end
     end
   end
 end

data/lib/epics/client.rb

@@ -724,7 +724,7 @@ class Epics::Client
       data["#{host_id.upcase}.#{sig.version}"] = dump_signature(sig)
     end
 
-    JSON.pretty_generate(data, JSON.dump_default_options)
+    JSON.pretty_generate(data)
   end
 
   # Keys without a certificate keep the bare-string form so key files stay readable by

data/lib/epics/generic_upload_request.rb

@@ -3,21 +3,17 @@ class Epics::GenericUploadRequest < Epics::GenericRequest
 
   def initialize(client, document, **options)
     super(client, **options)
-    self.document = document
+    @document = document
     aes_factory = Epics::Factories::Crypt::AesFactory.new
     aes = aes_factory.create
     @transaction_key = aes.key
     @crypt_service = Epics::Services::CryptService.new
   end
 
-  # Normalized on the way in so the bytes hashed for the electronic signature are the
-  # bytes transmitted.
-  def document=(value)
-    @document = value.gsub(/\n|\r/, '')
-  end
-
+  # The ES hash excludes CR and LF; the bank strips them before verifying. The order
+  # data itself is transmitted unchanged.
   def document_digest
-    @crypt_service.hash(document)
+    @crypt_service.hash(document.gsub(/\n|\r/, ''))
   end
 
   def to_transfer_xml

data/lib/epics/version.rb

@@ -2,6 +2,6 @@
 
 module Epics
 
-  VERSION = '3.0.0.rc2'
+  VERSION = '3.0.1'
 
 end

data/spec/builders_spec.rb

@@ -317,6 +317,60 @@ RSpec.describe 'Builders' do
           expect(container).not_to be_nil
           expect(container['containerType']).to eq('ZIP')
         end
+
+        it 'adds SignatureFlag after Service by default' do
+          instance = described_class::V3.new do |b|
+            b.add_btu_order_params(
+              filename: 'test.xml', service_name: 'MCT', msg_name: 'pain.001'
+            )
+          end
+          xml = parse_doc(instance)
+          params = xml.at('OrderDetails/BTUOrderParams')
+          expect(params.element_children.map(&:name)).to eq(%w[Service SignatureFlag])
+          expect(params.at('SignatureFlag')['requestEDS']).to be_nil
+        end
+
+        it 'sets requestEDS on SignatureFlag when request_eds is given' do
+          instance = described_class::V3.new do |b|
+            b.add_btu_order_params(
+              filename: 'test.xml',
+              service_name: 'MCT',
+              msg_name: 'pain.001',
+              request_eds: true
+            )
+          end
+          xml = parse_doc(instance)
+          params = xml.at('OrderDetails/BTUOrderParams')
+          expect(params.at('SignatureFlag')['requestEDS']).to eq('true')
+        end
+
+        it 'omits SignatureFlag when signature_flag is false' do
+          instance = described_class::V3.new do |b|
+            b.add_btu_order_params(
+              filename: 'test.xml',
+              service_name: 'MCT',
+              msg_name: 'pain.001',
+              signature_flag: false
+            )
+          end
+          xml = parse_doc(instance)
+          params = xml.at('OrderDetails/BTUOrderParams')
+          expect(params.at('SignatureFlag')).to be_nil
+        end
+
+        it 'rejects request_eds without signature_flag' do
+          expect do
+            described_class::V3.new do |b|
+              b.add_btu_order_params(
+                filename: 'test.xml',
+                service_name: 'MCT',
+                msg_name: 'pain.001',
+                signature_flag: false,
+                request_eds: true
+              )
+            end
+          end.to raise_error(ArgumentError, /request_eds/)
+        end
       end
     end
   end

data/spec/request_factory_spec.rb

@@ -439,6 +439,25 @@ RSpec.describe 'RequestFactory' do
         params = xml.at('//BTUOrderParams')
         expect(params['fileName']).to eq('custom.xml')
       end
+
+      it 'create_xe2 without override has SignatureFlag without requestEDS' do
+        xml = parse(factory.create_xe2(digest, transaction_key))
+        params = xml.at('//BTUOrderParams')
+        expect(params.at('SignatureFlag')).not_to be_nil
+        expect(params.at('SignatureFlag')['requestEDS']).to be_nil
+      end
+
+      it 'create_xe2 accepts request_eds override' do
+        xml = parse(factory.create_xe2(digest, transaction_key, request_eds: true))
+        params = xml.at('//BTUOrderParams')
+        expect(params.at('SignatureFlag')['requestEDS']).to eq('true')
+      end
+
+      it 'create_xe2 accepts signature_flag override' do
+        xml = parse(factory.create_xe2(digest, transaction_key, signature_flag: false))
+        params = xml.at('//BTUOrderParams')
+        expect(params.at('SignatureFlag')).to be_nil
+      end
     end
   end
 end

data/spec/support/ebics_shared_examples.rb

@@ -469,6 +469,10 @@ RSpec.shared_examples 'a valid ebicsRequest H005 upload' do |service_name:, msg_
     expect(service.at_xpath('e:MsgName', ns).text).to eq(msg_name)
   end
 
+  it 'has SignatureFlag' do
+    expect(xml.at_xpath('//e:header/e:static/e:OrderDetails/e:BTUOrderParams/e:SignatureFlag', ns)).not_to be_nil
+  end
+
   if scope
     it "has Scope #{scope}" do
       service = xml.at_xpath('//e:header/e:static/e:OrderDetails/e:BTUOrderParams/e:Service', ns)

data/spec/upload_digest_spec.rb

@@ -22,11 +22,18 @@ RSpec.describe 'upload order data digests' do
         .not_to eq(OpenSSL::Digest.digest('sha256', document))
     end
 
-    # Hashed bytes must equal transmitted bytes.
-    it 'normalizes once, so the digest covers exactly what is transmitted' do
-      expect(subject.document).not_to include("\n")
-      expect(subject.document_digest)
-        .to eq(OpenSSL::Digest.digest('sha256', subject.document))
+    # Callers may hash the content themselves, e.g. a container's HashValue over the
+    # canonical message, so the transmitted order data must be the input as given.
+    it 'transmits the document unchanged' do
+      subject.transaction_id = 'ABC'
+      order_data = Nokogiri::XML(subject.to_transfer_xml)
+                     .at_xpath('//e:OrderData', 'e' => 'urn:org:ebics:H004').text
+      compressed = Epics::Services::CryptService
+                     .new
+                     .decrypt_by_key(subject.transaction_key, Base64.decode64(order_data))
+
+      expect(document).to include("\n")
+      expect(Zlib::Inflate.inflate(compressed)).to eq(document)
     end
 
     it 'is identical for CRLF and LF encodings of the same document' do
@@ -56,6 +63,18 @@ RSpec.describe 'upload order data digests' do
         .to eq(data_digest_of(order).text)
     end
 
+    it 'transmits the document unchanged' do
+      order = Epics::CCT.new(client, document)
+      order.transaction_id = 'ABC'
+      order_data = Nokogiri::XML(order.to_transfer_xml).at_xpath('//e:OrderData', ns).text
+      compressed = Epics::Services::CryptService
+                     .new
+                     .decrypt_by_key(order.transaction_key, Base64.decode64(order_data))
+
+      expect(document).to include("\n")
+      expect(Zlib::Inflate.inflate(compressed)).to eq(document)
+    end
+
     it 'is reproducible across two builds of the same document' do
       expect(data_digest_of(Epics::CCT.new(client, document)).text)
         .to eq(data_digest_of(Epics::CCT.new(client, document)).text)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: epics
 version: !ruby/object:Gem::Version
-  version: 3.0.0.rc2
+  version: 3.0.1
 platform: ruby
 authors:
 - Lars Brillert