opensecret 0.0.962 → 0.0.988

data/lib/keytools/key.module.rb

@@ -0,0 +1,140 @@
+#!/usr/bin/ruby
+
+# The open key library generates keys, it stores their salts, it produces differing
+# representations of the keys (like base64 for storage and binary for encrypting).
+#
+# == Key Class Names their and Responsibility
+#
+# The 5 core key classes in the open key library are
+#
+# - {Key} represents keys in bits, binary and base 64 formats
+# - {Key64} for converting from to and between base 64 characters
+# - {Key256} uses key derivation functions to produce high entropy keys
+# - {KeyIO} reads and writes key metadata (like salts) from/to persistent storage
+# - {KeyCycle} for creating and locking the keys that underpin the security
+#
+# == The 5 Core Key Classes
+#
+#     Key              To initialize with a 264 binary bit string. To hold the
+#                      key and represent it when requested
+#                       - as a 264 bit binary bit string
+#                       - as a 256 bit binary bit string
+#                       - as a 256 bit raw bytes encryption key
+#                       - as a YACHT64 formatted string
+#
+#     Key64            To map in and out of the Yacht64 character set - from and to
+#                       - a binary bit string sequence
+#                       - a Base64 character encoding
+#                       - a UrlSafe Base64 character encoding
+#                       - a Radix64 character encoding
+#
+#     Key256           It generates a key in 3 different and important ways. It can
+#                      generate
+#
+#                        (a) from_password
+#                        (b) from_random (or it can)
+#                        (c) regenerate
+#
+#                      When generating from a password it takes a dictionary with
+#                      a pre-tailored "section" and writes BCrypt and Pbkdf2 salts
+#                      into it.
+#
+#                      When generating random it kicks of by creating a 55 byte
+#                      random key fo BCrypt and a 64 byte random key for Pbkdf2.
+#                      It then calls upon generate_from_password.
+#
+#                      When regenerating it queries the dictionary provided at the
+#                      pre-tailored "section" for the BCrypt and Pbkdf2 salts and
+#                      then uses input passwords (be they human randomly sourced)
+#                      and regenerates the keys it produced at an earlier sitting.
+#
+#     KeyIO            KeyIO is instantiated with a folder path and a "key reference".
+#                      KeyIO will then manage writing to and rereading from the structure
+#                      hel inside th efile. The file is named (primarily) by the
+#                      reference string.
+#
+#     KeyCycle         KeyLifeCycle implements the merry go round that palms off
+#                      responsibility to the intra-session cycle and then back again
+#                      to ever rotary inter-session(ary) cycle.
+###########            Maybe think of a method where we pass in
+###########            2 secrets - 1 human and 1 55 random bytes (session)
+###########
+###########            1  another 55 random key is created (the actual encryption key)
+###########            2  then the above key is encrypted TWICE (2 diff salts and keys)
+###########            3  Once by key from human password
+###########            4  Once by key from machine password
+###########            5  then the key from 1 is returned
+###########            6  caller encrypts file .................... (go 4 it)
+
+
+# Generates a 256 bit symmetric encryption key derived from a random
+# seed sequence of 55 bytes. These 55 bytes are then fed into the
+# {from_password} key derivation function and processed in a similar
+# way to if a human had generated the string.
+#
+
+
+# <b>Key derivation functions</b> exist to convert <b>low entropy</b> human
+# created passwords into a high entropy key that is computationally difficult
+# to acquire through brute force.
+#
+# == OpenSecret's Underlying Security Strategy
+#
+# <b>Randomly generate a 256 bit encryption key and encrypt it</b> with a key
+# derived from a human password and generated by at least two cryptographic
+# workhorses known as <b>key derivation functions</b>.
+#
+# The encryption key (encrypted by the one derived from a human password) sits
+# at the beginning of a long chain of keys and encryption - so much so that the
+# crypt material being outputted for storage is all but worthless to anyone but
+# its rightful owner.
+#
+# == Key Size vs Crack Time
+#
+# Cracking a 256 bit key would need roughly 2^255 iterations (half the space)
+# and this is akin to the number of atoms in the known universe.
+#
+# <b>The human key can put security at risk.</b>
+#
+# The rule of thumb is that a 40 character password with a good spread of the
+# roughly 90 typable characters, would produce security equivalent to that of
+# an AES 256bit key. As the password size and entropy drop, so does the security,
+# exponentially.
+#
+# As human generated passwords have a relatively small key space, key derivation
+# functions must be slow to compute with any implementation.
+#
+# == Key Derivation Functions for Command Line Apps
+#
+# A command line app (with no recourse to a central server) uses a Key
+# Derivation Function (like BCrypt, Aaron2 or PBKD2) in a manner different
+# to that employed by server side software.
+#
+# - server side passwords are hashed then both salt and hash are persisted
+# - command line apps do not store the key - they only store the salt
+# - both throw away the original password
+#
+# == One Key | One Session | One Crypt
+#
+# Command line apps use the derived key to <b>symmetrically encrypt and decrypt</b>
+# one and only one 48 character key and a new key is derived at the beginning
+# of every session.
+#
+# At the end of the session <b>all material encrypted by the outgoing key</b>
+# is removed. This aggressive key rotation strategy leaves no stone unturned in
+# the quest for ultimate security.
+#
+# == OpenSecret's CLI Key Derivation Architecture
+#
+# OpenSecret never accesses another server and giving its users total control
+# of their secret crypted materials. It strengthens the key derivation process
+# in three important ways.
+#
+# - [1] it does not store the key nor does it store the password
+#
+# - [2] a new master key is generated for every session only to hold the master index file
+#
+# - [3] it uses both <b>BCrypt</b> (Blowfish Crypt) and the indefatigable <b>PBKD2</b>
+module OpenKey
+
+end

data/lib/keytools/key.rb

@@ -0,0 +1,481 @@
+#!/usr/bin/ruby
+
+module OpenKey
+
+  # 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
+  # bytes and as base64.
+  #
+  # == Key | To and From Behaviour
+  #
+  # Use the <b>From</b> methods to create Keys from a variety of resources
+  # such as
+  #
+  # - a base64 encoded string
+  # - a binary byte string
+  # - a string of one and zero bits
+  # - a hexadecimal representation
+  #
+  # Once you have instantiated the key, you will then be able to convert it
+  # (within reason due to bit, byte and base64 lengths) to any of the above
+  # key representations.
+  #
+  # == Key | Bits Bytes and Base64
+  #
+  # The shoe doesn't always fit when its on the other foot and this is best
+  # illustratd with a table that maps bits to 8 bit bytes and 6 bit Base64
+  # characters.
+  #
+  #   | --------- | -------- | ------------ | ------------------------------- |
+  #   | Fit?      | Bits     | Bytes        | (and) Base64                    |
+  #   | --------- | -------- | ------------ | ------------------------------- |
+  #   | Perfect   | 168 Bits | is 21 bytes  | 28 Chars - bcrypt chops to this |
+  #   | Perfect   | 216 Bits | is 27 bytes  | 36 Chars -                      |
+  #   | Perfect   | 264 Bits | is 33 bytes  | 44 Chars - holder 4 256bit keys |
+  #   | Perfect   | 384 Bits | is 48 bytes  | 64 Chars - 216 + 168 equals 384 |
+  #   | --------- | -------- | ------------ | ------------------------------- |
+  #   | Imperfect | 128 Bits | 16 precisely | 22 Chars - 21 + 2 remain bits   |
+  #   | Imperfect | 186 Bits | 23 remain 2  | 31 Characers precisely          |
+  #   | Imperfect | 256 Bits | 32 precisely | 43 Chars - 42 + 4 remain bits   |
+  #   | --------- | -------- | ------------ | ------------------------------- |
+  #
+  # Yes, the shoe doesn't always fit when it's on the other foot.
+  #
+  # == Schoolboy Error
+  #
+  # <b>The strategy is so simple, we call it a schoolboy error.</b>
+  #
+  # If we want to use a key with n bits and either n % 6 or n % 8 (or both)
+  # are not zero - <b>we instantiate a Key</b> with the lowest common
+  # denominator of 6 and 8 that exceeds n.
+  #
+  # 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
+  # bits for hexadecimal). Here is an example mapping between
+  # a base 64 character, an integer and the six bit binary.
+  #
+  #    Character   Integer  Binary (6 Bit)
+  #
+  #       a           0        000000
+  #       b           1        000001
+  #       c           2        000010
+  #
+  #       y           25       011001
+  #       z           26       011010
+  #       A           27       011011
+  #       B           28       011100
+  #
+  #       8           60       111100
+  #       9           61       111101
+  #       /           62       111110
+  #       +           63       111111
+  #
+  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
+    #
+    # @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
+
+    end
+
+
+    def instantiate_from_base64 base64_string
+
+      @original64_string = replace_yacht64( base64_string )
+
+      @binary_bit_string = ""
+      @original64_string.each_char do |the_char|
+
+        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?
+
+        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) ]
+
+      end
+
+      assert_in_out_lengths @original64_string, @binary_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
+
+    end
+
+
+
+    # Retrieve a cryptographically strong key that is 64 encoded
+    # with a bit (not byte) count specified by the parameter.
+    #
+    # <b>Bit Count must be Multiple of 24</b>
+    #
+    # 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.
+    #
+    # 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.
+    #
+    # @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.
+    #
+    # @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
+
+      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
+
+      length_msg = "Expected [#{num_6bit_blocks}] characters not #{length_64string}."
+      raise RuntimeError, length_msg unless length_64string == num_6bit_blocks
+
+#####################      return to_yacht64( perfect_rand_64 )
+
+    end
+
+
+    # Return a representation of this key in YACHT64 format which is
+    # simply <b>Yet Another Coding Hieroglyphics-like Table (YACHT).
+    #
+    # This new format can suck in RADIX64 as well as Base64 and is
+    # safe for transportation with carriers such as
+    #
+    # - URLs
+    # - <b>one line text</b> (without newlines and carriage returns)
+    # - <b>environment variables</b>
+    # - INI, JSON, YAML and XML files
+    #
+    # <b>Character Order | Base64 | UrlSafe64 | Radix64 | YACHT64</b>
+    #
+    # 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.
+    #
+    # @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
+
+      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
+
+      return the_yacht64_encoding
+
+    end
+
+
+    def to_s
+      return @binary_bit_string
+    end
+
+
+    def to_264_bit_key
+
+      return [ to_s[ 0 .. (264-1) ] ].pack("B*")
+
+    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.
+    #
+    # <b>Size of BCrypt and PBKDF2 Derived Keys</b>
+    #
+    #   ----------- | --------- | ----------------- | ----------- |
+    #   ----------- | --------- | ----------------- | ----------- |
+    #   | 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  |
+    #   ----------- | --------- | ----------------- | ----------- |
+    #
+    # == 256 Bit Encryption Key | Remove 8 Bits
+    #
+    # The manufactured encryption key, an amalgam of the above now has
+    # 264 bits carried by 44 Base64 characters.
+    #
+    # 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.
+    #
+    # @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.
+    #
+    # 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>.
+    #
+    # @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
+
+      NUMBER_OF_BYTES_REQUIRED = 48
+      NUMBER_OF_BITS_EXPECTED = 384
+      BASE64_CHARACTER_COUNT = 64
+
+      raw_bytes = SecureRandom.random_bytes( 64 )
+
+      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
+
+      random_key = Key.from_byte_array( raw_bytes[ 0 .. ( NUMBER_OF_BYTES_REQUIRED - 1 ) ] )
+
+      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
+
+      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
+
+      return random_key
+
+    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.
+    #
+    # <b>Converting the Non-Alphanumeric Characters</b>
+    #
+    # 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
+    #
+    # - 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.
+    #
+    # @param char64_string [String]
+    #    string produced in either the Radix64 or the Base64 format
+    #
+    # @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
+
+
+
+    private
+
+
+    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 )
+
+      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
+
+    end
+
+
+  end
+
+
+end