opensecret 0.0.988 → 0.0.9925

data/lib/keytools/binary.map.rb

@@ -234,6 +234,55 @@ cipher.key = key
 
     end
 
+
+    def self.binbytes
+
+      for n in 0 .. 256
+        eight_bit_binary = "%08d" % [ n.to_s(2) ]
+        puts "#{eight_bit_binary} => #{n}"
+      end
+
+    end
+
+
+    def self.shovel
+
+      first_name = "joe"
+      last_name = "bloggs"
+
+      user_name = first_name
+      user_name << last_name
+
+      puts "Username   => #{user_name}"
+      puts "First name => #{first_name}"
+
+    end
+
+
+    def self.print_randoms
+      require 'securerandom'
+      for n in 0 .. 99
+        puts "#{from_rand}"
+      end
+
+    end
+
+
+    def self.from_rand
+      random_bit_string = ""
+      the_ints = Array.new
+      for n in 1 .. 48
+        random_integer = SecureRandom.random_number( 256 )
+        the_ints.push random_integer
+        random_bit_string += "%08d" % [ random_integer.to_s(2) ]
+      end
+      puts "Integers => #{the_ints.to_s}"
+      return random_bit_string
+    end
+
+##    BinaryMap.print_randoms
+##    BinaryMap.shovel
+##    BinaryMap.binbytes
 ##    BinaryMap.binary
 ##    BinaryMap.crypter
 ##    BinaryMap.bcrypter

data/lib/keytools/kdf.api.rb

@@ -0,0 +1,249 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module OpenKey
+
+  # The OpenKey underlying security strategy is to lock a master index file
+  # with a <b>symmetric encryption key</b> that is based on two randomly generated
+  # and amalgamated <b>55 and 45 character keys</b> and then to lock that key
+  # <b>(and only that key)</b> with a 256 bit symmetric encryption key derived from
+  # a human password and generated by at least two cryptographic workhorses known
+  # as <b>key derivation functions</b>.
+  #
+  # Random powerful keys are derived are seeded with 55 random bytes and
+  # then fed through the master key generator and its two key derivation
+  # functions (BCrypt and PBKDF2).
+  #
+  # == What Does the Master Encryption Key Generator Do?
+  #
+  # This class sits at the core of implementing that strategy and works to produce
+  # 256 bit encryption key derived from a human password which is then minced by
+  # two best of breed key derivation functions (BCrypt and PBKDF2).
+  #
+  # BCrypt (Blowfish) and PBKDF2 are the leading <b>key derivation functions</b>
+  # whose modus operandi is to convert <b>low entropy</b> human generated passwords
+  # into a high entropy key that is computationally infeasible to acquire via brute
+  # force.
+  #
+  # == 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.
+  #
+  # The 264 bit key is then digested to produce a 256bit encryption key.
+  class KdfApi
+
+
+    # BCrypt (Blowfish) and PBKDF2 are the leading <b>key derivation functions</b>
+    # whose modus operandi is to convert <b>low entropy</b> human generated passwords
+    # into a high entropy key that is computationally infeasible to acquire via brute
+    # force.
+    BCRYPT_SALT_KEY_NAME = "bcrypt.salt"
+
+ 
+    # BCrypt (Blowfish) and PBKDF2 are the leading <b>key derivation functions</b>
+    # whose modus operandi is to convert <b>low entropy</b> human generated passwords
+    # into a high entropy key that is computationally infeasible to acquire via brute
+    # force.
+    PBKDF2_SALT_KEY_NAME = "pbkdf2.salt"
+
+
+    # To create a high entropy encryption key we use the full 180 bits
+    # from the returned 180 bit BCrypt key produced by {KdfBCrypt}.
+    #
+    # When amalgamated with the <b>332 bits from the PBKDF2 Key</b> we
+    # achieve a powerful <b>union key length</b> of 512 bits.
+    BCRYPT_KEY_CONTRIBUTION_SIZE = 180
+
+
+    # The first 332 bits are used from the 384 bit key returned by the
+    # PBKDF2 algorithm.
+    #
+    # When amalgamated with the <b>180 bits from the BCrypt Key</b> we
+    # achieve a powerful <b>union key length</b> of 512 bits.
+    PBKDF2_KEY_CONTRIBUTION_SIZE = 332
+
+
+    # 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>.
+    AMALGAM_KEY_RAW_BIT_SIZE = BCRYPT_KEY_CONTRIBUTION_SIZE + PBKDF2_KEY_CONTRIBUTION_SIZE
+
+
+    # This method generates a 256 bit symmetric encryption key by passing a
+    # textual human sourced secret into two <b>key derivation functions</b>,
+    # namely <b>BCrypt and PBKDF2</b>. BCrypt, PBKDF2 and SCrypt are today's
+    # <b>in form best of breed</b> cryptographic workhorses for producing a
+    # high entropy key from possibly weak human sourced secret text.
+    #
+    # <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 )
+    #
+    #    strong_key = Key.from_random()
+    #    human_key.encrypt_key( strong_key, key_store )
+    #
+    #    strong_key.encrypt_file "/path/to/file-to-encrypt.pdf"
+    #    strong_key.encrypt_text "I am the text to encrypt."
+    #
+    # ---
+    #
+    # <b>Do not use the key derived from a human secret</b> to encrypt anything
+    # other than a <b>high entropy key</b> randomly sourced from 48 bytes.
+    # 
+    # Every time the user logs in, generate (recycle), another human key and
+    # another strong key and discard the previously outputted cipher texts.
+    #
+    # == BCrypt and the PBKDF2 Cryptographic Algorithms
+    #
+    # BCrypt (Blowfish) and PBKDF2 are the leading <b>key derivation functions</b>
+    # 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.
+    #
+    # 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
+    # via the byte (8 bit) protocols.
+    #
+    # <b>Size of BCrypt and PBKDF2 Derived Keys</b>
+    #
+    #   + --------- - --------- +
+    #   + --------- | --------- +
+    #   | Algorithm | Bit Count |
+    #   ----------- | --------- |
+    #   | BCrypt    |  180 Bits |
+    #   | Pbkdf2    |  332 Bits |
+    #   ----------- | --------- |
+    #   | Total     |  512 Bits |
+    #   + --------- | --------- +
+    #   + --------- - --------- +
+    #
+    # <b>256 Bit Encryption Key | Remove 8 Bits</b>
+    #
+    # The manufactured encryption key, an amalgam of the above now has
+    # 264 bits carried by 44 Base64 characters.
+    #
+    # Just before it is used to encrypt vital keys, eight (8) bits are
+    # removed from the end of the key. The key is then converted into a
+    # powerful 32 byte (256 bit) encryption agent and is hashed by the
+    # SHA256 digest and delivered.
+    #
+    # @param human_secret [String]
+    #    a robust human generated password with as much entropy as can
+    #    be mustered. Remember that 40 characters spread randomly over
+    #    the key space of about 90 characters and not relating to any
+    #    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
+    #    to <b>write key-value pairs</b> representing the BCrypt and
+    #    PBKDF2 salts through the {KeyPair.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
+
+      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 )
+
+      return derive_and_amalgamate( human_secret, bcrypt_salt, pbkdf2_salt )
+
+    end
+
+
+    # Regenerate the viciously unretrievable nor reversable key that was
+    # generated in the past and with the same salts that were used during
+    # the original key derivation process.
+    #
+    # @param key_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
+
+      bcrypt_salt = key_map.get( BCRYPT_SALT_KEY_NAME )
+      pbkdf2_salt = key_map.get( PBKDF2_SALT_KEY_NAME )
+
+      return derive_and_amalgamate( human_secret, bcrypt_salt, pbkdf2_salt )
+
+    end
+
+
+
+    private
+
+
+
+    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 )
+
+      assert_bcrypt_key_bit_length bcrypt_key
+      assert_pbkdf2_key_bit_length pbkdf2_key
+
+      amalgam_key = Key.new ( bcrypt_key.to_s[ 0 .. (BCRYPT_KEY_CONTRIBUTION_SIZE-1) ] + pbkdf2_key.to_s[ 0 .. (PBKDF2_KEY_CONTRIBUTION_SIZE-1) ] )
+
+      assert_amalgam_key_bit_length amalgam_key
+
+      return amalgam_key
+
+    end
+
+
+    def self.assert_bcrypt_key_bit_length bcrypt_key
+      bcrypt_key_bit_length = bcrypt_key.to_s.bytesize
+      bcrypt_keysize_msg = "Expecting #{KdfBCrypt::BCRYPT_KEY_EXPORT_BIT_LENGTH} not #{bcrypt_key_bit_length} bits in bcrypt key."
+      raise RuntimeError, bcrypt_keysize_msg unless bcrypt_key_bit_length == KdfBCrypt::BCRYPT_KEY_EXPORT_BIT_LENGTH
+    end
+
+
+    def self.assert_pbkdf2_key_bit_length pbkdf2_key
+      pbkdf2_key_bit_length = pbkdf2_key.to_s.bytesize
+      pbkdf2_keysize_msg = "Expecting #{KeyPbkdf2::PBKDF2_EXPORT_BIT_LENGTH} not #{pbkdf2_key_bit_length} bits in pbkdf2 key."
+      raise RuntimeError, pbkdf2_keysize_msg unless pbkdf2_key_bit_length == KeyPbkdf2::PBKDF2_EXPORT_BIT_LENGTH
+    end
+
+
+    def self.assert_amalgam_key_bit_length amalgam_key
+
+      amalgam_key_bit_length = amalgam_key.to_s.bytesize
+      amalgam_keysize_msg = "Expecting #{AMALGAM_KEY_RAW_BIT_SIZE} not #{amalgam_key_bit_length} bits in amalgam key."
+      raise RuntimeError, amalgam_keysize_msg unless amalgam_key_bit_length == AMALGAM_KEY_RAW_BIT_SIZE
+    end
+
+
+  end
+
+
+end

data/lib/keytools/kdf.bcrypt.rb

@@ -21,12 +21,10 @@ module OpenKey
   #
   # The <b>minimum cost</b> is 4 (16 iterations) and the maximum is 31.
   #
-  # <b>A cost of 16 will result in 2^16 = 65,536 iterations</b>.
+  # <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.
   #
-  #    This is a safe default and will slow the derivation time
-  #    to about a second on a powerful 2020 laptop.
-  #
-  class BCryptKeyGen
+  class KdfBCrypt
 
     require "bcrypt"
 
@@ -50,20 +48,21 @@ module OpenKey
     BCRYPT_KEY_LENGTH = 31
     
 
-    # When the key is transported using a 64 character set where
-    # each character is represented by 6 bits - the BCrypt key
-    # expands to 186 bits rather than the original 181 bits.
-    #
-    # This expansion is because of the remainder.
-    #
-    #    181 bits divided by 6 is 30 characters plus 1 character
-    #    for the extra bit.
+    # 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.
     #
-    #    The 31 transported characters then appear as
-    #    31 times 6 which equals 186 bits.
-    BCRYPT_KEY_TRANSPORT_LENGTH = 186
+    # 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
+    # The BCrypt algorithm salt string should be 22 characters
     # and may include forward slashes and periods.
     BCRYPT_SALT_LENGTH = 22
 
@@ -78,7 +77,7 @@ module OpenKey
     # The two sections are the
     # - BCrypt algorithm <b>version number</b> (2a or 2b) and
     # - a power of 2 integer defining the no. of interations
-    BCRYPT_OUTPUT_TEXT_PREFIX = "$2a$#{BCRYPT_ITERATION_INTEGER}$"
+    BCRYPT_OUTPUT_TEXT_PREFIX = "$2x$#{BCRYPT_ITERATION_INTEGER}$"
 
 
     # Key generators should use this method to create a BCrypt salt
@@ -101,15 +100,45 @@ module OpenKey
     # This method removes the $2a$16$ preamble string and stores only
     # the actual salt string whose length should be 22 characters.
     #
+    # <b>Why do BCrypt salts always end with zero, e, u or period</b>?
+    #
+    # Two <b>(2) leftover bits</b> is the short answer.
+    #
+    # This is because the salts are a random 16 bytes and must be
+    # stored in base64. The 16 bytes equals 128bits which when converted
+    # to base64 (6bits per character) results in 21 characters and only
+    # two leftover bits.
+    #
+    #    BCrypt Salt => t4bDqoJlHbb/k7bkt4/1Ku (22 characters)
+    #    BCrypt Salt => 9BjuJU67IG9Lz5tYUhOqeO (22 characters)
+    #    BCrypt Salt => grz.QREI35585Y3AaCoCTe (22 characters)
+    #    BCrypt Salt => zsxrVW2RGIltSu.AoS4E7e (22 characters)
+    #    BCrypt Salt => dTlRJZ6ijDDVk2cFoCQHPO (22 characters)
+    #    BCrypt Salt => S9B1azH7oD8L3.CQfxxzJO (22 characters)
+    #    BCrypt Salt => LoZh.q3NdnTIuOmR6gHJF. (22 characters)
+    #    BCrypt Salt => y6DKk23SmgNR863pTZ8nYe (22 characters)
+    #    BCrypt Salt => rokdUF6tg6wHV6F0ymKFme (22 characters)
+    #    BCrypt Salt => jrDpNgh.0OEIYaxsR7E7d. (22 characters)
+    #
+    # Don't forget BCrypt uses Radix64 (from OpenBSD). So the two (2)
+    # leftover bits result in 4 possible values which effectively is
+    #
+    #        a period (.)
+    #        a zero   (0)
+    #        an e     (e)
+    #        or a u   (u)
+    #
     # @return [String]
     #    the salt in a printable format like base64, hex or a string
     #    of ones and zeroes. This salt should be submitted in the exact
     #    same form to the {generate_key} method.
-    def self.generate_salt
+    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
+
     end
 
 
@@ -141,19 +170,30 @@ module OpenKey
     #    resubmitted here (in the future) to regenerate the same key.
     #
     # @return [Key]
-    #    a key holder containing the key which can then be accessed via
-    #    many different formats.
+    #    an {OpenKey::Key} that has been initialized from the 30 RADIX64
+    #    character output from the BCrypt algorithm.
+    #
+    #    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.
+    #
+    #    We discard the 31st character because 5 of its 6 bits are 100%
+    #    predictable. Thus the returned key will contribute 180 bits.
     def self.generate_key human_secret, bcrypt_salt
 
-      hashed_secret = BCrypt::Engine.hash_secret( human_secret, to_bcrypt_salt(bcrypt_salt) )
+      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
 
       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."
+      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
 
-      return Key.new(radix64_key_str)
+      chopped_radix64_key = radix64_key_str.chop()
+
+      return Key.from_radix64( chopped_radix64_key )
 
     end
 
@@ -162,11 +202,6 @@ module OpenKey
     private
 
 
-
-    def self.to_bcrypt_salt the_salt
-      return BCRYPT_OUTPUT_TEXT_PREFIX + the_salt
-    end
-
     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."