opensecret 0.0.962 → 0.0.988

data/lib/{plugins → modules/cryptology}/crypt.io.rb

@@ -3,6 +3,8 @@
 
 module OpenSecret
 
+  module ToolBelt
+
   # CryptIO concentrates on injecting and ingesting crypt properties into and
   # out of a key/value dictionary as well as injecting and ingesting cryptographic
   # materials into and out of text files.
@@ -217,4 +219,7 @@ module OpenSecret
   end
 
 
+  end
+
+
 end

data/lib/{crypto → modules/cryptology}/engineer.rb

@@ -2,6 +2,9 @@
 
 module OpenSecret
 
+  module ToolBelt
+
+
   require 'securerandom'
 
   # This class will be refactored into an interface implemented by a set
@@ -12,6 +15,7 @@ module OpenSecret
   # information in the most secure (but simple) manner.
   class Engineer
 
+
     # --
     # -- Get a viable machine password taking into account the human
     # -- password length and the specified mix_ratio.
@@ -38,7 +42,6 @@ module OpenSecret
     end
 
 
-
     # Amalgamate the parameter passwords using a specific mix ratio. This method
     # produces cryptographically stronger secrets than algorithms that simply
     # concatenate two string keys together. If knowledge of one key were gained, this
@@ -90,4 +93,7 @@ module OpenSecret
   end
 
 
+  end
+
+
 end

data/lib/modules/mappers/collateral.rb

@@ -0,0 +1,282 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module OpenSecret
+
+  module Mapper
+
+    # <b>Collateral</b> fingers (locates/points to) resource paths and objects that
+    # are accessible on the filesystem of either the workstation or its associated
+    # (external) drives.
+    #
+    # Its ubiquitous language distinguishes four (4) base paths for the
+    #
+    # - <b>frontend store</b> - usually a path to USB connected devices like phones
+    # - <b>mid-end store</b> - location is on workstation off the user's home directory 
+    # - <b>(local) backend store</b> - departure lounge located off the home directory 
+    # - <b>(remote) backend store</b> - arrival gate on S3, Google Drive or SSH drive
+    class Collateral
+      include Singleton
+
+
+      # After constructing the <b>{Collateral}</b> object the building
+      # blocks that all paths are fabricated from must be injected.
+      attr_accessor :domain_name, :frontend_path
+
+      ENV_OPS_KEY_NAME = "OPS_KEY"
+
+      # The context name is used in various places (filesystem especially)
+      # in order to disambiguate the question of which software creates, reads,
+      # and updates the containing collateral.
+      CONTEXT_NAME = "opensecret.io"
+
+      # The name of the frontend directory in which encrypted
+      # session envelopes are stored in a tree-like structure.
+      SESSION_ENVELOPES_NAME = "session.envelopes"
+
+      # The name of the frontend directory (library) in which crypt
+      # keys are stored in a tree-like structure.
+      KEY_STORE_LIBRARY_NAME = "keystore.library"
+
+      # The name of the backend directory (library) in which crypt
+      # material is stored in a tree-like structure.
+      CRYPT_STORE_LIBRARY_NAME = "crypt.library"
+
+      # The name of the frontend directory (library) in which the
+      # index files are harboured in a flat structure.
+      CONFIG_LIBRARY_NAME = "ops.configuration"
+
+      # The name of the frontend directory in which the master keys
+      # are (or will be) stored.
+      MASTER_KEYS_DIR_NAME = "known.master.keys"
+
+      # The public key filename will end with this constant suffix.
+      PUBLIC_KEY_NAME_SUFFIX = "public.key.txt"
+
+      # The private key filename will end with this constant suffix.
+      PRIVATE_KEY_NAME_SUFFIX = "private.key.txt"
+
+
+      # Write the public key text into a file within the master keys
+      # folder. The directory path is created if necessary.
+      #
+      # @param public_key_text [String]
+      #    the text totality that makes up the domain's public key
+      def write_public_key public_key_text
+        FileUtils.mkdir_p master_keys_path
+        File.write public_key_path, public_key_text
+      end
+
+
+      # Read the public key text from a file within the master keys
+      # folder. This method will fail if the public key isn't found.
+      #
+      # @return [String]
+      #    return the text totality making up the domain's public key
+      def read_public_key
+        return File.read( public_key_path )
+      end
+
+
+      # Write the private key text into a file within the master keys
+      # folder. The directory path is created if necessary.
+      #
+      # @param private_key_text [String]
+      #    the text totality that makes up the domain's private key
+      def write_private_key private_key_text
+        FileUtils.mkdir_p master_keys_path
+        File.write private_key_path, private_key_text
+      end
+
+
+      # Read the private key text from a file within the master keys
+      # folder. This method will fail if the private key isn't found.
+      #
+      # @return [String]
+      #    return the text totality making up the domain's private key
+      def read_private_key
+        return File.read( private_key_path )
+      end
+
+
+      # Return true if the private key exists within a file under the
+      # auspices of the current domain.
+      #
+      # @param private_key_text [String]
+      #    the text totality that makes up the domain's private key
+      def private_key_exists?
+        return File.file? private_key_path
+      end
+
+
+      # The path to the initial configuration file below the user's home
+      # directory. The directory name the configuration file sits in is
+      # a dot prefixed context name derived from the value inside the
+      # {Mapper::Collateral::CONTEXT_NAME} constant.
+      #
+      #     ~/.<<context-name>>/<<context-name>>-configuration.ini
+      #
+      # You can see the filename too is derived from the context with a
+      # trailing string ending in <b>.ini</b>.
+      #
+      # @return [String] full path to the context configuration file
+      def config_file
+        return File.join config_directory, "#{CONTEXT_NAME}.configuration.ini"
+      end
+
+
+      # This method returns the absolute path to the directory that the
+      # configuration file sits in. It is basically just the dot prefixed
+      # context name (the {Mapper::Collateral::CONTEXT_NAME} constant).
+      #
+      #     ~/.<<context-name>>
+      #
+      # @return [String] path to directory holding context configuration file
+      def config_directory
+        return File.join home_directory, ".#{CONTEXT_NAME}"
+      end
+
+
+      # The configuration file governing the files and behaviour
+      # of the specified domain.
+      def domain_config_file
+        return File.join config_library_path, "ops.domain.config.ini"
+      end
+
+      # The path within the frontend directory in which the
+      # data index and the index configuration files are stored.
+      # @return [String]
+      #    path to the base frontend index library directory
+      def config_library_path
+        return File.join frontend_base, CONFIG_LIBRARY_NAME
+      end
+
+
+
+
+
+      # The path to the session's folder that will be situated
+      # within the frontend drive location so that any session
+      # materials can be carried away with the external drive.
+      def session_folder
+        return File.join frontend_base, SESSION_ENVELOPES_NAME
+      end
+
+
+      # The path to the session's index file is an amalgam of the
+      # session folder {session_folder} and a <b>lowercased</b>
+      # session id stamp that should be the first n characters of
+      # the session id.
+      #
+      # @example
+      #
+      #    session id stamp = M4Tywsv3BgNJQSn2MrA3484T
+      #    session filename = session.m4tywsv3bgnjqsn2mra3484t.txt
+      #
+      # @param id_stamp [String]
+      #
+      #    the first n characters of the session id that will
+      #    be lowercased and sandwiched between the words
+      #    <tt>session.</tt> and <tt>.txt</tt>
+      #
+      # @return [String]
+      #    path to the session file that sits inside the frontend
+      #    drive in folder called <b>session.envelopes</b>
+      def session_index_file id_stamp
+        return File.join( session_folder, "session.#{id_stamp.downcase}.txt" )
+      end
+
+
+
+
+      # The path within the frontend directory in which the encrypted
+      # keystore envelopes live in a tree-like structure.
+      # @return [String]
+      #    path to the base frontend keystore data directory
+      def frontend_keystore_path
+        return File.join frontend_base, KEY_STORE_LIBRARY_NAME
+      end
+
+
+      # The path within the backend directory in which the encrypted
+      # crypt envelopes live in a tree-like structure.
+      # @return [String]
+      #    path to the backend crypt store data directory
+      def backend_cryptstore_path
+        return File.join storage_url, "#{@domain_name}.#{CRYPT_STORE_LIBRARY_NAME}"
+      end
+
+
+      # On non-windows systems the home directory is defined
+      # perfectly by Ruby's Dir object.
+      #
+      # On Windows we sometimes get /AppData/Roaming appended
+      # onto the actual home directory. In these cases this
+      # method removes it.
+      #
+      # @return [String] the path to the machine user's home directory
+      def home_directory
+
+        return Dir.home unless Gem.win_platform?
+
+        extraneous_path = "/AppData/Roaming"
+        if Dir.home.end_with? extraneous_path then
+          return Dir.home.gsub( extraneous_path, "" )
+        end
+
+        return Dir.home
+
+      end
+
+
+      # Log the configuration file to two places
+      #
+      # - the console
+      # - the log file below the user's home directory.
+      #
+      # The logging is done at the INFO level.
+      def log_config
+
+        log.info(x) { File.read(config_file).log_lines }
+        puts ""
+        puts File.read(config_file)
+        puts ""
+
+      end
+
+
+      private
+
+
+      def frontend_base
+        return File.join @frontend_path, "ops.#{@domain_name}"
+      end
+
+
+      def storage_url
+        return File.join config_directory, "#{CONTEXT_NAME}.storage"
+      end
+
+
+      def master_keys_path
+        return File.join frontend_base, MASTER_KEYS_DIR_NAME
+      end
+
+
+      def public_key_path
+        return File.join master_keys_path, "#{@domain_name}.#{PUBLIC_KEY_NAME_SUFFIX}"
+      end
+
+
+      def private_key_path
+        return File.join master_keys_path, "#{@domain_name}.#{PRIVATE_KEY_NAME_SUFFIX}"
+      end
+
+
+    end
+
+
+  end
+
+
+end

data/lib/modules/mappers/dictionary.rb

@@ -0,0 +1,288 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module OpenKey
+
+  require 'inifile'
+
+  # 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 Dictionary is <b>two-dimensional</b> so all key-value pairs are stored
+  # under the auspices of a section.
+  #
+  # The Dictionary 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 = Dictionary.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 = Dictionary.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 Dictionary < Hash
+
+    attr_accessor :backing_filepath, :section_id
+
+
+    # Create either a new empty dictionary or unmarshal (deserialize) the
+    # dictionary from an encrypted file depending on whether a file exists
+    # at the backing_file parameter location.
+    #
+    # If the backing file indeed exists, the crypt key will be employed to
+    # decode and then decrypt the contents before the unmarshal operation.
+    #
+    # The filepath is stored as an instance variable hence the {write}
+    # operation does not need to be told <b>where to?</b>
+    #
+    # @example
+    #    # Create Dictionary the first time
+    #    my_dictionary = Dictionary.create( "/path/to/backing/file" )
+    #
+    #    # Create Dictionary from an Encrypted Backing File
+    #    my_dictionary = Dictionary.create( "/path/to/backing/file", "crypt-key-1234-wxyz" )
+    #
+    # @param backing_file [String]
+    #    the backing file is the filepath to this Dictionary's encrypted
+    #    backing file when serialized. If no file exists at this path the
+    #    operation will instantiate and return a new empty {Hash} object.
+    #
+    # @param crypt_key [String]
+    #    if the backing file exists then this parameter must contain a
+    #    robust symmetric decryption key. The symmetric key will be used
+    #    for decryption after the base64 encoded file is read.
+    #
+    #    Note that the decryption key is never part of the dictionary object.
+    #    This class method knows it but the new Dictionary has no crypt key
+    #    instance variable. Another crypt key must then be introduced when
+    #    serializing (writing) the dictionary back into a file.
+    #
+    # @return [Dictionary]
+    #    return a new Dictionary that knows where to go if it needs
+    #    to read (deserialize) or write (serialize) itself.
+    #
+    #    If no file exists at the path a new empty {Hash} object is
+    #    returned.
+    #
+    #    If a file exists, then the crypt_key parameter is expected
+    #    to be the decryption and key and the dictionary will be based
+    #    on the decrypted contents of the file.
+    #
+    # @raise [ArgumentError]
+    #    An {ArgumentError} is raised if either no decryption key is provided
+    #    or one that is unsuitable (ie was not used within the encryption).
+    #    Errors can also arise if the block coding and decoding has not been
+    #    done satisfactorily.
+    def self.create backing_file, crypt_key = nil
+
+      key_missing = File.file?( backing_file ) && crypt_key.nil?
+      raise ArgumentError, "No crypt key provided for file #{backing_file}" if key_missing
+
+      dictionary = Dictionary.new
+      dictionary.backing_filepath = backing_file
+
+      return dictionary unless File.file? backing_file
+
+      file_contents = File.read( backing_file ).strip
+      plaintext_str = file_contents.block_decode_decrypt( crypt_key )
+      dictionary.ingest_contents( plaintext_str )
+
+      return dictionary
+      
+    end
+
+
+    # Create either a new dictionary containing the specified section or unmarshal
+    # (deserialize) the dictionary from an encrypted file depending on whether a
+    # file exists at the backing_file parameter location and then <b>create</b> the
+    # section <b>only if it does not exist</b>.
+    #
+    # If the backing file indeed exists, the crypt key will be employed to
+    # decode and then decrypt the contents before the unmarshal operation.
+    #
+    # The filepath is stored as an instance variable hence the {write}
+    # operation does not need to be told <b>where to?</b>
+    #
+    # This dictionary will also know which <b>"section"</b> should be used to
+    # put, add, update and delete key/value data. You can employ this dictionary
+    # such that <b>each instance only creates, updates, removes and/or reads</b>
+    # from a single section.
+    #
+    # @example
+    #    # Create Dictionary the first time with a section.
+    #    my_dictionary = Dictionary.create( "/path/to/file", "Europe" )
+    #
+    #    # Create Dictionary from an Encrypted Backing File
+    #    my_dictionary = Dictionary.create( "/path/to/file", "Europe", "1234-wxyz" )
+    #
+    # @param backing_file [String]
+    #    the backing file is the filepath to this Dictionary's encrypted
+    #    backing file when serialized.
+    #
+    # @param section_id [String]
+    #    the created dictionary know which <b>section</b> should be used to
+    #    put, add, update and delete key/value data. If the backing file
+    #    does not exist a new section is created in the empty dictionary.
+    #
+    #    If the file exists a new section is created only if it is not
+    #    already present inside the dictionary.
+    #
+    # @param crypt_key [String]
+    #    if the backing file exists then this parameter must contain a
+    #    robust symmetric decryption key. The symmetric key will be used
+    #    for decryption after the base64 encoded file is read.
+    #
+    #    Note that the decryption key is never part of the dictionary object.
+    #    This class method knows it but the new Dictionary has no crypt key
+    #    instance variable. Another crypt key must then be introduced when
+    #    serializing (writing) the dictionary back into a file.
+    #
+    # @return [Dictionary]
+    #    return a new Dictionary that knows where to go if it needs
+    #    to read (deserialize) or write (serialize) itself.
+    #
+    #    If no file exists at the path a new empty {Hash} object is
+    #    returned.
+    #
+    #    If a file exists, then the crypt_key parameter is expected
+    #    to be the decryption and key and the dictionary will be based
+    #    on the decrypted contents of the file.
+    #
+    # @raise [ArgumentError]
+    #    An {ArgumentError} is raised if either no decryption key is provided
+    #    or one that is unsuitable (ie was not used within the encryption).
+    #    Errors can also arise if the block coding and decoding has not been
+    #    done satisfactorily.
+    def self.create_with_section backing_file, section_id, crypt_key = nil
+
+      dictionary = create( backing_file, crypt_key = nil )
+      dictionary.section_id = section_id
+      dictionary[section_id] = {} unless dictionary.has_key?( section_id )
+
+      return dictionary
+      
+    end
+
+
+    # Write the data in this dictionary hash map into a file-system
+    # backend mirror whose path was specified in the {Dictionary.create}
+    # factory method.
+    #
+    # Technology for encryption at rest is mandatory when using this
+    # Dictionary to write and read files from the filesystem.
+    #
+    # Calling this {self.write} method when the file at the prescribed path
+    # does not exist results in the directory structure being created
+    # (if necessary) and then the (possibly encrypted) file being written.
+    #
+    # @param crypt_key [String]
+    #    this parameter must contain a robust symmetric crypt key to use for
+    #    the encryption before writing to the filesystem.
+    #
+    #    Note that the decryption key is never part of the dictionary object.
+    #    For uncrackable security this key must be changed every time the
+    #    file is written.
+    def write crypt_key
+
+      ini_file = IniFile.new
+      self.each_key do |section_name|
+        ini_file[section_name] = self[section_name]
+      end
+
+      crypted_text = ini_file.to_s.encrypt_block_encode( crypt_key )
+
+      FileUtils.mkdir_p File.dirname(@backing_filepath)
+      File.write @backing_filepath, crypted_text
+
+    end
+
+
+
+    def get key_name
+      return self[@section_id][key_name]
+    end
+
+
+
+    def put key_name, key_value
+      self[@section_id][key_name] = key_value
+    end
+
+
+
+
+    # Ingest the contents of the INI string and merge it into a
+    # this object which is a {Hash}.
+    #
+    # @param the_contents [String]
+    #    the INI string that will be ingested and morphed into
+    #    this dictionary.
+    #
+    # @raise [ArgumentError]
+    #    if the content contains any nil section name, key name
+    #    or key value.
+    def ingest_contents the_contents
+      
+      ini_file = IniFile.new( :content => the_contents )
+      ini_file.each do | data_group, data_key, data_value |
+        ingest_entry data_group, data_key, data_value
+      end
+
+    end
+
+
+    private
+
+
+    def ingest_entry section_name, key_name, value
+
+      msg = "A NIL object detected during ingestion of file [#{@filepath}]."
+      raise ArgumentError.new msg if section_name.nil? || key_name.nil? || value.nil?
+
+      if self.has_key? section_name then
+        self[section_name][key_name] = value
+      else
+        self.store section_name, { key_name => value }
+      end
+
+    end
+
+
+  end
+
+
+end