opensecret 0.0.9925 → 0.0.9949

data/lib/keytools/kdf.api.rb

@@ -28,9 +28,8 @@ module OpenKey
   # == How to Create the Encryption Key
   #
   # To create a high entropy encryption key this method takes the first
-  # 168 bits from the 186 bit BCrypt key produced by {KdfBCrypt} and
-  # the first 96 bits from the 132 bit PBKDF2 key produced inside the
-  # {KeyPbkdf2} class and amalgamates them to produce a 264 bit key.
+  # 168 bits from the 186 bit BCrypt key and the first 96 bits from the
+  # 132 bit PBKDF2 key and amalgamates them to produce a 264 bit key.
   #
   # The 264 bit key is then digested to produce a 256bit encryption key.
   class KdfApi
@@ -51,7 +50,7 @@ module OpenKey
 
 
     # To create a high entropy encryption key we use the full 180 bits
-    # from the returned 180 bit BCrypt key produced by {KdfBCrypt}.
+    # from the returned 180 bit BCrypt key.
     #
     # When amalgamated with the <b>332 bits from the PBKDF2 Key</b> we
     # achieve a powerful <b>union key length</b> of 512 bits.
@@ -67,8 +66,8 @@ module OpenKey
 
 
     # To create a high entropy encryption key we use the full 180 bits
-    # from the returned 180 bit BCrypt key produced by {KdfBCrypt} and
-    # the first 332 bits from the 384 bit key returned by PBKDF2.
+    # from the returned 180 bit BCrypt key and the first 332 bits from
+    # the 384 bit PBKDF2 key.
     #
     # On amalgamation, the outcome is a quality <b>union key length</b>
     # of <b>512 bits</b>.
@@ -107,19 +106,14 @@ module OpenKey
     # that exists to convert <b>low entropy</b> human generated passwords into a high
     # entropy key that is computationally infeasible to acquire through brute force.
     #
-    # To create a high entropy encryption key we use the full 180 bits
-    # from the returned 180 bit BCrypt key produced by {KdfBCrypt} and
-    # the first 332 bits from the 384 bit key returned by PBKDF2.
-    #
     # On amalgamation, the outcome is a quality <b>union key length</b>
     # of <b>512 bits</b>.
     #
     # == Creating a High Entropy Encryption Key
     #
     # To create a high entropy encryption key this method takes the first
-    # 168 bits from the 186 bit BCrypt key produced by {KdfBCrypt} and
-    # the first 96 bits from the 132 bit PBKDF2 key produced inside the
-    # {KeyPbkdf2} class and amalgamates them to produce a 264 bit key.
+    # 168 bits from the 186 bit BCrypt and the first 96 bits from the 132
+    # bit PBKDF2 key and amalgamates them to produce a 264 bit key.
     #
     # Note that all four of the above numbers are divisable by six (6), for
     # representation with a 64 character set, and eight (8), for transport
@@ -206,8 +200,8 @@ module OpenKey
 
     def self.derive_and_amalgamate( human_secret, bcrypt_salt, pbkdf2_salt )
 
-      bcrypt_key = OpenKey::KdfBCrypt.generate_key( human_secret, bcrypt_salt )
-      pbkdf2_key = OpenKey::KeyPbkdf2.generate_key( human_secret.reverse, pbkdf2_salt )
+      bcrypt_key = KdfBCrypt.generate_key( human_secret, bcrypt_salt )
+      pbkdf2_key = KeyPbkdf2.generate_key( human_secret.reverse, pbkdf2_salt )
 
       assert_bcrypt_key_bit_length bcrypt_key
       assert_pbkdf2_key_bit_length pbkdf2_key

data/lib/keytools/kdf.bcrypt.rb

@@ -3,7 +3,6 @@
 
 module OpenKey
 
-
   # BCrypt is a <b>Blowfish based Key Derivation Function (KDF)</b> that exists to
   # convert <b>low entropy</b> human created passwords into a high entropy key that
   # is computationally infeasible to acquire through brute force.
@@ -24,6 +23,25 @@ module OpenKey
   # <b>A cost of 16 will result in 2^16 = 65,536 iterations</b> and will slow the
   # derivation time to about a second on a powerful 2020 laptop.
   #
+  # == BCrypt Cost Iteration Timings on an Intel i-5 Laptop
+  #
+  # The benchmark timings were incredibly consistent and
+  # took almost exactly twice as long for every step.
+  #
+  # An IBM ThinkPad was used to generate the timings.
+  #
+  #    Memory RAM ~> 15GiB
+  #    Processors ~> Intel(R) Core(TM) i5-7200U CPU @ 2.50GHz
+  #
+  # The timing results (for 2 steps) multiplied by four (4).
+  #
+  #    3.84 seconds for 2^16 (65,536) iterations
+  #    0.96 seconds for 2^14 (16,384) iterations
+  #    0.24 seconds for 2^12 ( 4,096) iterations
+  #    0.06 seconds for 2^10 ( 1,024) iterations
+  #
+  # A double digit iteration cost must be provided to avoid
+  # an in-built failure trap. The default cost is now 10.
   class KdfBCrypt
 
     require "bcrypt"
@@ -32,13 +50,31 @@ module OpenKey
     # two so if the iteration integer is 12 there will be two
     # to the power of 12 ( 2^12 ) giving 4096 iterations.
     # The minimum number is 4 (16 iterations) and the max is 31.
+    #
     # @example
     #    Configuring 16 into this directive results in
     #       2^16 = 65,536 iterations
     #
-    #    This is a safe default and will slow the derivation time
-    #    to about a second on a powerful 2020 laptop.
-    BCRYPT_ITERATION_INTEGER = 16
+    # == BCrypt Cost Iteration Timings on an Intel i-5 Laptop
+    #
+    # The benchmark timings were incredibly consistent and
+    # took almost exactly twice as long for every step.
+    #
+    # An IBM ThinkPad was used to generate the timings.
+    #
+    #    Memory RAM ~> 15GiB
+    #    Processors ~> Intel(R) Core(TM) i5-7200U CPU @ 2.50GHz
+    #
+    # The timing results (for 2 steps) multiplied by four (4).
+    #
+    #    3.84 seconds for 2^16 (65,536) iterations
+    #    0.96 seconds for 2^14 (16,384) iterations
+    #    0.24 seconds for 2^12 ( 4,096) iterations
+    #    0.06 seconds for 2^10 ( 1,024) iterations
+    #
+    # A double digit iteration cost must be provided to avoid
+    # an in-built failure trap. The default cost is now 10.
+    BCRYPT_ITERATION_INTEGER = 10
 
     # The bcrypt algorithm produces a key that is 181 bits in
     # length. The algorithm then converts the binary 181 bits
@@ -46,13 +82,11 @@ module OpenKey
     #
     # 181 / 6 = 30 remainder 1 (so 31 characters are needed).
     BCRYPT_KEY_LENGTH = 31
-    
 
     # BCrypt key derivation (from text) implementations truncate
     # the first 55 characters of the incoming text.
     BCRYPT_MAX_IN_TEXT_LENGTH = 55
 
-
     # The BCrypt algorithm produces 181 raw binary bits which is just
     # one bit more than a 30 character base64 string. Hence the algorithm
     # puts out 31 characters.
@@ -60,7 +94,6 @@ module OpenKey
     # We discard the 31st character because 5 of its 6 bits are 100%
     # predictable. Thus the returned key will contribute 180 bits.
     BCRYPT_KEY_EXPORT_BIT_LENGTH = 180
-
     
     # The BCrypt algorithm salt string should be 22 characters
     # and may include forward slashes and periods.
@@ -134,15 +167,15 @@ module OpenKey
     #    same form to the {generate_key} method.
     def self.generate_bcrypt_salt
 
-      the_salt_str = BCrypt::Engine.generate_salt( BCRYPT_ITERATION_INTEGER )
-      bcrypt_salt = the_salt_str[ BCRYPT_OUTPUT_TEXT_PREFIX.length .. -1 ]
-      assert_bcrypt_salt bcrypt_salt
-      return bcrypt_salt
+      full_bcrypt_salt = BCrypt::Engine.generate_salt( BCRYPT_ITERATION_INTEGER )
+      main_bcrypt_salt = full_bcrypt_salt[ BCRYPT_OUTPUT_TEXT_PREFIX.length .. -1 ]
+      keep_bcrypt_salt = "#{BCRYPT_ITERATION_INTEGER}#{main_bcrypt_salt}"
+      assert_bcrypt_salt( keep_bcrypt_salt )
+      return keep_bcrypt_salt
 
     end
 
 
-
     # Key generators should first use the {generate_salt} method to create
     # a BCrypt salt string and then submit it to this method together with
     # a human generated password in order to derive a key.
@@ -181,16 +214,18 @@ module OpenKey
     #    predictable. Thus the returned key will contribute 180 bits.
     def self.generate_key human_secret, bcrypt_salt
 
+      iteration_int = bcrypt_salt[ 0 .. 1 ]
+      bcrypt_prefix = "$2x$#{iteration_int}$"
+      full_salt_str = bcrypt_prefix + bcrypt_salt[ 2 .. -1 ]
+
       assert_bcrypt_salt( bcrypt_salt )
-      full_bcrypt_salt = BCRYPT_OUTPUT_TEXT_PREFIX + bcrypt_salt
-      hashed_secret = BCrypt::Engine.hash_secret( human_secret, full_bcrypt_salt )
-      encoded64_key = BCrypt::Password.new( hashed_secret ).to_s
 
+      hashed_secret = BCrypt::Engine.hash_secret( human_secret, full_salt_str )
+      encoded64_key = BCrypt::Password.new( hashed_secret ).to_s
       key_begin_index = BCRYPT_OUTPUT_TEXT_PREFIX.length + BCRYPT_SALT_LENGTH
       radix64_key_str = encoded64_key[ key_begin_index .. -1 ]
       key_length_mesg = "The BCrypt key length should have #{BCRYPT_KEY_LENGTH} characters."
       raise RuntimeError, key_length_mesg unless radix64_key_str.length == BCRYPT_KEY_LENGTH
-
       chopped_radix64_key = radix64_key_str.chop()
 
       return Key.from_radix64( chopped_radix64_key )
@@ -198,14 +233,29 @@ module OpenKey
     end
 
 
-
     private
 
 
+    # ---
+    # --- Timings Code
+    # ---
+    # --- chopped_radix64_key = NIL
+    # --- require 'benchmark'
+    # --- timings = Benchmark.measure {
+    # ---
+    # ---     -- wrapped up code block
+    # ---
+    # --- }
+    # ---
+    # --- log.info(x) { "BCrypt key generation timings ~> #{timings}" }
+    # ---
+
+
     def self.assert_bcrypt_salt the_salt
       raise RuntimeError, "bcrypt salt not expected to be nil." if the_salt.nil?
-      salt_length_msg = "A bcrypt salt is expected to contain #{BCRYPT_SALT_LENGTH} characters."
-      raise RuntimeError, salt_length_msg unless the_salt.length == BCRYPT_SALT_LENGTH
+      bcrypt_total_length = 2 + BCRYPT_SALT_LENGTH
+      salt_length_msg = "BCrypt salt #{the_salt} is #{the_salt.length} and not #{bcrypt_total_length} characters."
+      raise RuntimeError, salt_length_msg unless the_salt.length == bcrypt_total_length
     end
 
 

data/lib/keytools/kdf.pbkdf2.rb

@@ -25,6 +25,32 @@ module OpenKey
   # The difficulty is in detecting the operating system's C libraries that are directly
   # accessed for OpenSSL functionality. If the distinction can be made accurately, those
   # with newer libraries can reap the benefits immediately.
+  #
+  # == PBKDF2 Cost Iteration Timings on an Intel i-5 Laptop
+  #
+  # An IBM ThinkPad was used to generate the timings.
+  #
+  #    Memory RAM ~> 15GiB
+  #    Processors ~> Intel(R) Core(TM) i5-7200U CPU @ 2.50GHz
+  #
+  # The timing results show that a prudent value is somewhere
+  # between one hundred thousand and ten million iterations.
+  #
+  #    9.6   seconds for 10,000,000 ten million iterations
+  #    0.96  seconds for  1,000,000 one million iterations
+  #    0.096 seconds for    100,000 one hundred thousand iterations
+  #
+  # Open key sets iteration counts for PBKDF2 in hexadecimal and
+  # a valid range starts at 1 and counts up in chunks of a hundred
+  # thousand (100,000).
+  #
+  #      1    ~>      100,000
+  #      5    ~>      500,000
+  #      10   ~>    1,000,000
+  #      16   ~>   16,000,000
+  #      256  ~>  256,000,000
+  #
+  # The maximum iteration multiplier allowed is 16,384.
   class KeyPbkdf2
 
 
@@ -32,7 +58,31 @@ module OpenKey
     # growth of <b>GPU driven cloud based computing</b> power
     # that is curently being honed by mining BitCoin and training
     # neural networks.
-    PBKDF2_ITERATION_COUNT = 1000000
+    #
+    # == PBKDF2 Cost Iteration Timings on an Intel i-5 Laptop
+    #
+    # An IBM ThinkPad was used to generate the timings.
+    #
+    #    Memory RAM ~> 15GiB
+    #    Processors ~> Intel(R) Core(TM) i5-7200U CPU @ 2.50GHz
+    #
+    # The timing results show that a prudent value is somewhere
+    # between one hundred thousand and ten million iterations.
+    #
+    # Open key sets iteration counts for PBKDF2 in hexadecimal and
+    # a valid range starts at 1 and counts up in chunks of a hundred
+    # thousand (100,000).
+    #
+    #      1    ~>      100,000
+    #      5    ~>      500,000
+    #      10   ~>    1,000,000
+    #      16   ~>   16,000,000
+    #      256  ~>  256,000,000
+    PBKDF2_ITERATION_MULTIPLIER = 1
+
+    # The quantity used to multiply the iteration multiplier by to
+    # gain the iteration count.
+    ONE_HUNDRED_THOUSAND = 100000
 
 
     # Documentation for this algorithm says this about the key length.
@@ -56,7 +106,6 @@ module OpenKey
     PBKDF2_EXPORT_BIT_LENGTH = PBKDF2_EXPORT_KEY_LENGTH * 8
 
 
-
     # The documented recommended salt length in bytes for the PBKDF2
     # algorithm is between <b>16 and 24 bytes</b>. The setting here is
     # at the upper bound of that range.
@@ -65,26 +114,38 @@ module OpenKey
 
     # Return a random cryptographic salt generated from twenty-four
     # random bytes produced by a secure random number generator. The
-    # returned salt is a Base64 encoded string that can be stored
-    # and given straight into the {KeyPbkdf2.generate_key} method.
+    # returned salt is primarily a Base64 encoded string that can be
+    # stored and then passed to the {KeyPbkdf2.generate_key} method.
+    #
+    #    + ------------ + -------- + ------------ + ------------- +
+    #    |              | Bits     | Bytes        | Base64        |
+    #    | ------------ | -------- | ------------ | ------------- |
+    #    | PBKDF2 Salt  | 192 Bits | 24 bytes     | 32 characters |
+    #    + ------------ + -------- + ------------ + ------------- +
+    #
+    # The leading part of the character sequence indicates the length
+    # of the salt in chunks of 100,000 and is plus sign separated.
     #
-    #   + ------------ + -------- + ------------ + ------------------- +
-    #   |              | Bits     | Bytes        | Base64              |
-    #   | ------------ | -------- | ------------ | ------------------- |
-    #   | PBKDF2 Salt  | 192 Bits | 24 bytes     | 32 characters       |
-    #   + ------------ + -------- + ------------ + ------------------- +
+    #     42+12345678abcdefgh12345678ABCDEFGH ~>  4,200,000 iterations
+    #      9+12345678abcdefgh12345678ABCDEFGH ~>    900,000 iterations
+    #    100+12345678abcdefgh12345678ABCDEFGH ~> 10,000,000 iterations
     #
-    # The returned salt consists of 32 base64 characters which can be
-    # stored and fed into generate key. Before being used, the generate
-    # key method will convert the 32 base64 characters back into a
-    # <b>24 byte binary</b> formatted string.
+    # Note that the generate key method will convert the trailing 32
+    # base64 characters back into a <b>24 byte binary</b> string.
     #
     # @return [String]
-    #    The returned salt consists of 32 base64 characters which can be
-    #    stored and fed into the {KeyPbkdf2.generate_key}. These characters
-    #    represent twenty-four (24) randomly and securely generated bytes.
+    #    a relatively small iteration count multiplier separated from the
+    #    main salt characters by a plus sign. The salt characters will
+    #    consist of 32 base64 characters which can be stored and fed into
+    #    the {generate_key}.
+    #
+    #    These 32 characters are a representation of the twenty-four (24)
+    #    randomly and securely generated bytes.
     def self.generate_pbkdf2_salt
-      return Key64.from_bits( Key.to_random_bits( PBKDF2_SALT_LENGTH_BYTES ) )
+
+      pbkdf2_salt = Key64.from_bits( Key.to_random_bits( PBKDF2_SALT_LENGTH_BYTES ) )
+      return "#{PBKDF2_ITERATION_MULTIPLIER}+#{pbkdf2_salt}"
+
     end
 
 
@@ -136,9 +197,12 @@ module OpenKey
     #    dictionary word or name is the way to generate a powerful key
     #    that has embedded a near 100% entropy rating.
     #
-    # @param pbkdf2_salt [String]
-    #    this parameter salt must consist of 32 base64 characters which
-    #    will be converted into a <b>24 byte binary</b> formatted string.
+    # @param pbkdf2_string [String]
+    #    this is a relatively small iteration count multiplier separated
+    #    from the main salt characters by a plus sign. The salt characters
+    #    will consist of 32 base64 characters which can be stored and fed
+    #    into the {generate_key}.
+    #
     #    The salt string presented here must have either been recently
     #    generated by {generate_pbkdf2salt} or read from a persistence
     #    store and resubmitted here in order to regenerate the same key.
@@ -147,9 +211,16 @@ module OpenKey
     #    a key holder containing the key which can then be accessed via
     #    many different formats. The {Key} returned by this method
     #    encapsulates the derived key with the specified byte count.
-    def self.generate_key human_secret, pbkdf2_salt
+    def self.generate_key human_secret, pbkdf2_string
+
+      KeyError.not_new pbkdf2_string, "PBKDF2 Algorithm Salt"
+      multiplier = pbkdf2_string.split("+")[0].to_i
+      pbkdf2_salt = pbkdf2_string.split("+")[1]
+
+      mult_msg = "Iteration multiplier is an integer from 1 to 16,384 not [#{multiplier}]."
+      raise ArgumentError, mult_msg_msg unless( multiplier > 0 && multiplier < 16385 )
+      iteration_count = multiplier * ONE_HUNDRED_THOUSAND
 
-      KeyError.not_new pbkdf2_salt, "PBKDF2 Algorithm Salt"
       binary_salt = Key.to_binary_from_bit_string( Key64.to_bits( pbkdf2_salt ) )
       err_msg = "Expected salt of #{PBKDF2_SALT_LENGTH_BYTES} bytes not #{binary_salt.length}."
       raise ArgumentError, err_msg unless binary_salt.length == PBKDF2_SALT_LENGTH_BYTES
@@ -157,7 +228,7 @@ module OpenKey
       pbkdf2_key = OpenSSL::PKCS5.pbkdf2_hmac(
         human_secret,
         binary_salt,
-        PBKDF2_ITERATION_COUNT,
+        iteration_count,
         PBKDF2_EXPORT_KEY_LENGTH,
         OpenSSL::Digest::SHA384.new
       )
@@ -167,6 +238,24 @@ module OpenKey
     end
 
 
+    private
+
+
+    # ---
+    # --- Timings Code
+    # ---
+    # --- chopped_radix64_key = NIL
+    # --- require 'benchmark'
+    # --- timings = Benchmark.measure {
+    # ---
+    # ---     -- wrapped up code block
+    # ---
+    # --- }
+    # ---
+    # --- log.info(x) { "PBKDF2 key generation timings ~> #{timings}" }
+    # ---
+
+
   end
 
 

data/lib/keytools/key.api.rb

@@ -2,6 +2,22 @@
 
 module OpenKey
 
+  # Use RubyMine to understand the correlations and dependencies on
+  # this now monolithic class that must be broken up before meaningful
+  # effective and efficient progress can be made.
+  #
+  # ---
+  #
+  # == REFACTOR KEY API TO DRAW OUT POSSIBLY THESE FIVE CONCEPTS.
+  # 
+  # - [1] the safe tty token
+  # - [2] the machine configurations in ~/.config/openkey/openkey.app.config.ini
+  # - [3] the login / logout session crumbs database
+  # - [4] the master content database holding local config, chapters and verses
+  # - [5] the safe databases that unmarshal into either JSON or file content
+  # 
+  # ---
+  # 
   # Use the key applications programming interface to transition the
   # state of three (3) core keys in accordance with the needs of the
   # executing use case.
@@ -93,7 +109,7 @@ module OpenKey
     #
     #    [srn1-apzd]
     #    app.instance.id = crnl-d3my
-    #    keystore.url.id = /home/apollo/abcd/ab-motors-inc
+    #    keystore.url.id = /home/joe/credentials/repo
     #    initialize.time = Fri May 25 11:59:46 2018 ( 18145.1159.462 )
     #
     # @param domain_name [String]
@@ -540,11 +556,11 @@ module OpenKey
     #    are logging out of from the shell on this machine.
     def self.do_logout( domain_name )
 
-      # --> @todo - user should ONLY type in ops logout | without domain name
-      # --> @todo - user should ONLY type in ops logout | without domain name
-      # --> @todo - user should ONLY type in ops logout | without domain name
-      # --> @todo - user should ONLY type in ops logout | without domain name
-      # --> @todo - user should ONLY type in ops logout | without domain name
+      # --> @todo - user should ONLY type in logout | without domain name
+      # --> @todo - user should ONLY type in logout | without domain name
+      # --> @todo - user should ONLY type in logout | without domain name
+      # --> @todo - user should ONLY type in logout | without domain name
+      # --> @todo - user should ONLY type in logout | without domain name
 
 
       # --> ######################
@@ -615,16 +631,97 @@ module OpenKey
     end
 
 
+    # Return a date/time string detailing when the master database was first created.
+    #
+    # @param the_master_db [Hash]
+    #    the master database to inspect = REFACTOR convert methods into a class instance
+    #
+    # @return [String]
+    #    return a date/time string representation denoting when the master database
+    #    was first created.
+    def self.to_db_create_date( the_master_db )
+      return the_master_db[ DB_CREATE_DATE ]
+    end
+
+
+    # Return the domain name of the master database.
+    #
+    # @param the_master_db [Hash]
+    #    the master database to inspect = REFACTOR convert methods into a class instance
+    #
+    # @return [String]
+    #    return the domain name of the master database.
+    def self.to_db_domain_name( the_master_db )
+      return the_master_db[ DB_DOMAIN_NAME ]
+    end
+
+
+    # Return the domain ID of the master database.
+    #
+    # @param the_master_db [Hash]
+    #    the master database to inspect = REFACTOR convert methods into a class instance
+    #
+    # @return [String]
+    #    return the domain ID of the master database.
+    def self.to_db_domain_id( the_master_db )
+      return the_master_db[ DB_DOMAIN_ID ]
+    end
+
+
+    # Return a dictionary containing a string key and the corresponding master database
+    # value whenever the master database key starts with the parameter string.
+    #
+    # For example if the master database contains a dictionary like this.
+    #
+    #      envelope@earth => { radius => 24034km, sun_distance_light_minutes => 8 }
+    #      textfile@kepler => { filepath => $HOME/keplers_laws.txt, filekey => Nsf8F34dhDT34jLKsLf52 }
+    #      envelope@jupiter => { radius => 852837km, sun_distance_light_minutes => 6 }
+    #      envelope@pluto => { radius => 2601km, sun_distance_light_minutes => 52 }
+    #      textfile@newton => { filepath => $HOME/newtons_laws.txt, filekey => sdDFRTTYu4567fghFG5Jl }
+    #
+    # with "envelope@" as the start string to match.
+    # The returned dictionary would have 3 elements whose keys are the unique portion of the string.
+    #
+    #      earth => { radius => 24034km, sun_distance_light_minutes => 8 }
+    #      jupiter => { radius => 852837km, sun_distance_light_minutes => 6 }
+    #      pluto => { radius => 2601km, sun_distance_light_minutes => 52 }
+    #
+    # If no matches are found an empty dictionary is returned.
+    #
+    # @param the_master_db [Hash]
+    #    the master database to inspect = REFACTOR convert methods into a class instance
+    #
+    # @param start_string [String]
+    #    the start string to match. Every key in the master database that
+    #    starts with this string is considered a match. The corresponding value
+    #    of each matching key is appended onto the end of an array.
+    #
+    # @return [Hash]
+    #    a dictionary whose keys are the unique (2nd) portion of the string with corresponding
+    #    values and in no particular order.
+    def self.to_matching_dictionary( the_master_db, start_string )
+
+      matching_dictionary = {}
+      the_master_db.each_key do | db_key |
+        next unless db_key.start_with?( start_string )
+        dictionary_key = db_key.gsub( start_string, "" )
+        matching_dictionary.store( dictionary_key, the_master_db[db_key] )
+      end
+      return matching_dictionary
+
+    end
+
+
     # To read the content we first find the appropriate shell key and the
-    # appropriate database ciphertext, one decrypts the other to produce the index
-    # database crypt key and that decrypts the current database's ciphertext to
-    # reveal the database in plaintext.
+    # appropriate database ciphertext, one decrypts the other to produce the master
+    # database decryption key which in turn reveals the JSON representation of the
+    # master database.
     #
-    # The plaintext is deserialized into a data structure and returned.
+    # The master database JSON is deserialized as a {Hash} and returned.
     #
-    # <b>Steps Taken To Read the Content</b>
+    # <b>Steps Taken To Read the Master Database</b>
     #
-    # Reading the content requires a rostra of actions namely
+    # Reading the master database requires a rostra of actions namely
     #
     # - reading the path to the <b>keystore breadcrumbs file</b>
     # - using the session token to derive the (unique to the) shell key
@@ -632,10 +729,19 @@ module OpenKey
     # - reading the encrypted and encoded content, decoding and decrypting it
     # - employing index key, ciphertext and random iv to reveal the content
     #
+    # @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]
     #    decode, decrypt and hen return the plain text content that was written
     #    to a file by the {write_content} method.
-    def self.read_app_content()
+    def self.read_master_db( use_grandparent_pid = false )
 
       # --
       # -- Get the filepath to the breadcrumbs file using the trail in
@@ -652,7 +758,7 @@ module OpenKey
       # --
       # -- Regenerate intra-session key from the session token.
       # --
-      intra_key = KeyLocal.regenerate_shell_key( to_token() )
+      intra_key = KeyLocal.regenerate_shell_key( to_token(), use_grandparent_pid )
 
       # --
       # -- Decrypt and acquire the content enryption key that was created
@@ -674,10 +780,10 @@ module OpenKey
       # --
       # -- Get the full ciphertext file (warts and all) and then top and
       # -- tail until just the valuable ciphertext is at hand. Decode then
-      # -- decrypt the ciphertext and instantiate a key database from it.
+      # -- decrypt the ciphertext and instantiate a key database from the
+      # -- resulting JSON string.
       # --
       crypt_txt = binary_from_read( crypt_filepath )
-
       json_content = power_key.do_decrypt_text( random_iv, crypt_txt )
 
       return KeyDb.from_json( json_content )
@@ -709,8 +815,8 @@ module OpenKey
     #    method and the resulting content will be encrypted and written to
     #    the file at path {content_ciphertxt_file_from_session_token}.
     #
-    #    This method's mirror is {read_app_content}.
-    def self.write_app_content( content_header, app_database )
+    #    This method's mirror is {read_master_db}.
+    def self.write_master_db( content_header, app_database )
 
       # --
       # -- Get the filepath to the breadcrumbs file using the trail in
@@ -918,13 +1024,9 @@ module OpenKey
       crypt_txt = binary_from_read( content_path )
       random_iv = KeyIV.in_binary( crumbs_map[ CONTENT_RANDOM_IV ] )
       crypt_key = Key.from_char64( crumbs_map[ CONTENT_ENCRYPT_KEY ] )
-      json_text = crypt_key.do_decrypt_text( random_iv, crypt_txt )
+      text_data = crypt_key.do_decrypt_text( random_iv, crypt_txt )
 
-      # --
-      # -- The decrypted content is expected to be a tree data structure
-      # -- streamed into JSON before encryption.
-      # --
-      return KeyDb.from_json( json_text )
+      return text_data
 
     end
 
@@ -967,7 +1069,7 @@ module OpenKey
     #    and if it exists we assert that the content filepath should also
     #    be present.
     #
-    def self.content_exists?( crumbs_map )
+    def self.db_envelope_exists?( crumbs_map )
 
       return false if crumbs_map.nil?
       return false unless crumbs_map.has_key?( CONTENT_EXTERNAL_ID )
@@ -1028,13 +1130,17 @@ module OpenKey
     private
 
 
+    # --------------------------------------------------------
+    # In order to separate keys into a new gem we must
+    # break knowledge of this variable name and have it
+    # instead passed in by clients.
+    TOKEN_VARIABLE_NAME = "SAFE_TTY_TOKEN"
+    TOKEN_VARIABLE_SIZE = 152
+    # --------------------------------------------------------
 
-    MACHINE_CONFIG_FILE = File.join( Dir.home, ".config/openkey/openkey.app.config.ini" )
 
+    MACHINE_CONFIG_FILE = File.join( Dir.home, ".config/openkey/openkey.app.config.ini" )
     SESSION_APP_DOMAINS = "session.app.domains"
-    TOKEN_VARIABLE_NAME = "OPEN_SESSION_TOKEN"
-    TOKEN_VARIABLE_SIZE = 150
-
     SESSION_IDENTIFIER_KEY = "session.identifiers"
     KEYSTORE_IDENTIFIER_KEY = "keystore.url.id"
     APP_INSTANCE_ID_KEY = "app.instance.id"
@@ -1072,7 +1178,11 @@ module OpenKey
     CONTENT_FILE_PREFIX = "tree.db"
     CONTENT_EXTERNAL_ID = "content.xid"
     CONTENT_ENCRYPT_KEY = "content.key"
-    CONTENT_RANDOM_IV = "content.iv"
+    CONTENT_RANDOM_IV   = "content.iv"
+
+    DB_CREATE_DATE = "db.create.date"
+    DB_DOMAIN_NAME = "db.domain.name"
+    DB_DOMAIN_ID = "db.domain.id"
 
 
     def self.binary_to_write( to_filepath, content_header, binary_ciphertext )
@@ -1121,9 +1231,9 @@ module OpenKey
       app_id = KeyId.derive_app_instance_identifier( domain_name )
 
       initial_db = KeyDb.new()
-      initial_db.store( "Database Birthday", KeyNow.fetch() )
-      initial_db.store( "App Domain Name", domain_name )
-      initial_db.store( "Application Id", app_id )
+      initial_db.store( DB_CREATE_DATE, KeyNow.fetch() )
+      initial_db.store( DB_DOMAIN_NAME, domain_name )
+      initial_db.store( DB_DOMAIN_ID, app_id )
       return initial_db.to_json
 
     end
@@ -1259,15 +1369,15 @@ module OpenKey
     end
 
 
-    def raise_token_error env_var_name, message
+    def self.raise_token_error env_var_name, message
 
       puts ""
       puts "#{TOKEN_VARIABLE_NAME} environment variable #{message}."
       puts "To instantiate it you can use the below command."
       puts ""
-      puts "$ export OPEN_SESSION_TOKEN=`ops token`"
+      puts "$ export #{TOKEN_VARIABLE_NAME}=`safe token`"
       puts ""
-      puts "ps => those are backticks around `ops token` (not apostrophes)."
+      puts "ps => those are backticks around `safe token` (not apostrophes)."
       puts ""
 
       raise RuntimeError, "#{TOKEN_VARIABLE_NAME} environment variable #{message}."