opensecret 0.0.962 → 0.0.988

data/lib/keytools/key.data.rb

@@ -0,0 +1,227 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module OpenKey
+
+  require 'inifile'
+
+  # This is a key-value store backed by unencrypted (plain-text) permanent
+  # file-system storage in INI format.
+  #
+  # == Key-Value Pair Groupings
+  #
+  # The key-value pairs can be collated into a
+  #
+  # - custom group with a name specified to methods {read} and {write}
+  # - default group that is accessible via the methods {get} and {put}
+  #
+  # The name given to the default group can be specified to the constructor.
+  # If none is provided the aptly named "default" is used.
+
+
+  # An OpenSession dictionary is a <b>2D (two dimensional) hash</b> data
+  # structure backed by an encrypted file.
+  #
+  # It supports operations to <b>read from</b> and <b>write to</b> a known
+  # filepath and given the correct symmetric encryption key it will
+  #
+  # - decrypt <b>after reading from</b> the file and
+  # - encrypt <b>before writing to</b> the file
+  #
+  # This dictionary extends {Hash} in order to deliver on its core key value
+  # storage and retrieve use cases. Extend this dictionary and provide
+  # context specific methods through constants to read and write context
+  # specific data.
+  #
+  # == The <em>Current</em> Dictionary Section
+  #
+  # This KeyData is <b>two-dimensional</b> so all key-value pairs are stored
+  # under the auspices of a section.
+  #
+  # The KeyData can track the <b>current section</b> for you and all data
+  # exchanges can occur in lieu of a single section if you so wish by using
+  # the provided {put} and {get} methods.
+  #
+  # To employ section management functionality you should pass in a current
+  # <b>section id</b> when creating the dictionary.
+  #
+  # @example
+  #    To use the dictionary in the raw (unextended) format you create
+  #    write and read it like this.
+  #
+  #    ----------------------------------------------------------------------
+  #
+  #    my_dictionary = KeyData.create( "/path/to/backing/file" )
+  #
+  #    my_dictionary["user23"] = {}
+  #    my_dictionary["user23"]["Name"] = "Joe Bloggs"
+  #    my_dictionary["user23"]["Email"] = "joebloggs@example.com"
+  #    my_dictionary["user23"]["Phone"] = "+44 07342 800080"
+  #
+  #    my_dictionary.write( "crypt-key-1234-wxyz" )
+  #
+  #    ----------------------------------------------------------------------
+  #
+  #    my_dictionary = KeyData.create( "/path/to/backing/file", "crypt-key-1234-wxyz" )
+  #    puts my_dictionary.has_key? "user23"   # => true
+  #    puts my_dictionary["user23"].length    # => 3
+  #    puts my_dictionary["user23"]["Email"]  # => "joebloggs@example.com"
+  #
+  #    ----------------------------------------------------------------------
+  class KeyData
+
+
+    # Initialize the key value store and auto write a time stamp that
+    # has nano-second accuracy with a key whose name is gleened from
+    # the constant {KeyData::INIT_TIME_STAMP_NAME}.
+    #
+    # The path to the backing INI file is gleened from the first
+    # backing file path parameter.
+    #
+    # @param backing_file_path [String]
+    #    the expected location of the file-backed key-value store.
+    #    If the folder and/or file do not exist the folder is created
+    #    and then the file is created along with the time stamps.
+    #
+    # @param the_default_group [String]
+    #    the name of the default group. If none is presented this value
+    #    will default to the aptly named "default".
+    def initialize backing_file_path, the_reference
+
+      @file_path = backing_file_path
+      @reference = the_reference
+
+      create_dir_if_necessary
+      put_stamps_if_necessary
+
+    end
+
+
+    # Stash the setting directive and its value into the configuration file
+    # using the default settings group.
+    #
+    # The default settings group is resolved via {Collateral::CONTEXT_NAME}
+    #
+    # @param key_name [String] the name of the key whose value is to be written
+    # @param key_value [String] the data item value of the key specified
+    def put key_name, key_value
+      write @reference, key_name, key_value
+    end
+
+
+    # Stash the setting directive and its value into the configuration file
+    # using the default settings group.
+    #
+    # The default settings group is resolved via {Collateral::CONTEXT_NAME}
+    #
+    # @param key_name [String] the name of the key whose value is to be written
+    # @return [String]
+    #    return the value of the configuration directive in the default group
+    def get key_name
+      read @reference, key_name
+    end
+
+
+    # Write the key/value pair in the parameter into this key/value store's
+    # base file-system backing INI file.
+    #
+    # This method assumes the existence of the backing configuration file at
+    # the @file_path instance variable that was set during initialization.
+    #
+    # Observable value is the written key/value pair within the specified
+    # section. The alternate flows are
+    #
+    # - if the section does not exist it is created
+    # - if the section and key exist the value is inserted or overwritten
+    #
+    # @param section_name [String] name grouping the section of config values
+    # @param key [String] the key name of config directive to be written into the file
+    # @param value [String] value of the config directive to be written into the file
+    #
+    def write section_name, key, value
+
+      config_map = IniFile.new( :filename => @file_path, :encoding => 'UTF-8' )
+      config_map = IniFile.load( @file_path ) if File.file? @file_path
+      config_map[section_name][key] = value
+      config_map.write
+
+    end
+
+
+    # Given the configuration key name and the context name, get the
+    # corresponding key value from the configuration file whose path
+    # is acquired using the {self#get_filepath} method.
+    #
+    # @param key_name [String] the key whose value is to be retrieved
+    #
+    # @return [String] the value configured for the parameter key
+    #
+    # @raise ArgumentError for any one of a long list of reasons that
+    #     cause the key value to not be retrieved. This can range from
+    #     non-existent directories and files, non readable files, incorrect
+    #     configurations right down to missing keys or even missing values.
+    def read section_name, key_name
+
+      raise ArgumentError.new "No configuration file found => [ #{@file_path} ]" unless File.exists? @file_path
+
+      the_text = File.read @file_path
+      raise ArgumentError.new "Configuration file is empty => [ #{@file_path} ]" if the_text.empty?
+
+      the_data = IniFile.load @file_path
+      key_exists = the_data[ section_name ].has_key?( key_name )
+      raise ArgumentError.new "Key [#{key_name}] not found in section [#{section_name}] => #{the_data.to_s}" unless key_exists
+
+      rawvalue = the_data[section_name][key_name]
+      raise ArgumentError.new "Empty value 4 key [#{section_name}][#{key_name}] => #{the_data.to_s}" if rawvalue.empty?
+
+      keyvalue = rawvalue.chomp.strip
+      raise ArgumentError.new "Whitespace value 4 key [#{section_name}][#{key_name}] => #{the_data.to_s}" if keyvalue.empty?
+
+      return keyvalue
+
+    end
+
+
+    # Get the time stamp that was written to the key-value store at
+    # the point it was first initialized and then subsequently written
+    # out (serialized) onto the file-system.
+    #
+    # The time stamp returned marks the first time this key-value store
+    # was conceived by a use case actor and subsequently serialized.
+    #
+    # @return [String]
+    #    the string time stamp denoting the first time this key-value
+    #    store was first initialized and then subsequently written out
+    #    (serialized) onto the file-system.
+    def time_stamp
+      return get INIT_TIME_STAMP_NAME
+    end
+
+
+
+    private
+
+
+
+    def create_dir_if_necessary
+
+      config_directory = File.dirname @file_path
+      return if (File.exist? config_directory) && (File.directory? config_directory)
+      FileUtils.mkdir_p config_directory
+
+    end
+
+
+    def put_stamps_if_necessary
+
+      return if File.file? @file_path
+
+      put INIT_TIME_STAMP_NAME, OpenSession::Stamp.yyjjj_hhmm_ss_nanosec
+
+    end
+
+
+  end
+
+
+end

data/lib/keytools/key.derivation.rb

@@ -0,0 +1,341 @@
+#!/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 {BCryptKeyGen} and
+  # the first 96 bits from the 132 bit PBKDF2 key produced inside the
+  # {Pbkdf2KeyGen} class and amalgamates them to produce a 264 bit key.
+  #
+  # The 264 bit key is then digested to produce a 256bit encryption key.
+  class KeyDerivation
+
+
+    # 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 the first 168 bits from the
+    # 186 bit BCrypt key produced by {BCryptKeyGen} is sliced off and used
+    # as the lead part of the generated key.
+    BCRYPT_KEY_CONTRIBUTION_SIZE = 168
+
+
+    # The first 96 bits from the 132 bit PBKDF2 key produced inside the
+    # {Pbkdf2KeyGen} class is amalgamated to the BCrypt 168 bit key to produce
+    # a 264 bit key.
+    PBKDF2_KEY_CONTRIBUTION_SIZE = 96
+
+
+    AMALGAM_KEY_RAW_BIT_SIZE = BCRYPT_KEY_CONTRIBUTION_SIZE + PBKDF2_KEY_CONTRIBUTION_SIZE
+
+    AMALGAM_KEY_SIX_BIT_COUNT = AMALGAM_KEY_RAW_BIT_SIZE / 6
+
+    AMALGAM_KEY_EIGHT_BYTE_COUNT = AMALGAM_KEY_RAW_BIT_SIZE / 8
+
+ 
+    # To acquire a <b>machine generated symmetric encryption key</b> pass
+    # in a {Key} initialized with {Key.from_random_bytes} and this method
+    # will digest it for extra security and produce a gold standard 256 bit
+    # encryption key ready to use with the AES256 algorithm.
+    #
+    # Do not use the {Key.from_random_bytes} as an encryption key, instead
+    # <b>encrypt and then persist</b> the key if you will need to decrypt the
+    # cipher text at some future date.
+    #
+    # <b>The 48 Bytes map to 64 Base64 Characters</b>
+    #
+    # To re-acquire the key for decryption, <b>read and unencrypt</b> the
+    # <b>64 base64 characters</b> with <b>Key.from_base64</b> and then pass
+    # it again to this method to <b>re-acquire</b> the original symmetric
+    # encryption/decryption key.
+    #
+    #   | -------- | ------------ | -------------------------------- |
+    #   | Bits     | Bytes        | Base64                           |
+    #   | -------- | ------------ | -------------------------------- |
+    #   | 384 Bits | is 48 bytes  | and 64 characters                |
+    #   | 256 Bits | 32 precisely | 43 Chars (42 + 4 remainder bits) |
+    #   | -------- | ------------ | -------------------------------- |
+    #
+    # For <b>simplicity's sake</b>, try to employ a <b>bit length</b> with
+    # a bit count that is a <b>multiple of both 6 and 8</b>. This method mashes
+    # up the raw key and provides you with a powerful 256 bit key.
+    #
+    # @param the_key [OpenKey::Key]
+    #    use <b>Key.from_random_bytes</b> to create a seed whose bit length
+    #    is a <b>multiple of <em>both 6 and 8</em></b>. This method will mash
+    #    up the raw key, thus provisioning a powerful 256 bit encryption key.
+    #
+    # @return [OpenKey::Key]
+    #    the raw key will be mashed up and this method will faithfully return
+    #    a powerful 256 bit encryption key.
+    def self.from_key the_key
+      return Digest::SHA256.digest( Digest::SHA384.digest( the_key.to_binary_bytes ) )
+    end
+
+
+
+    # This method generates a 256 bit symmetric encryption key derived from
+    # a human password and passed through two cryptographic workhorses
+    # (BCrypt and PBKDF2), the best of breed <b>key derivation functions</b>.
+    #
+    # == 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.
+    #
+    # == 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 {BCryptKeyGen} and
+    # the first 96 bits from the 132 bit PBKDF2 key produced inside the
+    # {Pbkdf2KeyGen} 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 | Base64 Chars      | 8 Bit Bytes |
+    #   ----------- | --------- | ----------------- | ----------- |
+    #   | BCrypt    |  168 Bits |   28 characters   |   21 bytes  |
+    #   | Pbkdf2    |   96 Bits |   16 characters   |   12 bytes  |
+    #   ----------- | --------- | ----------------- | ----------- |
+    #   | Total     |  264 Bits |   44 characters   |   33 bytes  |
+    #   ----------- | --------- | ----------------- | ----------- |
+    #
+    # <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 dictionary [Hash]
+    #    an instantiated hash object in which we will write the salts to
+    #    be persisted and regurgitated during the regenerate process.
+    #
+    # @return [Key]
+    #    the 256 bit symmetric encryption key derived from a human password
+    #    and passed through two cryptographic workhorses.
+    def self.from_password human_secret, dictionary
+
+      bcrypt_salt = BCryptKeyGen.generate_salt
+      pbkdf2_salt = Pbkdf2KeyGen.generate_salt
+
+      dictionary.put( BCRYPT_SALT_KEY_NAME, bcrypt_salt )
+      dictionary.put( PBKDF2_SALT_KEY_NAME, pbkdf2_salt )
+
+      return generate_from_secret_and_salts 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 dictionary [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 dictionary.
+    def self.regenerate human_secret, dictionary
+
+      bcrypt_salt = dictionary.get( BCRYPT_SALT_KEY_NAME )
+      pbkdf2_salt = dictionary.get( PBKDF2_SALT_KEY_NAME )
+      return generate_from_secret_and_salts human_secret, bcrypt_salt, pbkdf2_salt
+
+    end
+
+
+    # Derive a <b>short term (session scoped) encryption key</b> from the
+    # surrounding shell execution environment whilst giving two (2) important
+    # guarantees.
+    #
+    # The two guarantees governing the returned key are that it is
+    #
+    # - <b>the same</b> whenever called within this executing shell
+    # - <b>different</b> different when another shell is employed
+    #
+    # The much higher collision rate is tolerable because the key's lifetime
+    # is only <b>as long as commands are being typed into a given shell</b>
+    # or command prompt in the case of Windows.
+    #
+    # This method uses a one-way function to return a combinatorial digested
+    # session identification string using a number of distinct parameters that
+    # deliver the important behaviours of changing in certain circumstances
+    # and remaining unchanged in others.
+    #
+    # <b>Change | When Should the key Change?</b>
+    #
+    # What is really important is that the <b>key changes when</b>
+    #
+    # - the <b>command shell</b> changes
+    # - the workstation <b>shell user is switched</b>
+    # - the host machine <b>workstation</b> is changed
+    # - the user <b>SSH's</b> into another shell
+    #
+    # A distinct workstation is identified by the first MAC address and the
+    # hostname of the machine.
+    #
+    # <b>Unchanged | When Should the Key Remain Unchanged?</b>
+    #
+    # Remaining <b>unchanged</b> in certain scenarios is a feature that is
+    # just as important as changing in others. The key must remain
+    # <b>unchanged</b> when
+    #
+    # - the <b>user returns to a command shell</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 ...
+    #
+    # @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.from_session
+
+      require 'macaddr'
+
+      # Do not change the order of this data because it is reversed and
+      # the parent's shell ID hotly followed by the MAC address are the
+      # most significant data points.
+
+      raw_data_string = [
+        Socket.gethostname,
+        OpenSession::Home.instance.username,
+        Mac.addr.to_alphanumeric,
+        Process.ppid.to_s
+      ].join.reverse
+
+      return Digest::SHA256.digest( Digest::SHA512.digest( raw_data_string ) )
+
+    end
+
+
+
+    private
+
+
+
+    def self.generate_from_secret_and_salts human_secret, bcrypt_salt, pbkdf2_salt
+      bcrypt_key = OpenKey::BCryptKeyGen.generate_key( human_secret, bcrypt_salt )
+      pbkdf2_key = OpenKey::Pbkdf2KeyGen.generate_key( human_secret.reverse, pbkdf2_salt )
+      return merge_then_digest( bcrypt_key, pbkdf2_key )
+
+    end
+
+
+    def self.merge_then_digest bcrypt_key, pbkdf2_key
+
+      assert_bcrypt_key_bit_length bcrypt_key
+      assert_pbkdf2_key_bit_length pbkdf2_key
+
+      raw_key = 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 raw_key
+      assert_amalgam_key_six_bit_count raw_key
+      assert_amalgam_key_eight_bit_count raw_key
+
+      rawbytes_key = [ raw_key.to_s ].pack("B*")
+      digested_key = OpenSSL::Digest::SHA256.new.digest( rawbytes_key )
+      return Key.new ( Base64.urlsafe_encode64( digested_key ) )
+
+    end
+
+
+    def self.assert_bcrypt_key_bit_length bcrypt_key
+      bcrypt_key_bit_length = bcrypt_key.to_s.bytesize
+      bcrypt_keysize_msg = "Expecting #{BCryptKeyGen::BCRYPT_KEY_TRANSPORT_LENGTH} not #{bcrypt_key_bit_length} bits in bcrypt key."
+      raise RuntimeError, bcrypt_keysize_msg unless bcrypt_key_bit_length == BCryptKeyGen::BCRYPT_KEY_TRANSPORT_LENGTH
+    end
+
+
+    def self.assert_pbkdf2_key_bit_length pbkdf2_key
+      pbkdf2_key_bit_length = pbkdf2_key.to_s.bytesize
+      pbkdf2_keysize_msg = "Expecting #{Pbkdf2KeyGen::PBKDF2_KEY_TRANSPORT_LENGTH} not #{pbkdf2_key_bit_length} bits in pbkdf2 key."
+      raise RuntimeError, pbkdf2_keysize_msg unless pbkdf2_key_bit_length == Pbkdf2KeyGen::PBKDF2_KEY_TRANSPORT_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
+
+
+    def self.assert_amalgam_key_six_bit_count amalgam_key
+      amalgam_key_six_bit_length = amalgam_key.to_s.bytesize / 6
+      amalgam_key_six_bit_msg = "Expecting #{AMALGAM_KEY_SIX_BIT_COUNT} six bit blocks not #{amalgam_key_six_bit_length}."
+      raise RuntimeError, amalgam_key_six_bit_msg unless amalgam_key_six_bit_length == AMALGAM_KEY_SIX_BIT_COUNT
+    end
+
+
+    def self.assert_amalgam_key_eight_bit_count amalgam_key
+      amalgam_key_eight_bit_length = amalgam_key.to_s.bytesize / 8
+      amalgam_key_eight_bit_msg = "Expecting #{AMALGAM_KEY_EIGHT_BYTE_COUNT} eight bit blocks not #{amalgam_key_eight_bit_length}."
+      raise RuntimeError, amalgam_key_eight_bit_msg unless amalgam_key_eight_bit_length == AMALGAM_KEY_EIGHT_BYTE_COUNT
+    end
+
+
+  end
+
+
+end