cordawyn-iso8583 0.1.2

data/AUTHORS

@@ -0,0 +1,2 @@
+Tim Becker (tim@kuriositaet.de)
+Slava Kravchenko (cordawyn@gmail.com)

data/CHANGELOG

@@ -0,0 +1,5 @@
+0.1.2
+==========
+  branched from original 0.1.1;
+  cleaned-up files;
+  put all stuff into ISO8583 namespace (module)

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2009 Tim Becker 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,27 @@
+
+= ISO 8583 Financial Messaging for Ruby
+
+This package currently contains code for coding an decoding ISO 8583
+Financial Message.
+
+== Using
+
+The best place to get started using the library is the documentation of the
+Message class. Once a stable state is reached, this should be the only
+class you need to use ...
+
+== Installing
+
+You can install the +iso8583+ package by executing:
+
+	gem install iso8583
+
+== Source
+
+The source is most readily available on github[http://github.com/cordawyn/8583].
+
+== Mailing List
+
+In case you discover bugs, spelling errors, offer suggestions for
+improvements or would like to help out with the project, you can contact
+me directly (tim@kuriositaet.de).

data/Rakefile

@@ -0,0 +1,127 @@
+require "rake/rdoctask"
+require "rake/gempackagetask"
+require "rake/testtask"
+require "rake/clean"
+require "rubygems"
+
+# Some definitions that you'll need to edit in case you reuse this
+# Rakefile for your own project.
+
+SHORTNAME	= "iso8583"	# this should be the rubyforge project name
+DESC		= "Ruby implementation of ISO 8583 financial messaging"
+PKG_VERSION 	= "0.1.2"
+LONG_DESC	= <<END_DESC
+Ruby implementation of ISO 8583 financial messaging
+END_DESC
+RUBYFORGE_USER	= "cordawyn"
+
+# Specifies the default task to execute. This is often the "test" task
+# and we'll change things around as soon as we have some tests.
+
+task  :default => [:rdoc]
+
+# The directory to generate +rdoc+ in.
+RDOC_DIR = "doc/html"
+
+# This global variable contains files that will be erased by the `clean` task.
+# The `clean` task itself is automatically generated by requiring `rake/clean`.
+
+CLEAN << RDOC_DIR << "pkg"
+
+
+# This is the task that generates the +rdoc+ documentation from the
+# source files. Instantiating Rake::RDocTask automatically generates a
+# task called `rdoc`.
+
+Rake::RDocTask.new do |rd|
+  # Options for documenation generation are specified inside of
+  # this block. For example the following line specifies that the
+  # content of the README file should be the main page of the
+  # documenation.
+  rd.main = "README"
+
+  # The following line specifies all the files to extract
+  # documenation from.
+  rd.rdoc_files.include("README", "AUTHORS", "LICENSE", "TODO",
+			"CHANGELOG", "bin/**/*", "lib/**/*.rb",
+                        "examples/**/*rb", "doc/*.rdoc")
+  # This one specifies the output directory ...
+  rd.rdoc_dir 	= "doc/html"
+
+  # Or the HTML title of the generated documentation set.
+  rd.title 	= "#{SHORTNAME}: #{DESC}"
+
+  # These are options specifiying how source code inlined in the
+  # documentation should be formatted.
+
+  rd.options 	= ["--line-numbers", "--inline-source"]
+
+  # Check:
+  # `rdoc --help` for more rdoc options
+  # the {rdoc documenation home}[http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/index.html]
+  # or the documentation for the +Rake::RDocTask+ task[http://rake.rubyforge.org/classes/Rake/RDocTask.html]
+end
+
+# The GemPackageTask facilitates getting all your files collected
+# together into gem archives. You can also use it to generate tarball
+# and zip archives.
+
+# First you'll need to assemble a gemspec
+
+PKG_FILES 	= FileList["lib/**/*.rb", "bin/**/*", "examples/**/*", "[A-Z]*", "test/**/*"].to_a
+
+spec = Gem::Specification.new do |s|
+  s.platform = Gem::Platform::RUBY
+  s.summary = "#{SHORTNAME}: #{DESC}"
+  s.name = "#{RUBYFORGE_USER}-#{SHORTNAME}"
+  s.rubyforge_project = SHORTNAME
+  s.version = PKG_VERSION
+  s.files = PKG_FILES
+  s.requirements << "none"
+  s.require_path = "lib"
+  s.description = LONG_DESC
+  s.has_rdoc = true
+  s.authors = ["Slava Kravchenko", "Tim Becker"]
+  s.email = ["cordawyn@gmail.com", "tim.becker@kuriositaet.de"]
+  s.homepage = "http://github.com/cordawyn/8583/"
+end
+
+# Adding a new GemPackageTask adds a task named `package`, which generates
+# packages as gems, tarball and zip archives.
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar_gz = true
+end
+
+
+# This task is used to demonstrate how to upload files to Rubyforge.
+# Calling `upload_page` creates a current version of the +rdoc+
+# documentation and uploads it to the Rubyforge homepage of the project,
+# assuming it's hosted there and naming conventions haven't changed.
+#
+# This task uses `sh` to call the `scp` binary, which is plattform
+# dependant and may not be installed on your computer if you're using
+# Windows. I'm currently not aware of any pure ruby way to do scp
+# transfers.
+
+RubyForgeProject = SHORTNAME
+
+desc "Upload the web pages to the web."
+task :upload_pages => ["rdoc"] do
+  if RubyForgeProject then
+    path = "/var/www/gforge-projects/#{RubyForgeProject}"
+    sh "scp -r doc/html/* #{RUBYFORGE_USER}@rubyforge.org:#{path}"
+    sh "scp doc/images/*.png #{RUBYFORGE_USER}@rubyforge.org:#{path}/images"
+  end
+end
+
+# This task will run the unit tests provided in files called
+# `test/test*.rb`. The task itself can be run with a call to `rake test`
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.ruby_opts = ["-rubygems"]
+  t.test_files = FileList["test/*.rb"]
+  t.verbose = true
+end

data/TODO

@@ -0,0 +1,10 @@
+
+* mti_required : or something of the sort to indicate which fields are
+     required/mirrored/conditional for each message type
+
+* decode_check : currently the codecs are very liberal about what to accept
+    or parse. E.g. if an invalid date is received, it doesn't complain. Consider
+    collecting the errors and presenting them through in interface so
+    it may be decided after parsing the message whether to reject it or no
+
+* general cleanup/license/docs/readme

data/lib/berlin.rb

@@ -0,0 +1,82 @@
+# Copyright 2009 by Tim Becker (tim.becker@kuriostaet.de)
+# MIT License, for details, see the LICENSE file accompaning
+# this distribution
+
+require 'lib/iso8583'
+
+
+# Example of a protocol specification based on:
+# http://www.berlin-group.org/documents/BG_Authorisation_3.0.pdf
+# The Berlin Groups Authorisation Interface specification.
+# No gurantees are made that this is an accurate implemenation.
+# It currently serves as an example only.
+
+module ISO8583
+
+  class BerlinMessage < Message
+    mti_format N, :length => 4
+    mti 1100, "Authorization Request Acquirer Gateway"
+    mti 1110, "Authorization Request Response Issuer Gateway"
+    mti 1420, "Reversal Advice Acquirer Gateway" 
+    mti 1421, "Reversal Advice Repeat Acquirer Gateway" 
+    mti 1430, "Reversal Advice Response Issuer Gateway" 
+    mti 1804, "Network Management Request Acquirer Gateway or Issuer Gateway"
+    mti 1814, "Network Management Request Response Issuer Gateway or Acquirer Gateway"
+
+    bmp  2, "Primary Account Number (PAN)",               LLVAR_N,   :max    => 19
+    bmp  3,  "Processing Code",                           N,         :length =>  6
+    bmp  4,  "Amount (Transaction)",                      N,         :length => 12
+    bmp  6,  "Amount, Cardholder Billing" ,               N,         :length => 12
+    bmp  7,  "Date and Time, Transmission"  ,             MMDDhhmmss
+    bmp 10, "Conversion Rate, Cardholder Billing",        N,         :length =>  8
+    bmp 11, "System Trace Audit Number (STAN)",           N,         :length =>  6
+    bmp 12, "Date and Time, Local Transaction",           YYMMDDhhmmss
+    bmp 14, "Date, Expiration",                           YYMM
+    bmp 22, "POS Data Code",                              AN,        :length => 12
+    bmp 23, "Card Sequence Number",                       N,         :length =>  3
+    bmp 24, "Function Code",                              N,         :length =>  3
+    bmp 25, "Message Reason Code",                        N,         :length =>  4
+    bmp 26, "Card Acceptor Business Code",                N,         :length =>  4
+    bmp 30, "Amounts, Original",                          N,         :length => 24
+    bmp 32, "Acquiring Institution Identification Code",  LLVAR_N,   :max    => 11
+    bmp 35, "Track 2 Data",                               LLVAR_Z,   :max    => 37
+    bmp 37, "Retrieval Reference Number",                 ANP,       :length => 12
+    bmp 38, "Approval Code",                              ANP,       :length =>  6
+    bmp 39, "Action Code",                                N,         :length =>  3
+    bmp 41, "Card Acceptor Terminal Identification",      ANS,       :length =>  8
+    bmp 42, "Card Acceptor Identification Code",          ANS,       :length => 15
+    bmp 43, "Card Acceptor Name/Location",                LLVAR_ANS, :max    => 56
+    bmp 49, "Currency Code, Transaction",                 N,         :length =>  3
+    bmp 51, "Currency Code, Cardholder Billing",          N,         :length =>  3
+    bmp 52, "Personal Identification Number (PIN) Data",  B,         :length =>  8
+    bmp 53, "Security Related Control Information",       LLVAR_B,   :max    => 48
+    bmp 54, "Amounts, Additional",                        LLLVAR_ANS,:max    => 40
+
+    bmp 55, "Integrated Circuit Card (ICC) System Related Data", LLLVAR_B,   :max    => 255
+    bmp 56, "Original Data Elements",                            LLVAR_N,    :max    => 35
+    bmp 58, "Authorizing Agent Institution Identification Code", LLVAR_N,    :max    => 11
+    bmp 59, "Additional Data - Private",                         LLLVAR_ANS, :max    => 67
+    bmp 64, "Message Authentication Code (MAC) Field",           B,          :length => 8
+    
+    bmp_alias  2, :pan
+    bmp_alias  3, :proc_code
+    bmp_alias  4, :amount
+    bmp_alias 12, :exp_date
+  end
+
+end
+
+if __FILE__==$0
+  mes = ISO8583::BerlinMessage.new
+  mes.mti = 1110
+  mes[2] = 474747474747
+  mes["Processing Code"] = "123456"
+
+  pan = mes["Primary Account Number (PAN)"]
+  #mes.pan = 47474747474747
+
+  #puts mes.pan
+  puts mes.to_b
+  puts mes.to_s
+  #mes2 = BerlinMessage.parse input
+end

data/lib/bitmap.rb

@@ -0,0 +1,117 @@
+# Copyright 2009 by Tim Becker (tim.becker@kuriostaet.de)
+# MIT License, for details, see the LICENSE file accompaning
+# this distribution
+
+module ISO8583
+
+  # This class constructs an object for handling bitmaps
+  # with which ISO8583 messages typically begin.
+  # Bitmaps are either 8 or 16 bytes long, an extended length
+  # bitmap is indicated by the first bit being set.
+  # In all likelyhood, you won't be using this class much, it's used
+  # transparently by the Message class.
+  class Bitmap
+
+    # create a new Bitmap object. In case an iso message
+    # is passed in, that messages bitmap will be parsed. If
+    # not, this initializes and empty bitmap.
+    def initialize(message = nil)
+      @bmp = Array.new(128, false)
+      if !message
+
+      else
+        initialize_from_message message
+      end
+    end
+    
+    # yield once with the number of each set field.
+    def each #:yields: each bit set in the bitmap.
+      @bmp.each_with_index {|set, i| yield i+1 if set}
+    end
+    
+    # Returns whether the bit is set or not.
+    def [](i)
+      @bmp[i-1]
+    end
+
+    # Set the bit to the indicated value. Only `true` sets the
+    # bit, any other value unsets it.
+    def []=(i, value)
+      if i > 128 
+        raise ISO8583Exception.new("Bits > 128 are not permitted.")
+      elsif i < 2
+        raise ISO8583Exception.new("Bits < 2 are not permitted (continutation bit is set automatically)")
+      end
+      @bmp[i-1] = (value == true)
+    end
+
+    # Sets bit #i
+    def set(i)
+      self[i] = true
+    end
+    
+    # Unsets bit #i
+    def unset(i)
+      self[i] = false
+    end
+
+    # Generate the bytes representing this bitmap.
+    def to_bytes
+      arr = [self.to_s]
+      # tricky and ugly, setting bit[1] only when generating to_s...
+      count = self[1] ? 128 : 64
+      arr.pack("B#{count}")
+    end
+    alias_method :to_b, :to_bytes
+
+    # Generate a String representation of this bitmap in the form:
+    #	01001100110000011010110110010100100110011000001101011011001010
+    def to_s
+      #check whether any `high` bits are set
+      @bmp[0] = false
+      65.upto(128) {|i|
+        if self[i]
+          # if so, set continuation bit
+          @bmp[0] = true
+          break
+        end
+      }
+      str = ""
+      1.upto(self[1] ? 128 : 64) {|i|
+        str << (self[i] ? "1" : "0")
+      }
+      str
+    end
+
+
+    private
+
+    def initialize_from_message(message)
+      bmp = message.unpack("B64")[0]
+      if bmp[0,1] == "1"
+        bmp = message.unpack("B128")[0]
+      end
+
+      0.upto(bmp.length-1) do |i|
+        @bmp[i] = (bmp[i,1] == "1")
+      end
+    end
+
+    class << self
+      # Parse the bytes in string and return the Bitmap and bytes remaining in `str`
+      # after the bitmap is taken away.
+      def parse(str)
+        bmp  = Bitmap.new(str)
+        rest = bmp[1] ? str[16, str.length] : str[8, str.length]
+        [ bmp, rest ]
+      end
+    end
+    
+  end
+end
+
+if __FILE__==$0
+  mp = ISO8583::Bitmap.new
+  20.step(128,7) {|i| mp.set(i)}
+  print mp.to_bytes
+end

data/lib/codec.rb

@@ -0,0 +1,189 @@
+# Copyright 2009 by Tim Becker (tim.becker@kuriostaet.de)
+# MIT License, for details, see the LICENSE file accompaning
+# this distribution
+
+require 'date'
+
+module ISO8583
+
+  # Codec provides functionality to encode and decode values, codecs are
+  # used internally by Field instances in order to do character conversions
+  # and checking for proper values.
+  # Although they are used internally, you will probably need to write
+  # your own Codec sooner or later. The codecs used by Field instances are
+  # typically instances of Codec, it may or may not be usefull to subclass
+  # Codec.
+  # 
+  # Say, for example, a text field needs to be encoded in EBCDIC in the
+  # message, this is how a corresponding codec would be constructed:
+  #
+  #    EBCDIC_Codec = Codec.new
+  #    EBCDIC_Codec.encoder = lambda {|ascii_str|
+  #       raise ISO8583Exception.new("String (#{ascii_str})not valid!") unless =~ /someregexp/
+  #       ascii2ebcdic ascii_str  # implementing ascii_str is left as an excercise
+  #    }
+  #    EBCDIC_Codec.decode = lambda {|ebcdic_str|
+  #       # you may or may not want to raise exceptions at this point ....
+  #       # strip removes any padding...
+  #       ebcdic2ascii(ebcdic_str).strip
+  #    }
+  #
+  # This instance of Codec would then be used be the corresponding Field
+  # encoder/decoder, which may look similar to this:
+  #
+  #    EBCDIC         = Field.new
+  #    EBCDIC.codec   = EBCDIC_Codec
+  #    EBCDIC.padding = PADDING_LEFT_JUSTIFIED_SPACES
+  #
+  # Notice there is a bit of inconsistancy: the padding is added by the
+  # field, but removed by the codec. I would like to find a better
+  # solution to this...
+  #
+  # See also: Field, link:files/lib/fields_rb.html
+  #
+  # The following codecs are already implemented:
+  # [+ASCII_Number+]      encodes either a Number or String representation of 
+  #                       a number to the ASCII represenation of the number, 
+  #                       decodes ASCII  numerals to a number
+  # [+AN_Codec+]          passes through ASCII string checking they conform to [A-Za-z0-9]
+  #                       during encoding, no validity check during decoding. 
+  # [+ANP_Codec+]         passes through ASCII string checking they conform to [A-Za-z0-9 ] 
+  #                       during encoding, no validity check during decoding. 
+  # [+ANS_Codec+]         passes through ASCII string checking they conform to [\x20-\x7E]
+  #                       during encoding, no validity check during decoding.
+  # [+Null_Codec+]        passes anything along untouched.
+  # [<tt>Track2</tt>]     rudimentary check that string conforms to Track2
+  # [+MMDDhhmmssCodec+]   encodes Time, Datetime or String to the described date format, checking 
+  #                       that it is a valid date. Decodes to a DateTime instance, decoding and 
+  #                       encoding perform validity checks!
+  # [+YYMMDDhhmmssCodec+] encodes Time, Datetime or String to the described date format, checking 
+  #                       that it is a valid date. Decodes to a DateTime instance, decoding and 
+  #                       encoding perform validity checks!
+  # [+YYMMCodec+]         encodes Time, Datetime or String to the described date format (exp date), 
+  #                       checking that it is a valid date. Decodes to a DateTime instance, decoding
+  #                       and encoding perform validity checks!
+  #
+  class Codec
+    attr_accessor :encoder
+    attr_accessor :decoder
+
+    def decode(raw)
+      decoder.call(raw)
+    end
+
+    # length is either a fixnum or a lenth encoder.
+    def encode(value)
+      encoder.call(value)
+    end
+  end
+
+  # ASCII_Number
+  ASCII_Number = Codec.new
+  ASCII_Number.encoder= lambda{|num|
+    enc = num.to_s
+    raise ISO8583Exception.new("Invalid value: #{enc} must be numeric!") unless enc =~ /^[0-9]*$/
+    enc
+  }
+
+  ASCII_Number.decoder = lambda{|raw|
+    raw.to_i
+  }
+
+  PASS_THROUGH_DECODER = lambda{|str|
+    str.strip # remove padding
+  }
+
+  # Takes a number or str representation of a number and BCD encodes it, e.g.
+  # "1234" => "\x12\x34"
+  # 3456   => "\x34\x56"
+  #
+  # right justified with null ... (correct to do this? almost certainly not...)
+  Packed_Number = Codec.new
+  Packed_Number.encoder = lambda { |val|
+    val = val.to_s
+    val = val.length % 2 == 0 ? val : "0"+val
+    raise ISO8583Exception.new("Invalid value: #{val} must be numeric!") unless val =~ /^[0-9]*$/
+    [val].pack("H*")
+  }
+  Packed_Number.decoder = lambda{|encoded|
+    d = encoded.unpack("H*")[0].to_i
+  }
+
+  AN_Codec = Codec.new
+  AN_Codec.encoder = lambda{|str|
+    raise ISO8583Exception.new("Invalid value: #{str} must be [A-Za-y0-9]") unless str =~ /^[A-Za-z0-9]*$/
+    str
+  }
+  AN_Codec.decoder = PASS_THROUGH_DECODER
+
+  ANP_Codec = Codec.new
+  ANP_Codec.encoder = lambda{|str|
+    raise ISO8583Exception.new("Invalid value: #{str} must be [A-Za-y0-9 ]") unless str =~ /^[A-Za-z0-9 ]*$/
+    str
+  }
+  ANP_Codec.decoder = PASS_THROUGH_DECODER
+
+  ANS_Codec = Codec.new
+  ANS_Codec.encoder = lambda{|str|
+    raise ISO8583Exception.new("Invalid value: #{str} must be [\x20-\x7E]") unless str =~ /^[\x20-\x7E]*$/
+    str
+  }
+  ANS_Codec.decoder = PASS_THROUGH_DECODER
+
+  Null_Codec = Codec.new
+  Null_Codec.encoder = lambda {|str|
+    str
+  }
+  Null_Codec.decoder = lambda {|str|
+    str.gsub(/\000*$/, '')
+  } 
+
+  Track2 = Codec.new
+  Track2.encoder = lambda{|track2|
+    #SS | PAN | FS | Expiration Date | Service Code | Discretionary Data | ES | LRC
+    # SS = ;
+    # PAN = up to 19 digits (at least 9?)
+    # FS = '='
+    # Exp Date = YYMM
+    # SC: 3 digits or =
+    # ES = ?
+    # lrc : 1byte
+    raise ISO8583Exception.new("Invalid Track2 data: #{track2}") unless track2 =~ /^;*(\d{9,19})=(.*)\?.$/
+    track2
+  }
+  Track2.decoder = PASS_THROUGH_DECODER
+
+  def self._date_codec(fmt) 
+    c = Codec.new
+    c.encoder = lambda {|date|
+      enc = case date
+            when Date, Time
+              date.strftime(fmt)
+            when String
+              begin
+                dt = DateTime.strptime(date, fmt)
+                dt.strftime(fmt)
+              rescue
+                raise ISO8583Exception.new("Invalid format encoding: #{date}, must be #{fmt}.")
+              end
+            else  
+              raise ISO8583Exception.new("Don't know how to encode: #{date.class} to a time.")
+            end
+      return enc
+    }
+    c.decoder = lambda {|str|
+      begin
+        DateTime.strptime(str, fmt)
+      rescue
+        raise ISO8583Exception.new("Invalid format decoding: #{str}, must be #{fmt}.")
+      end
+    }
+
+    c
+  end
+
+  MMDDhhmmssCodec   = _date_codec("%m%d%H%M%S")
+  YYMMDDhhmmssCodec = _date_codec("%y%m%d%H%M%S")
+  YYMMCodec         = _date_codec("%y%m")
+
+end