opensecret 0.0.9925 → 0.0.9949

data/lib/session/time.stamp.rb

@@ -17,7 +17,6 @@ module OpenSession
 
     # Return two digit [mo] month index from 01 to 12.
     # @example 02 => in February
-    #
     def self.mo
       return Stamp.instance.time_now.strftime "%m"
     end
@@ -25,47 +24,37 @@ module OpenSession
 
     # Return three character abbreviated month name.
     # @example feb => in February
-    #
     def self.mmm
       return Stamp.instance.time_now.strftime( "%b" ).downcase
     end
 
 
-    #
     # Return three character abbreviated day of week.
     # @example tue => on Tuesday
-    #
     def self.ddd
       return Stamp.instance.time_now.strftime( "%a" ).downcase
     end
 
 
-    #
     # Return two digit (character) hour of day from 00 to 23.
     # @example 22 => between 22.00.00 and 22.59.59 inclusive
-    #
     def self.hh
       return Stamp.instance.time_now.strftime "%H"
     end
 
 
-    #
     # Return two digit minute of hour from [00] to [59].
-    #
     def self.mm
       return Stamp.instance.time_now.strftime "%M"
     end
 
 
-    #
     # Return two digit second of minute from [00] to [59].
-    #
     def self.ss
       return Stamp.instance.time_now.strftime "%S"
     end
 
 
-    #
     # Return a [3 digit] second and tenth of second
     # representation.
     #
@@ -90,35 +79,27 @@ module OpenSession
     #
     #  => 3 chars
     #  => 495
-    #
-    #
     def self.sst
       millisec_string = Stamp.instance.time_now.strftime "%L"
       return "#{ss}#{millisec_string[0]}"
     end
 
 
-    #
     # Return the [two] digit year (eg 19 for 2019).
     # that we are currently in.
-    #
     def self.yy
       return Stamp.instance.time_now.strftime("%Y")[2..-1]
     end
 
 
-    #
     # Return the [four] digit year (eg 2019)
     # that we are currently in.
-    #
     def self.yyyy
       return Stamp.instance.time_now.strftime("%Y")
     end
 
 
-    # ------------------------------------------------- -- #
-    # Return 3 digit julian day of year [001] to [366]. -- #
-    # ------------------------------------------------- -- #
+    # Return 3 digit julian day of year [001] to [366].
     def self.jjj
       return Stamp.instance.time_now.strftime "%j"
     end
@@ -140,7 +121,6 @@ module OpenSession
     end
 
 
-    #
     # Given two integer parameters (month index and 4 digit year) representing
     # the month in question this method returns the [PREVIOUS MONTHS] character
     # amalgam in the format [yymo_mmm] where
@@ -165,7 +145,6 @@ module OpenSession
     #  returns char => 1812.dec
     #  4 parameters => 1, 2019
     #  representing => January, 2019
-    #
     def self.previous_month_chars this_month_index, this_4digit_year
 
       prev_month_index = this_month_index == 1 ? 12 : ( this_month_index - 1 )
@@ -178,7 +157,6 @@ module OpenSession
 
     end
 
-    #
     # Using the current class time this method returns
     # the character amalgam for the [PREVIOUS MONTH] in
     # the format [yymo_mmm] where
@@ -201,7 +179,6 @@ module OpenSession
     #
     #  returns => 1812.dec
     #  if this month is => January 2019
-    #
     def self.yymo_mmm_prev
       return previous_month_chars mo.to_i, yyyy.to_i
     end
@@ -220,13 +197,11 @@ module OpenSession
     # @example
     #   => 1525
     #   => 03:25 pm
-    #
     def self.hhmm
       return "#{hh}#{mm}"
     end
 
 
-    #
     # Return the time of day to a TENTH of a second accuracy.
     # [8] characters will always be returned with the 5th one
     # being the (period) separator.
@@ -246,7 +221,6 @@ module OpenSession
     #
     #   => 8 chars
     #   => 1723.495
-    #
     def self.hhmm_sst
       return "#{hhmm}.#{sst}"
     end
@@ -281,7 +255,6 @@ module OpenSession
     #
     #   => 8 chars
     #   => 1723.495
-    #
     def self.yyjjj_hhmm_sst
       return "#{yyjjj}.#{hhmm}.#{sst}"
     end

data/lib/usecase/cmd.rb

@@ -10,7 +10,7 @@ module OpenSecret
   #
   # == Common Use Case Behaviour
   #
-  # This {OpenSecret::Command} use case is designed to be extended and does preparatory
+  # This {OpenSecret::UseCase} 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.
   #
@@ -26,21 +26,50 @@ module OpenSecret
   # - {stash} put directive key/value pair in default section
   # - {read} read the value at key_name from the parameter section
   # - {write} put directive key/value pair in parameter section
-  class Command
-=begin
-  # ---> rename from [Command] to [UseCase]
-  # ---> rename from [Command] to [UseCase]
-  # ---> rename from [Command] to [UseCase]
-  # ---> rename from [Command] to [UseCase]
-  # ---> rename from [Command] to [UseCase]
-  # ---> rename from [Command] to [UseCase]
-=end
+  class UseCase
+
+    # This variable should be set to true if the use case call
+    # originates from a shell different from the one through which
+    # the login ocurred.
+    #
+    # To proceed, the shell that hosted the safe login must be a
+    # parent or at least an ancestor of this shell.
+    #
+    # This variable need not be set if the login shell is the direct
+    # parent of this one (the every day manual usage scenario).
+    #
+    # If however the login occurred from a grand or great grandparent
+    # shell (as is the case when nested scripts make an agent-like call),
+    # this variable must be set to true.
+    attr_writer :from_script
+
+    # This prefix denotes keys and their values should be posted as environment
+    # variables within the context (for example terraform) before instigating the
+    # main action like terraform apply.
+    ENV_VAR_PREFIX_A = "evar."
+    ENV_VAR_PREFIX_B = "@evar."
+
+    # This prefix precedes keynames whose map value represents a file object.
+    FILE_KEY_PREFIX = "file::"
+
+    # The base64 encoded representation of the file content is placed into
+    # a map with this keyname.
+    FILE_CONTENT_KEY = "content64"
+
+    # The file base name is placed into a map with this keyname.
+    FILE_NAME_KEY = "filename"
+
+
+    # This is the root command typed into the shell to invoke one of the
+    # opensecret use cases.
+    COMMANDMENT = "safe"
+
 
     # The name of the environment variable that will hold the session token
     # generated by {self.generate_session_token}. This environment variable
     # is typically instantiated either manually (for ad-hoc use) or through
     # media such as dot profile.
-    ENV_VAR_KEY_NAME = "OPEN_SESSION_TOKEN"
+    ENV_VAR_KEY_NAME = "SAFE_TTY_TOKEN"
 
 
     # If and when this command line credentials management app needs to write
@@ -48,6 +77,33 @@ module OpenSecret
     # constant to denote the (off-home) directory name.
     APP_DIR_NAME = "opensecret.io"
 
+
+    # Get the master database. This behaviour can only complete
+    # correctly if a successful login precedes this call either
+    # in this or an ancestral shell environment.
+    #
+    # @return [Hash]
+    #     the hash data structure returned represents the master
+    #     database.
+    def get_master_database
+
+      begin
+
+        log.info(x) { "Request for master db with from_script set to #{@from_script}" }
+        return OpenKey::KeyApi.read_master_db( @from_script )
+
+      rescue OpenSSL::Cipher::CipherError => e
+
+        log.fatal(x) { "Exception getting master db for the safe book." }
+        log.fatal(x) { "The from_script parameter came set as [ #{@from_script} ]" }
+        log.fatal(x) { "The exception message is ~> [[ #{e.message} ]]" }
+        e.backtrace.log_lines
+        abort e.message
+
+      end
+
+    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
@@ -96,7 +152,6 @@ module OpenSecret
     # set a human readable string and then throw an exception.
     def check_pre_conditions
 
-
       begin
 
         pre_validation
@@ -112,6 +167,11 @@ module OpenSecret
         abort e.message
       end
 
+    end
+
+
+    # Override me if you need to
+    def pre_validation
 
     end
 
@@ -177,23 +237,20 @@ module OpenSecret
     # use case classes.
     def initialize
 
+      class_name = self.class.name.split(":").last.downcase
+      is_no_token_usecase = [ "token", "init", "id" ].include? class_name
+      return if is_no_token_usecase
 
-      class_name = self.class.name.downcase.split(":").last
-      is_pre_init_usecase = [ "safe", "store", "email" ].include? class_name
-      return if is_pre_init_usecase
+      exit(100) unless ops_key_exists?
 
-      @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
+      fact_filepath = File.sister_filepath( self, "ini", :execute )
+      log.info(x) { "Search location for INI factfile is [#{fact_filepath}]" }
+      return unless File.exists?( fact_filepath )
 
-      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." }
+      @facts = FactFind.new()
+      add_secret_facts @facts
+      @facts.assimilate_ini_file( fact_filepath )
+      @dictionary = @facts.f[ @facts.to_symbol( class_name ) ]
 
     end
 
@@ -232,6 +289,22 @@ module OpenSecret
     APPLICATION_GITHUB_URL = "https://github.io/opensecret.io"
 
 
+    def add_secret_facts fact_db
+
+      master_db = get_master_database()
+      raise ArgumentError.new "There is no open chapter here." if unopened_envelope?( master_db )
+      chapter_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
+      verse_id = master_db[ KEY_PATH ]
+      chapter_data = OpenKey::KeyDb.from_json( OpenKey::KeyApi.content_unlock( master_db[ chapter_id ] ) )
+      mini_dictionary = chapter_data[ master_db[ KEY_PATH ] ]
+
+      mini_dictionary.each do | key_str, value_str|
+        fact_db.assimilate_fact( "secrets", key_str, value_str )
+      end
+
+    end
+
+
     def create_header()
 
       return OpenKey::KeyApi.format_header(
@@ -258,9 +331,9 @@ module OpenSecret
       puts "To automate this step see the documentation."
       puts "To create the key run the below command."
       puts ""
-      puts "    export OPEN_SESSION_TOKEN=`ops token`"
+      puts "    export #{ENV_VAR_KEY_NAME}=`#{COMMANDMENT} token`"
       puts ""
-      puts "Those are backticks surrounding `ops token`"
+      puts "Those are backticks surrounding `#{COMMANDMENT} token`"
       puts "Not apostrophes."
       puts ""
 
@@ -304,25 +377,25 @@ module OpenSecret
     def print_unopened_envelope()
 
       puts ""
-      puts "Oops - before creating, reading or changing data you"
+      puts "Problem - before creating, reading or changing data you"
       puts "must first open a path to it like this."
       puts ""
-      puts "    ops open email.accounts joe@gmail.com"
+      puts "    #{COMMANDMENT} open email.accounts joe@gmail.com"
       puts ""
       puts " then you put data at that path"
       puts ""
-      puts "    ops put username joebloggs"
-      puts "    ops put password jo3s-s3cr3t"
-      puts "    ops put phone-no 07123456789"
-      puts "    ops put question \"Mums maiden name\""
+      puts "    #{COMMANDMENT} put username joebloggs"
+      puts "    #{COMMANDMENT} put password jo3s-s3cr3t"
+      puts "    #{COMMANDMENT} put phone-no 07123456789"
+      puts "    #{COMMANDMENT} put question \"Mums maiden name\""
       puts ""
       puts " and why not read it back"
       puts ""
-      puts "    ops get password"
+      puts "    #{COMMANDMENT} get password"
       puts ""
       puts " then close the path."
       puts ""
-      puts "    ops close"
+      puts "    #{COMMANDMENT} close"
       puts ""
 
     end
@@ -333,11 +406,11 @@ module OpenSecret
       puts ""
       puts "We are already logged in. 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 "    #{COMMANDMENT} open aws.credentials:s3reader"
+      puts "    #{COMMANDMENT} put access_key ABCD1234"
+      puts "    #{COMMANDMENT} put secret_key FGHIJ56789"
+      puts "    #{COMMANDMENT} put region_key eu-central-1"
+      puts "    #{COMMANDMENT} seal"
       puts ""
 
     end
@@ -350,7 +423,7 @@ module OpenSecret
       puts "Your domain [#{@domain_name}] is already setup."
       puts "You should already know the password."
       puts ""
-      puts "    ops login #{@domain_name}"
+      puts "    #{COMMANDMENT} login #{@domain_name}"
       puts ""
 
     end
@@ -363,7 +436,7 @@ module OpenSecret
       puts "The protector keys for [#{@domain_name}] have been setup."
       puts "From now on you simply login to use this domain."
       puts ""
-      puts "    ops login #{@domain_name}"
+      puts "    #{COMMANDMENT} login #{@domain_name}"
       puts ""
 
     end
@@ -375,7 +448,7 @@ module OpenSecret
       puts "Please initialize the app domain on this machine."
       puts "Give a domain name and a folder for key storage."
       puts ""
-      puts "    ops init <domain_name> \"$HOME/open.world\""
+      puts "    #{COMMANDMENT} init <domain_name> \"$HOME/open.world\""
       puts ""
 
     end
@@ -386,11 +459,11 @@ module OpenSecret
       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 "    #{COMMANDMENT} open aws.credentials:s3reader"
+      puts "    #{COMMANDMENT} put access_key ABCD1234"
+      puts "    #{COMMANDMENT} put secret_key FGHIJ56789"
+      puts "    #{COMMANDMENT} put region_key eu-central-1"
+      puts "    #{COMMANDMENT} seal"
       puts ""
 
     end
@@ -401,11 +474,11 @@ module OpenSecret
       puts ""
       puts "Success - you are logged in."
       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 "    #{COMMANDMENT} open aws.credentials:s3reader"
+      puts "    #{COMMANDMENT} put access_key ABCD1234"
+      puts "    #{COMMANDMENT} put secret_key FGHIJ56789"
+      puts "    #{COMMANDMENT} put region_key eu-central-1"
+      puts "    #{COMMANDMENT} seal"
       puts ""
 
     end

data/lib/usecase/config/README.md

@@ -0,0 +1,57 @@
+
+# Safe | Increasing Key Derivation Function Cost
+
+Safe uses two **key derivation functions** (**BCrypt** and **PBKDF2**) to transform the human sourced password into a key. The only role the resulting key plays is the encryption and decryption of a large **highly random computer generated key** which in turn protects the **master database**.
+
+### Why are two (2) key derivation algorithms used?
+
+Your credentials are still safe even in the rare case of a successful analytical attack being discovered on one of the algorithms.
+
+## Why High Computational Costs are Desirable?
+
+Unlike most algorithms, key derivation functions **work best when they run slowly!** This protects against brute force attacks where attackers use "rainbow tables" or try to iterate over common passwords in an attempt to rederive the key.
+
+Your responsibility is to make **safe as slow as is tolerable** by increasing the number of iterations required to derive each key.
+
+## Safe | Increasing the Cost of Both Key Derivation Functions
+
+You should increase the cost of **safe's** key derivation functions until safe commands run as slow as is tolerably and no less!
+
+```bash
+safe cost bcrypt 3
+safe cost pbkdf2 4
+```
+
+Both algorithms can be configured with a cost parameter from 1 to 7 inclusive. The default cost is 1 for both and is moderately secure and runs as slowly as is tolerable on an IBM ThinkPad laptop with an Intel Pentium i5 processor with 16G of RAM.
+
+Note that PBKDF2 has no maximum. BCrypt limits the cost to 2^16.
+
+<pre>
+    -------- - ------------ - --------------- - --------------------- - ---------------- -
+    |  Cost  |     BCrypt   |       BCrypt    |        PBKDF2         |     PBKDF2       |
+    |        |     Cost     |    Iterations   |         Cost          |   Iterations     |
+    | ------ - ------------ - --------------- - --------------------- - ---------------- |
+    |    1   |     2^10     |       1,024     |      3^0 x 100,000    |       100,000    |
+    |    2   |     2^11     |       2,048     |      3^1 x 100,000    |       300,000    |
+    |    3   |     2^12     |       4,096     |      3^2 x 100,000    |       900,000    |
+    |    4   |     2^13     |       8,192     |      3^3 x 100,000    |     2,700,000    |
+    |    5   |     2^14     |      16,384     |      3^4 x 100,000    |     8,100,000    |
+    |    6   |     2^15     |      32,768     |      3^5 x 100,000    |    24,300,000    |
+    |    7   |     2^16     |      65,536     |      3^6 x 100,000    |    72,900,000    |
+    -------- - ------------ - --------------- - --------------------- - ---------------- -
+</pre>
+
+When you increase the cost **safe will become perceivably slower**. With a cost of 7, a laptop takes many minutes but an AWS cloud compute optimized M5 server crunches through in mere seconds.
+
+## What is Your Data Worth?
+
+Attackers can bring a significant amount of modern data centre hardware to the table in order to access your credentials.
+
+However, these computing resources cost money and the amount of money an attacker spends will be proportional to the perceived gains from a successfully attack. The bigger the dollar signs in their eyes, the more they will spend.
+
+The default settings coupled with a **12 character password** takes (on average) 50 years to crack with computing resources that will cost $1,000 every single day.
+
+### Twenty Million Dollars
+
+If what you are protecting is worth more than **$(50 x 366 x 1,000)**, you should use an at least 16 character password and increase the computational cost parameters for both key derivation functions.
+