opensecret 0.0.9925 → 0.0.9949

data/lib/keytools/key.db.rb

@@ -5,7 +5,7 @@ module OpenKey
 
   require 'json'
 
-  # An envelope knows how to manipulate a JSON backed data structure
+  # 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.
   #
@@ -17,12 +17,12 @@ module OpenKey
   #
   # == JSON is Not Exposed in the Interface
   #
-  # An envelope doesn't expose the data format used in the implementation
+  # 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
   #
-  # An envelope supports operations to <b>read from</b> and <b>write to</b>
+  # 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
@@ -30,7 +30,7 @@ module OpenKey
   #
   # == Hashes as the Primary Data Structure
   #
-  # Envelope extends {Hash} as the core data structure for holding
+  # The key/value database openly extends {Hash} as the data structure for holding
   #
   # - strings
   # - arrays
@@ -93,38 +93,57 @@ module OpenKey
     end
 
 
-    # Fast forward tries to walk down this database tree as far as it can
-    # led by the <b>forward-slash separated</b> tree_path parameter.
+    # Create a new secondary tier map key value entry inside a primary tier
+    # map at the map_key_name location.
     #
-    # It stops the first time it encounters a key within the tree_path that
-    # is not next in line from the currently walked position and returns
-    # the sub tree at its point.
+    # A failure will occur if either the outer or inner keys already exist
+    # without their values being map objects.
     #
-    # @param tree_path [String]
+    # If this method is called against a new empty map, the resulting map
+    # structure will look like the below.
     #
-    #    this is a forward slash separated path that is expected to align
-    #    perfectly with a path down this tree database.
+    #     { outer_keyname ~> { inner_keyname ~> { entry_keyname, entry_value } } }
     #
-    #    The child tree is returned as soon as a dead end is reached where
-    #    the next branch in the tree_path does not correspond to a key at
-    #    the walked position.
+    # @param outer_keyname [String]
     #
-    #    The remaining subtree is returned if the tree_path end is reached.
-    def fast_forward( tree_path )
-
-      KeyError.not_new( tree_path, self )
-
-      ## @todo put a loop here
-      ## @todo put a loop here
-      ## @todo put a loop here
-      ## @todo put a loop here
-      ## @todo put a loop here
-      sub_tree = self[ tree_path ] if self.has_key?( tree_path )
+    #    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 )
 
-      sub_database = KeyDb.new()
-      sub_database.merge!( sub_tree )
+      KeyError.not_new( outer_keyname, self )
+      KeyError.not_new( inner_keyname, self )
+      KeyError.not_new( entry_keyname, self )
+      KeyError.not_new( entry_value,   self )
 
-      return sub_database
+      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
 
@@ -179,6 +198,31 @@ module OpenKey
     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.
     #
@@ -204,6 +248,17 @@ module OpenKey
     # @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
@@ -236,6 +291,16 @@ module OpenKey
     #     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))

data/lib/keytools/key.id.rb

@@ -110,7 +110,7 @@ module OpenKey
     #    It will also be different on this workstation if the application
     #    instance identifier provided is different.
     def self.derive_app_instance_machine_id( app_ref )
-      return derive_identifier( app_ref + KeyMach.derive_machine_identity_string() )
+      return derive_identifier( app_ref + KeyIdent.derive_machine_identifier() )
     end
 
 

data/lib/keytools/key.ident.rb

@@ -0,0 +1,243 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module OpenKey
+
+  # This class knows how to derive information from the machine environment to aide
+  # in producing identifiers unique to the machine and/or workstation, with functionality
+  # similar to that required by licensing software.
+  #
+  # == Identity is Similar to Licensing Software | Except Deeper
+  #
+  # Deriving the identity string follows similar principles to licensing
+  # software that attempts to determine whether the operating environment
+  # is the same or different. But it goes deeper than licensing software
+  # as it is not only concerned about the <b>same workstation</b> - it is
+  # also concerned about <b>the same shell or command line interface</b>.
+  #
+  # == Known Issues
+  #
+  # The dependent macaddr gem is known to fail in scenarios where a
+  # VPN tunnel is active and a tell tale sign is the ifconfig command
+  # returning the tun0 interface rather than "eth0" or something that
+  # resembles "ensp21".
+  #
+  # This is one of the error messages resulting from such a case.
+  #
+  #     macaddr.rb:86 from_getifaddrs undefined method pfamily (NoMethodError)
+  #
+  class KeyIdent
+
+    # 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
+    # a new shell is acquired.
+    #
+    # What is really important is that the <b>shell identity string changes</b> when
+    #
+    # - the <b>command shell</b> changes
+    # - the user <b>switches to another workstation user</b>
+    # - the <b>workstation or machine host</b> is changed
+    # - the user <b>SSH's</b> into another shell
+    #
+    # <b>Unchanged | When Should it Remain Unchanged?</b>
+    #
+    # Remaining <b>unchanged</b> is a feature that is as important and this must
+    # be so when and/or after
+    #
+    # - 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>
+    # - <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 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 [String]
+    #    Return a one line textual shell identity string.
+    #
+    #    As key derivation algorithms enforcing a maximum length may be length may
+    #    be applied, each character must add value so non-alphanumerics (mostly hyphens)
+    #    are cleansed out before returning.
+    def self.derive_shell_identifier( use_grandparent_pid = false )
+
+      require 'socket'
+
+      # -- Ensure that the most significant data points
+      # -- come first just like with numbers.
+
+      identity_text =
+      [
+        get_ancestor_pid( use_grandparent_pid ),
+        get_bootup_id(),
+        Etc.getlogin(),
+        Socket.gethostname()
+      ].join
+
+      return identity_text.to_alphanumeric
+
+    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.
+    #
+    # == Command Used to find the grandparent process ID.
+    #
+    #     $ ps -fp 31870 | awk "/tty/"' { print $3 } '
+    #     $ ps -fp 31870 | awk "/31870/"' { print $3 } '
+    #
+    # The one liner finds the parental process ID of the process with the given
+    # parameter process ID.
+    #
+    #     $ ps -fp 31870
+    #
+    #     UID        PID  PPID  C STIME TTY          TIME CMD
+    #     joe      31870  2618  0 12:55 tty2     00:01:03 /usr/bin/emacs25
+    #
+    # The ps command outputs two (2) lines and **awk** is employed to select the
+    # line containing the already known ID. We then print the 3rd string in the
+    # line which we expect to be the parent PID of the PID.
+    #
+    # == Warning | Do Not Use $PPID
+    #
+    # Using $PPID is fools gold because the PS command itself runs as another
+    # process so $PPID is this (calling) process ID and the number returned is
+    # exactly the same as the parent ID of this process - which is actually the
+    # grandparent of the invoked ps process.
+    #
+    # @param use_grandparent_pid [Boolean]
+    #    Set to true if the grandparent process ID is required and false if
+    #    only the parent process ID should be returned.
+    #
+    # @return [String]
+    #    Return ancestor process ID that belongs to either the parent process
+    #    or the grandparent process.
+    def self.get_ancestor_pid( use_grandparent_pid )
+
+      parental_process_id = Process.ppid.to_s()
+      grandparent_pid_cmd = "ps -fp #{parental_process_id} | awk \"/#{parental_process_id}/\"' { print $3 } '"
+      raw_grandparent_pid = %x[#{grandparent_pid_cmd}]
+      the_grandparent_pid = raw_grandparent_pid.chomp
+
+      log.debug(x) { "QQQQQ ~> QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ" }
+      log.debug(x) { "QQQQQ ~> Request Bool Use GPPID is ~> [[ #{use_grandparent_pid} ]]" }
+      log.debug(x) { "QQQQQ ~> Main Parent Process ID is ~> [[ #{parental_process_id} ]]" }
+      log.debug(x) { "QQQQQ ~> GrandParent Process ID is ~> [[ #{the_grandparent_pid} ]]" }
+      log.debug(x) { "QQQQQ ~> QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ" }
+
+      return ( use_grandparent_pid ? the_grandparent_pid : parental_process_id )
+
+    end
+
+
+    # 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_machine_identifier
+
+      require 'socket'
+
+      identity_text = [
+        Etc.getlogin,
+        get_machine_id(),
+        Socket.gethostname()
+      ].join.reverse
+
+      return identity_text
+
+    end
+
+
+    # If you need to know whether a Linux computer has been rebooted or
+    # you need an identifier that stays the same until the computer reboots,
+    # look no further than the read only (non sudoer accessible) **boot id**.
+    #
+    # 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 bootup ID hash value
+    def self.get_bootup_id
+
+      bootup_id_cmd = "cat /proc/sys/kernel/random/boot_id"
+      bootup_id_str = %x[ #{bootup_id_cmd} ]
+      return bootup_id_str.chomp
+
+    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
+
+
+    # If the system was rebooted on April 23rd, 2018 at 22:00:16 we
+    # expect this method not to return <b>2018-04-23 22:00:16</b>, but
+    # to return the <b>8 least significant digits</b> bootup time
+    # digits which in this case are <b>23220016</b>.
+    #
+    # Investigate all Linux flavours to understand whether this command
+    # works (or is it just Ubuntu). Also does Docker return a sensible
+    # value here?
+    #
+    # This method is not production ready. Not only is the time within
+    # a small range, also the most significant digit can fluctuate up
+    # or down randomly (in  a non-deterministic manner.
+    #
+    # @return [String] the time when the system was booted.
+    def self.get_bootup_time_digits
+
+      boot_time_cmd = "uptime -s"
+      uptime_string = %x[ #{boot_time_cmd} ]
+      return uptime_string.chomp.to_alphanumeric[ 6 .. -1 ]
+
+    end
+
+
+  end
+
+
+end

data/lib/keytools/key.local.rb

@@ -27,20 +27,31 @@ module OpenKey
     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
+    SESSION_TOKEN_SIZE = 128 + 22 + BCRYPT_ITER_COUNT_SIZE
 
 
-    # Given a 150 character session token, what is the index that pinpoints
+    # 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_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
 
 
-    # Instantiate the session by generating a random high entropy shell key
-    # and then generating an obfuscator key which we use to lock the shell
+    # 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.
@@ -73,27 +84,12 @@ module OpenKey
     #    and within the same shell on the same machine.
     def self.generate_shell_key_and_token
 
-      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) { "### #####################################################################" }
-      log.info(x) { "### Caller Details =>> =>> #{caller_details}"                              }
-      log.info(x) { "### #####################################################################" }
-
-
       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 )
 
-      log.info(x) { "BCrypt Salt Create => #{bcrypt_salt_key}" }
-      log.info(x) { "Obfuscate ShellKey => #{obfuscator_key.to_s()}" }
-      log.info(x) { "EncryptedKey Crypt => #{random_key_ciphertext}" }
-      log.info(x) { "Session Token Unit => #{session_token}" }
-
       return session_token
 
     end
@@ -103,17 +99,17 @@ module OpenKey
     # 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 four (4) data points, three (3)
+    # 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
-    # three (3) <b>session token segments</b> described below, and the
+    # four (4) <b>session token segments</b> described below, and the
     # shell identity key described in the {OpenKey::Identifier} class.
     #
-    # The session token is divided up into 3 segments with a total of 150
+    # The session token is divided up into 4 segments with a total of 152
     #  characters.
     #
     #   | -------- | ------------ | ------------------------------------- |
@@ -122,55 +118,36 @@ module OpenKey
     #   |    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   | 150 chars    | Session Token in Environment Variable |
+    #   |  Total   | 152 chars    | Session Token in Environment Variable |
     #   | -------- | ------------ | ------------------------------------- |
     #
-    # <b>How to Regenerate the Shell Key</b>
-    #
-    # The two steps for regenerating the shell key are
-    #
-    # - use the shell identity string and the BCrypt key derivation salt
-    #   in the third segment of the token to regenerate the shell identity
-    #   key.
-    #
-    # - put 3 items through AES 256 decryption to derive the 256 bit shell
-    #   crypt key. The 3 items are the <b>shell identity key</b> derived
-    #   in step 1, the AES IV (initialization vector, in the first segment
-    #   of the token, and the <b>ciphertext in the middle segment</b>.
-    #
     # @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 [OpenKey::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 )
-
-      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) { "### #####################################################################" }
-      log.info(x) { "### Caller Details =>> =>> #{caller_details}"                              }
-      log.info(x) { "### #####################################################################" }
-
+    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 .. -1 ].reverse
+      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 )
-
-      log.info(x) { "BCrypt Salt REGEND => #{bcrypt_salt}" }
-      log.info(x) { "SessionToken REGEN => #{session_token}" }
-      log.info(x) { "Chopped Ciphertext => #{key_ciphertext}" }
-      log.info(x) { "Obfuscate ShellKey => #{obfuscator_key.to_s()}" }
-
+      obfuscator_key = derive_session_crypt_key( bcrypt_salt, use_grandparent_pid )
       regenerated_key = obfuscator_key.do_decrypt_key( key_ciphertext )
 
       return regenerated_key
@@ -219,26 +196,29 @@ module OpenKey
     #
     # @param bcrypt_salt_key [OpenKey::Key]
     #
-    #    Either use the {KdfBCrypt.generate_bcrypt_salt} method to generate
-    #    the salt or retrieve and post in a previously generated salt which
-    #    must hold 22 printable characters.
+    #    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 [OpenKey::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
+    def self.derive_session_crypt_key bcrypt_salt_key, use_grandparent_pid = false
 
-      shell_id_text = KeyMach.derive_shell_identity_string()
+      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
 
-      log.info(x) { "Shell Identity Str => #{shell_id_text}" }
-      log.info(x) { "Shell Id TxtLength => #{shell_id_text.length()}" }
-      log.info(x) { "Truncate Shell Str => #{truncate_text}" }
-      log.info(x) { "Resulting IDString => #{shell_id_trim}" }
-
       return KdfBCrypt.generate_key( shell_id_trim, bcrypt_salt_key )
 
     end
@@ -247,6 +227,19 @@ module OpenKey
     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
@@ -254,8 +247,9 @@ module OpenKey
 
 
     def self.assert_bcrypt_salt_size bcrypt_salt
-      err_msg = "Expected BCrypt salt length of #{BCRYPT_SALT_LENGTH} not #{bcrypt_salt.length}."
-      raise RuntimeError, err_msg unless bcrypt_salt.length == BCRYPT_SALT_LENGTH
+      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