safedb 0.01.0001

data/lib/keytools/kdf.api.rb

@@ -0,0 +1,243 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module SafeDb
+
+  # The SafeDb 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 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
+
+
+    # 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.
+    #
+    # 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 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>.
+    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.
+    #
+    # 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 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
+    # 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 = 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
+
+      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

@@ -0,0 +1,265 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module SafeDb
+
+  # 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.
+  #
+  # As human generated passwords have a relatively small key space, key derivation
+  # functions must be slow to compute with any implementation.
+  #
+  # BCrypt offers a <b>cost parameter</b> that determines (via the powers of two)
+  # the number of iterations performed.
+  #
+  # If the cost parameter is 12, then 4096 iterations (two to the power of 12) will
+  # be enacted.
+  #
+  # == A Cost of 16 is 65,536 iterations
+  #
+  # 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> 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"
+
+    # The iteration count is determined using the powers of
+    # 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
+    #
+    # == 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
+    # into a (6-bit) Radix64 character.
+    #
+    # 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.
+    #
+    # 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.
+    BCRYPT_SALT_LENGTH = 22
+
+    # BCrypt outputs a single line of text that holds the prefix
+    # then the Radix64 encoded salt and finally the Radix64
+    # encoded hash key.
+    #
+    # The prefix consists of <b>two sections</b> sandwiched within
+    # two dollar <b>$</b> signs at the extremeties and a third dollar
+    # separating them.
+    #
+    # 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 = "$2x$#{BCRYPT_ITERATION_INTEGER}$"
+
+
+    # Key generators should use this method to create a BCrypt salt
+    # string and then call the {generate_key} method passing in the
+    # salt together with a human generated password in order to derive
+    # a key.
+    #
+    # The salt can be persisted and then resubmitted in order to
+    # regenerate the same key in the future.
+    #
+    # For the BCrypt algorithm this method depends on the constant
+    # {BCRYPT_ITERATION_INTEGER} so that two to the power of the
+    # integer is the number of iterations.
+    #
+    # A generated salt looks like this assuming the algorithm version
+    # is 2a and the interation integer is 16.
+    #
+    # <b>$2a$16$nkyYKCwljFRtcif6FCXn3e</b>
+    #
+    # 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_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.
+    #
+    # The salt can be persisted and then resubmitted again to this method
+    # in order to regenerate the same key at any time in the future.
+    #
+    # Generate a binary key from the bcrypt password derivation function.
+    #
+    # This differs from a server side password to hash usage in that we
+    # are interested in the 186bit key that bcrypt produces. This method
+    # returns this reproducible key for use during symmetric encryption and
+    # decryption.
+    #
+    # @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 bcrypt_salt [String]
+    #    the salt string that has either been recently generated via the
+    #    {generate_salt} method or read from a persistence store and
+    #    resubmitted here (in the future) to regenerate the same key.
+    #
+    # @return [Key]
+    #    an {SafeDb::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
+
+      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 )
+
+      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 )
+
+    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?
+      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
+
+
+  end
+
+
+end