iso8583 0.1.0

data/AUTHORS

@@ -0,0 +1 @@
+Tim Becker (tim@kuriositaet.de)

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,44 @@
+
+= ISO 8583 Financial Messaging for Ruby 
+
+This package currently contains code for coding an decoding ISO 8583
+Financial Message.
+
+
+== Installing
+
+You can install the +hello+ package by executing:
+
+	gem install iso7816 -r
+
+alternatively, you can download +.tar.gz+ or +.zip+ archives from 
+Rubyforge[http://rubyforge.org/frs/?group_id=1791].
+
+== Source
+
+The source is most readily available on github[http://github.com/a2800276/8583/], 
+and there should usually be a more or less current version available
+in the Rubyforge SVN repository.
+
+
+== 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,131 @@
+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.0'
+LONG_DESC	= <<END_DESC
+	Ruby implementation of ISO 8583 financial messaging
+END_DESC
+RUBYFORGE_USER	='a2800276'
+
+# 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 = 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.author="Tim Becker"
+  s.email="tim.becker@kuriositaet.de"
+  s.homepage="http://iso8583.rubyforge.org/"
+
+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,79 @@
+# 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.
+
+
+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
+
+if __FILE__==$0
+mes = 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
+
+# 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+i 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]
+      return [bmp,rest]
+    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,173 @@
+# Copyright 2009 by Tim Becker (tim.becker@kuriostaet.de)
+# MIT License, for details, see the LICENSE file accompaning
+# this distribution
+
+require 'date'
+
+# 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
+    return decoder.call(raw)
+  end
+
+  # length is either a fixnum or a lenth encoder.
+  def encode value
+    return 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
+}
+
+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 _date_codec(fmt) 
+  c = Codec.new
+  c.encoder =  lambda {|date|
+    enc = case date
+        when Time
+        when DateTime
+          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|
+    dt =  begin
+            DateTime.strptime str, fmt
+          rescue
+            raise ISO8583Exception.new("Invalid format decoding: #{str}, must be MMDDhhmmss.")
+          end
+    return dt
+  }
+
+  return c
+end
+
+MMDDhhmmssCodec   = _date_codec("%m%d%H%M%S") 
+YYMMDDhhmmssCodec = _date_codec("%y%m%d%H%M%S")
+YYMMCodec = _date_codec("%y%m")
+
+