tem_ruby 0.9.2 → 0.10.0

data/lib/tem/lifecycle.rb

@@ -1,8 +1,8 @@
 module Tem::Lifecycle
   def activate
-    issue_apdu([0x00, 0x10, 0x00, 0x00, 0x00])[0] == 0x90 
+    @transport.applet_apdu(:ins => 0x10)[:status] == 0x9000
   end
   def kill
-    issue_apdu([0x00, 0x11, 0x00, 0x00, 0x00])[0] == 0x90 
+    @transport.applet_apdu(:ins => 0x11)[:status] == 0x9000
   end
 end

data/lib/tem/seclosures.rb

@@ -14,8 +14,7 @@ module Tem::SeClosures
   
   def sec_trace
     #begin      
-      response = issue_apdu [0x00, 0x54, 0x00, 0x00, 0x00].flatten
-      trace = reply_data(response)
+      trace = @transport.applet_apdu! :ins => 0x54
       if trace.length > 2
         case read_tem_short(trace, 0) # trace version
         when 1
@@ -32,22 +31,20 @@ module Tem::SeClosures
   def solve_psfault
     # TODO: better strategy, lol
     next_cell = rand(16)
-    response = issue_apdu [0x00, 0x53, to_tem_ushort(next_cell), 0x00].flatten
-    tem_error(response) if failure_code(response)    
+    @transport.applet_apdu! :ins => 0x53, :p12 => to_tem_ushort(next_cell)
   end
   
   def execute(secpack, key_id = 0)
     # load SECpack
     buffer_id = post_buffer(secpack.tem_formatted_body)
-    response = issue_apdu [0x00, 0x50, to_tem_byte(buffer_id), to_tem_byte(key_id), 0x00].flatten
-    tem_error(response) if failure_code(response)
+    response = @transport.applet_apdu! :ins => 0x50, :p1 => buffer_id,
+                                                     :p2 => key_id
     tem_secpack_error(response) if read_tem_byte(response, 0) != 1
     
     # execute SEC
     sec_exception = nil
     loop do 
-      response = issue_apdu [0x00, 0x52, 0x00, 0x00, 0x00].flatten
-      tem_error(response) if failure_code(response)
+      response = @transport.applet_apdu! :ins => 0x52
       sec_status = read_tem_byte(response, 0)
       case sec_status
       when 2 # success
@@ -67,15 +64,14 @@ module Tem::SeClosures
       end
     end
   
-    # TODO: handle response to figure out if we need to do page faults or something
-    
     # unbind SEC
-    response = issue_apdu [0x00, 0x51, 0x00, 0x00, 0x00].flatten
+    response = @transport.applet_apdu! :ins => 0x51
     raise sec_exception if sec_exception
-    buffer_id, buffer_length = read_tem_byte(response, 0), read_tem_short(response, 1)
+    buffer_id = read_tem_byte(response, 0)
+    buffer_length = read_tem_short(response, 1)
     data_buffer = read_buffer buffer_id
     release_buffer buffer_id
     
     return data_buffer[0...buffer_length]
   end
-end
+end

data/lib/tem/tag.rb

@@ -1,28 +1,33 @@
 module Tem::Tag
-  def set_tag(tag_data)
-    buffer_id = post_buffer(tag_data)
-    response = issue_apdu [0x00, 0x30, to_tem_byte(buffer_id), 0x00, 0x00].flatten
-    tem_error(response) if failure_code(response)
-    release_buffer(buffer_id)
+  def set_tag(tag_data)    
+    buffer_id = post_buffer tag_data
+    begin
+      @transport.applet_apdu! :ins => 0x30, :p1 => buffer_id
+    ensure
+      release_buffer buffer_id
+    end
   end
   
   def get_tag_length
-    response = issue_apdu [0x00, 0x31, 0x00, 0x00, 0x00].flatten
-    tem_error(response) if failure_code(response)
+    response = @transport.applet_apdu! :ins => 0x31
     return read_tem_short(response, 0)
   end
   
   def get_tag_data(offset, length)
-    buffer_id = alloc_buffer(length)
-    response = issue_apdu [0x00, 0x32, to_tem_byte(buffer_id), 0x00, 0x04, to_tem_short(offset), to_tem_short(length)].flatten
-    tem_error(response) if failure_code(response)
-    tag_data = read_buffer(buffer_id)
-    release_buffer(buffer_id)
-    return tag_data
+    buffer_id = alloc_buffer length
+    begin
+      @transport.applet_apdu! :ins => 0x32, :p1 => buffer_id,
+                              :data => [to_tem_short(offset),
+                                        to_tem_short(length)].flatten
+      tag_data = read_buffer buffer_id
+    ensure
+      release_buffer buffer_id
+    end
+    tag_data
   end
 
   def get_tag
     tag_length = self.get_tag_length
-    get_tag_data(0, tag_length)
+    get_tag_data 0, tag_length
   end
 end

data/lib/tem/tem.rb

@@ -1,5 +1,3 @@
-require 'pp'
-
 class Tem::Session
   include Tem::Abi
   include Tem::Buffers
@@ -12,33 +10,19 @@ class Tem::Session
   include Tem::Tag
   include Tem::Toolkit
   
-  @@aid = [0x19, 0x83, 0x12, 0x29, 0x10, 0xBA, 0xBE]
+  CAPPLET_AID = [0x19, 0x83, 0x12, 0x29, 0x10, 0xBA, 0xBE]
   
-  def initialize(javacard)
-    @card = javacard
-    @card.select_applet(@@aid)
-  end
+  attr_reader :transport
   
-  def disconnect
-    # TODO: deselect applet, reset card
-    @card = nil
+  def initialize(transport)
+    @transport = transport
+    @transport.select_applet CAPPLET_AID
   end
   
-  def issue_apdu(apdu)
-    @card.issue_apdu apdu
-  end
-  
-  def failure_code(reply_apdu)
-    @card.failure_code reply_apdu
-  end
-  
-  def reply_data(reply_apdu)
-    @card.reply_data reply_apdu
-  end
-  
-  def tem_error(response)
-    fcode = failure_code response
-    raise "TEM returned error 0x#{'%04x' % fcode} while processing the request"
+  def disconnect
+    return unless @transport
+    @transport.disconnect
+    @transport = nil
   end
   
   def tem_secpack_error(response)

data/lib/tem/transport/auto_configurator.rb

@@ -0,0 +1,87 @@
+# :nodoc: namespace
+module Tem::Transport
+
+# Automatic configuration code. 
+module AutoConfigurator  
+  # The name of the environment variable that might supply the transport
+  # configuration.
+  ENVIRONMENT_VARIABLE_NAME = 'TEM_PORT'
+  
+  # The default configurations to be tried if no configuration is specified.
+  DEFAULT_CONFIGURATIONS = [
+    { :class => JcopRemoteTransport,
+      :opts => { :host => '127.0.0.1', :port => 8050} },
+    { :class => PcscTransport, :opts => { :reader_index => 0 }}
+  ]
+
+  # Creates a transport based on available configuration information.
+  def self.auto_transport
+    configuration = env_configuration
+    return try_transport(configuration) if configuration
+    
+    DEFAULT_CONFIGURATIONS.each do |config|
+      transport = try_transport(config)
+      return transport if transport
+    end
+    return nil
+  end
+
+  # Retrieves transport configuration information from an environment variable.
+  #
+  # :call-seq:
+  #   AutoConfigurator.env_configuration -> hash
+  #
+  # The returned configuration has the keys required by
+  # AutoConfigurator#try_transport
+  def self.env_configuration
+    return nil unless conf = ENV[ENVIRONMENT_VARIABLE_NAME]
+    
+    case conf[0]
+    when ?:
+      # :8050 -- JCOP emulator at port 8050
+      transport_class = JcopRemoteTransport
+      transport_opts = { :host => '127.0.0.1' }
+      transport_opts[:port] = conf[1..-1].to_i
+    when ?@
+      # @127.0.0.1:8050 -- JCOP emulator at host 127.0.0.1 port 8050
+      transport_class = JcopRemoteTransport
+      port_index = conf.rindex(?:) || conf.length
+      transport_opts = { :host => conf[1...port_index] }
+      transport_opts[:port] = conf[(port_index + 1)..-1].to_i
+    when ?#
+      # #2 -- 2nd PC/SC reader in the system
+      transport_class = PcscTransport
+      transport_opts = { :reader_index => conf[1..-1].to_i - 1 }
+    else
+      # Reader Name -- the PC/SC reader with the given name
+      transport_class = PcscTransport
+      transport_opts = { :reader_name => conf }
+    end
+    
+    transport_opts[:port] = 8050 if transport_opts[:port] == 0
+    if transport_opts[:reader_index] and transport_opts[:reader_index] < 0
+      transport_opts[:reader_index] = 0
+    end
+    { :class => transport_class, :opts => transport_opts }
+  end
+  
+  # Attempts to create a new TEM transport with the given configuration.
+  # :call-seq:
+  #   AutoConfigurator.try_transport(configuration) -> Transport or nil
+  #
+  # The configuration should have the following keys:
+  #   class:: the Ruby class implementing the transport
+  #   opts:: the options to be passed to the implementation's constructor
+  def self.try_transport(configuration)
+    raise 'No transport class specified' unless configuration[:class]
+    begin
+      transport = configuration[:class].new(configuration[:opts] || {})
+      transport.connect
+      return transport
+    rescue Exception
+      return nil
+    end
+  end
+end  # module AutoConfigurator
+
+end  # module Tem::Transport

data/lib/tem/transport/java_card_mixin.rb

@@ -0,0 +1,99 @@
+# :nodoc: namespace
+module Tem::Transport
+  
+# Module intended to be mixed into transport implementations to mediate between
+# a high level format for Javacard-specific APDUs and the wire-level APDU 
+# request and response formats.
+#
+# The mix-in calls exchange_apdu in the transport implementation. It supplies
+# the APDU data as an array of integers between 0 and 255, and expects a
+# response in the same format.
+module JavaCardMixin
+  # Selects a Javacard applet.
+  def select_applet(applet_id)
+    applet_apdu! :ins => 0xA4, :p1 => 0x04, :p2 => 0x00, :data => applet_id
+  end
+  
+  # APDU exchange with the JavaCard applet, raising an exception if the return
+  # code is not success (0x9000).
+  #
+  # :call_seq:
+  #   transport.applet_apdu!(apdu_data) -> array
+  #
+  # The apdu_data should be in the format expected by
+  # JavaCardMixin#serialize_apdu. Returns the response data, if the response
+  # status indicates success (0x9000). Otherwise, raises an exeception.
+  def applet_apdu!(apdu_data)
+    response = self.applet_apdu apdu_data
+    return response[:data] if response[:status] == 0x9000
+    raise "JavaCard response has error status 0x#{'%04x' % response[:status]}"
+  end
+
+  # Performs an APDU exchange with the JavaCard applet.
+  #
+  # :call-seq:
+  #   transport.applet_apdu(apdu_data) -> hash
+  #
+  # The apdu_data should be in the format expected by
+  # JavaCardMixin#serialize_apdu. The response will be as specified in
+  # JavaCardMixin#deserialize_response.
+  def applet_apdu(apdu_data)
+    apdu = Tem::Transport::JavaCardMixin.serialize_apdu apdu_data
+    response = self.exchange_apdu apdu
+    JavaCardMixin.deserialize_response response
+  end
+  
+  # Serializes an APDU for wire transmission.
+  #
+  # :call-seq:
+  #   transport.wire_apdu(apdu_data) -> array
+  #
+  # The following keys are recognized in the APDU hash:
+  #   cla:: the CLA byte in the APDU (optional, defaults to 0) 
+  #   ins:: the INS byte in the APDU -- the first byte seen by a JavaCard applet
+  #   p:: 
+  #   p1, p2:: the P1 and P2 bytes in the APDU (optional, both default to 0)
+  #   data:: the extra data in the APDU (optional, defaults to nothing)
+  def self.serialize_apdu(apdu_data)
+    raise 'Unspecified INS in apdu_data' unless apdu_data[:ins]
+    apdu = [ apdu_data[:cla] || 0, apdu_data[:ins] ]
+    if apdu_data[:p12]
+      unless apdu_data[:p12].length == 2
+        raise "Malformed P1,P2 - #{apdu_data[:p12]}"
+      end
+      apdu += apdu_data[:p12]
+    else
+      apdu << (apdu_data[:p1] || 0)
+      apdu << (apdu_data[:p2] || 0)
+    end
+    if apdu_data[:data]
+      apdu << apdu_data[:data].length
+      apdu += apdu_data[:data]
+    else
+      apdu << 0
+    end
+    apdu
+  end
+  
+  # De-serializes a JavaCard response APDU.
+  # 
+  # :call-seq:
+  #   transport.deserialize_response(response) -> hash
+  #
+  # The response contains the following keys:
+  #   status:: the 2-byte status code (e.g. 0x9000 is OK)
+  #   data:: the additional data in the response
+  def self.deserialize_response(response)
+    { :status => response[-2] * 256 + response[-1], :data => response[0...-2] }
+  end
+  
+  # Installs a JavaCard applet on the JavaCard.
+  #
+  # This would be really, really nice to have. Sadly, it's a far away TBD right
+  # now.
+  def install_applet(cap_contents)
+    raise "Not implemeted; it'd be nice though, right?"
+  end
+end  # module Tem
+
+end  # module Tem::Transport

data/lib/tem/transport/jcop_remote_protocol.rb

@@ -0,0 +1,51 @@
+# :nodoc: namespace
+module Tem::Transport
+  
+# Mixin implementing the JCOP simulator protocol.
+#
+# The (pretty informal) protocol specification is contained in the JavaDocs for
+# the class com.ibm.jc.terminal.RemoteJCTerminal and should be easy to find by
+# http://www.google.com/search?q=%22com.ibm.jc.terminal.RemoteJCTerminal%22  
+module JcopRemoteProtocol
+  # Encodes and sends a JCOP simulator message to a TCP socket.
+  #
+  # The message must contain the following keys:
+  #   type:: Integer expressing the message type (e.g. 1 = APDU exchange)
+  #   node:: Integer expressing the node address (e.g. 0 for most purposes)
+  #   data:: message payload, as an array of Integers ranging from 0 to 255
+  def send_message(socket, message)
+    raw_message = [message[:type], message[:node], message[:data].length].
+                  pack('CCn') + message[:data].pack('C*')
+    socket.send raw_message, 0
+  end
+  
+  # Reads and decodes a JCOP simulator message from a TCP socket.
+  # 
+  # :call_seq:
+  #   client.read_message(socket) -> Hash or nil
+  #
+  # If the other side of the TCP socket closes the connection, this method
+  # returns nil. Otherwise, a Hash is returned, with the format required by the
+  # JcopRemoteProtocol#send_message.
+  def recv_message(socket)
+    header = ''
+    while header.length < 4
+      partial = socket.recv 4 - header.length
+      return false if partial.length == 0
+      header += partial
+    end
+    message_type, node_address, data_length = *header.unpack('CCn')
+    raw_data = ''
+    while raw_data.length < data_length
+      partial = socket.recv data_length - raw_data.length
+      return false if partial.length == 0
+      raw_data += partial
+    end
+    
+    return false unless raw_data.length == data_length
+    data = raw_data.unpack('C*')
+    return { :type => message_type, :node => node_address, :data => data }
+  end
+end  # module JcopRemoteProtocol
+
+end  # namespace Tem::Transport

data/lib/tem/transport/jcop_remote_server.rb

@@ -0,0 +1,171 @@
+require 'socket'
+
+# :nodoc: namespace
+module Tem::Transport
+  
+# Stubs out the methods that can be implemented by the serving logic in a
+# JCOP remote server. Serving logic classes should mix in this module, to
+# avoid having unimplemented methods.
+module JcopRemoteServingStubs
+  # Called when a client connection accepted.
+  #
+  # This method serves as a notification to the serving logic implementation.
+  # Its return value is discarded.
+  def connection_start
+    nil
+  end
+  
+  # Called when a client connection is closed.
+  #
+  # This method serves as a notification to the serving logic implementation.
+  # Its return value is discarded.
+  def connection_end
+    nil
+  end
+  
+  # Serving logic handling an APDU exchange.
+  #
+  # :call-seq:
+  #   logic.exchange_apdu(apdu) -> array
+  #
+  # The |apdu| parameter is the request APDU, formatted as an array of
+  # integers between 0 and 255. The method should return the response APDU,
+  # formatted in a similar manner.  
+  def exchange_apdu(apdu)
+    # Dumb implementation that always returns OK.
+    [0x90, 0x00]
+  end
+end  # module JcopRemoteServingStubs
+    
+
+# A server for the JCOP simulator protocol.
+#
+# The JCOP simulator protocol is generally useful when talking to a real JCOP
+# simulator. This server is only handy for testing, and for forwarding
+# connections (JCOP's Eclipse plug-in makes the simulator listen to 127.0.0.1,
+# and sometimes you want to use it from another box).
+class JcopRemoteServer
+  include JcopRemoteProtocol  
+  
+  # Creates a new JCOP server.
+  #
+  # The options hash supports the following keys:
+  #   port:: the port to serve on
+  #   ip:: the IP of the interface to serve on (defaults to all interfaces)
+  #   reusable:: if set, the serving port can be shared with another
+  #              application (REUSEADDR flag will be set on the socket)
+  #
+  # If the |serving_logic| parameter is nil, a serving logic implementation
+  # must be provided when calling JcopRemoteServer#run. The server will crash
+  # otherwise.
+  def initialize(options, serving_logic = nil)
+    @logic = serving_logic
+    @running = false
+    @options = options
+    @mutex = Mutex.new
+  end
+  
+  # Runs the serving loop indefinitely.
+  #
+  # This method serves incoming conenctions until #stop is called.
+  #
+  # If |serving_logic| contains a non-nil value, it overrides any previously
+  # specified serving logic implementation. If no implementation is specified
+  # when the server is instantiated via JcopRemoteServer#new, one must be
+  # passed into |serving_logic|.
+  def run(serving_logic = nil)
+    @mutex.synchronize do
+      @logic ||= serving_logic
+      @serving_socket = serving_socket @options
+      @running = true
+    end
+    loop do
+      break unless @mutex.synchronize { @running }
+      begin
+        client_socket, client_address = @serving_socket.accept
+      rescue
+        # An exception will occur if the socket is closed
+        break
+      end
+      @logic.connection_start
+      loop do        
+        break unless @mutex.synchronize { @running }
+        break unless process_request client_socket
+      end
+      client_socket.close rescue nil
+      @logic.connection_end  # implemented by subclass
+    end
+    @mutex.synchronize do
+      @serving_socket.close if @serving_socket
+      @serving_socket = nil
+    end
+  end
+
+  # Stops the serving loop.
+  def stop
+    @mutex.synchronize do
+      if @running
+        @serving_socket.close rescue nil
+        @serving_socket = nil
+        @running = false
+      end
+    end
+    
+    # TODO(costan): figure out a way to let serving logic reach this directly.
+  end
+  
+  
+  # Creates a socket listening to incoming connections to this server.
+  # 
+  # :call-seq:
+  #   server.establish_socket(options) -> Socket
+  #
+  # The |options| parameter supports the same keys as the options parameter
+  # of JcopRemoteServer#new.
+  #
+  # Returns a Socket configured to accept incoming connections. 
+  def serving_socket(options)
+    port = options[:port] || 0
+    interface_ip = options[:ip] || '0.0.0.0'
+    serving_address = Socket.pack_sockaddr_in port, interface_ip
+    
+    socket = Socket.new Socket::AF_INET, Socket::SOCK_STREAM,
+                        Socket::PF_UNSPEC
+    
+    if options[:reusable]
+      socket.setsockopt Socket::SOL_SOCKET, Socket::SO_REUSEADDR, true
+    end
+    socket.setsockopt Socket::IPPROTO_TCP, Socket::TCP_NODELAY, true      
+    socket.bind serving_address
+    socket.listen 5
+    socket
+  end
+  private :serving_socket
+
+  # Performs a request/response cycle.
+  #
+  # :call-seq:
+  #   server.process_request(socket) -> Boolean
+  #
+  # Returns true if the server should do another request/response cycle, or
+  # false if this client indicated it's done talking to the server.
+  def process_request(socket)
+    return false unless request = recv_message(socket)
+    
+    case request[:type]
+    when 0
+      # Wait for card; no-op, because that should have happen when the client
+      # connected.
+      send_message socket, :type => 0, :node => 0, :data => [3, 1, 4, 1, 5, 9]
+    when 1
+      # ATR exchange; the class' bread and butter
+      response = @logic.exchange_apdu request[:data]
+      send_message socket, :type => 1, :node => 0, :data => response
+    else
+      send_message socket, :type => request[:type], :node => 0, :data => []
+    end
+  end
+  private :process_request    
+end  # module JcopRemoteServer
+
+end  # namespace Tem::Transport

data/lib/tem/transport/jcop_remote_transport.rb

@@ -0,0 +1,65 @@
+require 'socket'
+
+# :nodoc: namespace
+module Tem::Transport
+  
+# Implements the transport layer for a JCOP simulator instance.
+class JcopRemoteTransport
+  include JavaCardMixin
+  include JcopRemoteProtocol
+  
+  # Creates a new unconnected transport for a JCOP simulator serving TCP/IP.
+  #
+  # The options parameter must have the following keys:
+  #   host:: the DNS name or IP of the host running the JCOP simulator
+  #   port:: the TCP/IP port of the JCOP simulator server
+  def initialize(options)
+    @host, @port = options[:host], options[:port]
+    @socket = nil
+  end
+  
+  # 
+  def exchange_apdu(apdu)
+    send_message @socket, :type => 1, :node => 0, :data => apdu
+    recv_message(@socket)[:data]
+  end  
+
+  # Makes a transport-level connection to the TEM.
+  def connect
+    begin
+      Socket.getaddrinfo(@host, @port, Socket::AF_INET,
+                         Socket::SOCK_STREAM).each do |addr_info|
+        begin
+          @socket = Socket.new(addr_info[4], addr_info[5], addr_info[6])
+          @socket.connect Socket.pack_sockaddr_in(addr_info[1], addr_info[3])
+          break
+        rescue
+          @socket = nil
+        end
+      end  
+      raise 'Connection refused' unless @socket
+      
+      # Wait for the card to be inserted.
+      send_message @socket, :type => 0, :node => 0, :data => [0, 1, 0, 0]
+      recv_message @socket  # ATR should come here, but who cares      
+    rescue Exception
+      @socket = nil
+      raise
+    end
+  end
+
+  # Breaks down the transport-level connection to the TEM.
+  def disconnect
+    if @socket
+      @socket.close
+      @socket = nil
+    end
+  end
+  
+  def to_s
+    "#<JCOP Remote Terminal: disconnected>" if @socket.nil?
+    "#<JCOP Remote Terminal: #{@host}:#{@port}>"
+  end  
+end  # class JcopRemoteTransport 
+
+end  # module Tem::Transport