safedb 0.01.0001

data/lib/keytools/key.local.rb

@@ -0,0 +1,259 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module SafeDb
+
+  # The command line interface has a high entropy randomly generated
+  # key whose purpose is to <b>lock the application's data key</b> for
+  # the duration of the session which is between a login and a logout.
+  # 
+  # These keys are unique to only one shell session on one workstation
+  # and they live lives that are no longer (and mostly shorter) than
+  # the life of the parent shell.
+  #
+  # == The 4 CLI Shell Entities
+  #
+  # The four (4) important entities within the shell session are
+  #
+  # - an obfuscator key for locking the shell key during a session
+  # - a high entropy randomly generated shell key for locking the app data key
+  # - one environment variable whose value embodies three (3) data segments
+  # - a session id derived by pushing the env var through a one-way function
+  class KeyLocal
+
+
+    # The number of Radix64 characters that make up a valid BCrypt salt.
+    # To create a BCrypt salt use 
+    BCRYPT_SALT_LENGTH = 22
+
+
+    # There are two digits representing the BCrypt iteration count.
+    # The minimum is 10 and the maximum is 16.
+    BCRYPT_ITER_COUNT_SIZE = 2
+
+
+    # The session token comprises of 3 segments with fixed lengths.
+    # This triply segmented text token that can be used to decrypt
+    # and deliver the shell key.
+    SESSION_TOKEN_SIZE = 128 + 22 + BCRYPT_ITER_COUNT_SIZE
+
+
+    # Given a 152 character session token, what is the index that pinpoints
+    # the beginning of the 22 character BCrypt salt? The answer is given
+    # by this BCRYPT_SALT_START_INDEX constant.
+    BCRYPT_SALT_START_INDEX = SESSION_TOKEN_SIZE - BCRYPT_SALT_LENGTH - BCRYPT_ITER_COUNT_SIZE
+
+
+    # What index pinpoints the end of the BCrypt salt itself.
+    # This is easy as the final 2 characters are the iteration count
+    # so the end index is the length subtract 1 subtract 2.
+    BCRYPT_SALT_END_INDEX = SESSION_TOKEN_SIZE - 1
+
+
+    # Initialize the session by generating a random high entropy shell token
+    # and then generate an obfuscator key which we use to lock the shell
+    # key and return a triply segmented text token that can be used to decrypt
+    # and deliver the shell key as long as the same shell on the same machine
+    # is employed to make the call.
+    #
+    # <b>The 3 Session Token Segments</b>
+    #
+    # The session token is divided up into 3 segments with a total of 150
+    #  characters.
+    #
+    #   | -------- | ------------ | ------------------------------------- |
+    #   | Segment  | Length       | Purpose                               |
+    #   | -------- | ------------ | ------------------------------------- |
+    #   |    1     | 16 bytes     | AES Encrypt Initialization Vector(IV) |
+    #   |    2     | 80 bytes     | Cipher text from Random Key AES crypt |
+    #   |    3     | 22 chars     | Salt for obfuscator key derivation    |
+    #   | -------- | ------------ | ------------------------------------- |
+    #   |  Total   | 150 chars    | Session Token in Environment Variable |
+    #   | -------- | ------------ | ------------------------------------- |
+    #
+    # Why is the <b>16 byte salt and the 80 byte BCrypt ciphertext</b> represented
+    # by <b>128 base64 characters</b>?
+    #
+    #    16 bytes + 80 bytes = 96 bytes
+    #    96 bytes x 8 bits   = 768 bits
+    #    768 bits / 6 bits   = 128 base64 characters
+    #
+    # @return [String]
+    #    return a triply segmented text token that can be used to decrypt
+    #    and redeliver the high entropy session shell key on the same machine
+    #    and within the same shell on the same machine.
+    def self.generate_shell_key_and_token
+
+      bcrypt_salt_key = KdfBCrypt.generate_bcrypt_salt
+      obfuscator_key = derive_session_crypt_key( bcrypt_salt_key )
+      random_key_ciphertext = obfuscator_key.do_encrypt_key( Key.from_random() )
+      session_token = random_key_ciphertext + bcrypt_salt_key.reverse
+      assert_session_token_size( session_token )
+
+      return session_token
+
+    end
+
+
+    # Regenerate the random shell key that was instantiated and locked
+    # during the {instantiate_shell_key_and_generate_token} method.
+    #
+    # To successfully reacquire the randomly generated (and then locked)
+    # shell key we must be provided with five (5) data points, four (4)
+    # of which are embalmed within the 150 character session token
+    # parameter.
+    #
+    # <b>What we need to Regenerate the Shell Key</b>
+    #
+    # Regenerating the shell key is done in two steps when given the
+    # four (4) <b>session token segments</b> described below, and the
+    # shell identity key described in the {SafeDb::Identifier} class.
+    #
+    # The session token is divided up into 4 segments with a total of 152
+    #  characters.
+    #
+    #   | -------- | ------------ | ------------------------------------- |
+    #   | Segment  | Length       | Purpose                               |
+    #   | -------- | ------------ | ------------------------------------- |
+    #   |    1     | 16 bytes     | AES Encrypt Initialization Vector(IV) |
+    #   |    2     | 80 bytes     | Cipher text from Random Key AES crypt |
+    #   |    3     | 22 chars     | Salt 4 shell identity key derivation  |
+    #   |    4     |  2 chars     | BCrypt iteration parameter (10 to 16) |
+    #   | -------- | ------------ | ------------------------------------- |
+    #   |  Total   | 152 chars    | Session Token in Environment Variable |
+    #   | -------- | ------------ | ------------------------------------- |
+    #
+    # @param session_token [String]
+    #    a triply segmented (and one liner) text token instantiated by
+    #    {self.instantiate_shell_key_and_generate_token} and provided
+    #    here ad verbatim.
+    #
+    # @param use_grandparent_pid [Boolean]
+    #
+    #    Optional boolean parameter. If set to true the PID (process ID) used
+    #    as part of an obfuscator key and normally acquired from the parent
+    #    process should now be acquired from the grandparent's process.
+    #
+    #    Set to true when accessing the safe's credentials from a sub process
+    #    rather than directly through the logged in shell.
+    #
+    # @return [SafeDb::Key]
+    #    an extremely high entropy 256 bit key derived (digested) from 48
+    #    random bytes at the beginning of the shell (cli) session.
+    def self.regenerate_shell_key( session_token, use_grandparent_pid = false )
+
+      assert_session_token_size( session_token )
+      bcrypt_salt = session_token[ BCRYPT_SALT_START_INDEX .. BCRYPT_SALT_END_INDEX ].reverse
+      assert_bcrypt_salt_size( bcrypt_salt )
+
+      key_ciphertext = session_token[ 0 .. ( BCRYPT_SALT_START_INDEX - 1 ) ]
+      obfuscator_key = derive_session_crypt_key( bcrypt_salt, use_grandparent_pid )
+      regenerated_key = obfuscator_key.do_decrypt_key( key_ciphertext )
+
+      return regenerated_key
+
+    end
+
+
+    # Derive a <b>short term (session scoped) encryption key</b> from the
+    # surrounding shell and workstation (machine) environment with an
+    # important same/different guarantee.
+    #
+    # The <b>same / different guarantee promises</b> us that the derived
+    # key will be
+    #
+    # - <b>the same</b> whenever called from within this executing shell
+    # - <b>different</b> when the shell and/or workstation are different
+    #
+    # This method uses a one-way function to return a combinatorial digested
+    # session identification string using a number of distinct parameters that
+    # deliver the important behaviours of changing in certain circumstances
+    # and remaining unchanged in others.
+    #
+    # <b>Change | When Should the key Change?</b>
+    #
+    # What is really important is that the <b>key changes when</b>
+    #
+    # - the <b>command shell</b> changes
+    # - the workstation <b>shell user is switched</b>
+    # - the host machine <b>workstation</b> is changed
+    # - the user <b>SSH's</b> into another shell
+    #
+    # A distinct workstation is identified by the first MAC address and the
+    # hostname of the machine.
+    #
+    # <b>Unchanged | When Should the Key Remain Unchanged?</b>
+    #
+    # Remaining <b>unchanged</b> in certain scenarios is a feature that is
+    # just as important as changing in others. The key must remain
+    # <b>unchanged</b> when
+    #
+    # - the <b>user returns to a command shell</b>
+    # - the user exits their <b>remote SSH session</b>
+    # - <b>sudo is used</b> to execute the commands
+    # - the user comes back to their <b>workstation</b>
+    # - the clock ticks into another day, month, year ...
+    #
+    # @param bcrypt_salt_key [SafeDb::Key]
+    #
+    #    Either use BCrypt to generate the salt or retrieve and post in a
+    #    previously generated salt which must hold 22 printable characters.
+    #
+    # @param use_grandparent_pid [Boolean]
+    #
+    #    Optional boolean parameter. If set to true the PID (process ID) used
+    #    as part of an obfuscator key and normally acquired from the parent
+    #    process should now be acquired from the grandparent's process.
+    #
+    #    Set to true when accessing the safe's credentials from a sub process
+    #    rather than directly through the logged in shell.
+    #
+    # @return [SafeDb::Key]
+    #    a digested key suitable for short term (session scoped) use with the
+    #    guarantee that the same key will be returned whenever called from within
+    #    the same executing shell environment and a different key when not.
+    def self.derive_session_crypt_key bcrypt_salt_key, use_grandparent_pid = false
+
+      shell_id_text = KeyIdent.derive_shell_identifier( use_grandparent_pid )
+      truncate_text = shell_id_text.length > KdfBCrypt::BCRYPT_MAX_IN_TEXT_LENGTH
+      shell_id_trim = shell_id_text unless truncate_text
+      shell_id_trim = shell_id_text[ 0 .. ( KdfBCrypt::BCRYPT_MAX_IN_TEXT_LENGTH - 1 ) ] if truncate_text
+
+      return KdfBCrypt.generate_key( shell_id_trim, bcrypt_salt_key )
+
+    end
+
+
+    private
+
+
+    # 000000000000000000000000000000000000000000000000000000000000000
+    # How to determine the caller.
+    # Better strategy would be just to print the stack trace
+    # That gives you much more bang for the one line buck.
+    # 000000000000000000000000000000000000000000000000000000000000000
+    # calling_module = File.basename caller_locations(1,1).first.absolute_path, ".rb"
+    # calling_method = caller_locations(1,1).first.base_label
+    # calling_lineno = caller_locations(1,1).first.lineno
+    # caller_details = "#{calling_module} | #{calling_method} | (line #{calling_lineno})"
+    # log.info(x) { "### Caller Details =>> =>> #{caller_details}" }
+    # 000000000000000000000000000000000000000000000000000000000000000
+
+
+    def self.assert_session_token_size session_token
+      err_msg = "Session token has #{session_token.length} and not #{SESSION_TOKEN_SIZE} chars."
+      raise RuntimeError, err_msg unless session_token.length == SESSION_TOKEN_SIZE
+    end
+
+
+    def self.assert_bcrypt_salt_size bcrypt_salt
+      amalgam_length = BCRYPT_SALT_LENGTH + BCRYPT_ITER_COUNT_SIZE
+      err_msg = "Expected BCrypt salt length of #{amalgam_length} not #{bcrypt_salt.length}."
+      raise RuntimeError, err_msg unless bcrypt_salt.length == amalgam_length
+    end
+
+
+  end
+
+
+end

data/lib/keytools/key.now.rb

@@ -0,0 +1,402 @@
+#!/usr/bin/ruby
+
+module SafeDb
+
+  require 'singleton'
+
+  # This stamp sits at the centre of a fundamental DevOps pattern concerned
+  # with infrastructure provisioning and configuraion management.
+  #
+  # The central idea behind the pattern is to link every infrastructure
+  # object created during a session with a reference accurate to the nearest
+  # centi-second denoting the moment the software runtime (session) began.
+  class KeyNow
+    include Singleton
+
+    attr_reader :time_now
+
+    # Return two digit [mo] month index from 01 to 12.
+    # @example 02 => in February
+    #
+    def self.mo
+      return KeyNow.instance.time_now.strftime "%m"
+    end
+
+
+    # Return three character abbreviated month name.
+    # @example feb => in February
+    #
+    def self.mmm
+      return KeyNow.instance.time_now.strftime( "%b" ).downcase
+    end
+
+
+    #
+    # Return three character abbreviated day of week.
+    # @example tue => on Tuesday
+    #
+    def self.ddd
+      return KeyNow.instance.time_now.strftime( "%a" ).downcase
+    end
+
+
+    #
+    # Return two digit (character) hour of day from 00 to 23.
+    # @example 22 => between 22.00.00 and 22.59.59 inclusive
+    #
+    def self.hh
+      return KeyNow.instance.time_now.strftime "%H"
+    end
+
+
+    #
+    # Return two digit minute of hour from [00] to [59].
+    #
+    def self.mm
+      return KeyNow.instance.time_now.strftime "%M"
+    end
+
+
+    #
+    # Return two digit second of minute from [00] to [59].
+    #
+    def self.ss
+      return KeyNow.instance.time_now.strftime "%S"
+    end
+
+
+    #
+    # Return a [3 digit] second and tenth of second
+    # representation.
+    #
+    # The final digit is derived from the 1000 sliced
+    # millisecond of second running from 000 to 999.
+    #
+    # <tt>Truncation (Not Rounding)</tt>
+    #
+    # The [final] digit is acquired by TRUNCATING
+    # (chopping off) the last 2 of the 3 millisecond
+    # digits. No rounding is applied.
+    #
+    # The 3 returned digits comprise of the
+    #
+    # - second of minute => 2 digits | [00] to [59] (and)
+    # - tenth of second  => 1 digit from [0] to [9]
+    #
+    # @example
+    #
+    #  => The time at the 562nd millisecond  of the 49th
+    #     second of the minute.
+    #
+    #  => 3 chars
+    #  => 495
+    #
+    #
+    def self.sst
+      millisec_string = KeyNow.instance.time_now.strftime "%L"
+      return "#{ss}#{millisec_string[0]}"
+    end
+
+
+    #
+    # Return the [two] digit year (eg 19 for 2019).
+    # that we are currently in.
+    #
+    def self.yy
+      return KeyNow.instance.time_now.strftime("%Y")[2..-1]
+    end
+
+
+    #
+    # Return the [four] digit year (eg 2019)
+    # that we are currently in.
+    #
+    def self.yyyy
+      return KeyNow.instance.time_now.strftime("%Y")
+    end
+
+
+    # ------------------------------------------------- -- #
+    # Return 3 digit julian day of year [001] to [366]. -- #
+    # ------------------------------------------------- -- #
+    def self.jjj
+      return KeyNow.instance.time_now.strftime "%j"
+    end
+
+
+    # [yymo_mmm] returns an amalgam of
+    #
+    #    => the two-digit year
+    #    => the two-digit month index (starting at 01)
+    #    => a period (separator)
+    #    => the abbreviated month name
+    #
+    # @example
+    #   => 1908.aug
+    #   => for August 2019
+    #
+    def self.yymo_mmm
+      return "#{yy}#{mo}.#{mmm}"
+    end
+
+
+    #
+    # Given two integer parameters (month index and 4 digit year) representing
+    # the month in question this method returns the [PREVIOUS MONTHS] character
+    # amalgam in the format [yymo_mmm] where
+    #
+    #    => yy  | previous month's two-digit year
+    #    => mo  | previous month's two-digit month index
+    #    => .   | a period (separator)
+    #    => mmm | previous month's abbreviated month name
+    #
+    # -------------------
+    # Example 1 (Simple)
+    # -------------------
+    #
+    #  returns char => 1907.jul
+    #  4 parameters => 8, 2019
+    #  representing => August, 2019
+    #
+    # ----------------------
+    # Example 2 (Last Year)
+    # ----------------------
+    #
+    #  returns char => 1812.dec
+    #  4 parameters => 1, 2019
+    #  representing => January, 2019
+    #
+    def self.previous_month_chars this_month_index, this_4digit_year
+
+      prev_month_index = this_month_index == 1 ? 12 : ( this_month_index - 1 )
+      prev_2dig_mn_pad = sprintf '%02d', prev_month_index
+      prev_4digit_year = this_month_index == 1 ? ( this_4digit_year - 1 ) : this_4digit_year
+      prev_twodigit_yr = "#{prev_4digit_year.to_s}"[2..-1]
+      prev_months_name = Date::ABBR_MONTHNAMES[prev_month_index].downcase
+
+      return "#{prev_twodigit_yr}#{prev_2dig_mn_pad}.#{prev_months_name}"
+
+    end
+
+    #
+    # Using the current class time this method returns
+    # the character amalgam for the [PREVIOUS MONTH] in
+    # the format [yymo_mmm] where
+    #
+    #    => yy  | last month's two-digit year
+    #    => mo  | last month's two-digit month index
+    #    => .   | a period (separator)
+    #    => mmm | last month's abbreviated month name
+    #
+    # -------------------
+    # Example 1 (Simple)
+    # -------------------
+    #
+    #  returns => 1907.jul
+    #  if this month is => August 2019
+    #
+    # ----------------------
+    # Example 2 (Last Year)
+    # ----------------------
+    #
+    #  returns => 1812.dec
+    #  if this month is => January 2019
+    #
+    def self.yymo_mmm_prev
+      return previous_month_chars mo.to_i, yyyy.to_i
+    end
+
+
+    # Return 5 digit amalgam of year and julian day.
+    #  eg [19003] for [January 3rd 2019]
+    def self.yyjjj
+      return "#{yy}#{jjj}"
+    end
+
+
+    # Return the 4 digit amalgam of the hour and minute
+    # using the 24 hour clock.
+    #
+    # @example
+    #   => 1525
+    #   => 03:25 pm
+    #
+    def self.hhmm
+      return "#{hh}#{mm}"
+    end
+
+
+    #
+    # Return the time of day to a TENTH of a second accuracy.
+    # [8] characters will always be returned with the 5th one
+    # being the (period) separator.
+    #
+    # The first (separated) segment delivers a hhmm 24 hour
+    # clock representation of the stamped time.
+    #
+    # The 3 digits of the second segment comprise of
+    #
+    #   second of minute => 2 digits | [00] to [59]
+    #   tenth of second  => 1 digit from [0] to [9]
+    #
+    # @example
+    #   => The time at the 562nd millisecond  of the 49th
+    #      second of the 23rd minute of the 17th hour of
+    #      the day ( 17:23:49.562 )
+    #
+    #   => 8 chars
+    #   => 1723.495
+    #
+    def self.hhmm_sst
+      return "#{hhmm}.#{sst}"
+    end
+
+
+    # Return a string timestampt that is a period separated
+    # amalgam of the 2 digit year, 3 digit julian day, 2 digit
+    # hour, 2 digit minute, 2 digit second and 1 digit rounded
+    # down tenth of second.
+    #
+    # @example
+    #   => 19003.1025
+    #   => 10:25 am on January 3rd 2019
+    #
+    #
+    # Return the time of day to a TENTH of a second accuracy.
+    # [8] characters will always be returned with the 5th one
+    # being the (period) separator.
+    #
+    # The first (separated) segment delivers a hhmm 24 hour
+    # clock representation of the stamped time.
+    #
+    # The 3 digits of the second segment comprise of
+    #
+    # - second of minute => 2 digits | [00] to [59]
+    # - tenth of second  => 1 digit from [0] to [9]
+    #
+    # @example
+    #   => The time at the 562nd millisecond  of the 49th
+    #      second of the 23rd minute of the 17th hour of
+    #      the day ( 17:23:49.562 )
+    #
+    #   => 8 chars
+    #   => 1723.495
+    #
+    def self.yyjjj_hhmm_sst
+      return "#{yyjjj}.#{hhmm}.#{sst}"
+    end
+
+
+    # Return a string timestampt that is a period separated
+    # amalgam of the 2 digit year, 3 digit julian day, 2 digit
+    # hour, 2 digit minute, 2 digit second and <b>9 digit</b>
+    # nanosecond.
+    #
+    # @example
+    #   return  => 19003.1725.42.836592034
+    #   4 time  => 17:25:42 am on January 3rd 2019
+    #
+    # As per the above example, the time returned
+    #
+    # - is the 836592034 <b>nanosecond</b>
+    # - of the 42nd <b>second</b>
+    # - of the 25th <b>minute</b>
+    # - of the 17th <b>hour</b>
+    # - of the 3rd <b>day</b>
+    # - of the 20th <b>year</b>
+    # - of the 21st <b>century</b>
+    #
+    # @return [String]
+    #    Return the time of day to nanosecond accuracy.
+    #    23 characters are always returned with three (3) period
+    #    separators at the 6th, 11th and 14th positions.
+    def self.yyjjj_hhmm_ss_nanosec
+      nanosec_str = KeyNow.instance.time_now.strftime "%9N"
+      return "#{yyjjj}.#{hhmm}.#{ss}.#{nanosec_str}"
+    end
+
+
+    # Fetch the double barreled time stamp that is an amalgam of
+    # the human readable time now and a machine time representation
+    # from the moment this class was initialized.
+    #
+    # See the {yyjjj_hhmm_ss_nanosec} method for documentation of
+    # the nanosecond accurate time stamp.
+    #
+    # @return [String]
+    #    the double barreled time stamp containing a human readable
+    #    (right this moment) time and a <b>class initialized time</b>
+    #    representation with nanosecond accuracy.
+    def self.fetch
+      return "#{Time.now.ctime} ( #{yyjjj_hhmm_ss_nanosec} )"
+    end
+
+
+    # Grab the double barreled time stamp that is an amalgam of
+    # the human readable time now and a machine time representation
+    # from the moment this class was initialized.
+    #
+    #    On Friday June the 8th at about 6:26 pm.
+    #    Fri Jun 8 18:26:17 2018 ( 18159.1826.138 )
+    #
+    # See the {yyjjj_hhmm_sst} method for documentation of stamp
+    # that is accurate to the tenth of a second.
+    #
+    # @return [String]
+    #    the double barreled time stamp containing a human readable
+    #    (right this moment) time and a <b>class initialized time</b>
+    #    representation with tenth of a second accuracy.
+    def self.grab
+      time_with_consecutive_spaces = Time.now.ctime
+      human_readable_str = time_with_consecutive_spaces.gsub( "  ", " " )
+      return "#{human_readable_str} ( #{yyjjj_hhmm_sst} )"
+    end
+
+
+    # Return the Rubyfied time zone being used.
+    def self.zone
+      return KeyNow.instance.time_now.zone
+    end
+
+
+    # Log segments of time pertaining to the time stamp.
+    # @todo
+    #    move method contents into test class
+    def self.log_instance_time
+
+      log.info(x) { "[stamp] -------------- => -------------------------------- #" }
+      log.info(x) { "[stamp] eco time stamp => [#{KeyNow.instance.time_now.ctime}]" }
+      log.info(x) { "[stamp] -------------- => -------------------------------- #" }
+      log.info(x) { "[stamp] Univ Time Zone => #{zone}"  }
+      log.info(x) { "[stamp] Month Index is => #{mo}"    }
+      log.info(x) { "[stamp] Month Name is  => #{mmm}"   }
+      log.info(x) { "[stamp] Day Of Week is => #{ddd}"   }
+      log.info(x) { "[stamp] -------------- => -------------------------------- #" }
+      log.info(x) { "[stamp] Two Digit Year => #{yy}"    }
+      log.info(x) { "[stamp] Julian Cal Day => #{jjj}"   }
+      log.info(x) { "[stamp] Yr and Jul Day => #{yyjjj}" }
+      log.info(x) { "[stamp] Hour of Theday => #{hh}"    }
+      log.info(x) { "[stamp] Minute of Hour => #{mm}"    }
+      log.info(x) { "[stamp] Hour + Minute  => #{hhmm}"  }
+      log.info(x) { "[stamp] Second of Min  => #{ss}"    }
+      log.info(x) { "[stamp] 600 Min Slices => #{sst}"   }
+      log.info(x) { "[stamp] -------------- => -------------------------------- #" }
+      log.info(x) { "[stamp] The Time Stamp => #{yyjjj_hhmm_sst}" }
+      log.info(x) { "[stamp] -------------- => -------------------------------- #" }
+
+    end
+
+
+    # This singleton (one instance) class sets the time just once.
+    def initialize
+      @time_now = Time.now;
+    end
+
+
+    KeyNow.log_instance_time
+
+
+  end
+
+
+end