opensecret 0.0.988 → 0.0.9925

data/lib/keytools/key.pass.rb

@@ -0,0 +1,120 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module OpenKey
+
+  class KeyPass
+
+
+      # <tt>Collect something sensitive from the command line</tt> with a
+      # minimum length specified in the first parameter. This method can't
+      # know whether the information is a password, a pin number or whatever
+      # so it takes the integer minimum size at its word.
+      #
+      # <b>Question 5 to App Config | What is the Secret?</b>
+      #
+      # The client may need to acquire the secret if the answer to question 4 indicates the need
+      # to instantiate the keys and encrypt the application's plaintext database. The application
+      # should facilitate communication of the secret via
+      #
+      # - an environment variable
+      # - the system clipboard (cleared after reading)
+      # - a file whose path is a command parameter
+      # - a file in a pre-agreed location
+      # - a file in the present directory (with a pre-agreed name)
+      # - a URL from a parameter or pre-agreed
+      # - the shell's secure password reader
+      # - the DConf / GConf or GSettings configuration stores
+      # - a REST API
+      # - password managers like LastPass, KeePassX or 1Pass
+      # - the Amazon KMS (Key Management Store)
+      # - vaults from Ansible, Terraform and Kubernetes
+      # - credential managers like GitSecrets and Credstash
+      #
+      # @param prompt_twice [Boolean] indicate whether the user should be
+      #    prompted twice. If true the prompt_2 text must be provided and
+      #    converse is also true. A true value asserts that both times the
+      #    user enters the same (case sensitive) string.
+      #
+      # @return [String] the collected string text ( watch out for non-ascii chars)
+      # @raise [ArgumentError] if the minimum size is less than one
+      def self.password_from_shell prompt_twice
+
+        assert_min_size MINIMUM_PASSWORD_SIZE
+
+        sleep(1)
+        puts "\nEnter a Password  : "
+        first_secret = STDIN.noecho(&:gets).chomp
+
+        assert_input_text_size first_secret.length, MINIMUM_PASSWORD_SIZE
+        return first_secret unless prompt_twice
+
+        sleep(1)
+        puts "\nRe-enter the password : "
+        check_secret = STDIN.noecho(&:gets).chomp
+
+        assert_same_size_text first_secret, check_secret
+        
+        return first_secret
+
+      end
+
+
+      # --
+      # -- Raise an exception if asked to collect text that is less
+      # -- than 3 characters in length.
+      # --
+      def self.assert_min_size min_size
+
+        min_length_msg = "\n\nCrypts with 2 (or less) characters open up exploitable holes.\n\n"
+        raise ArgumentError.new min_length_msg if min_size < 3
+
+      end
+
+
+      # --
+      # -- Output an error message and then exit if the entered input
+      # -- text size does not meet the minimum requirements.
+      # --
+      def self.assert_input_text_size input_size, min_size
+
+        if( input_size < min_size  )
+
+          puts
+          puts "Input is too short. Please enter at least #{min_size} characters."
+          puts
+
+          exit
+
+        end
+
+      end
+
+
+      # --
+      # -- Assert that the text entered the second time is exactly (case sensitive)
+      # -- the same as the text entered the first time.
+      # --
+      def self.assert_same_size_text first_text, second_text
+        
+        unless( first_text.eql? second_text )
+
+          puts
+          puts "Those two bits of text are not the same (in my book)!"
+          puts
+
+          exit
+
+        end
+
+      end
+
+      private
+
+      MINIMUM_PASSWORD_SIZE = 4
+
+
+  end
+
+
+end

data/lib/keytools/key.rb

@@ -2,6 +2,23 @@
 
 module OpenKey
 
+  # First use the class methods to source keys, then use a key's instance
+  # methods to access its properties and in concert with other symmetrical
+  # information, you can use the keys to lock (encrypt) or unlock (decrypt)
+  # other keys and objecs.
+  #
+  # == Sourcing and Deriving Keys
+  #
+  # Keys can be
+  #
+  # - sourced from a secure random byte generating function
+  # - sourced from ciphertext and another (decryption) key
+  # - generated by passing a secret through key derivation functions
+  # - regenerated from a secret and previously stored salts
+  # - sourced from the current unique workstation shell environment
+  # - sourced from an environment variable containing ciphertext
+  #
+  #
   # Keys need to be viewed (represented) in multiple ways and the essence
   # of the key viewer is to input keys {as_bits}, {as_bytes} and {as_base64}
   # and then output the same key (in as far as is possible) - as bits, as
@@ -53,54 +70,6 @@ module OpenKey
   # So when we request a byte, or base64 representation the viewer will
   # truncate (not round down) to the desired length.
   #
-  #
-  # == YACHT 64 | Yet Another Character Table
-  #
-  # This binary key class is a dab hand at converting base64 strings
-  # into their 6-bit binary string equivalents.
-  #
-  # It can convert non-alphanumeric characters within either Base64 or
-  # Radix64 into the OpenKey YACHT64 standard which has a forward slash
-  # but neither a plus sign nor a period character.
-  #
-  # == Character Order | Base64 | UrlSafe64 | Radix64 | YACHT64
-  #
-  # The character sets for each of he four 64 fomats are as follows.
-  #
-  # - Base-64 is <b>A to Z</b> then <b>a to z</b> then <b>0 to 9</b> then <b>+</b> then <b>/</b>
-  # - Radix64 is <b>.</b> then <b>/</b> then <b>0 to 9</b> then <b>A to Z</b> then <b>a to z</b>
-  # - UrlSafeBase64 is Base64 but chars 63/64 are an <b>underscore (_)</b> and <b>hyphen (-)</b>
-  # - UrlSafeBase64 <b>does not have line breaks and carriage returns</b> (unlike Base64)
-  # - <b>OpenKey 64 (YACHT64)</b> uses the same 62 characters plus an @ sign and a forward slash
-  # - The 64 <b>OpenKey 64</b> characters are <b>obfuscated into a random order</b>
-  #
-  # <b>Why Order Doesn't Matter</b>
-  #
-  # Order doesn't matter if string of bits is used in key creation
-  # as long as this class is employed to do all the necessary
-  # conversions.
-  #
-  # Base64 and Radix64 (outputted by the OpenBSD inspired bcrypt)
-  # differ in both the order of characters and their choice of the
-  # two non-alphanumeric characters.
-  #
-  # == 4 Non-AlphaNumerics | Base64 | Radix64 | YACHT64
-  #
-  # The behaviour here is happy to convert base64 strings produced by either
-  # Radix64 or Base64 or UrlSafe Base64. Howeverr it aware of the
-  # <b>non alpha-numeric characters</b> and converts them before processing
-  # with the modus operandi that says
-  #
-  # - ignore the forward slash  in <b>YACHT64, Base64 and Radix64</b>
-  # - convert the <b>plus (+)</b> in Base64 to the <b>@ symbol</b> in YACHT64
-  # - convert the <b>period (.)</b> in <b>Radix64</b> to the @ symbol in YACHT64
-  # - convert <b>hyphen (-)</b> in <b>Url Safe Base64</b> into a fwd slash
-  # - convert <b>underscore (_)</b> in <b>Url Safe Base64</b> to an @ sign
-  # - <b>delete the (=) equals</b> padding character used by Base64
-  #
-  # Neither the OpenBSD backed Radix64 nor the OpenKey (YACHT64) entertain the
-  # concept of padding.
-  #
   # == Mapping Each Character to 6 Binary Bits
   #
   # We need 6 binary bits to represent a base64 character (and 4
@@ -125,353 +94,514 @@ module OpenKey
   #
   class Key
 
-    # The internal YACHT64 OpenKey character set that can handle
-    # conversion from either Radix64 or Base64. The 64 character
-    # sets are all similar in that they hold 64 characters and
-    # they define two non alphanumeric characters because the
-    # 26 lowercase, 26 uppercase and 10 digits only adds up to
-    # an agonising close 62 characters.
-    YACHT64_CHARACTER_SET = [
-      "a", "9", "W", "B", "f", "K", "O", "z",
-      "3", "s", "1", "5", "c", "n", "E", "J",
-      "L", "A", "l", "6", "I", "w", "o", "g",
-      "k", "N", "t", "Y", "S", "%", "T", "b",
-      "V", "R", "H", "0", "@", "Z", "8", "F",
-      "G", "j", "u", "m", "M", "h", "4", "p",
-      "q", "d", "7", "v", "e", "2", "U", "X",
-      "r", "C", "y", "Q", "D", "x", "P", "i"
-    ]
-
-
-    # Initialize an n bit binary key (of literally ones and zeroes)
-    # from the base64 represented string in the parameter.
-    #
-    # This method can convert either UNIX <b>Radix 64</b> or
-    # <b>Base 64</b> into a <b>string of ones and zeroes</b>.
-    #
-    # The difference between Radix64 and Base64 is the ordering
-    # of the characters and the choice of the two non alpha-numeric
-    # (63rd and 64th or 1st and 2nd) characters.
-    #
-    # @param base64_string [String]
-    #    the either Base64 or (unix) Radix 64 encoded string
+    # Initialize a key object from a bit string of ones and zeroes provided
+    # in the parameter string.
     #
-    # @raise [ArgumentError]
-    #    if the parameter string contains characters that are not
-    #    recognized as belonging to either the Base64 or the Radix64
-    #    character sets. See {OpenKey::Key::YACHT64_CHARACTER_SET} constant.
-    #    
-    # @raise [RuntimeError]
-    #    if the conversion does not result in 6 bits for every character
-    #    in the parameter string.
-    def self.from_base64 the_base64_string
-
-      new_key = Key.new
-      new_key.instantiate_from_base64 the_base64_string
-      return new_key
+    # For example a string of 384 bits (ones and zeroes) can be thought of
+    # as a 48 byte key which can also be represented with 64 more compact
+    # base64 characters.
+    #
+    #   | -------- | ------------ | -------------------------------- |
+    #   | Bits     | Bytes        | Base64                           |
+    #   | -------- | ------------ | -------------------------------- |
+    #   | 384 Bits | is 48 bytes  | and 64 characters                |
+    #   | -------- | ------------ | -------------------------------- |
+    #
+    # @param the_bit_string [String]
+    #    the bit string of ones and zeroes that represents the bits that
+    #    represent this key
+    def initialize the_bit_string
+      @bit_string = the_bit_string
+    end
 
+
+    # Return a (secure) randomly generated super high entropy 384 bit key
+    # that can be stored with <b>64 base64 characters</b> and used to
+    # <b><em>source digest functions</em></b> that can unreversibly convert
+    # the key to a <b>256 bit symmetric encryption key</b>.
+    #
+    #   | -------- | ------------ | -------------------------------- |
+    #   | Bits     | Bytes        | Base64                           |
+    #   | -------- | ------------ | -------------------------------- |
+    #   | 384 Bits | is 48 bytes  | and 64 characters                |
+    #   | -------- | ------------ | -------------------------------- |
+    #
+    # This key easily translates to a base64 and/or byte array format because
+    # the 384 bit count is a <b>multiple of both 6 and 8</b>.
+    #
+    # @return [OpenKey::Key]
+    #    return a key containing 384 random bits (or a random array of 48 bytes)
+    #    which can if necessary be serialized into 64 base64 characters.
+    #
+    # @raise [ArgumentError]
+    #    If a nil or zero length byte array is received.
+    #    Or if the number of bytes <b>multiplied by 8</b>
+    #    is <b>not a multiple of 6</b>.
+    def self.from_random
+      return Key.new( to_random_bits( RANDOM_KEY_BYTE_LENGTH ) )
     end
 
 
-    def instantiate_from_base64 base64_string
+    def self.to_random_bits the_byte_length
+      random_bit_string = ""
+      for n in 1 .. the_byte_length
+        random_integer = SecureRandom.random_number( EIGHT_BIT_INTEGER_SIZE )
+        random_bit_string += "%08d" % [ random_integer.to_s(2) ]
+      end
+      return random_bit_string
+    end
 
-      @original64_string = replace_yacht64( base64_string )
 
-      @binary_bit_string = ""
-      @original64_string.each_char do |the_char|
+    # Return the key represented by the parameter sequence of base64
+    # characters.
+    #
+    # @param char64_string [String]
+    #
+    #    The base64 character sequence which the returned key is
+    #    instantiated from. Naturally this character sequencee cannot
+    #    be nil, nor can it contain any characters that are not
+    #    present in {Key64::YACHT64_CHARACTER_SET}.
+    #
+    #    Ideally the number of parameter characters multiplied by 6
+    #    <b>should be a multiple of eight (8)</b> otherwise the new
+    #    key's bit string will require padding and extension.
+    #
+    # @return [OpenKey::Key]
+    #    return a key from the parameter sequence of base64 characters.
+    #
+    # @raise [ArgumentError]
+    #    If a nil or zero length byte array is received.
+    #    Or if the number of bytes <b>multiplied by 8</b>
+    #    is <b>not a multiple of 6</b>.
+    def self.from_char64 char64_string
+      return Key.new( Key64.to_bits( char64_string ) )
+    end
 
-        yacht64_index = YACHT64_CHARACTER_SET.index(the_char)
 
-        nil_msg = "Character [ #{the_char} ] is not in the YACHT64 table."
-        raise ArgumentError, nil_msg if yacht64_index.nil?
+    # Return a key represented by the parameter binary string.
+    #
+    # @param binary_text [String]
+    #    The binary string that the returned key will be
+    #    instantiated from.
+    #
+    # @return [OpenKey::Key]
+    #    return a key from the binary byte string parameter
+    def self.from_binary binary_text
+      ones_and_zeroes = binary_text.unpack("B*")[0]
+      return Key.new( ones_and_zeroes )
+    end
 
-        index_msg = "yacht64 index should run between 0 and 63 inclusive."
-        all_good = ( yacht64_index >= 0 ) && ( yacht64_index <= 63 )
-        raise ArgumentError, index_msg unless all_good
 
-        @binary_bit_string += "%06d" % [ yacht64_index.to_s(2) ]
+    # Convert a string of Radix64 characters into a key.
+    #
+    # This method converts the base64 string into the internal YACHT64 format
+    # and then converts that into a bit string so that a key can be instantiated.
+    #
+    # @param radix64_string [String]
+    #    the radix64 string to convert into akey. This string will be a subset
+    #    of the usual 62 character suspects together with period and forward
+    #    slash characters.
+    #
+    #    This parameter should not contain newlines nor carriage returns.
+    #
+    # @return [OpenKey::Key]
+    #    return a key from the parameter sequence of base64 characters.
+    #
+    # @raise [ArgumentError]
+    #    If a nil or zero length parameter array is received.
+    def self.from_radix64 radix64_string
+      return Key.new( Key64.from_radix64_to_bits( radix64_string ) )
+    end
 
-      end
 
-      assert_in_out_lengths @original64_string, @binary_bit_string
+    # When a key is initialized, it is internally represented as a
+    # string of ones and zeroes primarily for simplicity and can be
+    # visualized as bits that are either off or on.
+    #
+    # Once internalized a key can also be represented as
+    #
+    # - a sequence of base64 (or radix64) characters (1 per 6 bits)
+    # - a binary string suitable for encryption (1 byte per 8 bits)
+    # - a 256bit encryption key from Digest(ing) the binary form
+    #
+    # @return [String]
+    #    a string of literally ones and zeroes that represent the
+    #    sequence of bits making up this key.
+    def to_s
 
+      ## Write duplicate ALIAS method called ==> to_bits() <== (bits and pieces)
+      ## Write duplicate ALIAS method called ==> to_bits() <== (bits and pieces)
+      ## Write duplicate ALIAS method called ==> to_bits() <== (bits and pieces)
+      ## Write duplicate ALIAS method called ==> to_bits() <== (bits and pieces)
+      ## Write duplicate ALIAS method called ==> to_bits() <== (bits and pieces)
+      ## Write duplicate ALIAS method called ==> to_bits() <== (bits and pieces)
+      ## Write duplicate ALIAS method called ==> to_bits() <== (bits and pieces)
+
+      ## ---------------------------------------------
+      ## +++++++++ WARNING ++++++++
+      ## ---------------------------------------------
+      ##
+      ##      to_s does not need 2b called
+      ##      So both the below print the same.
+      ##
+      ##      So YOU MUST KEEP the to_s method until a proper test suite is in place.
+      ##      So YOU MUST KEEP the to_s method until a proper test suite is in place.
+      ##
+      ##        puts "#{the_key}"
+      ##        puts "#{the_key.to_s}"
+      ##
+      ##      So YOU MUST KEEP the to_s method until a proper test suite is in place.
+      ##      So YOU MUST KEEP the to_s method until a proper test suite is in place.
+      ##
+      ## ---------------------------------------------
+
+      return @bit_string
     end
 
 
+    # Convert this keys bit value into a printable character set
+    # that is suitable for storing in multiple places such as
+    # <b>environment variables</b> and <b>INI files</b>.
+    #
+    # @return [String]
+    #    printable characters from a set of 62 alpha-numerics
+    #    plus an @ symbol and a percent % sign.
+    #
+    # @raise ArgumentError
+    #    If the bit value string for this key is nil.
+    #    Or if the bit string length is not a multiple of six.
+    #    Or if it contains any character that is not a 1 or 0.
+    def to_char64
+      assert_non_nil_bits
+      return Key64.from_bits( @bit_string )
+    end
 
-    def self.from_byte_array the_byte_array
-
-      new_key = Key.new
-      new_key.instantiate_from_base64( Base64.urlsafe_encode64( the_byte_array ) )
-      return new_key
 
+    # Return the <b>un-printable <em>binary</em> bytes</b> representation
+    # of this key. If you store 128 bits it will produce 22 characters
+    # because 128 divide by 6 is 21 characters and a remainder of two (2)
+    # bits.
+    #
+    # The re-conversion of the 22 characters will now produce 132 bits which
+    # is different from the original 128 bits.
+    #
+    # @return [Byte]
+    #    a non-printable binary string of eight (8) bit bytes which can be
+    #    used as input to both digest and symmetric cipher functions.
+    def to_binary
+      return [ to_s ].pack("B*")
     end
 
 
+    # Return the <b>un-printable <em>binary</em> bytes</b> representation
+    # of this key. If you store 128 bits it will produce 22 characters
+    # because 128 divide by 6 is 21 characters and a remainder of two (2)
+    # bits.
+    #
+    # The re-conversion of the 22 characters will now produce 132 bits which
+    # is different from the original 128 bits.
+    #
+    # @return [Byte]
+    #    a non-printable binary string of eight (8) bit bytes which can be
+    #    used as input to both digest and symmetric cipher functions.
+    def self.to_binary_from_bit_string bit_string_to_convert
+      return [ bit_string_to_convert ].pack("B*")
+    end
+
 
-    # Retrieve a cryptographically strong key that is 64 encoded
-    # with a bit (not byte) count specified by the parameter.
+    # This method uses digests to convert the key's binary representation
+    # (which is either 48 bytes for purely random keys or 64 bytes for keys
+    # derived from human sourced secrets) into a key whose size is ideal for
+    # plying the ubiquitous <b>AES256 symmetric encryption algorithm</b>.
     #
-    # <b>Bit Count must be Multiple of 24</b>
+    # This method should only ever be called when this key has been derived
+    # from either a (huge) <b>48 byte random source</b> or from a key derivation
+    # function (KDF) such as BCrypt, SCrypt, PBKDF2 or a union from {KdfApi}
+    # which delivers 512 bit (64 byte) key for reduction to 256 bits.
     #
-    # The bit count parameter must be divisible by both 3 and 4
-    # (thus 24) so that it can be represented by a whole number
-    # of 8-bit bytes and a whole number of 6-bit base64 encoding
-    # characters.
+    # @return [String]
+    #    a binary string of thirty-two (32) eight (8) bit bytes which
+    #    if appropriate can be used as a symmetric encryption key especially
+    #    to the powerful AES256 cipher.
+    def to_aes_key
+      return Digest::SHA256.digest( to_binary() )
+    end
+
+
+    # This method uses the SHA384 digest to convert this key's binary
+    # representation into another (newly instantiated) key whose size
+    # is <b>precisely 384 bits</b>.
     #
-    # If this were not the case the leftover bits could not strictly
-    # be called "random" and could change in value when converted
-    # from one representation to the other.
+    # If you take the returned key and call
     #
-    # @param bit_count [Fixnum]
-    #    the number of bits divisable by 24 (both 3 and 4) so
-    #    that it can be represented by a whole number of 8-bit
-    #    bytes and a whole number of 6-bit base64 characters.
+    # - {to_char64} you get a 64 character base64 string
+    # - {to_s} you get a string of 384 ones and zeroes
+    # - {to_binary} you get a 48 byte binary string
     #
-    # @raise [ArgumentError]
-    #    if bit count parameter is not divisible by both 3 and 4
-    def self.to_random_yacht64 bit_count
-
-      mod24_msg = "The bit count of #{bit_count} is not divisable by 24."
-      raise ArgumentError, mod24_msg unless bit_count % 24 == 0
+    # @return [OpenKey::Key]
+    #    a key with a bit length (ones and zeroes) of <b>precisely 384</b>.
+    def to_384_bit_key
 
-      num_6bit_blocks = bit_count / 6
-      random64_string = SecureRandom.base64( num_6bit_blocks + 4 )
-      perfect_rand_64 = random64_string[ 0 .. num_6bit_blocks ]
-      length_64string = perfect_rand_64.length
+      a_384_bit_key = Key.from_binary( Digest::SHA384.digest( to_binary() ) )
 
-      length_msg = "Expected [#{num_6bit_blocks}] characters not #{length_64string}."
-      raise RuntimeError, length_msg unless length_64string == num_6bit_blocks
+      has_384_chars = a_384_bit_key.to_s.length == 384
+      err_msg = "Digested key length is #{a_384_bit_key.to_s.length} instead of 384."
+      raise RuntimeError, err_msg unless has_384_chars
 
-#####################      return to_yacht64( perfect_rand_64 )
+      return a_384_bit_key
 
     end
 
 
-    # Return a representation of this key in YACHT64 format which is
-    # simply <b>Yet Another Coding Hieroglyphics-like Table (YACHT).
+    # Use the {OpenSSL::Cipher::AES256} block cipher in CBC mode and the binary
+    # 256bit representation of this key to encrypt the parameter key.
     #
-    # This new format can suck in RADIX64 as well as Base64 and is
-    # safe for transportation with carriers such as
+    # Store the ciphertext provided by this method. To re-acquire (reconstitute)
+    # the parameter key use the {do_decrypt_key} decryption method with
+    # the ciphertext produced here.
     #
-    # - URLs
-    # - <b>one line text</b> (without newlines and carriage returns)
-    # - <b>environment variables</b>
-    # - INI, JSON, YAML and XML files
+    # <b>Only Encrypt Strong Keys</b>
     #
-    # <b>Character Order | Base64 | UrlSafe64 | Radix64 | YACHT64</b>
+    # Never encrypt a potentially weak key, like one derived from a human password
+    # (even though it is put through key derivation functions).
     #
-    # The character sets for each of he four 64 fomats are as follows.
+    # Once generated (or regenerated) a potentially weak key should live only as
+    # long as it takes for it to encrypt a strong key. The strong key can then
+    # be used to encrypt valuable assets.
     #
-    # - Base-64 is <b>A to Z</b> then <b>a to z</b> then <b>0 to 9</b> then <b>+</b> then <b>/</b>
-    # - Radix64 is <b>.</b> then <b>/</b> then <b>0 to 9</b> then <b>A to Z</b> then <b>a to z</b>
-    # - UrlSafeBase64 is Base64 but chars 63/64 are an <b>underscore (_)</b> and <b>hyphen (-)</b>
-    # - UrlSafeBase64 <b>does not have line breaks and carriage returns</b> (unlike Base64)
-    # - <b>OpenKey 64 (YACHT64)</b> uses the same 62 characters plus an @ sign and a forward slash
-    # - The 64 <b>OpenKey 64</b> characters are <b>obfuscated into a random order</b>
+    # <b>Enforcing Strong Key Size</b>
     #
-    # <b>Why Order Doesn't Matter</b>
+    # If one key is potentially weaker than the other, the weaker key must be this
+    # object and the strong key is the parameter key.
     #
-    # Order doesn't matter if string of bits is used in key creation
-    # as long as this class is employed to do all the necessary
-    # conversions.
+    # This method thus enforces the size of the strong key. A strong key has
+    # 384 bits of entropy, and is represented by 64 base64 characters.
     #
-    # Base64 and Radix64 (outputted by the OpenBSD inspired bcrypt)
-    # differ in both the order of characters and their choice of the
-    # two non-alphanumeric characters.
+    # @param key_to_encrypt [OpenKey::Key]
+    #    this is the key that will first be serialized into base64 and then locked
+    #    down using the 256 bit binary string from this host object as the symmetric
+    #    encryption key.
+    #
+    #    This method is sensitive to the size of the parameter key and expects to
+    #    encrypt <b>exactly 64 base64 characters</b> within the parameter key.
     #
     # @return [String]
-    #    Return the YACHT64 formatted textual string in a single line. This
-    #    string will consist of the 62 alpha-numeric characters and perhaps
-    #    an @ sign and a forward slash (/).
-    #
-    # @raise [RuntimeError]
-    #    raise an error if this class was initialized with a character that
-    #    was not recognised. Not withstanding the difference in non-whitespace
-    #    characters like carriage returns and newlines, an error is thrown
-    #    if the length of the original base64 and the output YACHT64 string are
-    #    not exactly the same length.
-    def to_yacht64
-
-      almost_base64 = replace_yacht64( @original64_string )
-      the_yacht64_encoding = ""
-
-      almost_base64.each_char do |the_char|
-        yacht64_index = YACHT64_CHARACTER_SET.index(the_char)
-        assert_yacht64_index yacht64_index
-        the_yacht64_encoding += YACHT64_CHARACTER_SET[ yacht64_index ]
-      end
+    #    The returned ciphertext should be stored. Its breakdown is as follows.
+    #    96 bytes are returned which equates to 128 base64 characters.
+    #    The random initialization vector (iv) accounts for the first 16 bytes.
+    #    The actual crypt ciphertext then accounts for the final 80 bytes.
+    #
+    # @raise [ArgumentError]
+    #    the size of the parameter (strong) key is enforced to ensure that it has
+    #    exactly 384 bits of entropy which are represented by 64 base64 characters.
+    def do_encrypt_key key_to_encrypt
 
-      length_msg = "The base64 and yacht64 string lengths are not equal."
-      goodlength = the_yacht64_encoding.length == @original64_string.length
-      raise RuntimeError, length_msg unless goodlength
+      crypt_cipher = OpenSSL::Cipher::AES256.new(:CBC)
 
-      return the_yacht64_encoding
+      crypt_cipher.encrypt()
+      random_iv = crypt_cipher.random_iv()
+      crypt_cipher.key = to_aes_key()
 
-    end
+      calling_module = File.basename caller_locations(1,1).first.absolute_path, ".rb"
+      calling_method = caller_locations(1,1).first.base_label
+      calling_lineno = caller_locations(1,1).first.lineno
+      caller_details = "#{calling_module} | #{calling_method} | (line #{calling_lineno})"
 
+      log.info(x) { "### #####################################################################" }
+      log.info(x) { "### Caller Details =>> =>> #{caller_details}"                              }
+      log.info(x) { "### #####################################################################" }
+      log.info(x) { "The BitStr Char representation of this key => #{to_s()}" }
+      log.info(x) { "256bit Digest (Urlsafe Base64) of this key => #{Base64.urlsafe_encode64(to_aes_key())}" }
+      log.info(x) { "The IncomingKey Base64 Char representation => #{key_to_encrypt.to_char64()}" }
+      log.info(x) { "Random IV Used for the AESs Key Encryption => #{Base64.urlsafe_encode64(random_iv)}" }
 
-    def to_s
-      return @binary_bit_string
-    end
+      cipher_text = crypt_cipher.update( key_to_encrypt.to_char64 ) + crypt_cipher.final
+      log.info(x) { "Cipher Text Produced after this Encryption => #{Base64.urlsafe_encode64(cipher_text)}" }
+
+      binary_text = random_iv + cipher_text
+      ones_zeroes = binary_text.unpack("B*")[0]
+      ciphertxt64 = Key64.from_bits( ones_zeroes )
 
+      log.info(x) { "Amalgam of Binary Random IV and Ciphertext => #{ciphertxt64}" }
+      log.info(x) { "------------------------------------------------------------------------- >>>>>>" }
 
-    def to_264_bit_key
+      size_msg = "Expected bit count is #{EXPECTED_CIPHER_BIT_LENGTH} not #{ones_zeroes.length}."
+      raise RuntimeError, size_msg unless ones_zeroes.length == EXPECTED_CIPHER_BIT_LENGTH
 
-      return [ to_s[ 0 .. (264-1) ] ].pack("B*")
+      return ciphertxt64
 
     end
 
 
-    # This method chops away anything after the first 256 bits and returns
-    # the result. Note that if the key was 24 bits long it will return
-    # the 24 bits without question.
+    # Use the {OpenSSL::Cipher::AES256} block cipher in CBC mode and the binary
+    # 256bit representation of this key to decrypt the parameter ciphertext and
+    # return the previously encrypted key.
     #
-    # <b>Size of BCrypt and PBKDF2 Derived Keys</b>
+    # To re-acquire (reconstitute) the original key call this method with the
+    # stored ciphertext that was returned by the {do_encrypt_key}.
     #
-    #   ----------- | --------- | ----------------- | ----------- |
-    #   ----------- | --------- | ----------------- | ----------- |
-    #   | Algorithm | Bit Count | Base64 Chars      | 8 Bit Bytes |
-    #   ----------- | --------- | ----------------- | ----------- |
-    #   | BCrypt    |  168 Bits |   28 characters   |   21 bytes  |
-    #   | Pbkdf2    |   96 Bits |   16 characters   |   12 bytes  |
-    #   ----------- | --------- | ----------------- | ----------- |
-    #   | Total     |  264 Bits |   44 characters   |   33 bytes  |
-    #   ----------- | --------- | ----------------- | ----------- |
+    # <b>Only Encrypt Strong Keys</b>
     #
-    # == 256 Bit Encryption Key | Remove 8 Bits
+    # Never encrypt a potentially weak key, like one derived from a human password
+    # (even though it is put through key derivation functions).
     #
-    # The manufactured encryption key, an amalgam of the above now has
-    # 264 bits carried by 44 Base64 characters.
+    # Once generated (or regenerated) a potentially weak key should live only as
+    # long as it takes for it to encrypt a strong key. The strong key can then
+    # be used to encrypt valuable assets.
     #
-    # Just before it is used to encrypt vital keys, eight (8) bits are
-    # removed from the end of the key. The key is then converted into a
-    # powerful 32 byte (256 bit) encryption agent and is hashed by the
-    # SHA256 digest and delivered.
+    # <b>Enforcing Strong Key Size</b>
     #
-    # @return [Byte]
-    #    a binary string of thirty-two (32) eight (8) bit bytes which
-    #    if appropriate can be used as a symmetric encryption key especially
-    #    to the powerful AES256 cipher.
-    def to_256_bit_key
-      return [ to_s[ 0 .. (256-1) ] ].pack("B*")
-    end
-
-
-    # Return the <b>un-printable <em>binary</em> bytes</b> representation
-    # of this key. If you store 128 bits it will produce 22 characters
-    # because 128 divide by 6 is 21 characters and a remainder of two (2)
-    # bits.
+    # If one key is potentially weaker than the other, the weaker key must be this
+    # object and the strong key is reconstituted and returned by this method.
     #
-    # The re-conversion of the 22 characters will now produce 132 bits which
-    # is different from the original 128 bits.
-    #
-    # @return [Byte]
-    #    a non-printable binary string of eight (8) bit bytes which can be
-    #    used as input to both digest and symmetric cipher functions.
-    def to_binary_bytes
-      return [ to_s ].pack("B*")
-    end
-
-
-    # Return a key that is stoked with 48 random bytes which translates to
-    # a length of either <b>384 bits</b> or <b>64 base64 characters</b>.
-    #
-    # <b>The 48 Bytes map to 64 Base64 Characters</b>
-    #
-    #   | -------- | ------------ | -------------------------------- |
-    #   | Bits     | Bytes        | Base64                           |
-    #   | -------- | ------------ | -------------------------------- |
-    #   | 384 Bits | is 48 bytes  | and 64 characters                |
-    #   | -------- | ------------ | -------------------------------- |
-    #
-    # This key easily translates to a base64 and/or byte array format because
-    # the 384 bit count is a <b>multiple of both 6 and 8</b>.
+    # @param ciphertext_to_decrypt [String]
+    #    Provide the ciphertext produced by our sister key encryption method.
+    #    The ciphertext should hold 96 bytes which equates to 128 base64 characters.
+    #    The random initialization vector (iv) accounts for the first 16 bytes.
+    #    The actual crypt ciphertext then accounts for the final 80 bytes.
     #
     # @return [Key]
-    #    return a key containing 384 random bits (or a random array of 48 bytes)
-    #    which can if necessary be serialized into 64 base64 characters.
-    def self.from_random_bytes
+    #    return the key that was serialized into base64 and then encrypted (locked down)
+    #    with the 256 bit binary symmetric encryption key from this host object.
+    #
+    # @raise [ArgumentError]
+    #    the size of the parameter ciphertext must be 128 base 64 characters.
+    def do_decrypt_key ciphertext_to_decrypt
+
+      calling_module = File.basename caller_locations(1,1).first.absolute_path, ".rb"
+      calling_method = caller_locations(1,1).first.base_label
+      calling_lineno = caller_locations(1,1).first.lineno
+      caller_details = "#{calling_module} | #{calling_method} | (line #{calling_lineno})"
 
-      NUMBER_OF_BYTES_REQUIRED = 48
-      NUMBER_OF_BITS_EXPECTED = 384
-      BASE64_CHARACTER_COUNT = 64
+      log.info(x) { "### #####################################################################" }
+      log.info(x) { "### Caller Details =>> =>> #{caller_details}"                              }
+      log.info(x) { "### #####################################################################" }
+      log.info(x) { "Amalgam of Binary Random IV and Ciphertext => #{ciphertext_to_decrypt}"    }
+      log.info(x) { "The Base64 Char representation of this key => #{to_s()}"                   }
+      log.info(x) { "256bit Digest (Urlsafe Base64) of this key => #{Base64.urlsafe_encode64(to_aes_key())}" }
 
-      raw_bytes = SecureRandom.random_bytes( 64 )
+      bit_text = Key64.to_bits(ciphertext_to_decrypt)
+      size_msg = "Expected bit count is #{EXPECTED_CIPHER_BIT_LENGTH} not #{bit_text.length}."
+      raise RuntimeError, size_msg unless bit_text.length == EXPECTED_CIPHER_BIT_LENGTH
 
-      too_short_msg = "Not enough (only [#{raw_bytes.length}]) random bytes generated."
-      raise RuntimeError, too_short_msg unless raw_bytes.length >= NUMBER_OF_BYTES_REQUIRED
+      cipher_x = OpenSSL::Cipher::AES256.new(:CBC)
+      cipher_x.decrypt()
 
-      random_key = Key.from_byte_array( raw_bytes[ 0 .. ( NUMBER_OF_BYTES_REQUIRED - 1 ) ] )
+      rawbytes = [ bit_text ].pack("B*")
 
-      bit_length = random_key.to_s.length
-      bit_lenth_msg = "Key with #{NUMBER_OF_BITS_EXPECTED} bits expected - not #{bit_length}."
-      raise RuntimeError, bit_length_msg unless bit_length == NUMBER_OF_BITS_EXPECTED
+      cipher_x.key = to_aes_key()
+      cipher_x.iv  = rawbytes[ 0 .. ( RANDOM_IV_BYTE_COUNT - 1 ) ]
+      key_chars_64 = cipher_x.update( rawbytes[ RANDOM_IV_BYTE_COUNT .. -1 ] ) + cipher_x.final
 
-      base64_length = random_key.to_yacht64.length
-      base64_lenth_msg = "Expected #{BASE64_CHARACTER_COUNT} base64 chars not #{base64_length}."
-      raise RuntimeError, base64_length_msg unless base64_length == BASE64_CHARACTER_COUNT
+      log.info(x) { "The OutgoingKey Base64 Char representation => #{key_chars_64}" }
 
-      return random_key
+      return Key.from_char64( key_chars_64 )
 
     end
 
 
+    # Use the {OpenSSL::Cipher::AES256} block cipher in CBC mode and the binary
+    # 256bit representation of this key to encrypt the parameter plaintext using
+    # the parameter random initialization vector.
+    #
+    # Store the ciphertext provided by this method. To re-acquire (reconstitute)
+    # the plaintext use the {do_decrypt_text} decryption method, giving
+    # it the same initialization vector and the ciphertext produced here.
+    #
+    # <b>Only Encrypt Once</b>
+    #
+    # Despite the initialization vector protecting against switch attacks you
+    # should <b>only use this or any other key once</b> to encrypt an object.
+    # While it is okay to encrypt small targets using two different keys, it
+    # pays not to do the same when the target is large.
+    #
+    # @param random_iv [String]
+    #    a randomly generated 16 byte binary string that is to be used as the
+    #    initialization vector (IV) - this is a requirement for AES encryption
+    #    in CBC mode - this IV does not need to be treated as a secret
+    #
+    # @param plain_text [String]
+    #    the plaintext or binary string to be encrypted. To re-acquire this string
+    #    use the {do_decrypt_text} decryption method, giving it the same
+    #    initialization vector (provided in the first parameter) and the ciphertext
+    #    returned from this method.
+    #
+    # @return [String]
+    #    The returned binary ciphertext should be encoded and persisted until such
+    #    a time as its re-acquisition by authorized parties becomes necessary.
+    def do_encrypt_text random_iv, plain_text
+
+      crypt_cipher = OpenSSL::Cipher::AES256.new(:CBC)
+
+      crypt_cipher.encrypt()
+      crypt_cipher.iv  = random_iv
+      crypt_cipher.key = to_aes_key()
 
+      return crypt_cipher.update( plain_text ) + crypt_cipher.final
+
+    end
 
 
-    # Convert non-alphanumeric characters within either Base64 or Radix64 into
-    # the OpenKey YACHT64 standard which has a forward slash but neither a plus sign
-    # nor a period character.
+    # Use the {OpenSSL::Cipher::AES256} block cipher in CBC mode and the binary
+    # 256bit representation of this key to decrypt the parameter ciphertext using
+    # the parameter random initialization vector.
     #
-    # <b>Converting the Non-Alphanumeric Characters</b>
+    # Use this method to re-acquire (reconstitute) the plaintext that was
+    # converted to ciphertext by the {do_encrypt_text} encryption method,
+    # naturally using the same initialization vector for both calls.
     #
-    # The behaviour here is happy to convert base64 strings produced by either
-    # Radix64 or Base64 or UrlSafe Base64. However, it is aware of the
-    # <b>non alpha-numeric characters</b> and converts them before processing
-    # with the modus operandi that says
+    # <b>Only Decrypt Once</b>
     #
-    # - ignore the forward slash  in <b>YACHT64, Base64 and Radix64</b>
-    # - convert the <b>plus (+)</b> in Base64 to the <b>@ symbol</b> in YACHT64
-    # - convert the <b>period (.)</b> in <b>Radix64</b> to the @ symbol in YACHT64
-    # - convert <b>hyphen (-)</b> in <b>Url Safe Base64</b> into a fwd slash
-    # - convert <b>underscore (_)</b> in <b>Url Safe Base64</b> to an @ sign
-    # - <b>delete the (=) equals</b> padding character used by Base64
+    # Consider <b>a key spent</b> as soon as it decrypts the one object it was
+    # created to decrypt. Like a bee dying after a sting, a key should die after
+    # it decrypts an object. Should re-decryption be necessary - another key
+    # should be derived or generated.
     #
-    # Neither the OpenBSD backed Radix64 nor the OpenKey (YACHT64) entertain the
-    # concept of padding.
+    # @param random_iv [String]
+    #    a randomly generated 16 byte binary string that is to be used as the
+    #    initialization vector (IV) - this is a requirement for AES decryption
+    #    in CBC mode - this IV does not need to be treated as a secret
     #
-    # @param char64_string [String]
-    #    string produced in either the Radix64 or the Base64 format
+    # @param cipher_text [String]
+    #    the ciphertext or binary string to be decrypted in order to re-acquire
+    #    (reconstitute) the plaintext that was converted to ciphertext by the
+    #    {do_encrypt_text} encryption method.
     #
     # @return [String]
-    #    an OpenKey YACHT64 standard string that does have a forward slash but neither
-    #    contains a plus sign, nor a period character - and are replaced by the @ symbol.
-    #    No equals padding character will be returned.
-    def replace_yacht64 char64_string
-      return char64_string.gsub(".", "@").gsub("/", "%").gsub("+", "@").gsub("-", "%").gsub("_", "@").delete("=")
-    end
+    #    if the plaintext (or binary string) returned here still needs to be
+    #    kept on the low, derive or generate another key to protect it.
+    def do_decrypt_text random_iv, cipher_text
 
+      raise ArgumentError, "Incoming cipher text cannot be nil." if cipher_text.nil?
 
+      crypt_cipher = OpenSSL::Cipher::AES256.new(:CBC)
 
-    private
+      crypt_cipher.decrypt()
+      crypt_cipher.iv  = random_iv
+      crypt_cipher.key = to_aes_key()
 
+      return crypt_cipher.update( cipher_text ) + crypt_cipher.final
 
-    def assert_yacht64_index yacht64_index
-        index_msg = "yacht64 index should run between 0 and 63 inclusive."
-        all_good = yacht64_index >= 0 && yacht64_index <= 63
-        raise ArgumentError, index_msg unless all_good
     end
 
 
-    def assert_in_out_lengths( in_string, out_string )
+    private
+
+
+    RANDOM_KEY_BYTE_LENGTH = 48
+
+    EIGHT_BIT_INTEGER_SIZE = 256
+
+    RANDOM_IV_BYTE_COUNT = 16
+
+    CIPHERTEXT_BYTE_COUNT = 80
+
+    EXPECTED_CIPHER_BIT_LENGTH = ( CIPHERTEXT_BYTE_COUNT + RANDOM_IV_BYTE_COUNT ) * 8
 
-      in_length = in_string.length
-      out_length = out_string.length
-      good_ratio = out_length == in_length * 6
-      size_msg = "Out string length [#{out_length}] not 6 times bigger than [#{in_length}]."
-      raise RuntimeError, size_msg unless good_ratio
 
+    def assert_non_nil_bits
+      nil_err_msg = "The bit string for this key is nil."
+      raise RuntimeError, nil_err_msg if @bit_string.nil?
     end