safedb 0.01.0001

data/lib/keytools/key.db.rb

@@ -0,0 +1,330 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module SafeDb
+
+  require 'json'
+
+  # A Key/Value database knows how to manipulate a JSON backed data structure
+  # (put, add etc) <b>after reading and then decrypting it</b> from a
+  # file and <b>before encrypting and then writing it</b> to a file.
+  #
+  # It provides behaviour to which we can create, append (add), update
+  # (change), read parts and delete essentially two structures
+  #
+  # - a collection of name/value pairs
+  # - an  ordered list of values
+  #
+  # == JSON is Not Exposed in the Interface
+  #
+  # A key/value database doesn't expose the data format used in the implementation
+  # allowing this to be changed seamlessly to YAMl or other formats.
+  #
+  # == Symmetric Encryption and Decryption
+  #
+  # A key/value database supports operations to <b>read from</b> and <b>write to</b>
+  # a known filepath and with a symmetric key it can
+  #
+  # - decrypt <b>after reading from</b> a file and
+  # - encrypt <b>before writing to</b> a (the same) file
+  #
+  # == Hashes as the Primary Data Structure
+  #
+  # The key/value database openly extends {Hash} as the data structure for holding
+  #
+  # - strings
+  # - arrays
+  # - other hashes
+  # - booleans
+  # - integers and floats
+  class KeyDb < Hash
+
+    # Return a key database data structure that is instantiated from
+    # the parameter JSON string.
+    #
+    # @param db_json_string [String]
+    #    this json formatted data structure will be converted into a
+    #    a Ruby hash (map) data structure and returned.
+    #
+    # @return [KeyDb]
+    #    a hash data structure that has been instantiated as per the
+    #    parameter json string content.
+    def self.from_json( db_json_string )
+
+      data_db = KeyDb.new()
+      data_db.merge!( JSON.parse( db_json_string ) )
+      return data_db
+
+    end
+
+
+
+    # Create a new key value entry inside a dictionary with the specified
+    # name at the root of this database. Successful completion means the
+    # named dictionary will contain one more entry than it need even if it
+    # did not previously exist.
+    #
+    # @param dictionary_name [String]
+    #
+    #    if a dictionary with this name exists at the root of the
+    #    database add the parameter key value pair into it.
+    #
+    #    if no dictionary exists then create one first before adding
+    #    the key value pair as the first entry into it.
+    #
+    # @param key_name [String]
+    #
+    #    the key part of the key value pair that will be added into the
+    #    dictionary whose name was provided in the first parameter.
+    #
+    # @param value [String]
+    #
+    #    the value part of the key value pair that will be added into the
+    #    dictionary whose name was provided in the first parameter.
+    def create_entry( dictionary_name, key_name, value )
+
+      KeyError.not_new( dictionary_name, self )
+      KeyError.not_new( key_name, self )
+      KeyError.not_new( value, self )
+
+      self[ dictionary_name ] = {} unless self.has_key?( dictionary_name )
+      self[ dictionary_name ][ key_name ] = value
+
+    end
+
+
+    # Create a new secondary tier map key value entry inside a primary tier
+    # map at the map_key_name location.
+    #
+    # A failure will occur if either the outer or inner keys already exist
+    # without their values being map objects.
+    #
+    # If this method is called against a new empty map, the resulting map
+    # structure will look like the below.
+    #
+    #     { outer_keyname ~> { inner_keyname ~> { entry_keyname, entry_value } } }
+    #
+    # @param outer_keyname [String]
+    #
+    #    if a dictionary with this name exists at the root of the
+    #    database add the parameter key value pair into it.
+    #
+    #    if no dictionary exists then create one first before adding
+    #    the key value pair as the first entry into it.
+    #
+    # @param inner_keyname [String]
+    #
+    #    if a map exists at this key name then an entry comprising of
+    #    a map_entry_key and a entry_value may either be added
+    #    (if the map_entry_key does not already exist), or updated if
+    #    it does.
+    #
+    #    if the map does not exist it will be created and its first and
+    #    only entry will be a key with inner_keyname along with a new
+    #    single entry map consisting of the entry_keyname and the
+    #    entry_value.
+    #
+    # @param entry_keyname [String]
+    #
+    #    this key will exist in the second tier map after this operation.
+    #
+    # @param entry_value [String]
+    #
+    #    this value will exist in the second tier map after this operation
+    #    and if the entry_keyname already existed its value is overwritten
+    #    with this one.
+    #
+    def create_map_entry( outer_keyname, inner_keyname, entry_keyname, entry_value )
+
+      KeyError.not_new( outer_keyname, self )
+      KeyError.not_new( inner_keyname, self )
+      KeyError.not_new( entry_keyname, self )
+      KeyError.not_new( entry_value,   self )
+
+      self[ outer_keyname ] = {} unless self.has_key?( outer_keyname )
+      self[ outer_keyname ][ inner_keyname ] = {} unless self[ outer_keyname ].has_key?( inner_keyname )
+      self[ outer_keyname ][ inner_keyname ][ entry_keyname ] = entry_value
+
+    end
+
+
+    # Does this database have an entry in the root dictionary named with
+    # the key_name parameter?
+    #
+    # @param dictionary_name [String]
+    #
+    #    immediately return false if a dictionary with this name does
+    #    <b>not exist</b> at the root of this database.
+    #
+    # @param key_name [String]
+    #
+    #    test whether a key/value pair answering to this name exists inside
+    #    the specified dictionary at the root of this database.
+    #
+    def has_entry?( dictionary_name, key_name )
+
+      KeyError.not_new( dictionary_name, self )
+      KeyError.not_new( key_name, self )
+
+      return false unless self.has_key?( dictionary_name )
+      return self[ dictionary_name ].has_key?( key_name )
+
+    end
+
+
+    # Get the entry with the key name in a dictionary that is itself
+    # inside another dictionary (named in the first parameter) which
+    # thankfully is at the root of this database.
+    #
+    # Only call this method if {has_entry?} returns true for the same
+    # dictionary and key name parameters.
+    #
+    # @param dictionary_name [String]
+    #
+    #    get the entry inside a dictionary which is itself inside a
+    #    dictionary (with this dictionary name) which is itself at the
+    #    root of this database.
+    #
+    # @param key_name [String]
+    #
+    #    get the value part of the key value pair that is inside a
+    #    dictionary (with the above dictionary name) which is itself
+    #    at the root of this database.
+    #
+    def get_entry( dictionary_name, key_name )
+
+      return self[ dictionary_name ][ key_name ]
+
+    end
+
+
+    # Delete an existing key value entry inside the dictionary with the specified
+    # name at the root of this database. Successful completion means the
+    # named dictionary will contain one less entry if that key existed.
+    #
+    # @param dictionary_name [String]
+    #
+    #    if a dictionary with this name exists at the root of the
+    #    database add the parameter key value pair into it.
+    #
+    #    if no dictionary exists throw an error
+    #
+    # @param key_name [String]
+    #
+    #    the key part of the key value pair that will be deleted in the
+    #    dictionary whose name was provided in the first parameter.
+    def delete_entry( dictionary_name, key_name )
+
+      KeyError.not_new( dictionary_name, self )
+      KeyError.not_new( key_name, self )
+
+      self[ dictionary_name ].delete( key_name )
+
+    end
+
+
+    # Read and inject into this envelope, the data structure found in a
+    # file at the path specified in the first parameter.
+    #
+    # Symmetric cryptography is mandatory for the envelope so we must
+    # <b>encrypt before writing</b> and <b>decrypt after reading</b>.
+    #
+    # An argument error will result if a suitable key is not provided.
+    #
+    # If the file does not exist (denoting the first read) all this method
+    # does is to stash the filepath as an instance variable and igore the
+    # decryption key which can be nil (or ommitted).
+    #
+    # @param the_filepath [String]
+    #     absolute path to the file which acts as the persistent mirror to
+    #     this data structure envelope.
+    #
+    # @param decryption_key [String]
+    #     encryption at rest is a given so this mandatory parameter must
+    #     contain a robust symmetric decryption key. The key will be used
+    #     for decryption after the read and it will not linger (ie not cached
+    #     as an instance variable).
+    #
+    # @raise [ArgumentError] if the decryption key is not robust enough.
+    def read the_filepath, decryption_key = nil
+
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+
+      raise RuntimeError, "This KeyDb.read() software is never called so how can I be here?"
+
+      @filepath = the_filepath
+      return unless File.exists? @filepath
+
+      cipher_text = Base64.decode64( File.read( @filepath ).strip )
+      plain_text = ToolBelt::Blowfish.decryptor( cipher_text, decryption_key )
+
+      data_structure = JSON.parse plain_text
+      self.merge! data_structure
+
+    end
+
+
+    # Write the data in this envelope hash map into a file-system
+    # backed mirror whose path was specified in the {self.read} method.
+    #
+    # Technology for encryption at rest is supported by this dictionary
+    # and to this aim, please endeavour to post a robust symmetric
+    # encryption key.
+    #
+    # Calling this {self.write} method when the file at the prescribed path
+    # does not exist results in the directory structure being created
+    # (if necessary) and then the encrypted file being written.
+    #
+    # @param encryption_key [String]
+    #     encryption at rest is a given so this mandatory parameter must
+    #     contain a robust symmetric encryption key. The symmetric key will
+    #     be used for the decryption after the read. Note that the decryption
+    #     key does not linger meaning it isn't cached in an instance variable.
+    def write encryption_key
+
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+      # @todo -> this is confused - it uses INI but above methods use JSON
+
+      raise RuntimeError, "This KeyDb.write( key ) software is never called so how can I be here?"
+
+      FileUtils.mkdir_p(File.dirname(@filepath))
+      cipher_text = Base64.encode64 ToolBelt::Blowfish.encryptor( self.to_json, encryption_key )
+      File.write @filepath, cipher_text
+
+      puts ""
+      puts "=== ============================"
+      puts "=== Envelope State ============="
+      puts "=== ============================"
+
+      a_ini_file = IniFile.new
+      self.each_key do |section_name|
+        a_ini_file[section_name] = self[section_name]
+      end
+      puts a_ini_file.to_s
+
+      puts "=== ============================"
+      puts ""
+
+    end
+
+
+  end
+
+
+end

data/lib/keytools/key.docs.rb

@@ -0,0 +1,195 @@
+#!/usr/bin/ruby
+
+# The open key library generates keys, it stores their salts, it produces differing
+# representations of the keys (like base64 for storage and binary for encrypting).
+#
+# == Key Class Names their and Responsibility
+#
+# The 5 core key classes in the open key library are
+#
+# - {Key} represents keys in bits, binary and base 64 formats
+# - {Key64} for converting from to and between base 64 characters
+# - {Key256} uses key derivation functions to produce high entropy keys
+# - {KeyIO} reads and writes key metadata (like salts) from/to persistent storage
+# - {KeyCycle} for creating and locking the keys that underpin the security
+#
+# == The 5 Core Key Classes
+#
+#     Key              To initialize with a 264 binary bit string. To hold the
+#                      key and represent it when requested
+#                       - as a 264 bit binary bit string
+#                       - as a 256 bit binary bit string
+#                       - as a 256 bit raw bytes encryption key
+#                       - as a YACHT64 formatted string
+#
+#     Key64            To map in and out of the Yacht64 character set - from and to
+#                       - a binary bit string sequence
+#                       - a Base64 character encoding
+#                       - a UrlSafe Base64 character encoding
+#                       - a Radix64 character encoding
+#
+#     Key256           It generates a key in 3 different and important ways. It can
+#                      generate
+#
+#                        (a) from_password
+#                        (b) from_random (or it can)
+#                        (c) regenerate
+#
+#                      When generating from a password it takes a dictionary with
+#                      a pre-tailored "section" and writes BCrypt and Pbkdf2 salts
+#                      into it.
+#
+#                      When generating random it kicks of by creating a 55 byte
+#                      random key fo BCrypt and a 64 byte random key for Pbkdf2.
+#                      It then calls upon generate_from_password.
+#
+#                      When regenerating it queries the dictionary provided at the
+#                      pre-tailored "section" for the BCrypt and Pbkdf2 salts and
+#                      then uses input passwords (be they human randomly sourced)
+#                      and regenerates the keys it produced at an earlier sitting.
+#
+#     KeyIO            KeyIO is instantiated with a folder path and a "key reference".
+#                      KeyIO will then manage writing to and rereading from the structure
+#                      hel inside th efile. The file is named (primarily) by the
+#                      reference string.
+#
+#     KeyCycle         KeyLifeCycle implements the merry go round that palms off
+#                      responsibility to the intra-session cycle and then back again
+#                      to ever rotary inter-session(ary) cycle.
+###########            Maybe think of a method where we pass in
+###########            2 secrets - 1 human and 1 55 random bytes (session)
+###########
+###########            1  another 55 random key is created (the actual encryption key)
+###########            2  then the above key is encrypted TWICE (2 diff salts and keys)
+###########            3  Once by key from human password
+###########            4  Once by key from machine password
+###########            5  then the key from 1 is returned
+###########            6  caller encrypts file .................... (go 4 it)
+
+
+# Generates a 256 bit symmetric encryption key derived from a random
+# seed sequence of 55 bytes. These 55 bytes are then fed into the
+# {from_password} key derivation function and processed in a similar
+# way to if a human had generated the string.
+#
+
+
+# <b>Key derivation functions</b> exist to convert <b>low entropy</b> human
+# created passwords into a high entropy key that is computationally difficult
+# to acquire through brute force.
+#
+# == SafeDb's Underlying Security Strategy
+#
+# <b>Randomly generate a 256 bit encryption key and encrypt it</b> with a key
+# derived from a human password and generated by at least two cryptographic
+# workhorses known as <b>key derivation functions</b>.
+#
+# The encryption key (encrypted by the one derived from a human password) sits
+# at the beginning of a long chain of keys and encryption - so much so that the
+# crypt material being outputted for storage is all but worthless to anyone but
+# its rightful owner.
+#
+# == Key Size vs Crack Time
+#
+# Cracking a 256 bit key would need roughly 2^255 iterations (half the space)
+# and this is akin to the number of atoms in the known universe.
+#
+# <b>The human key can put security at risk.</b>
+#
+# The rule of thumb is that a 40 character password with a good spread of the
+# roughly 90 typable characters, would produce security equivalent to that of
+# an AES 256bit key. As the password size and entropy drop, so does the security,
+# exponentially.
+#
+# As human generated passwords have a relatively small key space, key derivation
+# functions must be slow to compute with any implementation.
+#
+# == Key Derivation Functions for Command Line Apps
+#
+# A command line app (with no recourse to a central server) uses a Key
+# Derivation Function (like BCrypt, Aaron2 or PBKD2) in a manner different
+# to that employed by server side software.
+#
+# - server side passwords are hashed then both salt and hash are persisted
+# - command line apps do not store the key - they only store the salt
+# - both throw away the original password
+#
+# == One Key | One Session | One Crypt
+#
+# Command line apps use the derived key to <b>symmetrically encrypt and decrypt</b>
+# one and only one 48 character key and a new key is derived at the beginning
+# of every session.
+#
+# At the end of the session <b>all material encrypted by the outgoing key</b>
+# is removed. This aggressive key rotation strategy leaves no stone unturned in
+# the quest for ultimate security.
+#
+# == SafeDb's CLI Key Derivation Architecture
+#
+# SafeDb never accesses another server and giving its users total control
+# of their secret crypted materials. It strengthens the key derivation process
+# in three important ways.
+#
+# - [1] it does not store the key nor does it store the password
+#
+# - [2] a new master key is generated for every session only to hold the master index file
+#
+# - [3] it uses both <b>BCrypt</b> (Blowfish Crypt) and the indefatigable <b>PBKD2</b>
+
+
+  # After a successful initialization, the application instance is linked to a keystore
+  # whose contents are responsible for securing the application instance database.
+  #
+  # To ascertain what needs to be done to bridge the gap to full initialization the
+  # app needs to know 3 things from the KeyApi. These things are
+  #
+  # - the ID of this app instance on the machine
+  # - if a keystore been associated with this ID
+  # - whether the keystore secures the app database
+  #
+  # The answers dictate the steps that need to be undertaken to bring the database of
+  # the application instance under the secure wing of the KeyApi.
+  #
+  #
+  # == 1. What is the App Instance ID on this Machine?
+  #
+  # The KeyApi uses the "just given" application reference and the machine environment to
+  # respond with a <b>digested identifier</b> binding the application instance to the
+  # present machine (workstation).
+  #
+  #
+  # == 2. Has a Keystore been associated with this ID?
+  #
+  # The application's configuration manager is asked to find an associated KeyStore ID
+  # mapped against the app/machine id garnered by question 1.
+  #
+  # <b>No it has not!</b>
+  #
+  # If <b>NO</b> then a KeyStore ID is acquired <b>either from the init command's parameter</b>,
+  # or a <b>suitable default</b>. This new association between the app/machine ID and the
+  # KeyStore ID is then stored so the answer next time will be <b>YES</b>.
+  #
+  # <b>Yes it has!</b>
+  #
+  # Great - we now submit the KeyStore ID to the KeyApi so that it may answer question 3.
+  #
+  #
+  # == 3. Does the keystore secure the app instance database?
+  #
+  # For the KeyApi to answer, it needs the App's Instance ID and the KeyStore ID.
+  #
+  # <b>Not Yet!</b> Now <b>NO</b> means this application instance's database has not been
+  # brought under the protection of the KeyApi's multi-layered security net. For this it
+  # needs
+  #
+  # - the KeyStore ID
+  # - the application instance reference
+  # - the plaintext secret from which nothing of the host survives
+  # - the current application database plaintext
+  #
+  # <b>Yes it does!</b> If the app db keys <b>have been instantiated</b> and the client app is
+  # <b>sitting pretty</b> in possession of the database ciphertext, no more needs doing.
+
+module SafeDb
+
+end

data/lib/keytools/key.error.rb

@@ -0,0 +1,110 @@
+#!/usr/bin/ruby
+
+module SafeDb
+
+
+  # This class is the parent to all opensession errors
+  # that originate from the command line.
+  #
+  # All opensession cli originating errors are about
+  #
+  # - a problem with the input or
+  # - a problem with the current state or
+  # - a predictable future problem
+  class KeyError < StandardError
+
+
+    # Initialize the error and provide a culprit
+    # object which will be to-stringed and given
+    # out as evidence (look at this)!
+    #
+    # This method will take care of loggin the error.
+    #
+    # @param message [String] human readable error message
+    # @param culprit [Object] object that is either pertinent, a culprit or culpable 
+    def initialize message, culprit
+
+      super(message)
+
+      @the_culprit = culprit
+
+      log.info(x) { "An [Error] Occured => #{message}" }
+      log.info(x) { "Object of Interest => #{culprit.to_s}" } unless culprit.nil?
+      log.info(x) { "Class Name Culprit => #{culprit.class.name}" }
+      log.info(x) { "Error Message From => #{self.class.name}" }
+
+      thread_backtrace = Thread.current.backtrace.join("\n")
+      thread_backtrace.to_s.log_lines
+
+    end
+
+
+    # This method gives interested parties the object that
+    # is at the centre of the exception. This object is either
+    # very pertinent, culpable or at the very least, interesting.
+    #
+    # @return [String] string representation of culpable object
+    def culprit
+      return "No culprit identified." if @the_culprit.nil?
+      return @the_culprit.to_s
+    end
+
+
+    # Assert that the parameter string attribute is <b>not new</b> which
+    # means neither nil, nor empty nor consists solely of whitespace.
+    #
+    # The <b>NEW</b> acronym tells us that a bearer worthy of the name is
+    #
+    # - neither <b>N</b>il
+    # - nor <b>E</b>mpty
+    # - nor consists solely of <b>W</b>hitespace
+    #
+    # @param the_attribute [String]
+    #    raise a {KeyError} if the attribute is not new.
+    #
+    # @param the_desc [String]
+    #    a description of th attribute
+    #
+    # @raise [KeyError]
+    #
+    # The attribute cannot be <b>NEW</b>. The <b>NEW acronym</b> asserts
+    # that the attribute is
+    #
+    # - neither <b>N</b>il
+    # - nor <b>E</b>mpty
+    # - nor <b>W</b>hitespace only
+    #
+    def self.not_new the_attribute, the_desc
+
+      attribute_new = the_attribute.nil? || the_attribute.chomp.strip.empty?
+      return unless attribute_new
+
+      msg = "[the_desc] is either nil, empty or consists solely of whitespace."
+      raise KeyError.new( msg, the_desc )
+
+    end
+
+
+  end
+
+=begin
+  # Throw this error if the configured safe directory points to a file.
+  class SafeDirectoryIsFile < OpenError::CliError; end;
+
+  # Throw this error if safe directory path is either nil or empty.
+  class SafeDirNotConfigured < OpenError::CliError; end;
+
+  # Throw this error if the email address is nil, empty or less than 5 characters.
+  class EmailAddrNotConfigured < OpenError::CliError; end;
+
+  # Throw this error if the store url is either nil or empty.
+  class StoreUrlNotConfigured < OpenError::CliError; end;
+
+  # Throw if "prime folder" name occurs 2 or more times in the path.
+  class SafePrimeNameRepeated < OpenError::CliError; end;
+
+  # Throw if "prime folder" name occurs 2 or more times in the path.
+  class SafePrimeNameNotAtEnd < OpenError::CliError; end;
+=end
+
+end