opensecret 0.0.962 → 0.0.988

data/lib/interprete/cmd.rb

@@ -0,0 +1,621 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module OpenSecret
+
+  # The parent OpenSecret use case is designed to be extended by the cli
+  # (command line) use cases like {OpenSecret::Open}, {OpenSecret::Put} and
+  # {OpenSecret::Lock} because it describes behaviour common to at least two
+  # (but usually more) of the use cases.
+  #
+  # == Common Use Case Behaviour
+  #
+  # This {OpenSecret::Command} use case is designed to be extended and does preparatory
+  # work to create favourable and useful conditions to make use cases readable,
+  # less repetitive, simpler and concise.
+  class Command
+
+
+    # Get the envelope that <b>was opened</b> by the open command but
+    # <b>not locked</b> with the lock command.
+    #
+    # @return [Envelope]
+    #    return the Envelope that has been opened. The state carried alongside an
+    #    open envelope is an id, an encryption key and a filepath all inside the
+    #    userhome configuration file.
+    def get_envelope
+
+      encrypt_key = Mapper::Settings.read @c[:open][:open_name], @c[:open][:open_keyname]
+      rel_filepath = Mapper::Settings.read @c[:open][:open_name], @c[:open][:open_pathname]
+
+      put_filepath = File.join( Mapper::Collateral.instance.session_envelopes_path, rel_filepath )
+      the_envelope = Mapper::Envelope.new
+      the_envelope.read put_filepath, encrypt_key
+      return the_envelope
+
+    end
+
+
+    # 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 Session ID Change?</b>
+    #
+    # The session id is not a secret but it has to be unique due to its role
+    # in indexing the session envelopes and their changes.
+    #
+    # What is really important is that the <b>session id changes</b> when
+    #
+    # - the <b>domain</b> being used changes
+    # - the <b>command shell</b> changes
+    # - the user <b>switches to another workstation user</b>
+    # - the <b>workstation host</b> is changed
+    # - the <b>OPS KEY</b> environment variable changes
+    # - 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 it Remain Unchanged?</b>
+    #
+    # Remaining <b>unchanged</b> in certain scenarious is a session ID feature
+    # that is just as important as it changing in others.
+    #
+    # The session ID <b>must remain unchanged</b> when
+    #
+    # - the <b>user returns to a command shell</b>
+    # - the user <b>switches back to using a domain</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 ...
+    #
+    #     The pre-hash inputs are an amalgam of the below example data.
+    #
+    #     Mac Address  => 20cf3067dec3
+    #     Parent PID   => 5817
+    #     Machine Host => data-cruncher
+    #     Session Time => 18083.0310.41.796577366
+    #
+    # @return [String]
+    #    the session id
+    def session_id
+
+      require 'macaddr'
+      session_data_points = [
+        Mac.addr.to_alphanumeric,
+        Process.ppid.to_s,
+        Socket.gethostname,
+        ENV[ Mapper::Collateral::ENV_OPS_KEY_NAME ].strip,
+        OpenSession::Home.instance.username,
+        @domain_name
+      ].join
+
+      return OpenKey::Digester.mash( session_data_points, SESSION_ID_SIZE )
+
+    end
+
+
+    # Get the session key that is used for symmetric encryption and decryption
+    # of secret material pertinent to the opensecret use case.
+    #
+    # This depends on the {Command.session_key_password} for engineering the
+    # password using information specific to the workstation and the parent
+    # (bash) shell being used to execute opensecret.
+    #
+    # <b>Substituting Equals Back In</b>
+    #
+    # An environment variable holds the key's value and the <b>equals sign</b>
+    # is not allowed within environment variables (in some operating systems)
+    # mainly due to the fact that it is used as the key/value separator.
+    #
+    # The url safe base64 coding may produce one, two or three equal signs in
+    # a bid to pad the string into a multiple of 4 length.
+    #
+    # In this case, we replaced equals signs with @ symbols when encoding so
+    # we must reciprocate this action when decoding here.
+    #
+    # @return [String]
+    #    Return the original key generated by the {OpenSecret::Key} usecase.
+    #
+    # @raise [RuntimeError]
+    #    if either the ENV["OPS_KEY"] environment variable is not present or an
+    #    exception is thrown during decryption. An error is also thrown if the
+    #    environment variable or the key to be returned have a length less than
+    #    40 characters.
+    def get_session_key
+
+      key_ciphertext = mandatory_environment_variable Mapper::Collateral::ENV_OPS_KEY_NAME, 40
+      decoded_crypt = Base64.urlsafe_decode64( key_ciphertext.gsub("@","=") )
+      return ToolBelt::Blowfish.decryptor( decoded_crypt, session_key_password )
+
+    end
+
+
+    # @todo
+    #    this method should be within the env var services class.
+    #
+    # Return the contents of the environment variable key specified
+    # in the first parameter. The returned value is striped of both
+    # leading and trailing whitespace before it is returned.
+    #
+    # @param env_var_name [String]
+    #    the (uppercase) name of the environment variable to collect
+    #
+    # @param min_size [Number]
+    #    the minimum number of characters the environment variable's
+    #    value is allowed to contain.
+    #
+    # @return [String]
+    #    Return the <b>stripped</b> environment variable value whose
+    #    name matches the one specified by the first parameter.
+    #
+    # @raise [RuntimeError]
+    #    if either the environment variable is not present or the length
+    #    of the string value is less than the number of charactes
+    #    specified in the second parameterr.
+    def mandatory_environment_variable env_var_name, min_size
+
+      raw_env_var_value = ENV[env_var_name]
+      raise_error( env_var_name, "not present") unless raw_env_var_value
+
+      env_var_value = raw_env_var_value.strip
+      raise_error( env_var_name, "consists only of whitespace") if raw_env_var_value.empty?
+
+      size_msg = "length should be at [least] #{min_size} characters"
+      raise_error( env_var_name, size_msg ) unless env_var_value.length >= min_size
+
+      return env_var_value
+
+    end
+
+
+    # Instantiate the collateral object which is the single
+    # source of knowledge for any client wishing to know the
+    # path to a particular resource (collateral) file or
+    # directory on the accessible file system.
+    #
+    # This method simply enables, for all (child) use cases,
+    # the @collateral instance variable.
+    def instantiate_collateral
+
+      @collateral = Mapper::Collateral.instance
+
+      the_domain_name = Mapper::Settings.grab @c[:global][:domain_now_id]
+      the_frontend_path = Mapper::Settings.read( the_domain_name, @c[:global][:front_path_id] )
+      @collateral.domain_name = the_domain_name
+      @collateral.frontend_path = the_frontend_path
+
+    end
+
+
+    # Unlock the {OpenSSL::PKey::RSA} private key and return the cipher object
+    # usable for asymmetric encryption, decryption, signing and signature
+    # verification use cases.
+    #
+    # The returned private key can be used to generate its twin public key
+    # and should be used to verify the same public key as (if) and when the
+    # need arises.
+    #
+    # @param locked_private_key [String]
+    #    the locked up private key ciphertext
+    #
+    # @param unlock_key [String]
+    #    the symmetric encryption key that can be used to unlock the private
+    #    key ciphertext in the first parameter.
+    #
+    # @return [OpenSSL::PKey::RSA]
+    #    return the {OpenSSL::PKey::RSA} private key that will be
+    #    usable for asymmetric encryption, decryption, signing and signature
+    #    verification.
+    def unlock_private_key locked_private_key, unlock_key
+      return OpenSSL::PKey::RSA.new locked_private_key, unlock_key
+    end
+
+
+    # Return the {OpenSSL::PKey::RSA} private key which is a cipher object
+    # usable for asymmetric encryption, decryption, signing and signature
+    # verification use cases.
+    #
+    # The returned private key can be used to generate its twin public key
+    # and should be used to verify the same public key as (if) and when the
+    # need arises.
+    #
+    # @param private_key_text [String]
+    #    the private key plain text
+    #
+    # @return [OpenSSL::PKey::RSA]
+    #    return the {OpenSSL::PKey::RSA} private key that will be
+    #    usable for asymmetric encryption, decryption, signing and signature
+    #    verification.
+    def to_private_key private_key_text
+      return OpenSSL::PKey::RSA.new private_key_text
+    end
+
+
+    # Execute the use cases's flow from beginning when
+    # you validate the input and parameters through the
+    # memorize, execute and the final cleanup.
+    def flow_of_events
+
+      check_pre_conditions
+      pre_memorize
+      execute
+      post_memorize
+      cleanup
+      check_post_conditions
+
+    end
+
+
+    # Validate the input parameters and check that the current
+    # state is perfect for executing the use case.
+    #
+    # If either of the above fail - the validation function should
+    # set a human readable string and then throw an exception.
+    def check_pre_conditions
+
+
+      begin
+
+        pre_validation
+
+      rescue OpenError::CliError => e
+
+        puts ""
+        puts "Your command did not complete successfully."
+        puts "Pre validation checks failed."
+        puts ""
+        puts "   => #{e.message}"
+        puts ""
+        abort e.message
+      end
+
+
+    end
+
+
+    # After the main flow of events certain state conditions
+    # must hold true thus demonstrating that the observable
+    # value has indeed ben delivered.
+    #
+    # Child classes should subclass this method and place any
+    # post execution (post condition) checks in it and then
+    # make a call to this method through the "super" keyword.
+    def check_post_conditions
+
+      begin
+
+        post_validation
+
+      rescue OpenError::CliError => e
+
+        puts ""
+        puts "Your command did not complete successfully."
+        puts "Post validation checks failed."
+        puts ""
+        puts "   => #{e.message}"
+        ####        puts "   => #{e.culprit}"
+        puts ""
+        abort e.message
+      end
+
+    end
+
+
+    # Child classes should subclass this method and place any
+    # post execution (post condition) checks in it and then
+    # make a call to this method through the "super" keyword if
+    # this method gets any global behaviour in it worth calling.
+    def post_validation
+
+    end
+
+
+
+    # (Pre) memorize adds to permanent storage a configuration
+    # directive and its value <tt>provided by the user</tt>
+    # primarily because it avoids repitition in subsequent
+    # use case commands.
+    def pre_memorize
+
+    end
+
+
+
+    # Execute the main flow of events of the use case. Any
+    # exceptions thrown are captured and if the instance
+    # variale [@human_readable_message] is set - tell the
+    # user about it. Without any message - just tell the
+    # user something went wrong and tell them where the logs
+    # are that might carry more information.
+    def execute
+
+    end
+
+
+
+    # (Post) memorize will add to permanent storage) any
+    # key/values that have been derived or looked up during
+    # use case execution. This allows subsequent use case
+    # commands to
+    #
+    # - capitalize on
+    # - take direction from
+    # - and/or simply use
+    #
+    # the value in later use cases or processing.
+    def post_memorize
+
+    end
+
+
+
+    # If the use case validation went well, the memorization
+    # went well the 
+    def cleanup
+
+    end
+
+
+
+    # Resolve +two attached fact files+ with the first being general and
+    # relevant to every use case in the parameter specified domain, and
+    # the second being specific to this use case.
+    #
+    # The <b><em>general factfile</em></b> is expected to be on the class (load) path
+    # and below are paths for a generic domain name and for an example domain
+    # name of *openpost.io*
+    #
+    # - <tt>factbase/facts.<<domain>>.ini</tt>
+    # - <tt>factbase/facts.openpost.io.ini</tt>
+    #
+    # The <b><em>use case specific factfile</em></b> is also _expected_ to be on the class
+    # (load) path and below is a generic and a use case specific path using
+    # the example <tt>deliver</tt> use case.
+    #
+    # - <tt>factbase/facts.<<uc-name>>.usecase.ini</tt>
+    # - <tt>factbase/facts.deliver.usecase.ini</tt>
+    #
+    # The domain name is delivered in the parameter whilst the use case
+    # name is derived from the (extension) class name.
+    #
+    # @param fact_domain [String] domain of the general attached factfile
+    # @return [Hash] a 2d (two-dimensional) hash of keys and their corresponding values
+    def attached_facts fact_domain
+
+    end
+
+
+    # This use case is initialized primary by resolving the configured
+    # +general and use case specific facts+. To access the general facts,
+    # a domain name is expected in the parameter delegated by the extension
+    # use case classes.
+    def initialize
+
+
+      class_name = self.class.name.downcase.split(":").last
+      is_pre_init_usecase = [ "safe", "store", "email" ].include? class_name
+      return if is_pre_init_usecase
+
+      @ucid_str = self.class.name.do_flatten
+      log.info(x) { "Usecase class [self.class.name] converted to => #{@ucid_str}" }
+      @ucid_sym = @ucid_str.gsub(".", "_").to_sym
+
+      OpenSession::FactFind.instance.instantiate @ucid_str
+      OpenSession::FactFind.instance.assimilate "facts.opensecret.io.ini"
+
+      @c = OpenSession::FactFind.instance.f
+      @i = OpenSession::FactFind.instance.i
+      @p = OpenSession::FactFind.instance.f[@ucid_sym]
+
+      log.info(x) { "assimilated [#{@p.length}] facts specific to the [#{@ucid_str}] use case." }
+
+    end
+
+
+    private
+
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+    ## Important Refactor is to move Session behaviour to an OpenKey Session class.
+
+
+
+    OUTER_PATH = "outer.path"
+    INNER_PATH = "inner.path"
+
+    LAST_ACCESSED = "last.accessed.time"
+
+    SESSION_DICT_LOCK_SIZE = 32
+
+    SESSION_DICT_LOCK_NAME = "crypted.session.dict.lock"
+
+    ENVELOPE_KEY_SIZE = 32
+
+    ENVELOPE_KEY_NAME = "crypted.envelope.key"
+
+    ENVELOPE_ID_SIZE = 16
+
+    ENVELOPE_ID_NAME = "crypted.envelope.id"
+
+    SESSION_ID_SIZE = 64
+
+    SESSION_FILENAME_ID_SIZE = 24
+
+    SESSION_START_TIMESTAMP_NAME = "session.creation.time"
+
+    MASTER_LOCK_KEY_NAME = "master.session.lock.key"
+
+    def raise_error env_var_name, message
+
+      puts ""
+      puts "#{env_var_name} environment variable #{message}."
+      puts "To instantiate it you can use the below command."
+      puts ""
+      puts "$ export OPS_KEY=`ops key`"
+      puts ""
+      puts "ps => those are backticks around `ops key` (not apostrophes)."
+      puts ""
+
+      raise RuntimeError, "#{env_var_name} environment variable #{message}."
+
+    end
+
+
+
+    def ops_key_exists?
+
+      if ( ENV.has_key? Mapper::Collateral::ENV_OPS_KEY_NAME )
+        return true
+      end
+
+      puts ""
+      puts "opensecret needs you to create a session key."
+      puts "To automate this step see the documentation."
+      puts "To create the key run the below command."
+      puts ""
+      puts "    export OPS_KEY=`ops key`"
+      puts ""
+      puts "Those are backticks surrounding `ops key`"
+      puts "Not apostrophes."
+      puts ""
+
+      return false
+
+    end
+
+
+    def private_key_exists?
+
+      if @collateral.private_key_exists?
+        return true
+      end
+
+      puts ""
+      puts "Domain [ #{@domain_name} ] has not been initialized."
+      puts "Have you run the ops init command?"
+      puts ""
+      puts "    ops init #{@domain_name} $HOME/ops.#{@domain_name}"
+      puts ""
+
+      return false
+
+    end
+
+
+    def get_session_dictionary
+      
+      session_index_filepath = @collateral.session_index_file( session_id[0 .. (SESSION_FILENAME_ID_SIZE-1)] )
+
+      unless File.file? session_index_filepath
+        return OpenKey::Dictionary.create_with_section( session_index_filepath, create_envelope_id )
+      end
+
+      return OpenKey::Dictionary.create_with_section( session_index_filepath, read_envelope_id, read_session_dict_lock )
+
+    end
+
+
+    def create_session_dict_lock
+      session_dict_lock = OpenSecret::ToolBelt::Engineer.strong_key SESSION_DICT_LOCK_SIZE
+      session_dict_lock_crypt = session_dict_lock.encrypt_url_encode( get_session_key )
+      Mapper::Settings.write session_id, SESSION_DICT_LOCK_NAME, session_dict_lock_crypt
+      return session_dict_lock
+    end
+
+
+    def read_session_dict_lock
+      session_dict_lock_crypt = Mapper::Settings.read session_id, SESSION_DICT_LOCK_NAME
+      return session_dict_lock_crypt.url_decode_decrypt( get_session_key )
+    end
+
+
+    def create_envelope_key
+      envelope_key = OpenSecret::ToolBelt::Engineer.strong_key ENVELOPE_KEY_SIZE
+      envelope_key_crypt = envelope_key.encrypt_url_encode( get_session_key )
+      Mapper::Settings.write session_id, ENVELOPE_KEY_NAME, envelope_key_crypt
+      return envelope_key
+    end
+
+
+    def read_envelope_key
+      envelope_key_crypt = Mapper::Settings.read session_id, ENVELOPE_KEY_NAME
+      return envelope_key_crypt.url_decode_decrypt( get_session_key )
+    end
+
+
+    def create_envelope_id
+      envelope_id = OpenSecret::ToolBelt::Engineer.strong_key ENVELOPE_ID_SIZE
+      envelope_id_crypt = envelope_id.encrypt_url_encode( get_session_key )
+      Mapper::Settings.write session_id, ENVELOPE_ID_NAME, envelope_id_crypt
+      return envelope_id
+    end
+
+
+    def read_envelope_id
+      envelope_id_crypt = Mapper::Settings.read session_id, ENVELOPE_ID_NAME
+      return envelope_id_crypt.url_decode_decrypt( get_session_key )
+    end
+
+
+    #### [cGWy7vU4WwxcTQ5X710kVQGWD5EujUco0WiaxyLrMFzXMdNhCAYAba3DXENKVz94]
+    #### master.session.lock.key = FY27lfm96o6KlIXHS3u8tsmh9oBJiS5IU-oUkn4CLCkVAsOx_E2Wkzm2-d3ZIHfhG35ik1ENjhHcBJO4JebYQ-TR-t7xI8AVKC8jS3Y40qUbeCjFHjGDbpJI0RNYEWdyr4iSMygI6FbH-iCg9V4awA==
+    #### session.creation.time = 18092.2238.43.302186561
+    #### crypted.envelope.id = iPamzaAD17vmOH72DLikbwadIMc5HW8IBS88mxUseks8il74JEXuLpJI0RNYEWdyr4iSMygI6FbH-iCg9V4awA==
+    #### crypted.session.dict.lock = iSbFR3ZFGWzkFEXHMByugL_09FJL3wVRnmgjxqsvd5ds8zpfeQT-7ERiAAst49gQr4iSMygI6FbH-iCg9V4awA==
+
+    def create_crypt_store_locking_key
+
+      config_keystore = Mapper::KeyStore.new( @collateral.domain_config_file, @domain_name )
+      digester = OpenKey::Digester.new( config_keystore.time_stamp )
+
+      locking_key = digester.generate @master_p4ss
+      config_keystore.set_init_vector( digester.encrypted_iv )
+
+      session_key_crypt = Base64.urlsafe_encode64( ToolBelt::Blowfish.encryptor( locking_key, get_session_key ) )
+
+      Mapper::Settings.write session_id, MASTER_LOCK_KEY_NAME, session_key_crypt
+      Mapper::Settings.write session_id, SESSION_START_TIMESTAMP_NAME, OpenSession::Stamp.yyjjj_hhmm_ss_nanosec
+
+      return locking_key
+
+    end
+
+
+    def print_success_initializing
+
+      puts ""
+      puts "Success - now open a secret envelope, put, then seal."
+      puts ""
+      puts "    ops open aws.credentials:s3reader"
+      puts "    ops put access_key ABCD1234"
+      puts "    ops put secret_key FGHIJ56789"
+      puts "    ops put region_key eu-central-1"
+      puts "    ops seal"
+      puts ""
+
+    end
+
+
+  end
+
+
+end