safedb 0.01.0001

data/lib/usecase/cmd.rb

@@ -0,0 +1,487 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module SafeDb
+
+  # The parent SafeDb use case is designed to be extended by the cli
+  # (command line) use cases like {SafeDb::Open}, {SafeDb::Put} and
+  # {SafeDb::Lock} because it describes behaviour common to at least two
+  # (but usually more) of the use cases.
+  #
+  # == Common Use Case Behaviour
+  #
+  # This {SafeDb::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.
+  #
+  # == Machine (Workstation) Configuration File
+  #
+  # The global configuration filepath is found off the home directory using {Dir.home}.
+  #
+  #    ~/.safedb.net/safedb.net.configuration.ini
+  #
+  # The global configuration file in INI format is managed through the methods
+  #
+  # - {grab} read the value at key_name from the default section
+  # - {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 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
+    # safe 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 = "SAFE_TTY_TOKEN"
+
+
+    # If and when this command line credentials management app needs to write
+    # any configuration directives to the machine's userspace it will use this
+    # constant to denote the (off-home) directory name.
+    APP_DIR_NAME = "safedb.net"
+
+
+    # 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 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
+    # {APP_DIR_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(), "#{APP_DIR_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 {APP_DIR_NAME} constant).
+    #
+    #     ~/.<<context-name>>
+    #
+    # @return [String] path to directory holding context configuration file
+    def config_directory
+      return File.join( Dir.home, ".#{APP_DIR_NAME}" )
+    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
+      execute
+      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
+
+
+    # Override me if you need to
+    def pre_validation
+
+    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
+
+
+    # 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
+
+
+    # If the use case validation went well, the memorization
+    # went well the 
+    def cleanup
+
+    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.split(":").last.downcase
+      is_no_token_usecase = [ "token", "init", "id" ].include? class_name
+      return if is_no_token_usecase
+
+      exit(100) unless ops_key_exists?
+
+      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 )
+
+      @facts = FactFind.new()
+      add_secret_facts @facts
+      @facts.assimilate_ini_file( fact_filepath )
+      @dictionary = @facts.f[ @facts.to_symbol( class_name ) ]
+
+    end
+
+
+    private
+
+
+    ENV_PATH = "env.path"
+    KEY_PATH = "key.path"
+    ENVELOPE_KEY_PREFIX = "envelope@"
+
+    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"
+
+    APPLICATION_GEM_NAME = "safedb.net"
+    APPLICATION_GEM_WEBSITE = "https://www.safedb.net"
+    APPLICATION_GITHUB_URL = "https://github.com/devops4me/safedb.net"
+
+
+    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 = KeyDb.from_json( 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 KeyApi.format_header(
+        SafeDb::VERSION,
+        APPLICATION_GEM_NAME,
+        APPLICATION_GITHUB_URL,
+        @domain_name
+      )
+
+    end
+
+
+
+    def ops_key_exists?
+
+      log_env()
+
+      if ( ENV.has_key? ENV_VAR_KEY_NAME )
+        return true
+      end
+
+      puts ""
+      puts "safe 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 #{ENV_VAR_KEY_NAME}=`#{COMMANDMENT} token`"
+      puts ""
+      puts "Those are backticks surrounding `#{COMMANDMENT} token`"
+      puts "Not apostrophes."
+      puts ""
+
+      return false
+
+    end
+
+
+    def log_env()
+
+      log.info(x) { "Gem Root Folder    => #{Gem.dir()}" }
+      log.info(x) { "Gem Config File    => #{Gem.config_file()}" }
+      log.info(x) { "Gem Binary Path    => #{Gem.default_bindir()}" }
+      log.info(x) { "Gem Host Path      => #{Gem.host()}" }
+      log.info(x) { "Gem Caller Folder  => #{Gem.location_of_caller()}" }
+      log.info(x) { "Gem Paths List     => #{Gem.path()}" }
+      log.info(x) { "Gem Platforms      => #{Gem.platforms()}" }
+      log.info(x) { "Gem Ruby Version X => #{Gem.ruby()}" }
+      log.info(x) { "Gem Ruby Version Y => #{Gem::VERSION}" }
+      log.info(x) { "Gem Ruby Version Z => #{Gem.latest_rubygems_version()}" }
+      log.info(x) { "Gem User Folder    => #{Gem.user_dir()}" }
+      log.info(x) { "Gem User Home      => #{Gem.user_home()}" }
+
+      return
+
+    end
+
+
+    def unopened_envelope?( key_database )
+
+      return false if key_database.has_key?( ENV_PATH )
+      print_unopened_envelope()
+      return true
+
+    end
+
+
+    def print_unopened_envelope()
+
+      puts ""
+      puts "Problem - before creating, reading or changing data you"
+      puts "must first open a path to it like this."
+      puts ""
+      puts "    #{COMMANDMENT} open email.accounts joe@gmail.com"
+      puts ""
+      puts " then you put data at that path"
+      puts ""
+      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 "    #{COMMANDMENT} get password"
+      puts ""
+      puts " then close the path."
+      puts ""
+      puts "    #{COMMANDMENT} close"
+      puts ""
+
+    end
+
+
+    def print_already_logged_in
+
+      puts ""
+      puts "We are already logged in. Open a secret envelope, put, then seal."
+      puts ""
+      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
+
+
+    def print_already_initialized
+
+      puts ""
+      puts "You can go ahead and login."
+      puts "Your domain [#{@domain_name}] is already setup."
+      puts "You should already know the password."
+      puts ""
+      puts "    #{COMMANDMENT} login #{@domain_name}"
+      puts ""
+
+    end
+
+
+    def print_domain_initialized
+
+      puts ""
+      puts "It is time to login."
+      puts "The protector keys for [#{@domain_name}] have been setup."
+      puts "From now on you simply login to use this domain."
+      puts ""
+      puts "    #{COMMANDMENT} login #{@domain_name}"
+      puts ""
+
+    end
+
+
+    def print_not_initialized
+
+      puts ""
+      puts "Please initialize the app domain on this machine."
+      puts "Give a domain name and a folder for key storage."
+      puts ""
+      puts "    #{COMMANDMENT} init <domain_name> \"$HOME/open.world\""
+      puts ""
+
+    end
+
+
+    def print_success_initializing
+
+      puts ""
+      puts "Success - now open a secret envelope, put, then seal."
+      puts ""
+      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
+
+
+    def print_login_success
+
+      puts ""
+      puts "Success - you are logged in."
+      puts ""
+      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
+
+
+  end
+
+
+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.
+

data/lib/usecase/docker/README.md

@@ -0,0 +1,146 @@
+
+# safe jenkins <command>
+
+
+### safe jenkins post [aws|docker|git] <<jenkins-host-url>> | introduction
+
+Use **`safe jenkins post`** to inject both your **AWS IAM User** and **docker login/password** credentials into your Jenkins 2.0 continuous integration portal reachable by the **jenkins host url** given in the 4th parameter of the safe command.
+
+---
+
+## safe jenkins post | prerequisite
+
+Before you can inject credentials into jenkins using **`safe jenkins post`** you must
+
+- be logged into your safe
+- have opened the appropriate chapter/verse
+- have put the required credential key/value pairs into the safe
+- have the jenkins service up and running
+
+After the post (to jenkins), your continuous integration jobs will be able to access the credential values via their IDs as stated in the below table.
+
+---
+
+## safe jenkins post aws | key names table
+
+As credentials are WORO (write once, read often), safe makes the reading part very very easy (and secure) so your effort is frontloaded.
+
+| Safe Key    | Jenkins Credential IDs | Environment Variable  | Description                                              |
+|:-----------:|:----------------------:|:--------------------- |:-------------------------------------------------------- |
+| @access.key | safe.aws.access.key    | AWS_ACCESS_KEY_ID     | The AWS IAM user's access key credential.                |
+| @secret.key | safe.aws.secret.key    | AWS_SECRET_ACCESS_KEY | The AWS IAM user's secret key credential.                |
+| region.key  | safe.aws.region.key    | AWS_REGION            | The AWS region key that your Jenkins service points to.  |
+
+So you can see that by convention, safe expects the credential keys in the safe to be named a particular way, and likewise, you can be assured of the IDs it gives those credentials when posted to Jenkins.
+
+
+## safe jenkins post | credentials lifecycle
+
+The life of the credentials begins when you create an  IAM user and record its access and secret keys. Then
+
+- you login to safe and store the 3 keys and their values
+- safe jenkins post will read the values and post them to Jenkins
+- Jenkins stores the values in conjunction with the Jenkins Credential IDs
+- pipeline jobs ask Jenkins to put the Credential ID values against environment variables
+- tools like Terraform and AwsCli use the environment variables to work in the cloud
+
+
+## Jenkinsfile | Usage in Pipeline Jobs
+
+Here is a pipeline declaration within a Jenkinsfile that asks Jenkins to put the credential values in its secrets store into the stated environment variables.
+
+    environment
+    {
+        AWS_ACCESS_KEY_ID     = credentials( 'safe.aws.access.key' )
+        AWS_SECRET_ACCESS_KEY = credentials( 'safe.aws.secret.key' )
+        AWS_REGION            = credentials( 'safe.aws.region.key' )
+    }
+
+After **`safe jenkins post aws`** you can **click into the Credentials item in the Jenkins main menu** to assure yourself that the credentials have indeed been properly injected.
+
+---
+
+## How to Write AWS Credentials into your Safe
+
+In order to **`safe terraform apply`** or **`safe jenkins post aws <<jenkins-host-url>>`** or `safe visit` you must first put those ubiquitous IAM programmatic user credentials into your safe.
+
+    $ safe login joebloggs.com                  # open the book
+
+    $ safe open iam dev.s3.reader               # open chapter and verse
+    $ safe put @access.key ABCD1234EFGH5678     # Put IAM access key in safe
+    $ safe put @secret.key xyzabcd1234efgh5678  # Put IAM secret key in safe
+    $ safe put region.key eu-west-3             # infrastructure in Paris
+
+    $ safe open iam canary.admin                # open chapter and verse
+    $ safe put @access.key 4321DCBA8765WXYZ     # Put IAM access key in safe
+    $ safe put @secret.key 5678uvwx4321abcd9876 # Put IAM secret key in safe
+    $ safe put region.key eu-west-1             # infrastructure in Dublin
+
+    $ safe logout
+
+
+---
+
+
+## How to write DockerHub Credentials into your Safe
+
+#### safe jenkins post docker https://jenkins.example.com
+
+Before you can issue a **`safe jenkins post docker http://localhost:8080`** you must insert your docker login credentials in the form of a docker.username and @docker.password into your safe. Remember that any key starting with the `@ sign` tells the safe to keep it a secret like when you issue a **`safe show`** command.
+
+    $ safe login joebloggs.com         # open the book
+    $ safe open docker production      # at the docker (for production) chapter and verse
+    $ safe put docker.username admin   # Put the Docker repository login docker.username into the safe
+    $ safe put @docker.password s3cr3t # Put the Docker repository login @docker.password into the safe
+    $ safe logout
+
+When docker credentials are injected into a Jenkins service the safe will expect to find **lines** at the open chapter and verse location with key names **`docker.username`** and **`@docker.password`**.
+
+The safe promises to inject credentials with an ID of **safe.docker.login.id** so any jenkins jobs that need to use the docker login docker.username and password must specify this ID when talking to the Jenkins credentials service.
+
+
+### DockerHub Credentials Inject Response
+
+Here is an example of posting dockerhub credentials into a Jenkins service running on the local machine.
+
+``` bash
+safe jenkins post docker http://localhost:8080
+```
+
+If successful safe provides a polite response detailing what just happened.
+
+```
+ - Jenkins Host Url : http://localhost:8080/credentials/store/system/domain/_/createCredentials
+ -   Credentials ID : safe.docker.login.id
+ -  Inject Username : devops4me
+ - So what is this? : The docker repository login credentials in the shape of a username and password.
+
+  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                 Dload  Upload   Total   Spent    Left  Speed
+100   428    0     0  100   428      0  47555 --:--:-- --:--:-- --:--:-- 47555
+```
+
+---
+
+
+## safe integrations | we need your help
+
+**You can help to extend safe's integrations.**
+
+By design - safe integrations are simple to write. They primarily integrate with producers and consumers. To deliver efficacy to devops engineers safe will endeavour to
+
+- **send** credentials to **downstream consumers** and
+- **receive** credentials from **upstream producers**
+
+safe needs pull requests from the devops community and it promises to always strive to keep the task of writing an integration extremely simple.
+
+### integrations | what giving takes?
+
+Currently, writing an integration entails delivering 3 or 4 artifacts which are
+
+- 1 simple Ruby class
+- 1 README.md documenting the command structure, the prerequisites and the expected outcome
+- 1 class containing unit tests
+- (optionaly) an INI file if many configuration and facts are involved
+
+Giving doesn't take much so roll up your sleeves (or frocks) and get writing.