safedb 0.3.1011 → 0.4.1002

data/lib/keytools/key.id.rb

@@ -1,322 +0,0 @@
-#!/usr/bin/ruby
-# coding: utf-8
-
-
-module SafeDb
-
-
-  # 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 + derive_machine_identifier() )
-    end
-
-
-    # This method uses a one-way function to return a combinatorial digested
-    # machine identification string using a number of distinct input parameters
-    # to deliver the characteristic of producing the same identifier for the
-    # same machine, virtual machine, workstation and/or compute element, and
-    # reciprocally, a different one on a different machine.
-    #
-    # The userspace is also a key machine identifier so a different machine user
-    # generates a different identifier when all other things remain equal.
-    #
-    # @return [String]
-    #    a one line textual machine workstation or compute element identifier
-    #    that is (surprisingly) different when the machine user changes.
-    def self.derive_machine_identifier
-
-      require 'socket'
-
-      identity_text = [
-        Etc.getlogin,
-        get_machine_id(),
-        Socket.gethostname()
-      ].join.reverse
-
-      return identity_text
-
-    end
-
-
-    # The machine identifier is a UUID based hash value that is tied to the
-    # CPU and motherboard of the machine. This read-only identifier can be
-    # accessed without sudoer permissions so is perfect for license generators
-    # and environment sensitive software.
-    #
-    # In the modern era of virtualization you should always check the behaviour
-    # of the above identifiers when used inside
-    #
-    # - docker containers
-    # - Amazon EC2 servers (or Azure or GCE)
-    # - vagrant (VirtualBox/VMWare)
-    # - Windows MSGYWIN (Ubuntu) environments
-    # - Kubernetes pods
-    #
-    # @return [String] the machine ID hash value
-    def self.get_machine_id
-
-      machine_id_cmd = "cat /etc/machine-id"
-      machine_id_str = %x[ #{machine_id_cmd} ]
-      return machine_id_str.chomp
-
-    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

data/lib/modules/cryptology/amalgam.rb

@@ -1,70 +0,0 @@
-#!/usr/bin/ruby
-
-module SafeDb
-
-  module ToolBelt
-
-
-  # This class knows how to amalgamate passwords, keys and string data in
-  # a manner that is the cryptographical equivalent of synergy.
-  #
-  # The amalgamated keys are synergially (cryptographically) greater than
-  # the sum of their parts.
-  class Amalgam
-
-    # Amalgamate the two parameter passwords in a manner that is the
-    # cryptographical equivalent of synergy. The amalgamated keys are
-    # synergially greater than the sum of their parts.
-    #
-    # -- Get a viable machine password taking into account the human
-    # -- password length and the specified mix_ratio.
-    #
-    #
-    # @param human_password [String] the password originating from a human
-    # @param machine_key [String] a machine engineered ascii password (key)
-    # @mixparam machine_key [String] a machine engineered ascii password (key)
-    #
-    # @return [String] the union of the two parameter passwords
-    #
-    # @raise [ArgumentError] when the size of the two passwords and the
-    #     mix ratio do not conform to the constraint imposed by the below
-    #     equation which must hold true.
-    #     <tt>machine password length = human password length * mix_ratio - 1</tt>
-    #
-    def self.passwords human_password, machine_password, mix_ratio
-
-      size_error_msg = "Human pass length times mix_ratio must equal machine pass length."
-      lengths_are_perfect = human_password.length * mix_ratio == machine_password.length
-      raise ArgumentError.new size_error_msg unless lengths_are_perfect
-
-      machine_passwd_chunk = 0
-      amalgam_passwd_index = 0
-      amalgamated_password = ""
-
-      human_password.each_char do |passwd_char|
-
-        amalgamated_password[amalgam_passwd_index] = passwd_char
-        amalgam_passwd_index += 1
-
-        for i in 0..(mix_ratio-1) do
-          machine_pass_index = machine_passwd_chunk * mix_ratio + i
-          amalgamated_password[amalgam_passwd_index] = machine_password[machine_pass_index]
-          amalgam_passwd_index += 1
-        end
-
-        machine_passwd_chunk += 1
-
-      end
-
-      return amalgamated_password
-
-    end
-
-
-  end
-
-
-  end
-
-
-end

data/lib/modules/cryptology/engineer.rb

@@ -1,99 +0,0 @@
-#!/usr/bin/ruby
-
-module SafeDb
-
-  module ToolBelt
-
-
-  require 'securerandom'
-
-  # This class will be refactored into an interface implemented by a set
-  # of plugins that will capture sensitive information from users from an
-  # Ubuntu, Windows, RHEL, CoreOS, iOS or CentOS command line interface.
-  #
-  # An equivalent REST API will also be available for bringing in sensitive
-  # information in the most secure (but simple) manner.
-  class Engineer
-
-
-    # --
-    # -- Get a viable machine password taking into account the human
-    # -- password length and the specified mix_ratio.
-    # --
-    # -- machine password length = human password length * mix_ratio - 1
-    # --
-    def self.machine_key human_password_length, mix_ratio
-
-      machine_raw_secret = strong_key( human_password_length * ( mix_ratio + 1) )
-      return machine_raw_secret[ 0..( human_password_length * mix_ratio - 1 ) ]
-
-    end
-
-
-    # --
-    # -- Engineer a raw password that is similar (approximate) in
-    # -- length to the integer parameter.
-    # --
-    def self.strong_key approx_length
-
-      non_alphanum = SecureRandom.urlsafe_base64(approx_length);
-      return non_alphanum.delete("-_")
-
-    end
-
-
-    # Amalgamate the parameter passwords using a specific mix ratio. This method
-    # produces cryptographically stronger secrets than algorithms that simply
-    # concatenate two string keys together. If knowledge of one key were gained, this
-    # amalgamation algorithm still provides extremely strong protection even when
-    # one of the keys has a single digit length.
-    #
-    # This +length constraint formula+ binds the two input strings together with
-    # the integer mix ratio.
-    #
-    # <tt>machine password length = human password length * mix_ratio - 1</tt>
-    #
-    # @param human_password [String] the first password (shorter one) to amalgamate
-    # @param machine_password [String] the second password (longer one) to amalgamate
-    # @param mix_ratio [Fixnum] the mix ratio that must be respected by the
-    #    previous two parameters.
-    # @return [String] an amalgamated (reproducible) union of the 2 parameter passwords
-    #
-    # @raise [ArgumentError] if the length constraint assertion does not hold true
-    def self.get_amalgam_password human_password, machine_password, mix_ratio
-
-      size_error_msg = "Human pass length times mix_ratio must equal machine pass length."
-      lengths_are_perfect = human_password.length * mix_ratio == machine_password.length
-      raise ArgumentError.new size_error_msg unless lengths_are_perfect
-
-      machine_passwd_chunk = 0
-      amalgam_passwd_index = 0
-      amalgamated_password = ""
-
-      human_password.each_char do |passwd_char|
-
-        amalgamated_password[amalgam_passwd_index] = passwd_char
-        amalgam_passwd_index += 1
-
-        for i in 0..(mix_ratio-1) do
-          machine_pass_index = machine_passwd_chunk * mix_ratio + i
-          amalgamated_password[amalgam_passwd_index] = machine_password[machine_pass_index]
-          amalgam_passwd_index += 1
-        end
-
-        machine_passwd_chunk += 1
-
-      end
-
-      return amalgamated_password
-
-    end
-
-
-  end
-
-
-  end
-
-
-end