opensecret 0.0.988 → 0.0.9925

data/lib/keytools/kdf.pbkdf2.rb

@@ -15,7 +15,17 @@ module OpenKey
   # performed to create the key.
   #
   # <b>One million (1,000,000) should be the iteration count's lower bound.</b>
-  class Pbkdf2KeyGen
+  #
+  # == Upgrading the OpenSSL <em>pbkdf2_hmac</em> Behaviour
+  #
+  # As soon as the new Ruby and OpenSSL libraries become commonplace this class should
+  # be upgraded to use the <b>new and improved {OpenSSL::KDF.pbkdf2_hmac} behaviour</b>
+  # rather than {OpenSSL::PKCS5.pbkdf2_hmac}.
+  #
+  # The difficulty is in detecting the operating system's C libraries that are directly
+  # accessed for OpenSSL functionality. If the distinction can be made accurately, those
+  # with newer libraries can reap the benefits immediately.
+  class KeyPbkdf2
 
 
     # <b>One million iterations</b> is necessary due to the
@@ -25,46 +35,59 @@ module OpenKey
     PBKDF2_ITERATION_COUNT = 1000000
 
 
-    # The current output key length needed is 96 bits which is
-    # 12 bytes. However the algorithm's minimum byte length is
-    # 16 so that is what we must use.
-    PBKDF2_OUTPUT_KEY_LENGTH = 16
-    
-
-    # The documented recommended salt length in bytes is in between
-    # 16 and 24 bytes. The setting here is at the upper bound of
-    # that range.
-    PBKDF2_SALT_LENGTH_BITS = 24 * 8
-
-
-    # When the key is transported using a 64 character set where
-    # each character is represented by 6 bits - the PBKDF2 key
-    # expands to 132 bits rather than the original 128 bits.
+    # Documentation for this algorithm says this about the key length.
     #
-    # This expansion is because of the remainder.
+    # Make the key length <b>larger than or equal to the output length</b>
+    # of the <b>underlying digest function</b>, otherwise an attacker could
+    # simply try to brute-force the key.
     #
-    #    128 bits divided by 6 is 21 characters plus a remainder of two
-    #    (2) bits which must be transported one extra base64 character.
+    # According to PKCS#5, security is limited by the output length of
+    # the underlying digest function, i.e. security is not improved if a
+    # key length strictly larger than the digest output length is chosen.
     #
-    #    Hence the 22 transported characters are then observed to
-    #    be 132 bits in length (22 times 6).
-    PBKDF2_KEY_TRANSPORT_LENGTH = 132
+    # Therefore, when using PKCS5 for password storage, it suffices to
+    # store values equal to the digest output length, nothing is gained
+    # by storing larger values.
+    PBKDF2_EXPORT_KEY_LENGTH = OpenSSL::Digest::SHA384.new.digest_length
+
 
-    
+    # For a 384 bit digest the key length is 48 bytes and the bit length
+    # is 384 bits.
+    PBKDF2_EXPORT_BIT_LENGTH = PBKDF2_EXPORT_KEY_LENGTH * 8
 
-    # Retun a random cryptographic salt generated from twenty-four
+
+
+    # The documented recommended salt length in bytes for the PBKDF2
+    # algorithm is between <b>16 and 24 bytes</b>. The setting here is
+    # at the upper bound of that range.
+    PBKDF2_SALT_LENGTH_BYTES = 24
+
+
+    # Return a random cryptographic salt generated from twenty-four
     # random bytes produced by a secure random number generator. The
-    # returned salt is Base64 encoded.
+    # returned salt is a Base64 encoded string that can be stored
+    # and given straight into the {KeyPbkdf2.generate_key} method.
+    #
+    #   + ------------ + -------- + ------------ + ------------------- +
+    #   |              | Bits     | Bytes        | Base64              |
+    #   | ------------ | -------- | ------------ | ------------------- |
+    #   | PBKDF2 Salt  | 192 Bits | 24 bytes     | 32 characters       |
+    #   + ------------ + -------- + ------------ + ------------------- +
+    #
+    # The returned salt consists of 32 base64 characters which can be
+    # stored and fed into generate key. Before being used, the generate
+    # key method will convert the 32 base64 characters back into a
+    # <b>24 byte binary</b> formatted string.
     #
     # @return [String]
-    #    a base64 encoded representation of a twenty-four (24) randomly
-    #    and securely generated bytes.
-    def self.generate_salt
-      return Base64.urlsafe_encode64( SecureRandom.random_bytes( 24 ) )
+    #    The returned salt consists of 32 base64 characters which can be
+    #    stored and fed into the {KeyPbkdf2.generate_key}. These characters
+    #    represent twenty-four (24) randomly and securely generated bytes.
+    def self.generate_pbkdf2_salt
+      return Key64.from_bits( Key.to_random_bits( PBKDF2_SALT_LENGTH_BYTES ) )
     end
 
 
-
     # Generate a 128 bit binary key from the PBKDF2 password derivation
     # function. The most important input to this function is the human
     # generated key. The best responsibly sourced key with at least 95%
@@ -81,6 +104,31 @@ module OpenKey
     # The {Key} returned by this method encapsulates the derived
     # key of the byte (bit) length specified.
     #
+    # <b>PBKDF2 Output Key Length Note</b>
+    #
+    # Documentation for this algorithm says this about the key length.
+    #
+    #    Typically, the key length should be larger than or equal to the
+    #    output length of the underlying digest function, otherwise an
+    #    attacker could simply try to brute-force the key. According to
+    #    PKCS#5, security is limited by the output length of the underlying
+    #    digest function, i.e. security is not improved if a key length
+    #    strictly larger than the digest output length is chosen.
+    #
+    #    Therefore, when using PKCS5 for password storage, it suffices to
+    #    store values equal to the digest output length, nothing is gained
+    #    by storing larger values.
+    #
+    # <b>Upgrading the OpenSSL <em>pbkdf2_hmac</em> Behaviour</b>
+    #
+    # As soon as the new Ruby and OpenSSL libraries become commonplace this class should
+    # be upgraded to use the <b>new and improved {OpenSSL::KDF.pbkdf2_hmac} behaviour</b>
+    # rather than {OpenSSL::PKCS5.pbkdf2_hmac}.
+    #
+    # The difficulty is in detecting the operating system's C libraries that are directly
+    # accessed for OpenSSL functionality. If the distinction can be made accurately, those
+    # with newer libraries can reap the benefits immediately.
+    #
     # @param human_secret [String]
     #    a robust human generated password with as much entropy as can
     #    be mustered. Remember that 40 characters spread randomly over
@@ -89,9 +137,11 @@ module OpenKey
     #    that has embedded a near 100% entropy rating.
     #
     # @param pbkdf2_salt [String]
-    #    the salt string that has either been recently generated via the
-    #    {generate_salt} method or read from a persistence store and
-    #    resubmitted here in order to regenerate the same key.
+    #    this parameter salt must consist of 32 base64 characters which
+    #    will be converted into a <b>24 byte binary</b> formatted string.
+    #    The salt string presented here must have either been recently
+    #    generated by {generate_pbkdf2salt} or read from a persistence
+    #    store and resubmitted here in order to regenerate the same key.
     #
     # @return [Key]
     #    a key holder containing the key which can then be accessed via
@@ -99,61 +149,20 @@ module OpenKey
     #    encapsulates the derived key with the specified byte count.
     def self.generate_key human_secret, pbkdf2_salt
 
-      pbkdf2_key = OpenSSL::PKCS5.pbkdf2_hmac(
-        human_secret,
-        Base64.urlsafe_decode64( pbkdf2_salt ),
-        PBKDF2_ITERATION_COUNT,
-        PBKDF2_OUTPUT_KEY_LENGTH,
-        OpenSSL::Digest::SHA512.new
-      )
+      KeyError.not_new pbkdf2_salt, "PBKDF2 Algorithm Salt"
+      binary_salt = Key.to_binary_from_bit_string( Key64.to_bits( pbkdf2_salt ) )
+      err_msg = "Expected salt of #{PBKDF2_SALT_LENGTH_BYTES} bytes not #{binary_salt.length}."
+      raise ArgumentError, err_msg unless binary_salt.length == PBKDF2_SALT_LENGTH_BYTES
 
-      return Key.new ( Base64.urlsafe_encode64( pbkdf2_key ) )
-
-
-# ----> -----------------------------------------------------
-# ----> -----------------------------------------------------
-# ----> ruby --version
-# ----> ruby 2.3.1p112 (2016-04-26) [x86_64-linux-gnu]
-# ----> -----------------------------------------------------
-# ----> -----------------------------------------------------
-
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-########### If Condition => IF is Ruby 2.4.1 or greater Use this else use one above
-
-      pbkdf2_key = OpenSSL::KDF.pbkdf2_hmac(
+      pbkdf2_key = OpenSSL::PKCS5.pbkdf2_hmac(
         human_secret,
-        Base64.urlsafe_decode64( @crypt_salt ),
+        binary_salt,
         PBKDF2_ITERATION_COUNT,
-        PBKDF2_OUTPUT_KEY_LENGTH,
-        OpenSSL::Digest::SHA512.new
+        PBKDF2_EXPORT_KEY_LENGTH,
+        OpenSSL::Digest::SHA384.new
       )
 
-      return Key.new ( Base64.urlsafe_encode64( pbkdf2_key ) )
+      return Key.from_binary( pbkdf2_key )
 
     end
 

data/lib/keytools/kdf.scrypt.rb

@@ -0,0 +1,190 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module OpenKey
+
+
+  # SCrypt is a <b>Key Derivation Function (KDF)</b> with a reliable OpenSSL
+  # implementation that converts <b>low entropy</b> password-like text to a
+  # high entropy key that is computationally infeasible to acquire through brute
+  # force.
+  #
+  # SCrypt is incredibly resistant to attacks using dedicated hardware with
+  # massive memory to boot.
+  #
+  class KdfSCrypt
+
+    # SCrypt salts are recommended to contain 16 and 32 bytes
+    # inclusive. Here we opt for 24 bytes which unrolls out to
+    # 192 bits which serializes into 32 base64 characters.
+    SCRYPT_SALT_BYTE_LENGTH = 24
+
+    # The iteration count is determined using the powers of
+    # two so if the iteration integer is 12 there will be two
+    # to the power of 12 ( 2^12 ) giving 4096 iterations.
+    # The minimum number is 4 (16 iterations) and the max is 31.
+    # @example
+    #    Configuring 16 into this directive results in
+    #       2^16 = 65,536 iterations
+    #
+    #    This is a safe default and will slow the derivation time
+    #    to about a second on a powerful 2020 laptop.
+    SCRYPT_ITERATION_INTEGER = 16
+
+    # The scrypt algorithm produces a key that is 181 bits in
+    # length. The algorithm then converts the binary 181 bits
+    # into a (6-bit) Radix64 character.
+    #
+    # 181 / 6 = 30 remainder 1 (so 31 characters are needed).
+    SCRYPT_KEY_LENGTH = 31
+    
+
+    # When the key is transported using a 64 character set where
+    # each character is represented by 6 bits - the Scrypt key
+    # expands to 186 bits rather than the original 181 bits.
+    #
+    # This expansion is because of the remainder.
+    #
+    #    181 bits divided by 6 is 30 characters plus 1 character
+    #    for the extra bit.
+    #
+    #    The 31 transported characters then appear as
+    #    31 times 6 which equals 186 bits.
+    SCRYPT_KEY_TRANSPORT_LENGTH = 186
+    
+    # The scrypt algorithm salt string should be 22 characters
+    # and may include forward slashes and periods.
+    SCRYPT_SALT_LENGTH = 22
+
+    # Scrypt outputs a single line of text that holds the prefix
+    # then the Radix64 encoded salt and finally the Radix64
+    # encoded hash key.
+    #
+    # The prefix consists of <b>two sections</b> sandwiched within
+    # two dollar <b>$</b> signs at the extremeties and a third dollar
+    # separating them.
+    #
+    # The two sections are the
+    # - Scrypt algorithm <b>version number</b> (2a or 2b) and
+    # - a power of 2 integer defining the no. of interations
+    SCRYPT_OUTPUT_TEXT_PREFIX = "$2a$#{SCRYPT_ITERATION_INTEGER}$"
+
+
+    # Generate a secure random and unpredictable salt suitable for
+    # the SCrypt algorithm. SCrypt salts are recommended to contain
+    # 16 and 32 bytes inclusive. Here we opt for 24 bytes which
+    # unrolls to 192 bits which in turn is 32 base64 characters.
+    #
+    # The {OpenKey::KdfSCrypt::SCRYPT_SALT_BYTE_LENGTH} constant
+    # defines the <b>number of random bytes</b> required for a robust
+    # SCrypt salt.
+    #
+    # The salt can be persisted and then resubmitted in order to
+    # regenerate the same key in the future.
+    #
+    # @return [String]
+    #    the salt in a bit string format which can be converted to
+    #    in order to feed the derivation function or indeed converted
+    #    to base64 in order to persist it.
+    def self.generate_scrypt_salt
+      return Key.to_random_bits( SCRYPT_SALT_BYTE_LENGTH )
+    end
+
+
+
+    # Key generators should first use the {generate_salt} method to create
+    # a Scrypt salt string and then submit it to this method together with
+    # a human generated password in order to derive a key.
+    #
+    # The salt can be persisted and then resubmitted again to this method
+    # in order to regenerate the same key at any time in the future.
+    #
+    # Generate a binary key from the scrypt password derivation function.
+    #
+    # This differs from a server side password to hash usage in that we
+    # are interested in the 186bit key that scrypt produces. This method
+    # returns this reproducible key for use during symmetric encryption and
+    # decryption.
+    #
+    # @param secret_text [String]
+    #    a robust human generated password with as much entropy as can
+    #    be mustered. Remember that 40 characters spread randomly over
+    #    the key space of about 90 characters and not relating to any
+    #    dictionary word or name is the way to generate a powerful key
+    #    that has embedded a near 100% entropy rating.
+    #
+    # @param scrypt_salt [String]
+    #    the salt string that has either been recently generated via the
+    #    {generate_salt} method or read from a persistence store and
+    #    resubmitted here (in the future) to regenerate the same key.
+    #
+    # @return [Key]
+    #    a key holder containing the key which can then be accessed via
+    #    many different formats.
+    def self.generate_key secret_text, scrypt_salt
+
+      binary_salt = Key.to_binary_from_bit_string( scrypt_salt )
+
+      require "openssl"
+
+      puts ""
+      puts $LOADED_FEATURES.grep(/openssl/)
+      puts ""
+
+      scrypt_key = OpenSSL::KDF.scrypt(secret_text, salt: binary_salt, N: 2**SCRYPT_ITERATION_INTEGER, r: 8, p: 1, length: 33)
+
+
+
+=begin
+      hashed_secret = Scrypt::Engine.hash_secret( secret_text, to_scrypt_salt(scrypt_salt) )
+      encoded64_key = Scrypt::Password.new( hashed_secret ).to_s
+      key_begin_index = SCRYPT_OUTPUT_TEXT_PREFIX.length + SCRYPT_SALT_LENGTH
+      radix64_key_str = encoded64_key[ key_begin_index .. -1 ]
+      key_length_mesg = "The scrypt key length should have #{SCRYPT_KEY_LENGTH} characters."
+      raise RuntimeError, key_length_mesg unless radix64_key_str.length == SCRYPT_KEY_LENGTH
+
+      return Key.new(radix64_key_str)
+=end
+      return scrypt_key
+    end
+
+
+
+    private
+
+
+    def self.scrypt_test_method
+
+      puts ""
+      puts "##############################################################################"
+
+      key_count = 20
+      for n in 0 .. key_count
+        scrypt_saltbits = OpenKey::KdfSCrypt.generate_scrypt_salt
+        scrypt_key = OpenKey::KdfSCrypt.generate_key( "abonekanoby", scrypt_saltbits )
+        scrypt_saltchar = OpenKey::Key64.from_bits( scrypt_saltbits )
+        puts "#{n} Salt => #{scrypt_saltchar} (#{scrypt_saltchar.length}) => Key => #{scrypt_key} (#{scrypt_key.length})"
+      end
+
+      puts "##############################################################################"
+      puts ""
+
+    end
+
+
+
+    def self.to_scrypt_salt the_salt
+      return SCRYPT_OUTPUT_TEXT_PREFIX + the_salt
+    end
+
+    def self.assert_scrypt_salt the_salt
+      raise RuntimeError, "scrypt salt not expected to be nil." if the_salt.nil?
+      salt_length_msg = "A scrypt salt is expected to contain #{SCRYPT_SALT_LENGTH} characters."
+      raise RuntimeError, salt_length_msg unless the_salt.length == SCRYPT_SALT_LENGTH
+    end
+
+
+  end
+
+
+end

data/lib/keytools/key.64.rb

@@ -0,0 +1,326 @@
+#!/usr/bin/ruby
+
+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 objects.
+  #
+  # == 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
+  # 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.
+  #
+  # <b>The Big4 Character Sets | Base64 | UrlSafe64 | Radix64 | YACHT64</b>
+  #
+  # Base64 and Radix64 (from OpenBSD) differ in both the order of characters
+  # and their choice of the two non-alphanumeric characters. Base64 can also
+  # contain line breaks and equal signs for padding. UrlSafe base64 has different
+  # choices for the two non alphanum characters in keeping with URL standards.
+  #
+  # The character sets for each of the 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>
+  #
+  # == 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 Key64
+
+    # YACHT stands for <b>Yet Another Character Table</b> and it
+    # can map binary sequences onto 64 well chosen characters.
+    #
+    # 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 <b><em>agonisingly close</em></b> 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"
+    ]
+
+
+    # Radix64 strings can contain period characters in their midst.
+    PERIOD = "."
+
+    # Radix64 strings can contain forward slashes in their midst.
+    FORWARD_SLASH = "/"
+
+    # YACHT64 strings can contain at symbols in their midst.
+    AT_SYMBOL = "@"
+
+    # YACHT64 strings can contain percent signs in their midst.
+    PERCENT_SIGN = "%"
+
+
+    # Convert the parameter string of ones and zeroes into an
+    # internal base64 character set known as YACHT for yet another
+    # character table.
+    #
+    # @param bit_string [String]
+    #    a string of ones and zeroes that can be sliced into
+    #    six character chunks with each chunk then being mapped
+    #    to a YACHT64 character.
+    #
+    # @return [String]
+    #    printable characters from a set of 62 alpha-numerics
+    #    plus an @ symbol and a percent % sign.
+    #
+    # @raise ArgumentError
+    #    If the bit string 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 self.from_bits bit_string
+
+      nil_err_msg = "The parameter bit string cannot be nil."
+      raise ArgumentError, nil_err_msg if bit_string.nil?
+
+      bit_size_msg = "The bit string length is not a multiple of #{SIX}."
+      raise ArgumentError, bit_size_msg unless bit_string.length % SIX == 0
+
+      num_unknowns = bit_string.delete("10").length
+      unknowns_msg = "The bit string has #{num_unknowns} characters that are not 1 or 0."
+      raise ArgumentError, unknowns_msg if num_unknowns > 0
+
+      characters64 = ""
+      char_count = bit_string.length / SIX
+      for n in 0 .. (char_count-1)
+        six_bit_chunk = bit_string[ (n*SIX), SIX ]
+        six_bit_index = six_bit_chunk.to_i(2)
+        characters64 += Key64.character(six_bit_index)
+      end
+      
+      code_size_msg = "Length is #{characters64.length} but #{char_count} is expected."
+      raise RuntimeError, code_size_msg unless characters64.length == char_count
+
+      return characters64
+
+    end
+
+
+    # Convert the parameter characters based on an internal base64
+    # character set (known as YACHT) into a <b>bit string</b> of ones
+    # and zeroes.
+    #
+    # @param char64_string [String]
+    #    The base64 character sequence which which will be used to
+    #    derive the returned bit string. Naturally this character
+    #    sequencee cannot be nil, nor can it contain any characters
+    #    that are not present in {Key64::YACHT64_CHARACTER_SET}.
+    #
+    # @return [String]
+    #    a string of ones and zeroes that have been strung out
+    #    from each YACHT64 character. The returned string length of
+    #    ones and zeroes will be exactly 6 times the length of the
+    #    input parameter.
+    #
+    # @raise [ArgumentError]
+    #    If a nil or zero length character string is received.
+    #    Or if the character sequence contains a character not present
+    #    in the {Key64::YACHT64_CHARACTER_SET}.
+    #    
+    # @raise [RuntimeError]
+    #    if the conversion does not result in 6 bits for every character
+    #    in the parameter string.
+    def self.to_bits char64_string
+
+      bit_string = ""
+      char64_string.each_char do |the_char|
+
+        yacht64_index = YACHT64_CHARACTER_SET.index(the_char)
+        assert_yacht64_index( the_char, yacht64_index )
+        bit_string += "%06d" % [ yacht64_index.to_s(2) ]
+
+      end
+
+      assert_bit_lengths char64_string, bit_string
+      return bit_string
+
+    end
+
+
+    # Convert a string of Radix64 characters into a bit representation which
+    # will be 6 times longer than the input parameter. This method first
+    # converts the string into the internal YACHT64 format and then converts
+    # that to a bit string using the {Key64.to_bits} method.
+    #
+    # @param radix64_string [String]
+    #    the radix64 string to convert into bits. 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 [String]
+    #    a string of ones and zeroes that represent the bits converted from the
+    #    radix64 input. The return value will be exactly 6 times the number of
+    #    input characters.
+    def self.from_radix64_to_bits radix64_string
+
+      yacht64_chars = radix64_string.gsub( PERIOD, AT_SYMBOL ).gsub( FORWARD_SLASH, PERCENT_SIGN )
+      out_bitstring = to_bits( yacht64_chars )
+      assert_bit_lengths( radix64_string, out_bitstring )
+      return out_bitstring
+
+    end
+
+
+
+    private
+
+
+
+    SIX = 6
+
+    def self.character char_index
+
+      index_oob_msg = "The character index must be between 0 and 63 inclusive."
+      index_is_oob = char_index < 0 || char_index > 63
+      raise ArgumentError, index_oob_msg if index_is_oob
+      return YACHT64_CHARACTER_SET[ char_index ]
+
+    end
+
+    def self.assert_bit_lengths( in_string, out_string )
+
+      in_length = in_string.length
+      out_length = out_string.length
+      good_ratio = out_length == in_length * SIX
+      size_msg = "Bit string length [#{out_length}] not 6 times more than [#{in_length}]."
+      raise RuntimeError, size_msg unless good_ratio
+
+    end
+
+    def self.assert_yacht64_index the_char, yacht64_index
+
+      nil_msg = "Character [ #{the_char} ] not in YACHT character set."
+      raise ArgumentError, nil_msg if yacht64_index.nil?
+
+      index_msg = "Index of character [ #{the_char} ] not within expected bounds."
+      all_good = ( yacht64_index >= 0 ) && ( yacht64_index <= 63 )
+      raise ArgumentError, index_msg unless all_good
+
+    end
+
+
+  end
+
+
+end