as2 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a467f304fd7955e9f787078b8bbda6277e111e84e75d2cc02c935d6ccc00916
-  data.tar.gz: b75996e0b5064d1b4133f9ed8db0b9f629cb44746ade335edcd3a2fa04de0edf
+  metadata.gz: c823318d35a8e64297b050461d423414e07951268caa8fa1565fb5df4068b34f
+  data.tar.gz: 23322af75cf03f24e6a5df4d6d9b17e54ebdacd5a6569859a399cd1629f74735
 SHA512:
-  metadata.gz: b8b50c0291eed98d9f74333e094bf1a59cf4bedb987592082dddc04118e319dd85121f8434391fb473783320b6388ec836d0fe54901b02b8c3cdf70f95eb93b6
-  data.tar.gz: db4e30dba47bd613b3b9b5e0e47d33951e527a31249af79ce7f2073c66035cc9a3aa3a8ba5a88c0163b4e06eec814d6ac2bf48ee060935cc22ec57762bdd2b10
+  metadata.gz: a81d120d47bb35d6be109ea7dc873757b3e6f54b4236383a52234d57509cd9ad205beecf0e07faf7965ea5d1a5182da019868e4202ef2eac3c4aee133800b517
+  data.tar.gz: 4367841d4bcb9f3376c3ba963a247b0e9036e5e6dae011d2819bd646f4864e9d4ffa4cd3da0decb8f7104913e70ef185ee050fd004b96063b95894a36710466f

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.12.0 February 16, 2024
+
+Allow configuration of which base64 encoding scheme to apply to outbound message bodies.
+Improves compatibility with some versions of MuleSoft. [#36](https://github.com/alexdean/as2/pull/36)
+
 ## 0.11.0 September 14, 2023
 
   * Allow configuration of which encryption cipher to use when sending outbound messages. [#35](https://github.com/alexdean/as2/pull/35)

data/README.md

@@ -14,23 +14,25 @@ and with [OpenAS2](https://github.com/OpenAS2/OpenAs2App).
 These limitations may be removed over time as demand (and pull requests!) come
 along.
 
-  1. RFC defines a number of optional features that partners can pick and choose
-     amongst. We currently have hard-coded options for many of these. Our current
-     choices are likely the most common ones in use, but we do not offer all the
-     configuration options needed for a fully-compliant implementation. https://datatracker.ietf.org/doc/html/rfc4130#section-2.4.2
-     1. Encrypted or Unencrypted Data: We assume all messages are encrypted. An
-       error will result if partner sends us an unencrypted message.
-     2. Signed or Unsigned Data: We error if partner sends an unsigned message.
-       Partners can request unsigned MDNs, but we always send signed MDNs.
-     3. Optional Use of Receipt: We always send a receipt.
-     4. Use of Synchronous or Asynchronous Receipts: We do not support asynchronous
-       delivery of MDNs.
-     5. Security Formatting: We should be reasonably compliant here.
-     6. Hash Function, Message Digest Choices: We currently always use sha256 for
-        signing. Since [#20](https://github.com/alexdean/as2/pull/20) we have supported
-        allowing partners to request which algorithm we use for MIC generation in MDNs.
-  2. AS2 partners may agree to use separate certificates for data encryption and data signing.
-     We do not support separate certificates for these purposes.
+RFC defines a number of optional features that partners can pick and choose
+amongst. We currently have hard-coded options for many of these. Our current
+choices are likely the most common ones in use, but we do not offer all the
+configuration options needed for a fully-compliant implementation.
+
+https://datatracker.ietf.org/doc/html/rfc4130#section-2.4.2
+
+
+  1. Encrypted or Unencrypted Data: We assume all messages are encrypted. An
+    error will result if partner sends us an unencrypted message.
+  2. Signed or Unsigned Data: We error if partner sends an unsigned message.
+    Partners can request unsigned MDNs, but we always send signed MDNs.
+  3. Optional Use of Receipt: We always send a receipt.
+  4. Use of Synchronous or Asynchronous Receipts: We do not support asynchronous
+    delivery of MDNs.
+  5. Security Formatting: We should be reasonably compliant here.
+  6. Hash Function, Message Digest Choices: We currently always use sha256 for
+    signing. Since [#20](https://github.com/alexdean/as2/pull/20) we have supported
+    allowing partners to request which algorithm we use for MIC generation in MDNs.
 
 ## Installation
 
@@ -48,6 +50,87 @@ Or install it yourself as:
 
     $ gem install as2
 
+## Configuration
+
+Configuration objects need to be initialized for the local system and once for each partner.
+
+See scripts in `examples` directory for more usage info.
+
+A a certificate can be specified as either:
+
+  * a string path to a file containing a PEM-encoded X509 certificate
+  * or an instance of `OpenSSL::X509::Certificate`
+
+A private key can be specified as either:
+
+  * a string path to a file containing a PEM-encoded private key
+  * or an instance of `OpenSSL::PKey::PKey`
+
+### Local System
+
+Supported options:
+
+  * `name`: AS2 id for the local system. (Used as `As2-From` in outbound messages.)
+  * `url`: URL of this system. Mainly for informational purposes.
+  * `domain`: DNS domain name of this system. Mainly for informational purposes.
+  * `certificate`: Certificate used for signing outbound messages.
+  * `pkey`: Private key used for decrypting incoming messages.
+
+### Partners
+
+Supported options:
+
+  * `name`: AS2 id for this partner. (Used as `As2-To` in outbound messages.)
+  * `url`: URL to POST outbound messages to.
+  * `certificate`: Certificate to use for both encryption and signature verification.
+    * If this is specified, it will be used for both `encryption_certificate` and `signing_certificate`.
+  * `encryption_certificate`: Certificate to use for encrypting outbound messages.
+    * Only required if `certificate` is not set.
+  * `signing_certificate`: Certificate to use when verifying signatures on incoming messages.
+    * Only required if `certificate` is not set.
+  * `encryption_cipher`: Cipher to use when encrypting outbound messages. A default value is used if this is not specified.
+    * Call `As2::Client.valid_encryption_ciphers` for valid options.
+  * `tls_verify_mode`: Optional. Set to `OpenSSL::SSL::VERIFY_NONE` if partner is using a self-signed certificate for HTTPS.
+  * `mdn_format`: Format to use when building MDNs to send to partners.
+    * `v0`: older/original format which is less compatible with other AS2 systems, but is the default for backwards-compatibility reasons.
+    * `v1`: improved format with better compatibility with other AS2 systems.
+  * `outbound_format`: Format to use when building outbound messages.
+    * `v0`: older/original format which is less compatible with other AS2 systems, but is the default for backwards-compatibility reasons.
+    * `v1`: improved format with better compatibility with other AS2 systems.
+  * `base64_scheme`: What type of base64 encoding to perform on outbound message bodies.
+    * `rfc4648`: older/original format which is less compatible with other AS2 systems, but is the default for backwards-compatibility reasons.
+    * `rfc2045`: format understood by more AS2 systems & recommended for new integrations.
+
+### Example
+
+```ruby
+As2.configure do |conf|
+  conf.name = 'RUBYAS2'
+  conf.url = 'http://localhost:3000/as2'
+  conf.certificate = 'test/certificates/server.crt'
+  conf.pkey = 'test/certificates/server.key'
+  conf.domain = 'localhost'
+
+  conf.add_partner do |partner|
+    partner.name = 'MENDELSON'
+    partner.url = 'http://localhost:8080/as2/HttpReceiver'
+    partner.certificate = 'test/certificates/client.crt'
+    partner.outbound_format = 'v1'
+    partner.mdn_format = 'v1'
+    partner.base64_scheme = 'rfc2045'
+  end
+
+  conf.add_partner do |partner|
+    partner.name = 'OPENAS2'
+    partner.url = 'http://localhost:4088'
+    partner.certificate = 'test/certificates/client.crt'
+    partner.outbound_format = 'v1'
+    partner.mdn_format = 'v1'
+    partner.base64_scheme = 'rfc2045'
+  end
+end
+```
+
 ## Usage
 
 Generate self signed server certificate:

data/examples/server.rb

@@ -21,12 +21,18 @@ As2.configure do |conf|
     partner.name = 'MENDELSON'
     partner.url = 'http://localhost:8080/as2/HttpReceiver'
     partner.certificate = 'test/certificates/client.crt'
+    partner.outbound_format = 'v1'
+    partner.mdn_format = 'v1'
+    partner.base64_scheme = 'rfc2045'
   end
 
   conf.add_partner do |partner|
     partner.name = 'OPENAS2'
     partner.url = 'http://localhost:4088'
     partner.certificate = 'test/certificates/client.crt'
+    partner.outbound_format = 'v1'
+    partner.mdn_format = 'v1'
+    partner.base64_scheme = 'rfc2045'
   end
 end
 

data/lib/as2/client.rb

@@ -172,7 +172,7 @@ module As2
       document_payload << "Content-Transfer-Encoding: base64\r\n"
       document_payload << "Content-Disposition: attachment; filename=#{file_name}\r\n"
       document_payload << "\r\n"
-      document_payload << Base64.strict_encode64(document_content)
+      document_payload << base64_encode(document_content)
 
       signature = OpenSSL::PKCS7.sign(@server_info.certificate, @server_info.pkey, document_payload)
       signature.detached = true
@@ -201,7 +201,7 @@ module As2
       document_payload << "Content-Transfer-Encoding: base64\r\n"
       document_payload << "Content-Disposition: attachment; filename=#{file_name}\r\n"
       document_payload << "\r\n"
-      document_payload << Base64.strict_encode64(document_content)
+      document_payload << base64_encode(document_content)
 
       signature = OpenSSL::PKCS7.sign(@server_info.certificate, @server_info.pkey, document_payload)
       signature.detached = true
@@ -211,7 +211,7 @@ module As2
       # strip off the '-----BEGIN PKCS7-----' / '-----END PKCS7-----' delimiters
       bare_pem_signature.gsub!(/^-----[^\n]+\n/, '')
       # and update to canonical \r\n line endings
-      bare_pem_signature.gsub!(/(?<!\r)\n/, "\r\n")
+      bare_pem_signature = As2.canonicalize_line_endings(bare_pem_signature)
 
       # this is a hack until i can determine a better way to get the micalg parameter
       # from the pkcs7 signature generated above...
@@ -315,6 +315,11 @@ module As2
 
     private
 
+    def base64_encode(content)
+      encoded = As2.base64_encode(content, scheme: @partner.base64_scheme)
+      As2.canonicalize_line_endings(encoded)
+    end
+
     # extract the MDN body from a multipart/signed wrapper & attempt to verify
     # the signature
     #

data/lib/as2/config.rb

@@ -12,10 +12,20 @@ module As2
       end
     end
 
-    class Partner < Struct.new :name, :url, :encryption_certificate, :encryption_cipher, :signing_certificate, :tls_verify_mode, :mdn_format, :outbound_format
+    class Partner < Struct.new :name, :url, :encryption_certificate, :encryption_cipher, :signing_certificate, :tls_verify_mode, :mdn_format, :outbound_format, :base64_scheme
       def initialize
         # set default.
         self.encryption_cipher = 'aes-256-cbc'
+        self.base64_scheme = 'rfc4648'
+      end
+
+      def base64_scheme=(scheme)
+        scheme_s = scheme.to_s
+        valid_schemes = As2.valid_base64_schemes
+        if !valid_schemes.include?(scheme_s)
+          raise ArgumentError, "base64_scheme '#{scheme_s}' must be one of #{valid_schemes.inspect}"
+        end
+        self['base64_scheme'] = scheme_s
       end
 
       def url=(url)

data/lib/as2/server.rb

@@ -165,7 +165,7 @@ module As2
       # strip off the '-----BEGIN PKCS7-----' / '-----END PKCS7-----' delimiters
       bare_pem_signature.gsub!(/^-----[^\n]+\n/, '')
       # and update to canonical \r\n line endings
-      bare_pem_signature.gsub!(/(?<!\r)\n/, "\r\n")
+      bare_pem_signature = As2.canonicalize_line_endings(bare_pem_signature)
 
       # this is a hack until i can determine a better way to get the micalg parameter
       # from the pkcs7 signature generated above...

data/lib/as2/version.rb

@@ -1,3 +1,3 @@
 module As2
-  VERSION = "0.11.0"
+  VERSION = "0.12.0"
 end

data/lib/as2.rb

@@ -23,6 +23,54 @@ module As2
     "<#{server_info.name}-#{Time.now.strftime('%Y%m%d-%H%M%S')}-#{SecureRandom.uuid}@#{server_info.domain}>"
   end
 
+  def self.valid_base64_schemes
+    [
+      'rfc2045',
+      'rfc4648'
+    ]
+  end
+
+  # create a base64 string from content, based on the given encoding scheme
+  #
+  # @param [String] content
+  # @param [String] scheme one of As2.valid_base64_schemes
+  # @return [String]
+  def self.base64_encode(content, scheme: 'rfc4648')
+    case scheme.to_s
+    when 'rfc2045'
+      # "This method complies with RFC 2045."
+      # https://ruby-doc.org/stdlib-3.0.4/libdoc/base64/rdoc/Base64.html#method-i-encode64
+      # https://www.rfc-editor.org/rfc/rfc2045#section-6.8
+      then Base64.encode64(content)
+    when 'rfc4648'
+      # "This method complies with RFC 4648."
+      # https://ruby-doc.org/stdlib-3.0.4/libdoc/base64/rdoc/Base64.html#method-i-strict_encode64
+      # https://www.rfc-editor.org/rfc/rfc4648#section-4
+      then Base64.strict_encode64(content)
+    else
+      raise ArgumentError, "unsupported scheme '#{scheme}'. choose one of: #{valid_base64_schemes}"
+    end
+  end
+
+  # canonicalize all line endings in the given text.
+  #
+  #   "\n" becomes "\r\n"
+  # "\r\n" remains "\r\n"
+  #
+  #   Conversion to canonical form:
+  #   The entire body ... is converted to a universal canonical
+  #   form. ... For example, in the case of text/plain data, the text
+  #   must be converted to a supported character set and lines must
+  #   be delimited with CRLF delimiters in accordance with RFC 822.
+  #
+  # https://www.rfc-editor.org/rfc/rfc2049#page-9
+  #
+  # @param [String] content
+  # @return [String] content, but with all bare \n replaced by \r\n
+  def self.canonicalize_line_endings(content)
+    content.gsub(/(?<!\r)\n/, "\r\n")
+  end
+
   # Select which algorithm to use for calculating a MIC, based on preferences
   # stated by sender & our list of available algorithms.
   #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: as2
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - OfficeLuv
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-14 00:00:00.000000000 Z
+date: 2024-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mail
@@ -205,7 +205,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Simple AS2 server and client implementation