opensecret 0.0.988 → 0.0.9925

data/lib/keytools/key.data.rb

@@ -1,227 +0,0 @@
-#!/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

@@ -1,341 +0,0 @@
-#!/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