opensecret 0.0.9925 → 0.0.9949

data/lib/usecase/terraform/README.md

@@ -0,0 +1,91 @@
+
+# safe terraform <command>
+
+### safe terraform | introduction
+
+This terraform use case exports the AWS IAM user access key, secret key and region key into (very safe) environment variables and then runs the specified terraform be it **init**, **plan**, **apply** or **destroy**.
+
+
+## safe terraform | credential creation
+
+The first use case is importing the IAM user credentials into safe.
+
+    $ safe login joebloggs.com                  # open the book
+    $ safe open iam dev.s3.writer               # 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 prod.provisioner            # 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
+
+Take care to specify these 3 key names **@access.key**, **@secret.key**, **region.key** and note that safe's convention is to sensitively treat the value's of keys beginning with an **@** sign. **safe show** and other readers **mask out (redact)** these sensitive values.
+
+
+## safe terraform | running terraform
+
+Now and forever you can return to the chapter and verse and enjoy a secure credentials transfer where safe makes the IAM user credentials available to Terraform via environment variables. **Never do the plain text credentials touch the floor (disk).**
+
+### Why no safe terraform init?
+**safe only gets involved when credentials are involved**.
+**safe** is not trying to wrap command willy nilly. safe's policy is to keep external tool interfaces as **small** as possible. **`terraform init .`** does not involve credentials so safe does not get involved.
+
+    $ cd /path/to/terraform/dir     # go to directory holding your .tf file
+    $ safe login joebloggs.com      # login to your chosen book
+    $ safe open iam dev.s3.writer   # open chapter and verse holding IAM creds
+    $ terraform init .              # the usual terraform init command
+    $ safe terraform plan           # credentials are exported then terraform plan is run
+    $ safe terraform apply          # credentials are exported then terraform apply is run
+    $ safe terraform destroy        # credentials are exported then terraform destroy is run
+
+You can even change directories and run other terraform projects against the opened IAM user. You can also open an IAM user, run commands, open another run commands and then reopen the first and run commands.
+
+As long as you stay within your shell window - your safe login will persist. Once your session is finished you either logout or exit the shell.
+
+### Shortcut Alert
+
+**safe terraform** is a shortcut for **safe terraform apply**
+
+    $ safe terraform apply
+    $ safe terraform
+
+## safe terraform | pre-conditions
+
+To enact a successful safe terraform call you will need
+
+- to have created an IAM user
+- to open chapter and verse which
+- has these 3 keys @access.key @secret.key and region.key (at least)
+- terraform installed on the machine or container
+
+
+## safe terraform | benefits
+
+The safe terraform command is both an ultra secure and extremely convenient way of launching terraform.
+
+Your precious AWS IAM user credentials do not leave the safe and exist within (environment variable) memory only for the duration of the terraform command.
+
+It is safe as you need neither expose your AWS credentials in plain text in **~/.aws/credentials**, nor risk them sliding into version control. It is convenient because switching IAM users and AWS regions is as easy as typing the now ubiquitous safe open command.
+
+
+## quick tip | view then goto
+
+No need to type out the safe open command everytime. Use it the very first time you create a path to chapter and verse.
+
+    safe open <<chapter>> <<verse>>
+
+Then use safe view and safe goto instead of safe open.
+
+    $ safe view             # list all chapter and verses
+    $ safe goto <<index>>   # use the number from safe view to open the location
+    $ safe show             # look at your mini dictionary
+
+
+## safe terraform | only for aws
+
+This command currently only supports the AWS provider but will be extended to support Google's Compute Engine and more besides.
+

data/lib/usecase/terraform/terraform.rb

@@ -0,0 +1,121 @@
+#!/usr/bin/ruby
+	
+module OpenSecret
+
+  # This terraform use case exports the AWS IAM user access key, secret key and region key
+  # into (very safe) environment variables and then runs terraform init, plan, apply or destroy.
+  #
+  # This is both ultra secure and extremely convenient because the credentials do not leave
+  # the safe and exist within (environment variable) memory only for the duration of the
+  # terraform command.
+  #
+  # It is safe because you do not need to expose your AWS credentials in plain text.
+  # It is convenient because switching IAM users and AWS regions is as easy as typing the now
+  # ubiquitous safe open command.
+  #
+  #     safe open <<chapter>> <<verse>>
+  class Terraform < UseCase
+
+    attr_writer :command
+
+    # This prefix is tagged onto environment variables which Terraform will read
+    # and convert for consumption into module input variables.
+    TERRAFORM_EVAR_PREFIX = "TF_VAR_"
+
+    def execute
+
+      return unless ops_key_exists?
+      master_db = get_master_database()
+      return if unopened_envelope?( master_db )
+
+      # Get the open chapter identifier (id).
+      # Decide whether chapter already exists.
+      # Then get (or instantiate) the chapter's hash data structure
+      chapter_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
+      verse_id = master_db[ KEY_PATH ]
+      chapter_exists = OpenKey::KeyApi.db_envelope_exists?( master_db[ chapter_id ] )
+
+
+      # -- @todo begin
+      # -- Throw an exception (error) if the chapter
+      # -- either exists and is empty or does not exist.
+      # -- @todo end
+
+
+      # Unlock the chapter data structure by supplying
+      # key/value mini-dictionary breadcrumbs sitting
+      # within the master database at the section labelled
+      # envelope@<<actual_chapter_id>>.
+      chapter_data = OpenKey::KeyDb.from_json( OpenKey::KeyApi.content_unlock( master_db[ chapter_id ] ) )
+
+      # Now read the three AWS IAM credentials @access.key, @secret.key and region.key
+      # into the 3 environment variables terraform expects to find.
+
+      # ############## | ############################################################
+      # @todo refactor | ############################################################
+      # -------------- | 000000000000000000000000000000000000000000000000000000000000
+      # export-then-execute
+      # -------------------
+      # Put all the code above in a generic export-then-execute use case
+      # Then you pass in a Key/Value Dictionary
+      #
+      # { "AWS_ACCESS_KEY_ID" => "@access_key",
+      #   "AWS_SECRET_ACCESS_KEY" => "@secret_key",
+      #   "AWS_DEFAULT_REGION" => "region_key"
+      # }
+      #
+      # And pass in a command array [ "terraform #{command_name} #{auto_approve}", "terraform graph ..." ]
+      #
+      # Validation is done by the generic use case (which loops checking that every value exists
+      # as a key at the opened location.
+      #
+      # If all good the generic use case exports the ENV vars and runs each command in the list.
+      # PS - configure map in INI not code file
+      #
+      # The extra power will speed up generation of environment variable use cases including
+      # ansible, s3 bucket operations, git interactions and more.
+      #
+      # ############## | ############################################################
+      # ############## | ############################################################
+
+      puts ""
+      puts "@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@"
+      puts ""
+
+      ENV[ "AWS_ACCESS_KEY_ID"     ] = chapter_data[ verse_id ][ "@access.key" ]
+      ENV[ "AWS_SECRET_ACCESS_KEY" ] = chapter_data[ verse_id ][ "@secret.key" ]
+      ENV[ "AWS_DEFAULT_REGION"    ] = chapter_data[ verse_id ][ "region.key"  ]
+
+      mini_dictionary = chapter_data[ verse_id ]
+      mini_dictionary.each do | key_str, value_object |
+
+        is_env_var = key_str.start_with?( ENV_VAR_PREFIX_A ) || key_str.start_with?( ENV_VAR_PREFIX_B )
+        next unless is_env_var
+
+        env_var_name = key_str[ ENV_VAR_PREFIX_A.length .. -1 ] if key_str.start_with? ENV_VAR_PREFIX_A
+        env_var_name = key_str[ ENV_VAR_PREFIX_B.length .. -1 ] if key_str.start_with? ENV_VAR_PREFIX_B
+        env_var_keyname = TERRAFORM_EVAR_PREFIX + env_var_name
+        ENV[ env_var_keyname ] = value_object
+        puts "Environment variable #{env_var_keyname} has been set."
+
+      end
+
+      puts ""
+      puts "@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@"
+      puts ""
+
+      auto_approve = @command && @command.eql?( "plan" ) ? "" : "-auto-approve"
+      command_name = @command ? @command : "apply"
+      system "terraform #{command_name} #{auto_approve}"
+
+      puts ""
+      puts "@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@"
+      puts ""
+
+    end
+
+
+  end
+
+
+end

data/lib/usecase/token.rb

@@ -3,88 +3,12 @@
 module OpenSecret
 
   # The <tt>token use case</tt> prints out an encrypted session token tied
-  # to the workstation and shell environment. It should be called like this
-  # and <tt>printenv</tt> can be used to verify that a shell-scoped
-  # environment variable tying OPEN_SESSION_TOKEN to a 150 character session
-  # token, has been created.
-  #
-  #    export OPEN_SESSION_TOKEN=`ops token`
-  #    printenv
-  #
-  # Note the <b>back-ticks</b> surrounding the <tt>ops token</tt> call.
-  #
-  # When the shell closes OPEN_SESSION_TOKEN disappears forever. However if you want to
-  # continue using the same shell you can wipe this away.
-  #
-  #    $ unset OPEN_SESSION_TOKEN           # Delete the shell session token
-  #    $ env | grep OPEN_SESSION_TOKEN      # Check OPEN_SESSION_TOKEN is deleted
-  #
-  #    You can also delete every env var created by this shell.
-  #
-  #    $ env -i bash             # Rewind to (after) login variables
-  #
-  # == How to instantiate a Command Line Session
-  #
-  # Initialize the session by generating a random high entropy shell token
-  # and then generating an obfuscator key which we use to lock the shell
-  # key and return a triply segmented text token that can be used to decrypt
-  # and deliver the shell key as long as the same shell on the same machine
-  # is employed to make the call.
-  #
-  # == The 3 Session Token Segments
-  #
-  # The session token is divided up into 3 segments with a total of 150
-  #  characters.
-  #
-  #   | -------- | ------------ | ------------------------------------- |
-  #   | Segment  | Length       | Purpose                               |
-  #   | -------- | ------------ | ------------------------------------- |
-  #   |    1     | 16 bytes     | AES Encrypt Initialization Vector(IV) |
-  #   |    2     | 80 bytes     | Cipher text from Random Key AES crypt |
-  #   |    3     | 22 chars     | Salt for obfuscator key derivation    |
-  #   | -------- | ------------ | ------------------------------------- |
-  #   |  Total   | 150 chars    | Session Token in Environment Variable |
-  #   | -------- | ------------ | ------------------------------------- |
-  #
-  # Why is the <b>16 byte salt and the 80 byte BCrypt ciphertext</b> represented
-  # by <b>128 base64 characters</b>?
-  #
-  #    16 bytes + 80 bytes = 96 bytes
-  #    96 bytes x 8 bits   = 768 bits
-  #    768 bits / 6 bits   = 128 base64 characters
-  #
-  # == Other ways to instantiate the session token
-  #
-  # The session token environment variable can be delivered
-  #
-  # - with the export command
-  # - via a docker run ENV parameter
-  # - using the dot profile script
-  #
-  class Token < Command
+  # to the workstation and shell environment. See the root README.md on how
+  # to export it and create a simple command alias for it in the ~/.bash_aliases
+  # script which is executed when the shell starts.
+  class Token < UseCase
 
 
-    # The <tt>token use case</tt> prints out an encrypted session token tied
-    # to the workstation and shell environment. It should be called like this
-    # and <tt>printenv</tt> can be used to verify that a shell-scoped
-    # environment variable tying OPEN_SESSION_TOKEN to an (approximately) 48 character
-    # session password, has been created.
-    #
-    #    export OPEN_SESSION_TOKEN=`ops token`
-    #    printenv
-    #
-    # Note the <b>back-ticks</b> surrounding the <tt>ops token</tt> call.
-    #
-    # <b>How to instantiate a Command Line Session</b>
-    #
-    #    $ printenv
-    #    $ export OPEN_SESSION_TOKEN=`ops token`
-    #    $ printenv
-    #
-    #    The 2nd printenv should reveal a shell specific environment variable.
-    #
-    #    OPEN_SESSION_TOKEN=FvxETEpmoVUetyJ0jJk19aus1pQkzLZ8OVJccatYnC9GxDE4Iy3AyWNZ...
-    #
     def execute
 
       print OpenKey::KeyLocal.generate_shell_key_and_token()

data/lib/usecase/update/README.md

@@ -0,0 +1,55 @@
+
+
+# safe rename
+
+Changing your mind is a basic human right! In lieu of this, safe provides a **rename** use case that can be used to rename
+
+- a chapter
+- a verse
+- a key (at a chapter and verse location)
+
+<blockquote>
+As yet safe has no command for renaming books. You can achieve this by first cloning the book then deleting the original.
+</blockquote>
+
+## safe rename | chapter
+
+To rename a chapter you must not have an open location. If you do you must first close it before renaming.
+
+    $ safe close
+    $ safe view
+    $ safe rename <old-name> <new-name>
+
+When safe sees that the book is not open, it knows that you want to rename the chapter.
+
+The rename command returns a view allowing you to check that the chapter name has indeed been updated.
+
+
+## safe rename | verse
+
+To rename the verse you must have its chapter (and only its chapter) open.
+
+    $ safe close
+    $ safe open <chapter>
+    $ safe view
+    $ safe rename <old-name> <new-name>
+
+The rename command returns a view of all the verses in the open chapter allowing you to check that the verse name has indeed been updated.
+
+## safe rename | key
+
+Most of the time you will want to rename keys in the mini-dictionary at a chapter and verse location. To do this you must open the chapter and verse first.
+
+    $ safe open <chapter> <verse>
+    $ safe show
+    $ safe rename <old-name> <new-name>
+
+The rename command shows you the mini-dictionary (hashing out sensitive credentials) allowing you to check that the key name has indeed been updated.
+
+## safe rename | be aware
+
+Be aware of the following when renaming.
+
+- key names that start with @ guard the key's value during a safe show
+- renaming keys that are required for integration functionality will need you pass the --force switch
+

data/lib/usecase/update/rename.rb

@@ -0,0 +1,180 @@
+#!/usr/bin/ruby
+	
+module OpenSecret
+
+  # The <b>put use case</b> follows <b>open</b> and it adds secrets into an
+  # <em>(encrypted at rest)</em> <b>envelope</b>. Put can be called many times
+  # and when done, the <b>lock use case</b> can be called to commit all opened
+  # secrets into the configured storage engines.
+  #
+  # Calling <em>put</em> <b>before</b> calling open or <b>after</b> calling lock
+  # is not allowed and will result in an error.
+  #
+  # == Put Pre-Conditions
+  #
+  # When the put use case is called - the below conditions ring true.
+  #
+  # - the <b>folder path</b> ending in ../../my must exist
+  # - a session id, filename and encryption key ( in workstation config )
+  #
+  # == Observable Value
+  #
+  # The observable value delivered by +put+ boils down to
+  #
+  # - a new <b>friends.xyz123abc.os.txt</b> file if this is the first put.
+  # - a new group_name/key_name (like monica/surname) entry is added if required
+  # - a secret value is added against the key or updated if it already exists
+  # - a new session id and encryption key is generated and used to re-encrypt
+  #
+  # == Example | Bill Clinton's Secrets
+  #
+  # In our fictitious example Bill Clinton uses opensecret to lock away the
+  # names and dates of his lady friends.
+  #
+  #    $ opensecret init bill.clinton@example.com
+  #    $ opensecret open my/friends
+  #
+  #    $ opensecret put monica/surname lewinsky
+  #    $ opensecret put monica/from "April 1989"
+  #    $ opensecret put monica/to "September 1994"
+  #
+  #    $ opensecret put hilary/surname clinton
+  #    $ opensecret put hilary/from "January 1988"
+  #    $ opensecret put hilary/to "Present Day"
+  #
+  #    $ opensecret lock
+  #
+  # Soon follow up use cases will be unveiled, enabling us to
+  #
+  # - <b>get</b>
+  # - <b>read</b>
+  # - <b>list</b>
+  # - <b>look</b>
+  # - <b>peep</b> and
+  # - <b>peek</b>
+  class Rename < UseCase
+
+
+    attr_writer :secret_id, :secret_value
+
+
+    # The <b>put use case</b> follows <b>open</b> and it adds secrets into an
+    # <em>(encrypted at rest)</em> envelope. Put can be called many times to
+    # add secrets. Finally the <b>lock use case</b> commits all opened secrets
+    # into the configured storage engines.
+    #
+    # Calling <em>put</em> <b>before</b> calling open or <b>after</b> calling lock
+    # is not allowed and will result in an error.
+    #
+    # == Put Pre-Conditions
+    #
+    # When the put use case is called - the below conditions ring true.
+    #
+    # - the <b>folder path</b> ending in ../../my must exist
+    # - a session id, filename and encryption key ( in workstation config )
+    #
+    # == Observable Value
+    #
+    # The observable value delivered by +put+ boils down to
+    #
+    # - a new <b>friends.xyz123abc.os.txt</b> file if this is the first put.
+    # - a new group_name/key_name (like monica/surname) entry is added if required
+    # - a secret value is added against the key or updated if it already exists
+    # - a new session id and encryption key is generated and used to re-encrypt
+    #
+    # == How to Pretty Print a Hash in JSON Format
+    #
+    # This pretty prints a Hash (dictionary) data structure in JSON format.
+    #
+    #    puts "---\n"
+    #    puts JSON.pretty_generate( master_db )
+    #    puts "---\n"
+    #
+    def execute
+
+      return unless ops_key_exists?
+      master_db = OpenKey::KeyApi.read_master_db()
+
+      return if unopened_envelope?( master_db )
+
+      envelope_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
+      has_content = OpenKey::KeyApi.db_envelope_exists?( master_db[ envelope_id ] )
+
+      # --
+      # -- To get hold of the content we must either
+      # --
+      # --   a) unlock it using the breadcrumbs or
+      # --   b) start afresh with a new content db
+      # --
+      content_box = OpenKey::KeyDb.from_json( OpenKey::KeyApi.content_unlock( master_db[ envelope_id ] ) ) if has_content
+      content_box = OpenKey::KeyDb.new() unless has_content
+      content_hdr = create_header()
+
+      # --
+      # -- If no content envelope exists we need to place
+      # -- an empty one inside the appdb content database.
+      # --
+      master_db[ envelope_id ] = {} unless has_content
+
+      # --
+      # -- This is the PUT use case so we append a
+      # --
+      # --   a) key for the new dictionary entry
+      # --   b) value for the new dictionary entry
+      # --
+      # -- into the current content envelope and write
+      # -- the envelope to the content filepath.
+      # --
+      crumbs_dict = master_db[ envelope_id ]
+      content_box.create_entry( master_db[ KEY_PATH ], @secret_id, @secret_value )
+      OpenKey::KeyApi.content_lock( crumbs_dict, content_box.to_json, content_hdr )
+
+      # --
+      # -- Three envelope crumbs namely the external ID, the
+      # -- random iv and the crypt key are written afresh into
+      # -- the master database.
+      # --
+      OpenKey::KeyApi.write_master_db( content_hdr, master_db )
+      print_put_success
+
+# --->      secret_ids = @secret_id.split("/")
+# --->      if ( envelope.has_key? secret_ids.first )
+# --->        envelope[secret_ids.first][secret_ids.last] = @secret_value
+# --->      else
+# --->        envelope[secret_ids.first] = { secret_ids.last => @secret_value }
+# --->      end
+
+    end
+
+
+    private
+
+
+    def print_put_success
+
+      puts ""
+      puts "Success putting a key/value pair into the open envelope."
+      puts "You can put more in and then close the envelope."
+      puts ""
+      puts "    #{COMMANDMENT} close"
+      puts ""
+
+    end
+
+
+    # Perform pre-conditional validations in preparation to executing the main flow
+    # of events for this use case. This method may throw the below exceptions.
+    #
+    # @raise [SafeDirNotConfigured] if the safe's url has not been configured
+    # @raise [EmailAddrNotConfigured] if the email address has not been configured
+    # @raise [StoreUrlNotConfigured] if the crypt store url is not configured
+    def pre_validation
+
+
+    end
+
+
+  end
+
+
+end