passvault 0.1.2

data/lib/conn_constants.rb

@@ -0,0 +1,116 @@
+# Uncommented constants are DESFire comments.
+class Connection
+  # This file holds the constants used for data transmission and commands.
+  #
+  # In another language, we would have spread the constants accross multiple
+  # classes (for the card, chip and reader constants) and then imported those
+  # constants. But in Ruby doing so might cause the constants to silently
+  # collide. Putting them in the same class enables warnings in case of constant
+  # redefinition.
+
+  # ============================================================================
+  # DESFire (card) related constants
+  # ============================================================================
+
+  # fixed fields values
+
+  # CLA field for DESFire commands.
+  CARD_CLA = 0x90
+
+  # SW1 field for DESFire answers.
+  SW1 = 0x91
+
+  # Hash from DESFire response codes name (symbols) to the codes (integers).
+  STATUS = {
+      :OPERATION_OK                 => 0x00,
+      :ADDITIONAL_FRAME             => 0xAF,
+      :NO_CHANGES                   => 0x0C,
+      :ILLEGAL_COMMAND_CODE         => 0x1C,
+      :INTEGRITY_ERROR              => 0x1E,
+      :NO_SUCH_KEY                  => 0x40,
+      :LENGTH_ERROR                 => 0x7E,
+      :PERMISSION_DENIED            => 0x9D,
+      :PARAMETER_ERROR              => 0x9E,
+      :APPLICATION_NOT_FOUND        => 0xA0,
+      :APPLICATION_INTEGRITY_ERROR  => 0xA1,
+      :AUTHENTICATION_ERROR         => 0xAE,
+      :BOUNDARY_ERROR               => 0xBE,
+      :COMMAND_ABORTED              => 0xCA,
+      :DUPLICATE_ERROR              => 0xDE,
+      :FILE_NOT_FOUND               => 0xF0,
+      :OUT_OF_EEPROM_ERROR          => 0x0E,
+  }
+
+  CHANGE_KEY              = 0xC4
+  CREATE_APPLICATION      = 0xCA
+  CREATE_STD_DATA_FILE    = 0xCD
+  GET_CIPHERED_NONCE      = 0x0A
+  SELECT_APPLICATION      = 0x5A
+  SEND_MORE_DATA          = 0xAF
+  FORMAT_PICC             = 0xFC
+  GET_APP_IDS             = 0x6A
+  GET_FILE_IDS            = 0x6F
+  DELETE_APP              = 0xDA
+  DELETE_FILE             = 0xDF
+  READ_DATA               = 0xBD
+  WRITE_DATA              = 0x3D
+  GET_KEY_SETTINGS        = 0x45
+  GET_FILE_SETTINGS       = 0xF5
+  GET_VERSION             = 0x60
+  CHANGE_KEY_SETTINGS     = 0x54
+
+  # Padding beginning marker when reading a whole file with encrypted
+  # communication.
+  WHOLE_FILE_PAD_MARKER = "\x80"
+
+  # ============================================================================
+  # PN532 (chip) related constants
+  # ============================================================================
+
+  # Communication direction: send data to the chip.
+  TO_CHIP             = 0xD4
+
+  # Communicaiton direction: receive data from the chip.
+  FROM_CHIP           = 0xD5
+
+  # PN532 command: poll for tags.
+  LIST_PASSIVE_TARGET = 0x4A
+
+  # PN532 command: send data to/from the chip.
+  DATA_EXCHANGE       = 0x40
+
+  # PN532 response code (prefix).
+  LIST_RESPONSE       = 0x4B
+
+  # PN532 data response codes (array) (prefix).
+  DATA_RESPONSE       = [0x41, 0x00]
+
+  # PN532 success response codes (array) (suffix).
+  SUCCESS_SUFFIX      = [0x90, 0x00]
+
+  # ============================================================================
+  # ACR112 (reader) releated constants
+  # ============================================================================
+
+  # ACR112: class field for pseudo-APDU commands.
+  READER_CLA        = 0xFF
+
+  # ACR112 pseudo-APDU commands: send data.
+  DIRECT_TRANSMIT   = 0x00
+
+  # ACR112 pseudo-APDU commands: retrieve an answer.
+  GET_RESPONSE      = 0xC0
+
+  # ACR112 response code (SW1 field).
+  SUCCESS           = 0x61
+
+  # ACR112 response code (SW1 field).
+  ERROR             = 0x63
+
+  # ACR112 response codes (SW2 field for SW1=ERROR).
+  OPERATION_FAILED  = 0x00
+
+  # ACR112 response codes (SW2 field for SW1=ERROR).
+  NO_ANSWER         = 0x01
+
+end

data/lib/conn_init.rb

@@ -0,0 +1,92 @@
+class Connection
+  # This files contains logic related to the initialization and termination of the
+  # connection.
+
+  # Connect to a card trough a reader.
+  def initialize()
+    super({}) # no options
+
+    @context = PCSC::Context.new
+
+    # find readers
+    begin
+      reader_names = @context.readers
+    rescue Exception => e
+      puts "No smartcard readers were detected."
+      disconnect
+      exit
+    end
+
+    # select a single reader
+    if reader_names.length == 1
+      @reader_name = reader_names.first
+    else
+      puts "Multiple readers available, please select one by number."
+      @reader_name = nil
+      while @reader_name == nil
+        reader_names.each_with_index do |r,i|
+          puts "#{i}) #{r.strip}"
+        end
+        begin
+          @reader_name = reader_names[gets.strip.to_i]
+        rescue
+          puts "Invalid selection."
+        end
+      end
+    end
+
+    # The following two lines are lifted from the supermethod, since they were
+    # the only thing of interest there, due to idiosyncraties of the ACR122.
+
+    # The card object is used to transmit data, tough we don't need to use it
+    # directly, as data transmission is wrapped by the exchange_apdu(apdu)
+    # function.
+
+    @card = @context.card(@reader_name, :shared)
+
+    # the Answer To Reset for the card
+    @atr = @card.info[:atr]
+
+    # Wait until a card is inserted in the reader. Normally the super() call
+    # takes care of this, but the ACR122 is a broken beast which always
+    # indicates that a card is present, even if it isn't the case.
+
+    msg_displayed = false
+    while true
+      begin
+        poll
+        break
+      rescue Smartcard::PCSC::Exception => e
+        status = e.pcsc_status_code
+        if status == Smartcard::PCSC::FFILib::Status[:comm_data_lost]
+          puts "No cards detected, please insert your card." if !msg_displayed
+          msg_displayed = true
+        else
+          puts "error: #{e.message}"
+          disconnect
+          exit
+        end
+      end
+    end
+  end
+
+  # Search for a card. This succeeds if a card is detected, else it throws a
+  # <tt>Smartcard::PCSC::Exception</tt> with +pcsc_status_code+ field set to the
+  # <tt>:comm_data_lost</tt> status after some time.
+  def poll(max_tags = 1, baud = 0)
+    response = send_chip_cmd LIST_PASSIVE_TARGET, [max_tags, baud]
+    throw :protocol_error unless response[0] == LIST_RESPONSE
+  end
+
+  # Release all resources associated with the card.
+  def disconnect
+    # :unpower is necessary if we want to relaunch the program without unpluging
+    # the reader.
+    unless @card.nil?
+      @card.disconnect(:unpower)
+      @card = nil
+    end
+    super
+  end
+
+end

data/lib/conn_transmit.rb

@@ -0,0 +1,96 @@
+require_relative 'crypto'
+
+class Connection
+  # This file holds the implementation of the communication logic between the
+  # computer and the card. There are three "hardware" levels we need to go
+  # trought in order to send data to the card: the reader, the chip and the card
+  # itself. However the whole picture is a little more complex and looks like
+  # this:
+  #
+  # +---------------------------------------------------------------+
+  # | card_cmd -> card_apdu -> chip_cmd -> chip_apdu -> reader_apdu |
+  # +---------------------------------------------------------------+
+  #
+  # To each of the arrows in the diagram above correspond a method named
+  # send_<thing_before_the_arrow>. The function transforms the thing before the
+  # arrow into the thing after the arrow and passes it along the
+  # chain. Afterwards it gets a response for the thing after the arrow and
+  # transforms it into a response for the thing before the arrow, which is then
+  # returned.
+  #
+  # Transforming the responses usually consists of stripping some response codes
+  # from the output.
+
+  include Crypto
+
+  # Thrown when the contact with the card is lost.
+  CARD_CONTACT_LOST_ERROR =
+    'Contact with the tag was lost, please verify that the card is in the ' \
+    'reader, then relaunch the application.'
+
+  # Send a chip APDU trough the reader (by wrapping the chip APDU inside a
+  # reader pseudo-APDU) and return the chip response. This takes care of the
+  # reader response codes.
+  def send_chip_apdu(chip_apdu)
+    nbytes = chip_apdu.length
+    pseudo_apdu = [READER_CLA, DIRECT_TRANSMIT, 0x00, 0x00, nbytes, *chip_apdu]
+    reader_response = exchange_apdu(pseudo_apdu)
+
+    # check the reader response
+    case reader_response[0]
+    when ERROR
+      throw :operation_failed   if reader_response[1] == OPERATION_FAILED
+      throw :no_answer          if reader_response[1] == NO_ANSWER
+      throw :unknown_error
+    when SUCCESS
+      # fetch the actual card/chip response
+      fetch_len = reader_response[1]
+      pseudo_apdu = [READER_CLA, GET_RESPONSE, 0x00, 0x00, fetch_len]
+      exchange_apdu(pseudo_apdu)
+    else
+      throw :protocol_error
+    end
+  end
+
+  # Send a chip command and return the command response (not comprising the chip
+  # response codes).
+  #
+  # There are two useful commands: +DATA_EXCHANGE+ (used in send_car_apdu()) and
+  # +LIST_PASSIVE_TARGET+ (used by <tt>poll()</tt>).
+  def send_chip_cmd(cmd, args)
+    chip_apdu = [TO_CHIP, cmd, *args]
+    response = send_chip_apdu(chip_apdu)
+    len = response.length
+    throw :protocol_error unless
+      response[0]            == FROM_CHIP &&
+      response[len-2..len-1] == SUCCESS_SUFFIX
+    return response[1..len-3]
+  end
+
+  # Send a card APDU to the card and return the card's answer. This takes care
+  # of chip command DATA_EXCHANGE return codes.
+  def send_card_apdu(card_apdu, tag_no=1)
+    response = send_chip_cmd(DATA_EXCHANGE, [tag_no, *card_apdu])
+    raise CARD_CONTACT_LOST_ERROR unless response[0..1] == DATA_RESPONSE
+    return response[2..response.length-1]
+  end
+
+  # Send a command to the card and return an array whose first element is the
+  # command response (not comprising the card response codes) and the second is
+  # a successful status (needed to know if additional frames are available).
+  def send_card_cmd(cmd, args=[])
+    apdu = args.length == 0 \
+        ? [CARD_CLA, cmd, 0x00, 0x00, 0x00]
+        : [CARD_CLA, cmd, 0x00, 0x00, args.length, *args, 0x00]
+    response = send_card_apdu(apdu)
+    len = response.length
+    throw :protocol_error unless response[len-2] == SW1
+    status = response[len-1]
+    throw STATUS.key(status), true unless
+      status == STATUS[:OPERATION_OK]       ||
+      status == STATUS[:ADDITIONAL_FRAME]
+
+    return [len < 3 ? [] : response[0..len-3], status]
+  end
+
+end

data/lib/connection.rb

@@ -0,0 +1,28 @@
+require 'smartcard'
+
+# An instance of the class Connection represents a connection to a DESFire tag
+# trough an ACR122 reader outfitted with PN532 chip. In our passworld vault
+# program there is only one instance of this class.
+#
+# The class extends the class Smartcard::Iso::PcscTransport from which it
+# inherits most notably the method <tt>exchange_apdu(apdu)</tt> which is used to
+# send APDUs (Application Protocol Data Unit) to the reader.
+#
+# We found out that object-oriented decomposition didn't work well to model the
+# mechanisms of data transmission to the card, as it is more functional in
+# nature. We elected to model inside this single class. To improve readability,
+# the class is split inside multiple files that cover different concerns. The
+# files are described below in the <tt>connection.rb</tt> file.
+class Connection < Smartcard::Iso::PcscTransport ; end
+
+# Initialization and termination of the connection.
+require_relative 'conn_init'
+
+# Constants used for data transmission and commands.
+require_relative 'conn_constants'
+
+# Tranmission of APDUs at various levels (reader, chip, card).
+require_relative 'conn_transmit'
+
+# Functions wrapping commands to be sent to the card.
+require_relative 'conn_cmds'

data/lib/console_ui.rb

@@ -0,0 +1,243 @@
+require 'clipboard'
+require 'highline/import'
+require 'smartcard'
+
+require_relative 'vault'
+
+class ConsoleUI
+
+  # Displayed when running the console program.
+  HEADER = "
+     _____                             _
+    |  _  |___ ___ ___ _ _ _ ___ ___ _| |
+    |   __| .'|_ -|_ -| | | | . |  _| . |
+    |__|  |__,|___|___|_____|___|_| |___|
+
+
+             _____         _ _
+            |  |  |___ _ _| | |_
+            |  |  | .'| | | |  _|
+             \\___/|__,|___|_|_|
+
+
+  (Type \"help\" to display available commands.)"
+
+  # Time after which the the console program forgets the vault master password
+  # and the associated key.
+  TIMEOUT = 300
+
+  # The console program entry point.
+  def self.run
+    ui = ConsoleUI.new()
+    ui.loop()
+  rescue Smartcard::PCSC::Exception => e
+    case e.pcsc_status
+    when :reader_unavailable
+      puts "\nThe reader was disconnected or is otherwise unavailable. " \
+        "You can't disconnect the card during the execution of the program, " \
+        "even if you reconnect it before executing a command."
+    else
+      puts "\n#{e.message()}"
+    end
+  rescue Exception => e
+    puts "\n#{e.message()}"
+  ensure
+    ui.leave() if ui
+  end
+
+  # Loop on user input (commands).
+  def loop
+    puts HEADER
+    @continue = true
+    while @continue
+      if catch :timeout do
+        command = request('> ')
+        execute(command.strip)
+        false
+      end then
+        @vault.deauthenticate()
+        puts 'The prompt timed out, please re-do the last command.'
+      end
+    end
+  end
+
+  # Exit the console program.
+  def leave
+    @vault.destroy()
+  end
+
+  private ######################################################################
+
+  # Initialize the UI by creating a new +Vault+ object.
+  def initialize
+    @vault = Vault.new()
+  end
+
+  # Display the help of the console program.
+  def help()
+    puts ''
+    puts '-- user commands --'
+    puts 'list            : list the names of registered credentials'
+    puts 'display <name>  : display a registered credential'
+    puts 'clip <name>     : same as "display", but copies the password'
+    puts '                   to the clipboard instead of displaying it'
+    puts 'add <name>      : register a new credential'
+    puts 'remove <name>   : remove a registered credential'
+    puts 'edit <name>     : change a registered credential'
+    puts 'quit            : exit the program'
+    puts 'help            : display this help message'
+    puts ''
+    puts '-- administration commands --'
+    puts 'reset           : reinitialize the vault'
+    puts 'erase           : erase the vault from the tag'
+    puts ''
+  end
+
+  # Ask the user for input, and throws <tt>:timeout</tt> (with value +true+) if
+  # the user is inactive for more than +TIMEOUT+ seconds.
+  def request(prompt, &block)
+    time = Time.now.to_i
+    answer = ask("\n#{prompt}", &block)
+    time = Time.now.to_i - time
+    throw :timeout, true if time > TIMEOUT
+    answer
+  end
+
+  # Prompt the user for a password. The password won't show on the screen (like
+  # in the Unix login prompt).
+  def enter_pass(prompt)
+    request(prompt) do |p| p.echo = false end
+  end
+
+  # Prompt for the tag's master password. Allows for a special case if the
+  # password is left empty.
+  def enter_tag_pass
+    master_prompt = 'Enter the tag master password (leave empty for default): '
+    pass = enter_pass(master_prompt)
+    pass = :default if pass == ""
+    return pass
+  end
+
+  # If not authenticated with the vault, prompt for the vault pass and perform
+  # the authentication.
+  def check_vault_pass
+    return true if @vault.authenticated?()
+    pass = enter_pass(
+      "Enter the vault master password \n" \
+      "(you will need to re-enter it after 5 minutes of inactivity): ")
+    @vault.authenticate(pass)
+    return true
+  rescue => e
+    return handle_auth_error(e)
+  end
+
+  # Re-raise the exception if it is not <tt>Vault::AUTHENTICATION_ERROR</tt>,
+  # else display the approrpiate message and return false.
+  def handle_auth_error(exception)
+    raise exception unless exception.message == Vault::AUTHENTICATION_ERROR
+    puts "\n#{exception.message}"
+    return false
+  end
+
+  # Execute a command entered by the user.
+  def execute(command)
+    # The regex will set $1 to the credential name.
+    name_regex = '(?<name>[[:graph:]]*)'
+    case command
+    when 'erase'                    ; erase()
+    when 'create', 'reset'          ; reset()
+    when 'help'                     ; help()
+    when 'quit'                     ; @continue = false
+    when 'list'                     ; list()
+    when /display #{name_regex}/    ; display($1)
+    when /clip #{name_regex}/       ; clip($1)
+    when /add #{name_regex}/        ; add($1)
+    when /remove #{name_regex}/     ; remove($1)
+    when /edit #{name_regex}/       ; edit($1)
+    else                            ; unknown(command)
+    end
+  rescue Exception => e
+    raise e unless e.message == Vault::UNKNOWN_NAME_ERROR
+    puts "\n#{e.message}"
+  end
+
+  # See <tt>help()</tt> for a description.
+  def erase()
+    tag_pass = enter_tag_pass()
+    @vault.erase(tag_pass)
+  rescue => e
+    return handle_auth_error(e)
+  end
+
+  # See <tt>help()</tt> for a description.
+  def reset()
+    tag_pass = enter_tag_pass()
+    return unless tag_pass
+    vault_pass = enter_pass('Enter the new vault pass: ')
+    @vault.reset(tag_pass, vault_pass)
+  rescue => e
+    return handle_auth_error(e)
+  end
+
+  # See <tt>help()</tt> for a description.
+  def list()
+    return unless check_vault_pass()
+    puts "\nList of available credentials:"
+    @vault.credentials_names().each { |name| puts "- #{name}" }
+  end
+
+  # See <tt>help()</tt> for a description.
+  def display(name)
+    return unless check_vault_pass()
+    login, pass = @vault.credential(name)
+    puts ""
+    puts "login: #{login}"
+    puts "pass:  #{pass}"
+  end
+
+  # See <tt>help()</tt> for a description.
+  def clip(name)
+    return unless check_vault_pass()
+    login, pass = @vault.credential(name)
+    puts ""
+    puts "login name: #{login}"
+    Clipboard.copy(pass)
+  end
+
+  # See <tt>help()</tt> for a description.
+  def add(name)
+    return unless check_vault_pass()
+    login = request('Enter a login: ')
+    pass = enter_pass('Enter a password: ')
+    @vault.add(name, login, pass)
+  rescue Vault::CredentialError => e
+    puts "\n#{e.message}"
+  end
+
+  # See <tt>help()</tt> for a description.
+  def remove(name)
+    return unless check_vault_pass()
+    @vault.remove(name)
+  end
+
+  # See <tt>help()</tt> for a description.
+  def edit(name)
+    return unless check_vault_pass()
+    login = request('Enter a login: ')
+    pass = enter_pass('Enter a new password: ')
+    @vault.edit(name, login, pass)
+  rescue Vault::CredentialError => e
+    puts "\n#{e.message}"
+  end
+
+  # Called when an unknown command is entered.
+  def unknown(command)
+    puts "\nUnknown command: #{command}"
+    puts 'Type "help" to display available commands.'
+  end
+end
+
+# # entry point
+# if __FILE__ == $PROGRAM_NAME
+#   ConsoleUI.run
+# end