opensecret 0.0.988 → 0.0.9925

data/lib/keytools/key.db.rb

@@ -0,0 +1,265 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module OpenKey
+
+  require 'json'
+
+  # An envelope knows how to manipulate a JSON backed data structure
+  # (put, add etc) <b>after reading and then decrypting it</b> from a
+  # file and <b>before encrypting and then writing it</b> to a file.
+  #
+  # It provides behaviour to which we can create, append (add), update
+  # (change), read parts and delete essentially two structures
+  #
+  # - a collection of name/value pairs
+  # - an  ordered list of values
+  #
+  # == JSON is Not Exposed in the Interface
+  #
+  # An envelope doesn't expose the data format used in the implementation
+  # allowing this to be changed seamlessly to YAMl or other formats.
+  #
+  # == Symmetric Encryption and Decryption
+  #
+  # An envelope supports operations to <b>read from</b> and <b>write to</b>
+  # a known filepath and with a symmetric key it can
+  #
+  # - decrypt <b>after reading from</b> a file and
+  # - encrypt <b>before writing to</b> a (the same) file
+  #
+  # == Hashes as the Primary Data Structure
+  #
+  # Envelope extends {Hash} as the core data structure for holding
+  #
+  # - strings
+  # - arrays
+  # - other hashes
+  # - booleans
+  # - integers and floats
+  class KeyDb < Hash
+
+    # Return a key database data structure that is instantiated from
+    # the parameter JSON string.
+    #
+    # @param db_json_string [String]
+    #    this json formatted data structure will be converted into a
+    #    a Ruby hash (map) data structure and returned.
+    #
+    # @return [KeyDb]
+    #    a hash data structure that has been instantiated as per the
+    #    parameter json string content.
+    def self.from_json( db_json_string )
+
+      data_db = KeyDb.new()
+      data_db.merge!( JSON.parse( db_json_string ) )
+      return data_db
+
+    end
+
+
+
+    # Create a new key value entry inside a dictionary with the specified
+    # name at the root of this database. Successful completion means the
+    # named dictionary will contain one more entry than it need even if it
+    # did not previously exist.
+    #
+    # @param dictionary_name [String]
+    #
+    #    if a dictionary with this name exists at the root of the
+    #    database add the parameter key value pair into it.
+    #
+    #    if no dictionary exists then create one first before adding
+    #    the key value pair as the first entry into it.
+    #
+    # @param key_name [String]
+    #
+    #    the key part of the key value pair that will be added into the
+    #    dictionary whose name was provided in the first parameter.
+    #
+    # @param value [String]
+    #
+    #    the value part of the key value pair that will be added into the
+    #    dictionary whose name was provided in the first parameter.
+    def create_entry( dictionary_name, key_name, value )
+
+      KeyError.not_new( dictionary_name, self )
+      KeyError.not_new( key_name, self )
+      KeyError.not_new( value, self )
+
+      self[ dictionary_name ] = {} unless self.has_key?( dictionary_name )
+      self[ dictionary_name ][ key_name ] = value
+
+    end
+
+
+    # Fast forward tries to walk down this database tree as far as it can
+    # led by the <b>forward-slash separated</b> tree_path parameter.
+    #
+    # It stops the first time it encounters a key within the tree_path that
+    # is not next in line from the currently walked position and returns
+    # the sub tree at its point.
+    #
+    # @param tree_path [String]
+    #
+    #    this is a forward slash separated path that is expected to align
+    #    perfectly with a path down this tree database.
+    #
+    #    The child tree is returned as soon as a dead end is reached where
+    #    the next branch in the tree_path does not correspond to a key at
+    #    the walked position.
+    #
+    #    The remaining subtree is returned if the tree_path end is reached.
+    def fast_forward( tree_path )
+
+      KeyError.not_new( tree_path, self )
+
+      ## @todo put a loop here
+      ## @todo put a loop here
+      ## @todo put a loop here
+      ## @todo put a loop here
+      ## @todo put a loop here
+      sub_tree = self[ tree_path ] if self.has_key?( tree_path )
+
+      sub_database = KeyDb.new()
+      sub_database.merge!( sub_tree )
+
+      return sub_database
+
+    end
+
+
+    # Does this database have an entry in the root dictionary named with
+    # the key_name parameter?
+    #
+    # @param dictionary_name [String]
+    #
+    #    immediately return false if a dictionary with this name does
+    #    <b>not exist</b> at the root of this database.
+    #
+    # @param key_name [String]
+    #
+    #    test whether a key/value pair answering to this name exists inside
+    #    the specified dictionary at the root of this database.
+    #
+    def has_entry?( dictionary_name, key_name )
+
+      KeyError.not_new( dictionary_name, self )
+      KeyError.not_new( key_name, self )
+
+      return false unless self.has_key?( dictionary_name )
+      return self[ dictionary_name ].has_key?( key_name )
+
+    end
+
+
+    # Get the entry with the key name in a dictionary that is itself
+    # inside another dictionary (named in the first parameter) which
+    # thankfully is at the root of this database.
+    #
+    # Only call this method if {has_entry?} returns true for the same
+    # dictionary and key name parameters.
+    #
+    # @param dictionary_name [String]
+    #
+    #    get the entry inside a dictionary which is itself inside a
+    #    dictionary (with this dictionary name) which is itself at the
+    #    root of this database.
+    #
+    # @param key_name [String]
+    #
+    #    get the value part of the key value pair that is inside a
+    #    dictionary (with the above dictionary name) which is itself
+    #    at the root of this database.
+    #
+    def get_entry( dictionary_name, key_name )
+
+      return self[ dictionary_name ][ key_name ]
+
+    end
+
+
+    # Read and inject into this envelope, the data structure found in a
+    # file at the path specified in the first parameter.
+    #
+    # Symmetric cryptography is mandatory for the envelope so we must
+    # <b>encrypt before writing</b> and <b>decrypt after reading</b>.
+    #
+    # An argument error will result if a suitable key is not provided.
+    #
+    # If the file does not exist (denoting the first read) all this method
+    # does is to stash the filepath as an instance variable and igore the
+    # decryption key which can be nil (or ommitted).
+    #
+    # @param the_filepath [String]
+    #     absolute path to the file which acts as the persistent mirror to
+    #     this data structure envelope.
+    #
+    # @param decryption_key [String]
+    #     encryption at rest is a given so this mandatory parameter must
+    #     contain a robust symmetric decryption key. The key will be used
+    #     for decryption after the read and it will not linger (ie not cached
+    #     as an instance variable).
+    #
+    # @raise [ArgumentError] if the decryption key is not robust enough.
+    def read the_filepath, decryption_key = nil
+
+      raise RuntimeError, "This KeyDb.read() software is never called so how can I be here?"
+
+      @filepath = the_filepath
+      return unless File.exists? @filepath
+
+      cipher_text = Base64.decode64( File.read( @filepath ).strip )
+      plain_text = ToolBelt::Blowfish.decryptor( cipher_text, decryption_key )
+
+      data_structure = JSON.parse plain_text
+      self.merge! data_structure
+
+    end
+
+
+    # Write the data in this envelope hash map into a file-system
+    # backed mirror whose path was specified in the {self.read} method.
+    #
+    # Technology for encryption at rest is supported by this dictionary
+    # and to this aim, please endeavour to post a robust symmetric
+    # encryption key.
+    #
+    # Calling this {self.write} method when the file at the prescribed path
+    # does not exist results in the directory structure being created
+    # (if necessary) and then the encrypted file being written.
+    #
+    # @param encryption_key [String]
+    #     encryption at rest is a given so this mandatory parameter must
+    #     contain a robust symmetric encryption key. The symmetric key will
+    #     be used for the decryption after the read. Note that the decryption
+    #     key does not linger meaning it isn't cached in an instance variable.
+    def write encryption_key
+
+      raise RuntimeError, "This KeyDb.write( key ) software is never called so how can I be here?"
+
+      FileUtils.mkdir_p(File.dirname(@filepath))
+      cipher_text = Base64.encode64 ToolBelt::Blowfish.encryptor( self.to_json, encryption_key )
+      File.write @filepath, cipher_text
+
+      puts ""
+      puts "=== ============================"
+      puts "=== Envelope State ============="
+      puts "=== ============================"
+
+      a_ini_file = IniFile.new
+      self.each_key do |section_name|
+        a_ini_file[section_name] = self[section_name]
+      end
+      puts a_ini_file.to_s
+
+      puts "=== ============================"
+      puts ""
+
+    end
+
+
+  end
+
+
+end

data/lib/keytools/{key.module.rb → key.docs.rb}

@@ -135,6 +135,61 @@
 # - [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>
+
+
+  # After a successful initialization, the application instance is linked to a keystore
+  # whose contents are responsible for securing the application instance database.
+  #
+  # To ascertain what needs to be done to bridge the gap to full initialization the
+  # app needs to know 3 things from the KeyApi. These things are
+  #
+  # - the ID of this app instance on the machine
+  # - if a keystore been associated with this ID
+  # - whether the keystore secures the app database
+  #
+  # The answers dictate the steps that need to be undertaken to bring the database of
+  # the application instance under the secure wing of the KeyApi.
+  #
+  #
+  # == 1. What is the App Instance ID on this Machine?
+  #
+  # The KeyApi uses the "just given" application reference and the machine environment to
+  # respond with a <b>digested identifier</b> binding the application instance to the
+  # present machine (workstation).
+  #
+  #
+  # == 2. Has a Keystore been associated with this ID?
+  #
+  # The application's configuration manager is asked to find an associated KeyStore ID
+  # mapped against the app/machine id garnered by question 1.
+  #
+  # <b>No it has not!</b>
+  #
+  # If <b>NO</b> then a KeyStore ID is acquired <b>either from the init command's parameter</b>,
+  # or a <b>suitable default</b>. This new association between the app/machine ID and the
+  # KeyStore ID is then stored so the answer next time will be <b>YES</b>.
+  #
+  # <b>Yes it has!</b>
+  #
+  # Great - we now submit the KeyStore ID to the KeyApi so that it may answer question 3.
+  #
+  #
+  # == 3. Does the keystore secure the app instance database?
+  #
+  # For the KeyApi to answer, it needs the App's Instance ID and the KeyStore ID.
+  #
+  # <b>Not Yet!</b> Now <b>NO</b> means this application instance's database has not been
+  # brought under the protection of the KeyApi's multi-layered security net. For this it
+  # needs
+  #
+  # - the KeyStore ID
+  # - the application instance reference
+  # - the plaintext secret from which nothing of the host survives
+  # - the current application database plaintext
+  #
+  # <b>Yes it does!</b> If the app db keys <b>have been instantiated</b> and the client app is
+  # <b>sitting pretty</b> in possession of the database ciphertext, no more needs doing.
+
 module OpenKey
 
 end

data/lib/keytools/key.error.rb

@@ -0,0 +1,110 @@
+#!/usr/bin/ruby
+
+module OpenKey
+
+
+  # This class is the parent to all opensession errors
+  # that originate from the command line.
+  #
+  # All opensession cli originating errors are about
+  #
+  # - a problem with the input or
+  # - a problem with the current state or
+  # - a predictable future problem
+  class KeyError < StandardError
+
+
+    # Initialize the error and provide a culprit
+    # object which will be to-stringed and given
+    # out as evidence (look at this)!
+    #
+    # This method will take care of loggin the error.
+    #
+    # @param message [String] human readable error message
+    # @param culprit [Object] object that is either pertinent, a culprit or culpable 
+    def initialize message, culprit
+
+      super(message)
+
+      @the_culprit = culprit
+
+      log.info(x) { "An [Error] Occured => #{message}" }
+      log.info(x) { "Object of Interest => #{culprit.to_s}" } unless culprit.nil?
+      log.info(x) { "Class Name Culprit => #{culprit.class.name}" }
+      log.info(x) { "Error Message From => #{self.class.name}" }
+
+      thread_backtrace = Thread.current.backtrace.join("\n")
+      thread_backtrace.to_s.log_lines
+
+    end
+
+
+    # This method gives interested parties the object that
+    # is at the centre of the exception. This object is either
+    # very pertinent, culpable or at the very least, interesting.
+    #
+    # @return [String] string representation of culpable object
+    def culprit
+      return "No culprit identified." if @the_culprit.nil?
+      return @the_culprit.to_s
+    end
+
+
+    # Assert that the parameter string attribute is <b>not new</b> which
+    # means neither nil, nor empty nor consists solely of whitespace.
+    #
+    # The <b>NEW</b> acronym tells us that a bearer worthy of the name is
+    #
+    # - neither <b>N</b>il
+    # - nor <b>E</b>mpty
+    # - nor consists solely of <b>W</b>hitespace
+    #
+    # @param the_attribute [String]
+    #    raise a {KeyError} if the attribute is not new.
+    #
+    # @param the_desc [String]
+    #    a description of th attribute
+    #
+    # @raise [KeyError]
+    #
+    # The attribute cannot be <b>NEW</b>. The <b>NEW acronym</b> asserts
+    # that the attribute is
+    #
+    # - neither <b>N</b>il
+    # - nor <b>E</b>mpty
+    # - nor <b>W</b>hitespace only
+    #
+    def self.not_new the_attribute, the_desc
+
+      attribute_new = the_attribute.nil? || the_attribute.chomp.strip.empty?
+      return unless attribute_new
+
+      msg = "[the_desc] is either nil, empty or consists solely of whitespace."
+      raise KeyError.new( msg, the_desc )
+
+    end
+
+
+  end
+
+=begin
+  # Throw this error if the configured safe directory points to a file.
+  class SafeDirectoryIsFile < OpenError::CliError; end;
+
+  # Throw this error if safe directory path is either nil or empty.
+  class SafeDirNotConfigured < OpenError::CliError; end;
+
+  # Throw this error if the email address is nil, empty or less than 5 characters.
+  class EmailAddrNotConfigured < OpenError::CliError; end;
+
+  # Throw this error if the store url is either nil or empty.
+  class StoreUrlNotConfigured < OpenError::CliError; end;
+
+  # Throw if "prime folder" name occurs 2 or more times in the path.
+  class SafePrimeNameRepeated < OpenError::CliError; end;
+
+  # Throw if "prime folder" name occurs 2 or more times in the path.
+  class SafePrimeNameNotAtEnd < OpenError::CliError; end;
+=end
+
+end

data/lib/keytools/key.id.rb

@@ -0,0 +1,271 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+
+module OpenKey
+
+
+  # This class derives <b>non secret but unique identifiers</b> based on different
+  # combinations of the <b>application, shell and machine (compute element)</b>
+  # references.
+  #
+  # == Identifier Are Not Secrets
+  #
+  # <b>And their starting values are retrievable</b>
+  #
+  # Note that the principle and practise of <b>identifiers is not about keeping secrets</b>.
+  # An identifier can easily give up its starting value/s if and when brute force is
+  # applied. The properties of a good iidentifier (ID) are
+  #
+  # - non repeatability (also known as uniqueness)
+  # - non predictability (of the next identifier)
+  # - containing alphanumerics (for file/folder/url names)
+  # - human readable (hence hyphens and separators)
+  # - non offensive (no swear words popping out)
+  #
+  # == Story | Identifiers Speak Volumes
+  #
+  # I told a friend what the turnover of his company was and how many clients he had.
+  # He was shocked and wanted to know how I had gleened this information.
+  #
+  # The invoices he sent me (a year apart). Both his invoice IDs (identifiers) and his
+  # user IDs where integers that counted up. So I could determine how many new clients
+  # he had in the past year, how many clients he had when I got the invoice, and I
+  # determined the turnover by guesstimating the average invoice amount.
+  #
+  # Many successful website attacks are owed to a predictable customer ID or a counter
+  # type session ID within the cookies.
+  #
+  # == Good Identifiers Need Volumes
+  #
+  # IDs are not secrets - but even so, a large number of properties are required
+  # to produce a high quality ID.
+  #
+  class KeyId
+
+
+    # The identity chunk length is set at four (4) which means each of the
+    # fabricated identifiers comprises of four character segments divided by
+    # hyphens. Only the <b>62 alpha-numerics ( a-z, A-Z and 0-9 )</b> will
+    # appear within identifiers - which maintains simplicity and provides an
+    # opportunity to re-iterate that <b>identifiers</b> are designed to be
+    # <b>unpredictable</b>, but <b>not secret</b>.
+    IDENTITY_CHUNK_LENGTH = 4
+
+
+    # A hyphen is the chosen character for dividing the identifier strings
+    # into chunks of four (4) as per the {IDENTITY_CHUNK_LENGTH} constant.
+    SEGMENT_CHAR = "-"
+
+
+    # Get an identifier that is <b>always the same</b> for the parameter
+    # application reference <b>regardless of the machine or shell</b> or
+    # even the machine user, coming together to make the request.
+    #
+    # The returned identifier will consist only of alphanumeric characters
+    # and one hyphen, plus it always starts and ends with an alphanumeric.
+    #
+    # @param app_instance_ref [String]
+    #    the string reference of the application instance (or shard) that
+    #    is in play and needs to be digested into a unique but not-a-secret
+    #    identifier.
+    #
+    # @return [String]
+    #    An identifier that is guaranteed to be the same whenever the
+    #    same application reference is provided on any machine, using any
+    #    user through any shell interface or command prompt.
+    #
+    #    It must be different for any other application reference.
+    def self.derive_app_instance_identifier( app_instance_ref )
+      return derive_identifier( app_instance_ref )
+    end
+
+
+    # Get an identifier that is <b>always the same</b> for the application
+    # instance (with reference given in parameter) on <b>this machine</b>
+    # and is always different when either/or or both the application ref
+    # and machine are different.
+    #
+    # The returned identifier will consist of only alphanumeric characters
+    # and hyphens - it will always start and end with an alphanumeric.
+    #
+    # This behaviour draws a fine line around the concept of machine, virtual
+    # machine, <b>workstation</b> and/or <b>compute element</b>.
+    #
+    # <b>(aka) The AIM ID</b>
+    #
+    # Returned ID is aka the <b>Application Instance Machine (AIM)</b> Id.
+    #
+    # @param app_ref [String]
+    #    the string reference of the application instance (or shard) that
+    #    is being used.
+    #
+    # @return [String]
+    #    an identifier that is guaranteed to be the same whenever the
+    #    same application reference is provided on this machine.
+    #
+    #    it must be different on another machine even when the same
+    #    application reference is provided.
+    #
+    #    It will also be different on this workstation if the application
+    #    instance identifier provided is different.
+    def self.derive_app_instance_machine_id( app_ref )
+      return derive_identifier( app_ref + KeyMach.derive_machine_identity_string() )
+    end
+
+
+    # The <b>32 character</b> <b>universal identifier</b> bonds a digested
+    # <b>application state identifier</b> with the <b>shell identifier</b>.
+    # This method gives <b>dual double guarantees</b> to the effect that
+    #
+    # - a change in one, or in the other,  or in both returns a different universal id
+    # - the same app state identifier in the same shell produces the same universal id
+    #
+    # <b>The 32 Character Universal Identifier</b>
+    #
+    # The universal identifier is an amalgam of two digests which can be individually
+    # retrieved from other methods in this class. An example is
+    #
+    #       universal id => hg2x0-g3uslf-pa2bl5-09xvbd-n4wcq
+    #       the shell id => g3uslf-pa2bl5-09xvbd
+    #       app state id => hg2x0-n4wcq
+    #
+    # The 32 character universal identifier comprises of 18 session identifier
+    # characters (see {derive_session_id}) <b>sandwiched between</b>
+    # ten (10) digested application identifier characters, five (5) in front and
+    # five (5) at the back - all segmented by four (4) hyphens.
+    #
+    # @param app_reference [String]
+    #    the chosen plaintext application reference identifier that
+    #    is the input to the digesting (hashing) algorithm.
+    #
+    # @param session_token [String]
+    #    a triply segmented (and one liner) text token instantiated by
+    #    {KeyLocal.generate_shell_key_and_token} and provided
+    #    here ad verbatim.
+    #
+    # @return [String]
+    #    a 32 character string that cannot feasibly be repeated due to the use
+    #    of one way functions within its derivation. The returned identifier bonds
+    #    the application state reference with the present session.
+    def self.derive_universal_id( app_reference, session_token )
+
+      shellid = derive_session_id( session_token )
+      app_ref = derive_identifier( app_reference + shellid )
+      chunk_1 = app_ref[ 0 .. IDENTITY_CHUNK_LENGTH ]
+      chunk_3 = app_ref[ ( IDENTITY_CHUNK_LENGTH + 1 ) .. -1 ]
+
+      return "#{chunk_1}#{shellid}#{SEGMENT_CHAR}#{chunk_3}".downcase
+
+    end
+
+
+    # The session ID generated here is a derivative of the 150 character
+    # session token instantiated by {KeyLocal.generate_shell_key_and_token}
+    # and provided here <b>ad verbatim</b>.
+    #
+    # The algorithm for deriving the session ID is as follows.
+    #
+    # - convert the 150 characters to an alphanumeric string
+    # - convert the result to a bit string and then to a key
+    # - put the key's binary form through a 384 bit digest
+    # - convert the digest's output to 64 YACHT64 characters
+    # - remove the (on average 2) non-alphanumeric characters
+    # - cherry pick a spread out 12 characters from the pool
+    # - hiphenate the character positions five (5) and ten (10)
+    # - ensure the length of the resultant ID is fourteen (14)
+    #
+    # The resulting session id will look something like this
+    #
+    #       g3sf-pab5-9xvd
+    #
+    # @param session_token [String]
+    #    a triply segmented (and one liner) text token instantiated by
+    #    {KeyLocal.generate_shell_key_and_token} and provided here ad
+    #    verbatim.
+    #
+    # @return [String]
+    #    a 14 character string that cannot feasibly be repeated
+    #    within the keyspace of even a gigantic organisation.
+    #
+    #    This method guarantees that the session id will always be the same when
+    #    called by commands within the same shell in the same machine.
+    def self.derive_session_id( session_token )
+
+      assert_session_token_size( session_token )
+      random_length_id_key = Key.from_char64( session_token.to_alphanumeric )
+      a_384_bit_key = random_length_id_key.to_384_bit_key()
+      a_64_char_str = a_384_bit_key.to_char64()
+      base_64_chars = a_64_char_str.to_alphanumeric
+
+      id_chars_pool = KeyAlgo.cherry_picker( ID_TRI_CHUNK_LEN, base_64_chars )
+      id_hyphen_one = id_chars_pool.insert( IDENTITY_CHUNK_LENGTH, SEGMENT_CHAR )
+      id_characters = id_hyphen_one.insert( ( IDENTITY_CHUNK_LENGTH * 2 + 1 ), SEGMENT_CHAR )
+
+      err_msg = "Shell ID needs #{ID_TRI_TOTAL_LEN} not #{id_characters.length} characters."
+      raise RuntimeError, err_msg unless id_characters.length == ID_TRI_TOTAL_LEN
+
+      return id_characters.downcase
+
+    end
+
+
+    # This method returns a <b>10 character</b> digest of the parameter
+    # <b>reference</b> string.
+    #
+    # <b>How to Derive the 10 Character Identifier</b>
+    #
+    # So how are the 10 characters derived from the reference provided in
+    # the first parameter. The algorithm is this.
+    #
+    # - reverse the reference and feed it to a 256 bit digest
+    # - chop away the rightmost digits so that 252 bits are left
+    # - convert the one-zero bit str to 42 (YACHT64) characters
+    # - remove the (on average 1.5) non-alphanumeric characters
+    # - cherry pick and return <b>spread out 8 characters</b>
+    #
+    # @param reference [String]
+    #    the plaintext reference input to the digest algorithm
+    #
+    # @return [String]
+    #    a 10 character string that is a digest of the reference string
+    #    provided in the parameter.
+    def self.derive_identifier( reference )
+
+      bitstr_256 = Key.from_binary( Digest::SHA256.digest( reference.reverse ) ).to_s
+      bitstr_252 = bitstr_256[ 0 .. ( BIT_LENGTH_252 - 1 ) ]
+      id_err_msg = "The ID digest needs #{BIT_LENGTH_252} not #{bitstr_252.length} chars."
+      raise RuntimeError, id_err_msg unless bitstr_252.length == BIT_LENGTH_252
+
+      id_chars_pool = Key64.from_bits( bitstr_252 ).to_alphanumeric
+      undivided_str = KeyAlgo.cherry_picker( ID_TWO_CHUNK_LEN, id_chars_pool )
+      id_characters = undivided_str.insert( IDENTITY_CHUNK_LENGTH, SEGMENT_CHAR )
+
+      min_size_msg = "Id length #{id_characters.length} is not #{(ID_TWO_CHUNK_LEN + 1)} chars."
+      raise RuntimeError, min_size_msg unless id_characters.length == ( ID_TWO_CHUNK_LEN + 1 )
+
+      return id_characters.downcase
+
+    end
+
+
+    private
+
+
+    ID_TWO_CHUNK_LEN = IDENTITY_CHUNK_LENGTH * 2
+    ID_TRI_CHUNK_LEN = IDENTITY_CHUNK_LENGTH * 3
+    ID_TRI_TOTAL_LEN = ID_TRI_CHUNK_LEN + 2
+
+    BIT_LENGTH_252 = 252
+
+
+    def self.assert_session_token_size session_token
+      err_msg = "Session token has #{session_token.length} and not #{KeyLocal::SESSION_TOKEN_SIZE} chars."
+      raise RuntimeError, err_msg unless session_token.length == KeyLocal::SESSION_TOKEN_SIZE
+    end
+
+
+  end
+
+
+end