smartcard 0.4.1 → 0.4.2

data/CHANGELOG

@@ -1,3 +1,5 @@
+v0.4.2. GlobalPlatform applet instalation.
+
 v0.4.1. Workaround ATR resend bug in JCOP simulator 3.2.7.
 
 v0.4.0. High-level functionality for ISO7816 cards.

data/Manifest

@@ -1,5 +1,9 @@
 BUILD
 CHANGELOG
+LICENSE
+Manifest
+README
+Rakefile
 ext/smartcard_pcsc/extconf.rb
 ext/smartcard_pcsc/pcsc.h
 ext/smartcard_pcsc/pcsc_card.c
@@ -13,6 +17,10 @@ ext/smartcard_pcsc/pcsc_namespace.c
 ext/smartcard_pcsc/pcsc_reader_states.c
 ext/smartcard_pcsc/pcsc_surrogate_reader.h
 ext/smartcard_pcsc/pcsc_surrogate_wintypes.h
+lib/smartcard.rb
+lib/smartcard/gp/asn1_ber.rb
+lib/smartcard/gp/cap_loader.rb
+lib/smartcard/gp/des.rb
 lib/smartcard/gp/gp_card_mixin.rb
 lib/smartcard/iso/auto_configurator.rb
 lib/smartcard/iso/iso_card_mixin.rb
@@ -22,13 +30,12 @@ lib/smartcard/iso/jcop_remote_transport.rb
 lib/smartcard/iso/pcsc_transport.rb
 lib/smartcard/iso/transport.rb
 lib/smartcard/pcsc/pcsc_exception.rb
-lib/smartcard.rb
-LICENSE
-Manifest
-Rakefile
-README
-smartcard.gemspec
+test/gp/asn1_ber_test.rb
+test/gp/cap_loader_test.rb
+test/gp/des_test.rb
 test/gp/gp_card_mixin_test.rb
+test/gp/hello.apdu
+test/gp/hello.cap
 test/iso/auto_configurator_test.rb
 test/iso/iso_card_mixin_test.rb
 test/iso/jcop_remote_test.rb

data/Rakefile

@@ -10,13 +10,13 @@ Echoe.new('smartcard') do |p|
   p.summary = 'Interface with ISO 7816 smart cards.'
   p.url = 'http://www.costan.us/smartcard'
   
-  p.need_tar_gz = !Platform.windows?
-  p.need_zip = !Platform.windows?
+  p.need_tar_gz = !Gem.win_platform?
+  p.need_zip = !Gem.win_platform?
   p.clean_pattern += ['ext/**/*.manifest', 'ext/**/*_autogen.h']
   p.rdoc_pattern = /^(lib|bin|tasks|ext)|^BUILD|^README|^CHANGELOG|^TODO|^LICENSE|^COPYING$/
   
   p.eval = proc do |p|
-    if Platform.windows?
+    if Gem.win_platform?
       p.files += ['lib/smartcard/pcsc.so']
       p.platform = Gem::Platform::CURRENT
 

data/lib/smartcard.rb

@@ -12,4 +12,7 @@ require 'smartcard/iso/transport.rb'
 require 'smartcard/iso/auto_configurator.rb'
 
 
+require 'smartcard/gp/asn1_ber.rb'
+require 'smartcard/gp/cap_loader.rb'
+require 'smartcard/gp/des.rb'
 require 'smartcard/gp/gp_card_mixin.rb'

data/lib/smartcard/gp/asn1_ber.rb

@@ -0,0 +1,199 @@
+# Encoding and decoding of ASN.1-BER data.
+#
+# Author:: Victor Costan
+# Copyright:: Copyright (C) 2009 Massachusetts Institute of Technology
+# License:: MIT
+
+# :nodoc: namespace
+module Smartcard::Gp
+  
+
+# Logic for encoding and decoding ASN.1-BER data as specified in X.690-0207.
+module Asn1Ber
+  # Decodes a TLV tag (the data type).
+  #
+  # Args:
+  #   data:: the array to decode from
+  #   offset:: the position of the first byte containing the tag 
+  #
+  # Returns the offset of the first byte after the tag, and the tag information.
+  # Tag information is a hash with the following keys.
+  #   :class:: the tag's class (symbol, named after X690-0207)
+  #   :primitive:: if +false+, the tag's value is a sequence of TLVs
+  #   :number:: the tag's number
+  def self.decode_tag(data, offset)
+    class_bits = data[offset] >> 6 
+    tag_class = [:universal, :application, :context, :private][class_bits]
+    tag_primitive = (data[offset] & 0x20) == 0
+    tag_number = (data[offset] & 0x1F)
+    if tag_number == 0x1F
+      tag_number = 0
+      loop do      
+        offset += 1
+        tag_number <<= 7
+        tag_number |= (data[offset] & 0x7F)
+        break if (data[offset] & 0x80) == 0
+      end
+    end
+    return (offset + 1), { :class => tag_class, :primitive => tag_primitive,
+                           :number => tag_number }
+  end
+
+  # Decodes a TLV length.
+  #
+  # Args:
+  #   data:: the array to decode from
+  #   offset:: the position of the first byte containing the length
+  #
+  # Returns the offset of the first byte after the length, and the length. The
+  # returned value might be +:indefinite+ if the encoding uses the indefinite
+  # length.
+  def self.decode_length(data, offset)
+    return (offset + 1), data[offset] if (data[offset] & 0x80) == 0
+    len_bytes = (data[offset] & 0x7F)
+    return (offset + 1), :indefinite if len_bytes == 0
+    length = 0
+    len_bytes.times do
+      offset += 1
+      length = (length << 8) | data[offset]
+    end
+    return (offset + 1), length
+  end
+  
+  
+  # Decodes a TLV value.
+  #
+  # Args:
+  #   data:: the array to decode from
+  #   offset:: the position of the first byte containing the length
+  #
+  # Returns the offset of the first byte after the value, and the value.
+  def self.decode_value(data, offset, length)    
+    return offset + length, data[offset, length] unless length == :indefinite
+    
+    length = 0
+    loop do
+      raise 'Unterminated data' if offset + length + 2 > data.length
+      break if data[offset + length, 2] == [0, 0]
+      length += 1
+    end
+    return (offset + length + 2), data[offset, length]
+  end
+  
+  # Maps a TLV value with a known tag to a Ruby data type.
+  def self.map_value(value, tag)
+    # TODO(costan): map primitive types if necessary
+    value
+  end
+  
+  # Decodes a TLV (tag-length-value).
+  #
+  # Returns a hash that contains tag and value information. See decode_tag for
+  # the keys containing the tag information. Value information is contained in
+  # the :value: tag.
+  def self.decode_tlv(data, offset)
+    offset, tag = decode_tag data, offset
+    offset, length = decode_length data, offset
+    offset, value = decode_value data, offset, length
+    
+    tag[:value] = tag[:primitive] ? map_value(value, tag) : decode(value)
+    return offset, tag
+  end
+  
+  # Decodes a sequence of TLVs (tag-length-value).
+  #
+  # Returns an array with one element for each TLV in the sequence. See
+  # decode_tlv for the format of each array element.
+  def self.decode(data, offset = 0, length = data.length - offset)
+    sequence = []
+    loop do
+      break if offset >= length
+      offset, tlv = decode_tlv data, offset
+      sequence << tlv
+    end
+    sequence
+  end
+  
+  # Encodes a TLV tag (the data type).
+  #
+  # Args:
+  #   tag:: a hash with the keys produced by decode_tag.
+  #
+  # Returns an array of byte values.
+  def self.encode_tag(tag)
+    tag_classes = { :universal => 0, :application => 1, :context => 2,
+                    :private => 3 } 
+    tag_lead = (tag_classes[tag[:class]] << 6) | (tag[:primitive] ? 0x00 : 0x20)
+    return [tag_lead | tag[:number]] if tag[:number] < 0x1F
+    
+    number_bytes, number = [], tag[:number]
+    first = true
+    while number != 0
+      byte = (number & 0x7F)
+      number >>= 7
+      byte |= 0x80 unless first
+      first = false
+      number_bytes << byte
+    end
+    [tag_lead | 0x1F] + number_bytes.reverse
+  end
+  
+  # Encodes a TLV length (the length of the data).
+  #
+  # Args::
+  #   length:: the length to be encoded (number of :indefinite)
+  #
+  # Returns an array of byte values.
+  def self.encode_length(length)
+    return [0x80] if length == :indefinite
+    return [length] if length < 0x80
+    length_bytes = []
+    while length > 0
+      length_bytes << (length & 0xFF)
+      length >>= 8
+    end
+    [0x80 | length_bytes.length] + length_bytes.reverse
+  end
+  
+  # Encodes a TLV (tag-length-value).
+  #
+  # Args::
+  #   tlv:: hash with tag and value information, to be encoeded as TLV; see
+  #         decode_tlv for the hash keys encoding the tag and value
+  #
+  # Returns an array of byte values.
+  def self.encode_tlv(tlv)
+    value = tlv[:primitive] ? tlv[:value] : encode(tlv[:value])
+    [encode_tag(tlv), encode_length(value.length), value].flatten
+  end
+  
+  # Encodes a sequence of TLVs (tag-length-value).
+  #
+  # Args::
+  #   tlvs:: an array of hashes to be encoded as TLV
+  #
+  # Returns an array of byte values.
+  def self.encode(tlvs)
+    tlvs.map { |tlv| encode_tlv tlv }.flatten
+  end
+  
+  # Visitor pattern for decoded TLVs.
+  #
+  # Args:
+  #   tlvs:: the TLVs to visit
+  #   tag_path:: internal, do not use
+  #
+  # Yields: |tag_path, value| tag_path lists the numeric tags for the current
+  # value's tag, and all the parents' tags.
+  def self.visit(tlvs, tag_path = [], &block)
+    tlvs.each do |tlv|
+      tag_number = encode_tag(tlv).inject { |acc, v| (acc << 8) | v }
+      new_tag_path = tag_path + [tag_number]
+      yield new_tag_path, tlv[:value]
+      next if tlv[:primitive]
+      visit tlv[:value], new_tag_path, &block
+    end
+  end
+end  # module Smartcard::Gp::Asn1Ber
+  
+end  # namespace

data/lib/smartcard/gp/cap_loader.rb

@@ -0,0 +1,88 @@
+# Loads JavaCard CAP files.
+#
+# Author:: Victor Costan
+# Copyright:: Copyright (C) 2009 Massachusetts Institute of Technology
+# License:: MIT
+
+require 'zip/zip'
+
+# :nodoc: namespace
+module Smartcard::Gp
+
+
+# Logic for loading JavaCard CAP files.
+module CapLoader
+  # Loads a CAP file.
+  #
+  # Returns a hash mapping component names to component data.
+  def self.load_cap(cap_file)
+    components = {}    
+    Zip::ZipFile.open(cap_file) do |file|
+      file.each do |entry|
+        data = entry.get_input_stream { |io| io.read }
+        offset = 0
+        while offset < data.length          
+          tag = TAG_NAMES[data[offset, 1].unpack('C').first]
+          length = data[offset + 1, 2].unpack('n').first
+          value = data[offset + 3, length]
+          components[tag] = value
+          offset += 3 + length
+        end
+      end
+    end    
+    components
+  end
+  
+  # Serializes CAP components for on-card loading.
+  #
+  # Returns an array of bytes.
+  def self.serialize_components(components)
+    [:header, :directory, :import, :applet, :class, :method, :static_field,
+     :export, :constant_pool, :reference_location].map { |name|
+      tag = TAG_NAMES.keys.find { |k| TAG_NAMES[k] == name }
+      if components[name]
+        length = [components[name].length].pack('n').unpack('C*')
+        data = components[name].unpack('C*')
+        [tag, length, data]
+      else
+        []
+      end
+    }.flatten
+  end
+  
+  # Parses the Applet section in a CAP file, obtaining applet AIDs.
+  #
+  # Returns an array of hashes, one hash per applet. The hash has a key +:aid+
+  # that contains the applet's AID.
+  def self.parse_applets(components)    
+    applets = []
+    return applets unless section = components[:applet]
+    offset = 1
+    section[0].times do
+      aid_length = section[offset]
+      install_method = section[offset + 1 + aid_length, 2].unpack('n').first
+      applets << { :aid => section[offset + 1, aid_length].unpack('C*'),
+                   :install_method => install_method }
+      offset += 3 + aid_length
+    end
+    applets
+  end
+  
+  # Loads a CAP file and serializes its components for on-card loading.
+  #
+  # Returns an array of bytes.
+  def self.cap_load_data(cap_file)
+    components = load_cap cap_file
+    { :data => serialize_components(components),
+      :applets => parse_applets(components) } 
+  end
+    
+  # Maps numeric tags to tag names.
+  TAG_NAMES = {
+    1 => :header, 2 => :directory, 3 => :applet, 4 => :import,
+    5 => :constant_pool, 6 => :class, 7 => :method, 8 => :static_field,
+    9 => :reference_location, 10 => :export, 11 => :descriptor, 12 => :debug
+  }
+end  # module Smartcard::Gp::CapLoader
+
+end  # namespace

data/lib/smartcard/gp/des.rb

@@ -0,0 +1,68 @@
+# DES and 3DES encryption and MAC logic for GlobalPlatform secure channels.
+#
+# Author:: Victor Costan
+# Copyright:: Copyright (C) 2009 Massachusetts Institute of Technology
+# License:: MIT
+
+require 'openssl'
+
+# :nodoc: namespace
+module Smartcard::Gp
+  
+
+# DES and 3DES encryption and MAC logic for GlobalPlatform secure channels.
+module Des
+  # Generates random bytes for session nonces.
+  #
+  # Args:
+  #   bytes:: how many bytes are desired
+  #
+  # Returns a string of random bytes.
+  def self.random_bytes(bytes)
+    OpenSSL::Random.random_bytes bytes
+  end
+
+  # Perform DES or 3DES encryption.
+  #
+  # Args:
+  #   key:: the encryption key to be used (8-byte or 16-byte)
+  #   data:: the data to be encrypted or decrypted
+  #   iv:: initialization vector
+  #   decrypt:: if +false+ performs encryption, otherwise performs decryption
+  #
+  # Returns the encrypted / decrypted data.
+  def self.crypt(key, data, iv = nil, decrypt = false)
+    cipher_name = key.length == 8 ? 'DES-CBC' : 'DES-EDE-CBC'
+    cipher = OpenSSL::Cipher::Cipher.new cipher_name
+    decrypt ? cipher.decrypt : cipher.encrypt
+    cipher.key = key
+    cipher.iv = iv || ("\x00" * 8)
+    cipher.padding = 0
+    crypted = cipher.update data
+    crypted += cipher.final
+    crypted
+  end
+  
+  # Computes a MAC using DES mixed with 3DES. 
+  def self.mac_retail(key, data, iv = nil)
+    # Output transformation: add 80, then 00 until it's block-sized.
+    data = data + "\x80"
+    data += "\x00" * (8 - data.length % 8) unless data.length % 8 == 0
+
+    # DES-encrypt everything except for the last block.
+    iv = crypt(key[0, 8], data[0, data.length - 8], iv)[-8, 8]
+    # Take the chained block and supply it to a 3DES-encryption. 
+    crypt(key, data[-8, 8], iv)
+  end
+  
+  def self.mac_3des(key, data)
+    # Output transformation: add 80, then 00 until it's block-sized.
+    data = data + "\x80"
+    data += "\x00" * (8 - data.length % 8) unless data.length % 8 == 0
+    
+    # The MAC is the last block from 3DES-encrypting the data.
+    crypt(key, data)[-8, 8]
+  end
+end  # module Smartcard::Gp::Des
+
+end  # namespace

data/lib/smartcard/gp/gp_card_mixin.rb

@@ -4,24 +4,383 @@
 # Copyright:: Copyright (C) 2009 Massachusetts Institute of Technology
 # License:: MIT
 
+require 'set'
+
 # :nodoc: namespace
 module Smartcard::Gp
 
 
+# Module intended to be mixed into transport implementations to add commands for
+# talking to GlobalPlatform smart-cards.
+#
+# The module talks to the card exclusively via methods in
+# Smartcard::Iso::IsoCardMixin, so the transport requirements are the same as
+# for that module.
 module GpCardMixin
   include Smartcard::Iso::IsoCardMixin
   
   # Selects a GlobalPlatform application.
   def select_application(app_id)
-    iso_apdu! :ins => 0xA4, :p1 => 0x04, :p2 => 0x00, :data => app_id
+    ber_data = iso_apdu! :ins => 0xA4, :p1 => 0x04, :p2 => 0x00, :data => app_id
+    app_tags = Asn1Ber.decode ber_data
+    app_data = {}
+    Asn1Ber.visit app_tags do |path, value|
+      case path
+      when [0x6F, 0xA5, 0x9F65]
+        app_data[:max_apdu_length] = value.inject(0) { |acc, v| (acc << 8) | v }
+      when [0x6F, 0x84]
+        app_data[:aid] = value
+      end
+    end
+    app_data
+  end
+  
+  # The default application ID of the GlobalPlatform card manager. 
+  def gp_card_manager_aid
+    [0xA0, 0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00]
+  end
+  
+  # Issues a GlobalPlatform INITIALIZE UPDATE command.
+  #
+  # This should not be called directly. Call secure_session insteaad.
+  #
+  # Args:
+  #   host_challenge:: 8-byte array with a unique challenge for the session
+  #   key_version:: the key in the Security domain to be used (0 = any key)
+  #
+  # Returns a hash containing the command's parsed response. The keys are:
+  #   :key_diversification:: key diversification data
+  #   :key_version:: the key in the Security domain chosen to be used
+  #   :protocol_id:: numeric ID for the secure protocol to be used
+  #   :counter:: counter for creating session keys
+  #   :challenge:: the card's 6-byte challenge
+  #   :auth:: the card's 8-byte authentication value
+  def gp_setup_secure_channel(host_challenge, key_version = 0)
+    raw = iso_apdu! :cla => 0x80, :ins => 0x50, :p1 => key_version, :p2 => 0,
+                    :data => host_challenge
+    response = {
+      :key_diversification => raw[0, 10],
+      :key_version => raw[10], :protocol_id => raw[11],
+      :counter => raw[12, 2].pack('C*').unpack('n').first,
+      :challenge => raw[14, 6], :auth => raw[20, 8]
+    }
+  end
+  
+  # Wrapper around iso_apdu! that adds a MAC to the APDU.
+  def gp_signed_apdu!(apdu_data)    
+    apdu_data = apdu_data.dup
+    apdu_data[:cla] = (apdu_data[:cla] || 0) | 0x04
+    apdu_data[:data] = (apdu_data[:data] || []) + [0, 0, 0, 0, 0, 0, 0, 0]
+    
+    apdu_bytes = Smartcard::Iso::IsoCardMixin.serialize_apdu(apdu_data)[0...-9]
+    mac = Des.mac_retail @gp_secure_channel_keys[:cmac], apdu_bytes.pack('C*'),
+                         @gp_secure_channel_keys[:mac_iv]
+    @gp_secure_channel_keys[:mac_iv] = mac
+    
+    apdu_data[:data][apdu_data[:data].length - 8, 8] = mac.unpack('C*')
+    iso_apdu! apdu_data
+  end
+    
+  # Issues a GlobalPlatform EXTERNAL AUTHENTICATE command.
+  #
+  # This should not be called directly. Call secure_session insteaad.
+  #
+  # Args:
+  #   host_auth:: 8-byte host authentication value
+  #   security:: array of desired security flags (leave empty for the default
+  #              of no security)
+  #
+  # The return value is irrelevant. The card will fire an ISO exception if the 
+  # authentication doesn't work out.
+  def gp_lock_secure_channel(host_auth, security = [])
+    security_level = 0
+    security_flags = { :command_mac => 0x01, :response_mac => 0x10,
+                       :command_encryption => 0x02 }
+    security.each do |flag|
+      security_level |= security_flags[flag]
+    end
+    gp_signed_apdu! :cla => 0x80, :ins => 0x82, :p1 => security_level, :p2 => 0,
+                    :data => host_auth
+  end
+  
+  # Sets up a secure session with the current GlobalPlatform application.
+  #
+  # Args:
+  #   keys:: hash containing 3 3DES encryption keys, identified by the following
+  #          keys:
+  #            :senc:: channel encryption key
+  #            :smac:: channel MAC key
+  #            :dek:: data encryption key
+  def secure_channel(keys = gp_development_keys)
+    host_challenge = Des.random_bytes 8
+    card_info = gp_setup_secure_channel host_challenge.unpack('C*')
+    card_counter = [card_info[:counter]].pack('n')
+    card_challenge = card_info[:challenge].pack('C*')
+
+    # Compute session keys.
+    session_keys = {}
+    derivation_data = "\x01\x01" + card_counter + "\x00" * 12
+    session_keys[:cmac] = Des.crypt keys[:smac], derivation_data    
+    derivation_data[0, 2] = "\x01\x02"
+    session_keys[:rmac] = Des.crypt keys[:smac], derivation_data
+    derivation_data[0, 2] = "\x01\x82"
+    session_keys[:senc] = Des.crypt keys[:senc], derivation_data
+    derivation_data[0, 2] = "\x01\x81"
+    session_keys[:dek] = Des.crypt keys[:dek], derivation_data
+    session_keys[:mac_iv] = "\x00" * 8
+    @gp_secure_channel_keys = session_keys
+        
+    # Compute authentication cryptograms.
+    card_auth = Des.mac_3des session_keys[:senc],
+        host_challenge + card_counter + card_challenge
+    host_auth = Des.mac_3des session_keys[:senc],
+        card_counter + card_challenge + host_challenge
+        
+    unless card_auth == card_info[:auth].pack('C*')
+      raise 'Card authentication invalid' 
+    end    
+
+    gp_lock_secure_channel host_auth.unpack('C*')
+  end
+  
+  # Secure channel keys for development GlobalPlatform cards.
+  #
+  # Most importantly, the JCOP cards and simulator work with these keys.
+  def gp_development_keys
+    key = (0x40..0x4F).to_a.pack('C*')
+    { :senc => key, :smac => key, :dek => key }
+  end
+  
+  # Issues a GlobalPlatform GET STATUS command.
+  #
+  # Args:
+  #   scope:: the information to be retrieved from the card, can be:
+  #     :issuer_sd:: the issuer's security domain
+  #     :apps:: applications and supplementary security domains
+  #     :files:: executable load files
+  #     :files_modules:: executable load files and executable modules
+  #   query_aid:: the AID to look for (empty array to get everything)
+  #
+  # Returns an array of application information data. Each element represents an
+  # application, and is a hash with the following keys:
+  #   :aid:: the application or file's AID
+  #   :lifecycle:: the state in the application's lifecycle (symbol)
+  #   :permissions:: a Set of the application's permissions (symbols)
+  #   :modules:: array of modules in an executable load file, each array element
+  #              is a hash with the key :aid which has the module's AID
+  def gp_get_status(scope, query_aid = [])
+    scope_byte = { :issuer_sd => 0x80, :apps => 0x40, :files => 0x20,
+                   :files_modules => 0x10 }[scope]
+    data = Asn1Ber.encode [{:class => :application, :primitive => true,
+                            :number => 0x0F, :value => query_aid}]
+    apps = []    
+    first = true  # Set to false after the first GET STATUS is issued.
+    loop do
+      raw = iso_apdu :cla => 0x80, :ins => 0xF2, :p1 => scope_byte,
+                     :p2 => (first ? 0 : 1), :data => [0x4F, 0x00]
+      if raw[:status] != 0x9000 && raw[:status] != 0x6310 
+        Smartcard::Iso::IsoCardMixin.raise_response_exception raw
+      end
+      
+      offset = 0
+      loop do
+        break if offset >= raw[:data].length
+        aid_length, offset = raw[:data][offset], offset + 1
+        app = { :aid => raw[:data][offset, aid_length] }
+        offset += aid_length
+        
+        if scope == :issuer_sd
+          lc_states = { 1 => :op_ready, 7 => :initialized, 0x0F => :secured,
+                        0x7F => :card_locked, 0xFF => :terminated }
+          lc_mask = 0xFF
+        else
+          lc_states = { 1 => :loaded, 3 => :installed, 7 => :selectable,
+              0x83 => :locked, 0x87 => :locked }
+          lc_mask = 0x87
+        end
+        app[:lifecycle] = lc_states[raw[:data][offset] & lc_mask]
+
+        permission_bits = raw[:data][offset + 1]
+        app[:permissions] = Set.new()
+        [[1, :mandated_dap], [2, :cvm_management], [4, :card_reset],
+         [8, :card_terminate], [0x10, :card_lock], [0x80, :security_domain],
+         [0xA0, :delegate], [0xC0, :dap_verification]].each do |mask, perm|
+          app[:permissions] << perm if (permission_bits & mask) == mask
+        end
+        offset += 2
+        
+        if scope == :files_modules
+          num_modules, offset = raw[:data][offset], offset + 1
+          app[:modules] = []
+          num_modules.times do
+            aid_length = raw[:data][offset]
+            app[:modules] << { :aid => raw[:data][offset + 1, aid_length] }
+            offset += 1 + aid_length            
+          end
+        end
+        
+        apps << app
+      end
+      break if raw[:status] == 0x9000
+      first = false  # Need more GET STATUS commands.
+    end
+    apps
+  end
+  
+  # The GlobalPlatform applications available on the card.
+  def applications
+    select_application gp_card_manager_aid
+    secure_channel
+    gp_get_status :apps
+    
+    # TODO(costan): there should be a way to query the AIDs without asking the
+    #               SD, which requires admin keys.
+  end
+  
+  # Issues a GlobalPlatform DELETE command targeting an executable load file.
+  #
+  # Args:
+  #   aid:: the executable load file's AID
+  #
+  # The return value is irrelevant. 
+  def gp_delete_file(aid)
+    data = Asn1Ber.encode [{:class => :application, :primitive => true,
+                            :number => 0x0F, :value => aid}]
+    response = iso_apdu! :cla => 0x80, :ins => 0xE4, :p1 => 0x00, :p2 => 0x80,
+                         :data => data
+    delete_confirmation = response[1, response[0]]
+    delete_confirmation
+  end
+  
+  # Deletes a GlobalPlatform application.
+  #
+  # Returns +false+ if the application was not found on the card, or a true
+  # value if the application was deleted.
+  def delete_application(application_aid)
+    select_application gp_card_manager_aid
+    secure_channel
+    
+    files = gp_get_status :files_modules
+    app_file_aid = nil
+    files.each do |file|
+      next unless modules = file[:modules]
+      next unless modules.any? { |m| m[:aid] == application_aid }
+      gp_delete_file file[:aid]
+      app_file_aid = file[:aid]
+    end    
+    app_file_aid
+  end
+  
+  # Issues a GlobalPlatform INSTALL command that loads an application's file.
+  #
+  # The command should be followed by a LOAD command (see gp_load).
+  #
+  # Args:
+  #   file_aid:: the AID of the file to be loaded
+  #   sd_aid:: the AID of the security domain handling the loading
+  #   data_hash:: 
+  #   params:: 
+  #   token:: load token (needed by some SDs)
+  #
+  # Returns a true value if the command returns a valid install confirmation.
+  def gp_install_load(file_aid, sd_aid = nil, data_hash = [], params = {},
+                      token = [])
+    ber_params = []
+                      
+    data = [file_aid.length, file_aid, sd_aid.length, sd_aid,
+            Asn1Ber.encode_length(data_hash.length), data_hash,
+            Asn1Ber.encode_length(ber_params.length), ber_params,
+            Asn1Ber.encode_length(token.length), token].flatten
+    response = iso_apdu! :cla => 0x80, :ins => 0xE6, :p1 => 0x02, :p2 => 0x00,
+                         :data => data
+    response == [0x00]
+  end
+  
+  # Issues a GlobalPlatform INSTALL command that installs an application and
+  # makes it selectable.
+  #
+  # Args:
+  #   file_aid:: the AID of the application's executable load file
+  #   module_aid:: the AID of the application's module in the load file
+  #   app_aid:: the application's AID (application will be selectable by it)
+  #   privileges:: array of application privileges (e.g. :security_domain)
+  #   params:: application install parameters
+  #   token:: install token (needed by some SDs)
+  #
+  # Returns a true value if the command returns a valid install confirmation.
+  def gp_install_selectable(file_aid, module_aid, app_aid, privileges = [],
+                            params = {}, token = [])
+    privilege_byte = 0
+    privilege_bits = { :mandated_dap => 1, :cvm_management => 2,
+        :card_reset => 4, :card_terminate => 8, :card_lock => 0x10,
+        :security_domain => 0x80, :delegate => 0xA0, :dap_verification => 0xC0 }
+    privileges.each { |privilege| privilege_byte |= privilege_bits[privilege] }
+    
+    param_tags = [{:class => :private, :primitive => true, :number => 9,
+                   :value => params[:app] || []}]
+    ber_params = Asn1Ber.encode(param_tags)
+    
+    data = [file_aid.length, file_aid, module_aid.length, module_aid,
+            app_aid.length, app_aid, 1, privilege_byte,
+            Asn1Ber.encode_length(ber_params.length), ber_params,
+            Asn1Ber.encode_length(token.length), token].flatten
+    response = iso_apdu! :cla => 0x80, :ins => 0xE6, :p1 => 0x0C, :p2 => 0x00,
+                         :data => data
+    response == [0x00]
+  end
+    
+  # Issues a GlobalPlatform LOAD command.
+  #
+  # Args:
+  #   file_data:: the file's data
+  #   max_apdu_length:: the maximum APDU length, returned from
+  #                     select_application
+  #
+  # Returns a true value if the loading succeeds. 
+  def gp_load_file(file_data, max_apdu_length)
+    data_tag = { :class => :private, :primitive => true, :number => 4,
+                 :value => file_data }
+    ber_data = Asn1Ber.encode [data_tag]
+    
+    max_data_length = max_apdu_length - 5
+    offset = 0
+    block_number = 0
+    loop do
+      block_length = [max_data_length, ber_data.length - offset].min
+      last_block = (offset + block_length >= ber_data.length)
+      response = iso_apdu! :cla => 0x80, :ins => 0xE8,
+                           :p1 => (last_block ? 0x80 : 0x00),
+                           :p2 => block_number,
+                           :data => ber_data[offset, block_length]
+      offset += block_length
+      block_number += 1
+      break if last_block
+    end
+    true
   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?"
+  # Args:
+  #   cap_file:: path to the applet's CAP file
+  #   package_aid:: the applet's package AID
+  #   applet_aid:: the AID used to select the applet; if nil, the first AID
+  #                in the CAP's Applet section is used (this works pretty well)
+  #   install_data:: data to be passed to the applet at installation time
+  def install_applet(cap_file, package_aid, applet_aid = nil, install_data = [])
+    load_data = CapLoader.cap_load_data(cap_file)
+    applet_aid ||= load_data[:applets].first[:aid]
+
+    delete_application applet_aid
+    
+    manager_data = select_application gp_card_manager_aid
+    max_apdu = manager_data[:max_apdu_length]
+    secure_channel
+        
+    gp_install_load package_aid, gp_card_manager_aid
+    gp_load_file load_data[:data], max_apdu
+    gp_install_selectable package_aid, applet_aid, applet_aid, [],
+                          { :app => install_data }    
   end
 end  # module GpCardMixin