safedb 0.3.1011 → 0.4.1002

data/lib/{keytools/key.ident.rb → utils/identity/machine.id.rb}

@@ -26,11 +26,62 @@ module SafeDb
   #
   #     macaddr.rb:86 from_getifaddrs undefined method pfamily (NoMethodError)
   #
-  class KeyIdent
+  class MachineId
+
+    # This method uses a one-way function to return a combinatorial digested
+    # machine identification string using a number of distinct input parameters
+    # to deliver the characteristic of producing the same identifier for the
+    # same machine, virtual machine, workstation and/or compute element, and
+    # reciprocally, a different one on a different machine.
+    #
+    # The userspace is also a key machine identifier so a different machine user
+    # generates a different identifier when all other things remain equal.
+    #
+    # @return [String]
+    #    a one line textual machine workstation or compute element identifier
+    #    that is (surprisingly) different when the machine user changes.
+    def self.derive_user_machine_id
+
+      require 'socket'
+
+      identity_text = [
+        Etc.getlogin,
+        get_machine_id(),
+        Socket.gethostname()
+      ].join.reverse
+
+      return identity_text
+
+    end
+
+
+    # The machine identifier is a UUID based hash value that is tied to the
+    # CPU and motherboard of the machine. This read-only identifier can be
+    # accessed without sudoer permissions so is perfect for license generators
+    # and environment sensitive software.
+    #
+    # In the modern era of virtualization you should always check the behaviour
+    # of the above identifiers when used inside
+    #
+    # - docker containers
+    # - Amazon EC2 servers (or Azure or GCE)
+    # - vagrant (VirtualBox/VMWare)
+    # - Windows MSGYWIN (Ubuntu) environments
+    # - Kubernetes pods
+    #
+    # @return [String] the machine ID hash value
+    def self.get_machine_id
+
+      machine_id_cmd = "cat /etc/machine-id"
+      machine_id_str = %x[ #{machine_id_cmd} ]
+      return machine_id_str.chomp
+
+    end
+
 
     # This method returns a plaintext string hat is guaranteed to be the same
     # whenever called within the same shell for the same user on the same
-    # workstation, virtual machine, container or SSH session and different whenever
+    # workstation, virtual machine, container or SSH branch and different whenever
     # a new shell is acquired.
     #
     # What is really important is that the <b>shell identity string changes</b> when
@@ -47,7 +98,7 @@ module SafeDb
     #
     # - the <b>user returns to a command shell</b>
     # - the user <b>switches back to using a domain</b>
-    # - the user exits their <b>remote SSH session</b>
+    # - the user exits their <b>remote SSH branch</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 ...
@@ -91,7 +142,7 @@ module SafeDb
     # - Kubernetes pods
     #
     # @return [String] the bootup ID hash value
-    def self.get_bootup_id
+    def self.get_bootup_id()
 
       bootup_id_cmd = "cat /proc/sys/kernel/random/boot_id"
       bootup_id_str = %x[ #{bootup_id_cmd} ]
@@ -100,6 +151,18 @@ module SafeDb
     end
 
 
+    # Logs a list of the last few times that this machine has rebooted.
+    # This log can be useful when used in conjunction with the behaviour
+    # that gets the bootup identifier.
+    def self.log_reboot_times()
+
+      the_cmd = "last reboot"
+      the_str = %x[ #{the_cmd} ]
+      the_str.log_lines()
+
+    end
+
+
     # Return an ancestor process ID meaning return either the parent process
     # ID or the grandparent process ID. The one returned depends on the paremeter
     # boolean value.

data/lib/utils/inspect/inspector.rb

@@ -0,0 +1,81 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+
+# To use this inspector copy and paste this code into any class at any position.
+
+
+# It will print out
+#
+# - the global variables
+# - the class constants
+# - the loaded features
+# - the local variables
+# - the last exception
+# - the command line variables
+#
+# This is extremely handly for troubleshooting
+
+
+=begin
+
+      puts ""
+      puts "QQQ QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ"
+      puts "QQQ ~~~~~~~~~~~~~ Global Variable Array List ~~~~~~~~~~~~~~~~ QQQQQ"
+      puts "QQQ QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ"
+
+      puts global_variables().inspect
+
+      puts "QQQ QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ"
+      puts "QQQ ~~~~~~~~~~~~~ Global Variable Values Printed ~~~~~~~~~~~~~~~~ QQQQQ"
+      puts "QQQ QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ"
+
+      global_variables().sort.each do |name|
+
+        puts "<<< ------------------------------------------------------------------->>>"
+        puts "<<< #{name.to_s} >>>"
+        puts "<<< ------------------------------------------------------------------->>>"
+        next if name.to_s.eql?( "$FILENAME" )
+        global_variable_value = eval "#{name}.inspect"
+        puts "<<< #{global_variable_value}"
+
+      end
+
+      puts ""
+      puts "QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ"
+      puts "QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ"
+      puts ""
+      puts "QQQQQQQQQQQ QQQQQQQQQQ QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ"
+      puts "QQQQQQQQQQQ Bug Finder QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ"
+      puts "QQQQQQQQQQQ QQQQQQQQQQ QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ"
+      puts ""
+      self.instance_variables().map do |attribute|
+        puts "=============================================="
+        puts "----------------------------------------------"
+        puts attribute
+        pp self.instance_variable_get(attribute)
+      end
+      puts "=============================================="
+      puts "QQQQQQQQQQQ QQQQQQQQQQ QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ"
+      puts "QQQQQQQQQQQ QQQQQQQQQQ QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ"
+      puts ""
+      puts "### ------------------------------------"
+      puts "### Inspect View"
+      puts "### ------------------------------------"
+      pp self.inspect
+      puts "### ------------------------------------"
+      puts "QQQQQQQQQQQ QQQQQQQQQQQQQQQ QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ"
+      puts "QQQQQQQQQQQ Local Variables QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ"
+      puts "QQQQQQQQQQQ QQQQQQQQQQQQQQQ QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ"
+
+      local_variables().map do |attribute|
+        puts "=============================================="
+        puts "----------------------------------------------"
+        puts attribute
+        pp binding().local_variable_get(attribute.to_sym)
+      end
+      puts "QQQQQQQQQQQ QQQQQQQQQQQQQQQ QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ"
+
+      puts ""
+
+=end

data/lib/{keytools → utils/kdfs}/kdf.api.rb

@@ -82,12 +82,12 @@ module SafeDb
     #
     # <b>Example | Derive Key from Password</b>
     #
-    #    key_store = KeyPair.new( "/path/to/kdf-salt-data.ini" )
-    #    key_store.use( "peter-pan" )
-    #    human_key = KdfApi.generate_from_password( "my_s3cr3t", key_store )
+    #    data_store = DataMap.new( "/path/to/kdf-salt-data.ini" )
+    #    data_store.use( "peter-pan" )
+    #    human_key = KdfApi.generate_from_password( "my_s3cr3t", data_store )
     #
     #    strong_key = Key.from_random()
-    #    human_key.encrypt_key( strong_key, key_store )
+    #    human_key.encrypt_key( strong_key, data_store )
     #
     #    strong_key.encrypt_file "/path/to/file-to-encrypt.pdf"
     #    strong_key.encrypt_text "I am the text to encrypt."
@@ -149,22 +149,22 @@ module SafeDb
     #    dictionary word or name is the way to generate a powerful key
     #    that has embedded a near 100% entropy rating.
     #
-    # @param key_map [KeyPair]
-    #    The KeyPair storage service must have been initialized and a
-    #    section specified using {KeyPair.use} thus allowing this method
+    # @param data_map [DataMap]
+    #    The DataMap storage service must have been initialized and a
+    #    section specified using {DataMap.use} thus allowing this method
     #    to <b>write key-value pairs</b> representing the BCrypt and
-    #    PBKDF2 salts through the {KeyPair.set} behaviour.
+    #    PBKDF2 salts through the {DataMap.set} behaviour.
     #
     # @return [Key]
     #    the 256 bit symmetric encryption key derived from a human password
     #    and passed through two cryptographic workhorses.
-    def self.generate_from_password human_secret, key_map
+    def self.generate_from_password human_secret, data_map
 
       bcrypt_salt = KdfBCrypt.generate_bcrypt_salt
       pbkdf2_salt = KeyPbkdf2.generate_pbkdf2_salt
 
-      key_map.set( BCRYPT_SALT_KEY_NAME, bcrypt_salt )
-      key_map.set( PBKDF2_SALT_KEY_NAME, pbkdf2_salt )
+      data_map.set( BCRYPT_SALT_KEY_NAME, bcrypt_salt )
+      data_map.set( PBKDF2_SALT_KEY_NAME, pbkdf2_salt )
 
       return derive_and_amalgamate( human_secret, bcrypt_salt, pbkdf2_salt )
 
@@ -175,18 +175,18 @@ module SafeDb
     # generated in the past and with the same salts that were used during
     # the original key derivation process.
     #
-    # @param key_map [Hash]
+    # @param data_map [Hash]
     #    an instantiated and populated hash object containing the salts
     #    which were created in the past during the generation. These are
     #    now vital for a successful regeneration.
     #
     # @return [Key]
     #    the 256 bit symmetric encryption key that was previously generated
-    #    from the secret and the cryptographic salts within the key_map.
-    def self.regenerate_from_salts human_secret, key_map
+    #    from the secret and the cryptographic salts within the data_map.
+    def self.regenerate_from_salts human_secret, data_map
 
-      bcrypt_salt = key_map.get( BCRYPT_SALT_KEY_NAME )
-      pbkdf2_salt = key_map.get( PBKDF2_SALT_KEY_NAME )
+      bcrypt_salt = data_map.get( BCRYPT_SALT_KEY_NAME )
+      pbkdf2_salt = data_map.get( PBKDF2_SALT_KEY_NAME )
 
       return derive_and_amalgamate( human_secret, bcrypt_salt, pbkdf2_salt )
 

data/lib/{keytools/key.local.rb → utils/kdfs/kdfs.rb}

@@ -5,21 +5,21 @@ 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.
+  # the duration of the branch which is between a login and a logout.
   # 
-  # These keys are unique to only one shell session on one workstation
+  # These keys are unique to only one shell 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
+  # The four (4) important entities within the shell are
   #
-  # - an obfuscator key for locking the shell key during a session
+  # - an obfuscator key for locking the shell key during a branch
   # - 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
+  # - a branch id derived by pushing the env var through a one-way function
+  class KeyDerivation
 
 
     # The number of Radix64 characters that make up a valid BCrypt salt.
@@ -32,33 +32,33 @@ module SafeDb
     BCRYPT_ITER_COUNT_SIZE = 2
 
 
-    # The session token comprises of 3 segments with fixed lengths.
+    # The shell 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
+    SHELL_TOKEN_SIZE = 128 + 22 + BCRYPT_ITER_COUNT_SIZE
 
 
-    # Given a 152 character session token, what is the index that pinpoints
+    # Given a 152 character shell 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
+    BCRYPT_SALT_START_INDEX = SHELL_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
+    BCRYPT_SALT_END_INDEX = SHELL_TOKEN_SIZE - 1
 
 
-    # Initialize the session by generating a random high entropy shell token
+    # Initialize the branch 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>
+    # <b>The 3 Shell Token Segments</b>
     #
-    # The session token is divided up into 3 segments with a total of 150
+    # The shell token is divided up into 3 segments with a total of 150
     #  characters.
     #
     #   | -------- | ------------ | ------------------------------------- |
@@ -68,7 +68,7 @@ module SafeDb
     #   |    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 |
+    #   |  Total   | 150 chars    | Shell Token in Environment Variable |
     #   | -------- | ------------ | ------------------------------------- |
     #
     # Why is the <b>16 byte salt and the 80 byte BCrypt ciphertext</b> represented
@@ -80,17 +80,17 @@ module SafeDb
     #
     # @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 redeliver the high entropy branch 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 )
+      obfuscator_key = derive_branch_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 )
+      shell_token = random_key_ciphertext + bcrypt_salt_key.reverse
+      assert_shell_token_size( shell_token )
 
-      return session_token
+      return shell_token
 
     end
 
@@ -100,16 +100,16 @@ module SafeDb
     #
     # 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
+    # of which are embalmed within the 150 character shell 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
+    # four (4) <b>shell 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
+    # The shell token is divided up into 4 segments with a total of 152
     #  characters.
     #
     #   | -------- | ------------ | ------------------------------------- |
@@ -120,25 +120,25 @@ module SafeDb
     #   |    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 |
+    #   |  Total   | 152 chars    | Shell Token in Environment Variable |
     #   | -------- | ------------ | ------------------------------------- |
     #
-    # @param session_token [String]
+    # @param shell_token [String]
     #    a triply segmented (and one liner) text token instantiated by
     #    {self.instantiate_shell_key_and_generate_token} and provided
     #    here ad verbatim.
     #
     # @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 )
+    #    random bytes at the beginning of the shell (cli) branch.
+    def self.regenerate_shell_key( shell_token )
 
-      assert_session_token_size( session_token )
-      bcrypt_salt = session_token[ BCRYPT_SALT_START_INDEX .. BCRYPT_SALT_END_INDEX ].reverse
+      assert_shell_token_size( shell_token )
+      bcrypt_salt = shell_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 )
+      key_ciphertext = shell_token[ 0 .. ( BCRYPT_SALT_START_INDEX - 1 ) ]
+      obfuscator_key = derive_branch_crypt_key( bcrypt_salt )
       regenerated_key = obfuscator_key.do_decrypt_key( key_ciphertext )
 
       return regenerated_key
@@ -146,7 +146,7 @@ module SafeDb
     end
 
 
-    # Derive a <b>short term (session scoped) encryption key</b> from the
+    # Derive a <b>short term (branch scoped) encryption key</b> from the
     # surrounding shell and workstation (machine) environment with an
     # important same/different guarantee.
     #
@@ -157,7 +157,7 @@ module SafeDb
     # - <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
+    # branch identification string using a number of distinct parameters that
     # deliver the important behaviours of changing in certain circumstances
     # and remaining unchanged in others.
     #
@@ -180,7 +180,7 @@ module SafeDb
     # <b>unchanged</b> when
     #
     # - the <b>user returns to a command shell</b>
-    # - the user exits their <b>remote SSH session</b>
+    # - the user exits their <b>remote SSH branch</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 ...
@@ -191,12 +191,12 @@ module SafeDb
     #    previously generated salt which must hold 22 printable characters.
     #
     # @return [SafeDb::Key]
-    #    a digested key suitable for short term (session scoped) use with the
+    #    a digested key suitable for short term (branch 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
+    def self.derive_branch_crypt_key bcrypt_salt_key
 
-      shell_id_text = KeyIdent.derive_shell_identifier()
+      shell_id_text = MachineId.derive_shell_identifier()
       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
@@ -222,9 +222,9 @@ module SafeDb
     # 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
+    def self.assert_shell_token_size shell_token
+      err_msg = "shell token has #{shell_token.length} and not #{SHELL_TOKEN_SIZE} chars."
+      raise RuntimeError, err_msg unless shell_token.length == SHELL_TOKEN_SIZE
     end