safedb 0.01.0001

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 SafeDb
+
+  # 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 safe to lock away the
+  # names and dates of his lady friends.
+  #
+  #    $ safe init bill.clinton@example.com
+  #    $ safe open my/friends
+  #
+  #    $ safe put monica/surname lewinsky
+  #    $ safe put monica/from "April 1989"
+  #    $ safe put monica/to "September 1994"
+  #
+  #    $ safe put hilary/surname clinton
+  #    $ safe put hilary/from "January 1988"
+  #    $ safe put hilary/to "Present Day"
+  #
+  #    $ safe 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 = KeyApi.read_master_db()
+
+      return if unopened_envelope?( master_db )
+
+      envelope_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
+      has_content = 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 = KeyDb.from_json( KeyApi.content_unlock( master_db[ envelope_id ] ) ) if has_content
+      content_box = 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 )
+      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.
+      # --
+      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

data/lib/usecase/use.rb

@@ -0,0 +1,41 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # The <b>use <em>use case</em></b> borrowed from the database world denotes which
+  # domain will be used <b>for now (and evermore)</b> on the workstation until another
+  # use command is issued.
+  #
+  # == Observable Value
+  #
+  # The workstation configuration file will point to the domain name specified
+  # marking it as the current and correct domain to use.
+  #
+  # == Alternative / Error Flows
+  #
+  # Error - if the domain name is not listed in the configuration file.
+  # Error - if the (dictionary) path to the domain's base does not exist
+  #
+  class Use < UseCase
+
+    attr_writer :domain_name
+
+
+    # The <b>use <em>use case</em></b> is borrowed from the database world and it denotes
+    # the domain to be used <b>for now (and evermore)</b> for this workstation until another
+    # use command is issued.
+    #
+    # The parameter domain_name must be set after an object instance is acquired but
+    # before the execute method runs.
+    def execute
+    end
+
+
+    def pre_validation
+    end
+
+
+  end
+
+
+end

data/lib/usecase/verse.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  class Verse < UseCase
+
+    def execute
+
+      return unless ops_key_exists?
+      master_db = get_master_database()
+      return if unopened_envelope?( master_db )
+      print master_db[ KEY_PATH ]
+
+    end
+
+
+  end
+
+
+end

data/lib/usecase/view.rb

@@ -0,0 +1,71 @@
+#!/usr/bin/ruby
+
+module SafeDb
+
+  # View provides a bird's eye view of the domain's content and links well with
+  # the <b>goto</b>, <b>show</b> and <b>tell</b> commands.
+  #
+  #     $ xxx view
+  #     $ xxx goto 5   # shortcut for xxx open <<envelope_name>> <<key_name>>
+  #     $ xxx show
+  #     $ xxx tell
+  #     $ xxx tell url
+  #
+  # View maps out and numbers each envelope/key combination.
+  # Goto with the number effectively shortcuts the open pinpointer.
+  # Show prints out the dictionary at the opened path but masks any secrets.
+  # Tell without a parameter echoes the secret.
+  # Tell with parameter echoes the value of the parameter key (eg url).
+  #
+  # Once goto is enacted all path CRUD commands come into play as if you had
+  # opened the path. These include put, copy, paste, show, tell and delete.
+  class View < UseCase
+
+    def execute
+
+      return unless ops_key_exists?
+      master_db = KeyApi.read_master_db()
+
+      open_envelope = "(none)" if master_db[ ENV_PATH ].nil?
+      open_envelope = master_db[ ENV_PATH ] unless master_db[ ENV_PATH ].nil?
+      open_key_path = "(none)" if master_db[ KEY_PATH ].nil?
+      open_key_path = master_db[ KEY_PATH ] unless master_db[ KEY_PATH ].nil?
+
+      puts ""
+      puts "--- Book Birthday ~> #{KeyApi.to_db_create_date(master_db)}\n"
+      puts "--- The Book Name ~> #{KeyApi.to_db_domain_name(master_db)}\n"
+      puts "--- The Book (Id) ~> #{KeyApi.to_db_domain_id(master_db)}\n"
+      puts "---\n"
+      puts "--- Chapter ~> #{open_envelope}\n"
+      puts "--- + Verse ~> #{open_key_path}\n"
+      puts "---\n"
+
+      goto_location = 1
+      envelope_dictionaries = KeyApi.to_matching_dictionary( master_db, ENVELOPE_KEY_PREFIX )
+      envelope_dictionaries.each_pair do | envelope_name, crumb_dictionary |
+        is_opened_chapter = envelope_name.eql?( open_envelope )
+        envelope_content = KeyDb.from_json( KeyApi.content_unlock( crumb_dictionary ) )
+        envelope_content.each_key do | envelope_key |
+          is_opened_verse = envelope_key.eql?( open_key_path )
+          is_open = is_opened_chapter && is_opened_verse
+          openend = is_open ? " (( open location ))" : ""
+          fixdint = format( "%02d", goto_location )
+          goindex = is_open ? "" : "[#{fixdint}] "
+          puts "--- --- --------------------------------------" if is_open
+          puts "--- #{goindex}#{envelope_name} ~> #{envelope_key}#{openend}\n"
+          puts "--- --- --------------------------------------" if is_open
+          goto_location += 1
+        end
+      end
+
+      puts ""
+
+      return
+
+    end
+
+
+  end
+
+
+end

data/lib/usecase/vpn/README.md

@@ -0,0 +1,150 @@
+
+# Switch On an OpenVPN Client Connection
+
+    safe vpn
+
+## Introduction
+
+This DevOps task is a collaboration to **switch on a VPN connection** with safe as the credentials provider, nmcli on Ubuntu and an OpenVPN account embodied details within an ovpn file.
+
+## Task Preconditions
+
+To switch on a client OpenVPN connection the following must hold true
+
+- a shell safe tokenize, login and open has ocurred
+- the opened safe location must have a key vpn.id
+- safe write <<runtime.dir>> must eject <<vpn.id>>.ovpn
+- the ovpn file must be valid and point to a running accessible openvpn server
+- the ubiquitous @password field must hold a credible value
+- the VPN connection is assumed to be not just switched off, but deleted (at the start)
+
+
+
+
+# Switch Off an OpenVPN Client Connection
+
+    dot vpn down
+
+## Introduction
+
+This DevOps task is a collaboration to **switch on a VPN connection** with safe as the credentials provider, nmcli on Ubuntu and an OpenVPN account embodied details within an ovpn file.
+
+## Task Preconditions
+
+To switch on a client OpenVPN connection the following must hold true
+
+- a shell safe tokenize, login and open has ocurred
+- the opened safe location must have a key vpn.id
+- safe write <<runtime.dir>> must eject <<vpn.id>>.ovpn
+- the ovpn file must be valid and point to a running accessible openvpn server
+- the ubiquitous @password field must hold a credible value
+- the VPN connection is assumed to be not just switched off, but deleted (at the start)
+
+
+# safe vpn up | safe vpn down
+
+    $ safe open vpn production
+    $ safe vpn up
+    $ ... (do work using vpn)
+    $ safe vpn down
+
+## safe vpn | introduction
+
+Once you put VPN credentials into a mini-dictionary (in a safe book chapter and verse), you can bring up a VPN connection and after doing your work through the VPN you can tear it down.
+
+**[The strategy used to bring the OpenVPN connection up and down can be found here.](http://www.devopswiki.co.uk/wiki/middleware/network/openvpn/openvpn)**
+
+
+### safe vpn | ovpn | requirements
+
+Currently the safe vpn command is only integration tested with the following tech requirements
+
+- an Ubuntu 16.04 and Ubuntu 18.04 operating system
+- the nmcli (network manager command line) client which is installed if absent
+- an OpenVPN server
+- VPN configuration imported via an OpenVPN **`*.ovpn`** file
+
+
+## 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
+
+
+
+
+
+

data/lib/usecase/vpn/vpn.ini

@@ -0,0 +1,31 @@
+
+[vpn]
+
+vpn.id         =  rb>> @f[:secrets][:vpn_id]
+vpn.filename   =  rb>> @s[:vpn_id] + ".ovpn"
+export.folder  =  rb>> File.join( Dir.home, ".config/safe.db" )
+vpn.filepath   =  rb>> File.join( @s[:export_folder], @s[:vpn_filename] )
+vpn.username   =  rb>> @f[:secrets][:username]
+vpn.password   =  rb>> @f[:secrets][:@password]
+safe.write.cmd =  rb>> "safe write --script " + @s[:vpn_filepath]
+
+nm.import.cmd  =  rb>> "sudo nmcli connection import type openvpn file " + @s[:vpn_filepath]
+nm.default.cmd =  rb>> "nmcli connection modify " + @s[:vpn_id] + " ipv4.never-default true"
+nm.user.cmd    =  rb>> "nmcli connection modify " + @s[:vpn_id] + " +vpn.data username=" + @s[:vpn_username]
+nm.reload.cmd  =  rb>> "sudo nmcli connection reload " + @s[:vpn_id]
+nm.flags.cmd   =  rb>> "nmcli connection modify " + @s[:vpn_id] + " +vpn.data password-flags=0"
+this.user      =  rb>> Etc.getlogin()
+
+nm.directory   =  /etc/NetworkManager/system-connections
+nm.filepath    =  rb>> File.join @s[:nm_directory], @s[:vpn_id]
+nm.cache.name  =  rb>> @s[:vpn_id] + ".ini"
+nm.cache.path  =  rb>> File.join( Gem.user_home(), @s[:nm_cache_name] )
+
+chown.cmd.1    =  rb>> "sudo chown " + @s[:this_user] + ":" + @s[:this_user] + " " + @s[:nm_filepath]
+chown.cmd.2    =  rb>> "sudo chown root:root " + @s[:nm_filepath]
+
+nm.conn.up     =  rb>> "nmcli connection up " + @s[:vpn_id]
+nm.restart     =  sudo service network-manager restart
+
+nm.conn.off    =  rb>> "nmcli con down id " + @s[:vpn_id]
+nm.conn.del    =  rb>> "nmcli connection delete " + @s[:vpn_id]

data/lib/usecase/vpn/vpn.rb

@@ -0,0 +1,54 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # This vpn use case sets up vpn connection paraphernelia and can bring up a VPN connection
+  # and then tear it down.
+  #
+  #     safe vpn up
+  #     safe vpn down
+  class Vpn < UseCase
+
+    attr_writer :command
+
+    def execute
+
+      if( @command && @command.eql?( "down" ) )
+
+        puts ""
+        system @dictionary[ :nm_conn_off ]; sleep 2;
+        system @dictionary[ :nm_conn_del ]
+        puts ""
+        return
+
+      end
+
+      puts ""
+      system @dictionary[ :safe_write_cmd ]
+      puts "[#{@dictionary[ :vpn_filename ]}] temporarily exported to [#{@dictionary[ :vpn_filepath ]}]."
+      system @dictionary[ :nm_import_cmd  ]
+      File.delete( @dictionary[ :vpn_filepath ] )
+      puts "Exported file [#{@dictionary[ :vpn_filepath ]}] has now been deleted."
+
+      system @dictionary[ :nm_default_cmd ]
+      system @dictionary[ :nm_user_cmd    ]
+      system @dictionary[ :nm_reload_cmd  ]
+      system @dictionary[ :nm_flags_cmd   ]
+      system @dictionary[ :chown_cmd_1    ]
+
+      vpn_data = IniFile.load( @dictionary[:nm_filepath] )
+      vpn_data['vpn-secrets'] = { 'password' => @dictionary[:vpn_password] }
+      vpn_data.write()
+
+      system @dictionary[ :chown_cmd_2 ]
+      system @dictionary[ :nm_restart  ]; sleep 2;
+      system @dictionary[ :nm_conn_up  ]
+      puts ""
+
+    end
+
+
+  end
+
+
+end

data/lib/version.rb

@@ -0,0 +1,3 @@
+module SafeDb
+  VERSION = "0.01.0001"
+end

data/safedb.gemspec

@@ -0,0 +1,34 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'version'
+
+Gem::Specification.new do |spec|
+
+  spec.name          = "safedb"
+  spec.version       = SafeDb::VERSION
+  spec.authors       = [ "Apollo Akora" ]
+  spec.email         = [ "devopsassets@gmail.com" ]
+
+  spec.summary       = %q{safe locks and unlocks secrets in a simple, secure and intuitive way.}
+  spec.description   = %q{safe is a credentials manager for the linux command line written in Ruby. It locks and unlocks secrets in a safe simple and intuitive manner. You can then visit websites, manufacture keys and passwords, inject credentials into Jenkins, and interact with many tools including S3, GoogleDrive, Terraform, Git and Docker.}
+  spec.homepage      = "https://www.safedb.net"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+
+  spec.metadata["yard.run"] = "yri"
+  spec.bindir        = "bin"
+  spec.executables   = [ 'safe' ]
+  spec.require_paths = ["lib"]
+  spec.required_ruby_version = '>= 2.5.0'
+
+  spec.add_dependency 'inifile', '~> 3.0'
+  spec.add_dependency 'thor', '~> 0.2'
+  spec.add_dependency 'bcrypt'
+
+  spec.add_development_dependency "bundler", "~> 1.16"
+
+end