passvault 0.1.2

data/lib/key_settings.rb

@@ -0,0 +1,124 @@
+module Rights
+
+# Used in communication settings in place of a key, to indicate that an
+# authentication with the key being changed should be performed in order to
+# change a key.
+CHANGED_KEY = 0xE
+
+# Used in communication settings in place of a key, to indicate that a key
+# cannot be changed.
+IMMUTABLE   = 0xF
+
+# The key settings determine the level of authentication needed to perform
+# operations on the tag (DESFire) top-level, or on an application.
+class KeySettings
+
+  # Is the application/tag master key modifiable? Takes values 0 or 1.
+  attr_reader :master_change
+
+  # Can the commands (+GetFileIDs+, +GetFileSettings+, +GetKeySettings+) /
+  # (+GetApplicationIDs+, +GetKeySettings+) be performed without application/tag
+  # master key authentication? Takes values 0 or 1.
+  attr_reader :auth_get
+
+  # Can files/applications be created or deleted / created without
+  # application/tag master key authentication? Takes values 0 or 1.
+  attr_reader :auth_create
+
+  # Can the key settings for this application/tag be changed again? Takes values
+  # 0 or 1.
+  attr_reader :settings_change
+
+  # Only defined for application keys settings. Defines the key needed to change
+  # application keys. It can be an application key number between 0x0 and 0xE
+  # (inclusive, 0x0 being the application master key) or one of the constants
+  # +CHANGED_KEY+ (authenticated with the key that will be changed) or
+  # +IMMUTABLE+ (keys cannot be changed) (constants defined in the +Rights+
+  # module). Takes a value +key+ such that (0x0 <= +key+ <= 0xF).
+  attr_reader :change_key
+
+  # The constructor takes a hash of parameters, which correspond to the class
+  # attributes.
+  def initialize(hash={})
+    @master_change = hash[:master_change] || 1
+    @auth_get = hash[:auth_get] || 1
+    @auth_create = hash[:auth_create] || 0
+    @settings_change = hash[:settings_change] || 1
+    @change_key = hash[:change_key] || 0x0
+  end
+
+  # Creates a +KeySettings+ object from a byte representing the key settings.
+  def self.from_byte(byte)
+    KeySettings.new(
+      :master_change    => (byte & 0x1) % 2,
+      :auth_get         => (byte & 0x2) % 2,
+      :auth_create      => (byte & 0x4) % 2,
+      :settings_change  => (byte & 0x8) % 2,
+      :change_key       => byte >> 4)
+  end
+
+  # Returns a byte representing the key settings, fit to be used as a
+  # command parameter.
+  def to_byte
+    1  * @master_change +
+    2  * @auth_get +
+    4  * @auth_create +
+    8  * @settings_change +
+    16 * @change_key
+  end
+
+  # Can key +changing_key+ of application +aid+ be changed by authenticating
+  # with key +change_key+?
+  def can_change_key?(aid, changing_key, change_key)
+    if aid == 0
+      changing_key == 0 && change_key == 0
+    elsif @change_key == IMMUTABLE
+      false
+    elsif @change_key == CHANGED_KEY
+      change_key == changing_key
+    elsif @change_key == changing_key
+      change_key == 0
+    else
+      change_key == @change_key
+    end
+  end
+
+  # Can we perform the application-level +GetFileIDs+, +GetFileSettings+ and
+  # +GetKeySettings+ commands if authenticated with the given key on the given
+  # application?
+  def can_get?(key_no)
+    @auth_get == 1 or key_no == 0
+  end
+
+  # Can we perform the top-level +GetApplicationIDs+ and
+  # +GetKeySettings+) commands if authenticated with the given key?
+  def can_get0?(aid, key_no)
+    aid == 0 and (@auth_get == 1 or key_no == 0)
+  end
+
+  # Can we create or delete a file if authenticated with the given key?
+  def can_edit_file?(key_no)
+    @auth_create == 1 or key_no == 0
+  end
+
+  # Can we create an application if authenticated with the given key on the
+  # given application?
+  def can_create_app?(aid, key_no)
+    aid == 0 and (@auth_create = 1 or key_no = 0)
+  end
+
+  # Can we delete an application if authenticated with the given key on the given
+  # application?
+  def can_delete_app?(aid, key_no)
+    aid == 0 and key_no == 0
+  end
+
+  # Can we change this key settings on the tag's currently selected application
+  # if authenticated with the given key?
+  def can_change_key_settings?(key_no)
+    @settings_change and key_no == 0
+  end
+
+end
+
+end

data/lib/rights.rb

@@ -0,0 +1,6 @@
+# This module contains classes that represent permission for various parts of
+# the applications.
+module Rights ; end
+
+require_relative 'file_access'
+require_relative 'key_settings'

data/lib/vault.rb

@@ -0,0 +1,357 @@
+require_relative 'connection'
+require_relative 'crypto'
+require_relative 'rights'
+
+# The Vault class represents a vault stored on a tag. It implements all
+# operations that can be performed on the vault.
+#
+# A vault stores credentials as <tt>[name, login, pass, hmac]</tt>
+# quadruplets. When we say "a credential" we refer to this quadruplet. The name
+# is ciphered with AES. The later three elements are ciphered together using
+# AES. The three first elements are padded with zeroes to attain their mandated
+# length (see constants). The HMAC is computed on unpadded (name || login ||
+# pass). The three keys are derives from the vault password using PKBDF2,
+# altough they use different salt. All the salt include the tag UID, and the
+# salt for the ciphering of the last three elements include the credential name.
+#
+# For a credential, 112 bytes of data are stored of memory. This is a multiple
+# of 8, so no padding is required in AES.
+#
+# When a vault object is initialized, it scans the tag to get a map from
+# credential names to the file where the credential is stored. It also builds
+# lists of unused applications ids and of unused file ids on existing
+# applications.
+class Vault
+  include Crypto
+  include Rights
+
+  # This is the default tag master key, and the initial key for new
+  # applications.
+  ZERO_KEY = Array.new(16, 0).pack('C*')
+
+  # These are the access rights we use when creating a new file.
+  FILE_RIGHTS = FileAccess.new(
+    read: 0, write: 0, rw: 0, change: 0, com_set: CS_CIPHERED)
+
+  # These are the key settings for the tag master key.
+  # This is set when creating the vault.
+  TAG_KEY_SETTINGS = KeySettings.new(change_key: 0x0,
+    master_change: 1, auth_get: 1, auth_create: 1, settings_change: 1)
+
+  # These are the key settings for new applications.
+  VAULT_KEY_SETTINGS = KeySettings.new(
+    master_change: 1, auth_get: 0, auth_create: 0, settings_change: 0)
+
+  # Number of files that a DESFire application can hold.
+  NB_FILES = 15
+
+  # The length of the name of a credential in the tag's memory. This is the
+  # maximum length for a name, and a padding of nul characters is added to reach
+  # this length if needed.
+  NAME_LEN  = 16
+
+  # The length of the login in a credential in the tag's memory. This is the
+  # maximum length for a login, and a padding of nul characters is added to
+  # reach this length if needed.
+  LOGIN_LEN = 32
+
+  # The length of the password in a credential in the tag's memory. This is the
+  # maximum length for a password, and a padding of nul characters is added to
+  # reach this length if needed.
+  PASS_LEN  = 32
+
+  # The total length on a credential in the tag's memory.
+  TOTAL_LEN = NAME_LEN + LOGIN_LEN + PASS_LEN + HMAC_LEN
+
+  # Raised if the tag contents changed while the program was running.
+  TAG_CHANGED_ERROR =
+    'Tag content changed while the program was running.'
+
+  # Raised if the tag memory becomes full.
+  TAG_FULL_ERROR =
+    'Tag full, remove some credentials to be able to add other.'
+
+  # Raised when we are supplied an unknown credential name.
+  UNKNOWN_NAME_ERROR =
+    'The credential name is unknown. Use "list" to view existing names.'
+
+  # Raised if we are supplied an incorrect vault or tag password.
+  AUTHENTICATION_ERROR =
+    'The supplied password is incorrect, please try again.'
+
+  # Raised if we detect that the tag memory has been tempered with.
+  TEMPER_ERROR =
+    'The card has been tempered with (invalid signature).'
+
+  # Text used for credential errors where the name is already used.
+  NAME_IN_USE_TEXT =
+    'Credential name already in use, choose another one.'
+
+  # Thrown when the user supplies an invalid credential (name, login or pass too
+  # long, or empty).
+  class CredentialError < StandardError ; end
+
+  public #######################################################################
+
+  # Erase the vault from the tag and restore it to a pristine state
+  # (memory wiped, tag master key set to +ZERO_KEY+).
+  def erase(tag_pass)
+    deauthenticate()
+    tag_key = derive_tag_key(tag_pass)
+    authentication { @conn.select_app_auth(0, tag_key) }
+    @conn.format()
+    @conn.change_key(0, tag_key, ZERO_KEY)
+  end
+
+  # Reset the vault: erases the tag and creates a new vault on it using the
+  # given vault master password.
+  def reset(tag_pass, vault_pass)
+    deauthenticate()
+    tag_key = derive_tag_key(tag_pass)
+    vault_key = derive_key(vault_pass, @uid, 16)
+    authentication { @conn.select_app_auth(0, tag_key) }
+    @conn.format()
+    @conn.change_key_settings(TAG_KEY_SETTINGS)
+    ensure_free_file([], [1], vault_key) # create application 1
+  end
+
+  # Returns a list of credentials names.
+  def credentials_names
+    return @locations.each_key()
+  end
+
+  # Returns the <tt>[login, pass]</tt> from the named credential.
+  def credential(name)
+    _ ,_ ,content = get_location(name)
+    triplet_aes = content.byteslice(NAME_LEN, LOGIN_LEN + PASS_LEN + HMAC_LEN)
+    triplet = aes_decipher(triplet_aes, derive_aes_key(name))
+
+    login = triplet.byteslice(0, LOGIN_LEN).tr("\x00", '')
+    pass  = triplet.byteslice(LOGIN_LEN, PASS_LEN).tr("\x00", '')
+    hmac  = triplet.byteslice(LOGIN_LEN + PASS_LEN, HMAC_LEN)
+
+    raise TEMPER_ERROR if hmac != hmac(name +  login + pass, derive_aes_key('hmac'))
+    return [login, pass]
+  end
+
+  # Adds a new credential to the vault.
+  def add(name, login, pass)
+    ensure_free_file(@free_files, @free_apps, @key)
+    aid, fid = @free_files.first
+    raise CredentialError.new(NAME_IN_USE_TEXT)  unless @locations[name] == nil
+    write_credentials(name, login, pass, aid, fid)
+    # Do this only after that potential exception have been thrown.
+    @locations[name] = @free_files.shift
+  end
+
+  # Replace the login and password for the named credential.
+  def edit(name, login, pass)
+    aid, fid = get_location(name)
+    write_credentials(name, login, pass, aid, fid)
+  end
+
+  # Remove the named credential from the vault.
+  def remove(name)
+    aid, fid, _ = get_location(name)
+    @free_files << [aid, fid]
+    @locations.delete(name)
+    @conn.select_app_auth(aid, @key)
+    # We do not remove the file, else the memory would be lost, instead
+    # we overwrite the previous credential with zeroes.
+    rand1 = Random.new(Random.new_seed).bytes(32)
+    rand2 = Random.new(Random.new_seed).bytes(32)
+    write_credentials('', rand1, rand2, aid, fid, true)
+  end
+
+  # Set the password and derive the key, then scans the card for available
+  # credentials (see <tt>scan()</tt>).
+  def authenticate(pass)
+    key = derive_desfire_key(pass, @uid)
+    authentication { @conn.select_app_auth(1, key) }
+    @pass = pass
+    @key  = key
+    @conn.select_app(0)
+    scan()
+  end
+
+  # Forget all that is known about the card password, key and content.
+  def deauthenticate
+    @pass = nil
+    @key = nil
+    unscan()
+  end
+
+  # Indicate if we know the key to access the card.
+  def authenticated?
+    return @pass != nil
+  end
+
+  # "Destroy" the +Vault+ object by releasing the connection to the tag. Leaves
+  # the object in an unusable state.
+  def destroy
+    deauthenticate()
+    @conn.disconnect
+  end
+
+  private ######################################################################
+
+  # Creates the +Vault+ object by establishing a connection to the tag,
+  # retrieving its UID, and setting some default values.
+  def initialize
+    @conn = Connection.new
+    @uid = @conn.get_uid().pack('C*')
+    @continue = true
+    @pass = nil
+    @key = nil
+  end
+
+  # Try to run some authentication code. In case of failure, catch the throwed
+  # symbol and convert it into an exception.
+  def authentication(&block)
+    raise AUTHENTICATION_ERROR if
+      catch(:AUTHENTICATION_ERROR) do
+        raise AUTHENTICATION_ERROR if
+          catch(:authentication_failed) { block.call() ; false }
+      end
+  end
+
+  # * Sets <tt>@locations</tt> to a map from credential names to <tt>[aid,
+  #   fid]</tt> pair.
+  #
+  # * Sets <tt>@free_files</tt> to a list of <tt>[aid, fid]</tt>
+  #   pairs representing unused files.
+  #
+  # * Sets <tt>@free_apps</tt> to a list of unused applications ids.
+  def scan
+    @locations = {}
+    @free_files = []
+    @free_apps = (1..28).to_a
+    @conn.get_app_ids().each do |aid|
+      @free_apps.delete(aid)
+      add_free_files(aid)
+    end
+  end
+
+  # Adds the free files in the application +aid+ to @free_files.
+  def add_free_files(aid)
+    @conn.select_app_auth(aid, @key)
+    @free_files += Array.new(NB_FILES, aid).zip(1..NB_FILES)
+    @conn.get_file_ids.each { |fid| check_free_file(aid, fid) }
+  end
+
+  # If the file <tt>[aid, fid]</tt> isn't free, remove it from the list of free
+  # files and update <tt>@locations</tt> according to the file's content.
+  def check_free_file(aid, fid)
+    content = @conn.read_whole_file(fid)
+    name = get_name(content)
+    if name != '' # if not an erased file
+      @free_files.delete([aid, fid])
+      @locations[name] = [aid, fid]
+    end
+  end
+
+  # Get the name of a credential from the stored credential.
+  def get_name(content)
+    name_ciphered = content.byteslice(0, NAME_LEN)
+    name_deciphered = aes_decipher(name_ciphered, derive_aes_key(''))
+    return name_deciphered.tr("\x00", '')
+  end
+
+  # Erases all informations registered by <tt>scan()</tt>.
+  def unscan
+    @locations = nil
+    @free_files = nil
+    @free_apps = nil
+  end
+
+  # Derives the tag master key from the tag password. The password may have the
+  # special value <tt>:default</tt>, in which case +ZERO_KEY+ is used.
+  def derive_tag_key(tag_pass)
+    return ZERO_KEY if tag_pass == :default
+    return derive_desfire_key(tag_pass, @uid)
+  end
+
+  # Returns the memory location where the named credential is stored and the
+  # encrypted credential stored there as an <tt>[aid, fid, content]</tt>
+  # array. Also authenticates ourselves with the returned aid, and ensures that
+  # the tag content did not change since we last scanned the tag.
+  def get_location(name)
+    raise UNKNOWN_NAME_ERROR if @locations[name] == nil
+    aid, fid = @locations[name]
+    @conn.select_app_auth(aid, @key)
+    content = @conn.read_whole_file(fid)
+    tag_name = get_name(content)
+    raise TAG_CHANGED_ERROR if name != tag_name
+    return [aid, fid, content]
+  end
+
+  # Derives the AES key used to store a credential from the credential name.
+  # The credential name is used as salt in addition to the tag's UID. The key is
+  # derived from the vault master password.
+  def derive_aes_key(name)
+    return derive_key(@pass, @uid + name, 32)
+  end
+
+  # Ensure there is an unused <tt>[aid, fid]</tt> pair in <tt>@free_files</tt>
+  # available to add a credential to the vault (this does not actually create
+  # the file, but might create an application). Note that this does *not* ensure
+  # that there is memory left on the vault, as this can only be detected by
+  # writing to the vault.
+  def ensure_free_file(free_files, free_apps, vault_key)
+    return unless free_files.empty?
+    raise TAG_FULL_ERROR if free_apps.empty?
+
+    new_app = free_apps.shift
+    @conn.select_app(0)
+    @conn.create_app(new_app, 1, VAULT_KEY_SETTINGS)
+    @conn.select_app_auth(new_app, ZERO_KEY)
+    @conn.change_key(0, ZERO_KEY, vault_key)
+    free_files += Array.new(NB_FILES, new_app).zip(1..NB_FILES)
+  end
+
+  # Write the supplied credential to the supplied location on the tag. This
+  # does not modify any class variable.
+  def write_credentials(name, login, pass, aid, fid, bypass_check=false)
+    check_credential_sanity(name, login, pass) unless bypass_check
+    @conn.select_app_auth(aid, @key)
+
+    padded_name   = name.ljust(NAME_LEN,   "\x00")
+    padded_login  = login.ljust(LOGIN_LEN, "\x00")
+    padded_pass   = pass.ljust(PASS_LEN,   "\x00")
+    hmac_data     = hmac(name + login + pass, derive_aes_key('hmac'))
+    triplet       = padded_login + padded_pass + hmac_data
+    ciph_name     = aes_encipher(padded_name, derive_aes_key(''))
+    ciph_triplet  = aes_encipher(triplet,     derive_aes_key(name))
+    content       = ciph_name + ciph_triplet
+
+    raise TAG_FULL_ERROR if
+      catch :OUT_OF_EEPROM_ERROR do
+        # If the file already exiting (e.g. when editing it), there is no need
+        # to create the file.
+        catch :DUPLICATE_ERROR do
+          @conn.create_file(fid, FILE_RIGHTS, TOTAL_LEN)
+        end
+        false
+      end
+    @conn.write_file(fid, 0, TOTAL_LEN, content)
+  end
+
+  # Check if the supplied name, login and password are neither too long nor too
+  # short.
+  def check_credential_sanity(name, login, pass)
+    if name.length > NAME_LEN
+      raise CredentialError.new("Name too long (max #{NAME_LEN} chars.)")
+    elsif login.length > LOGIN_LEN
+      raise CredentialError.new("Login too long (max #{LOGIN_LEN} chars.)")
+    elsif pass.length > PASS_LEN
+      raise CredentialError.new("Pass too long (max #{PASS_LEN} chars.)")
+    elsif name.length == 0
+      raise CredentialError.new('Empty name')
+    elsif pass.length == 0
+      raise CredentialError.new('Empty pass')
+    elsif login.length == 0
+      raise CredentialError.new('Empty login')
+    end
+  end
+
+end