safedb 0.01.0001

data/lib/keytools/key.id.rb

@@ -0,0 +1,271 @@
+#!/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 + KeyIdent.derive_machine_identifier() )
+    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/keytools/key.ident.rb

@@ -0,0 +1,243 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module SafeDb
+
+  # This class knows how to derive information from the machine environment to aide
+  # in producing identifiers unique to the machine and/or workstation, with functionality
+  # similar to that required by licensing software.
+  #
+  # == Identity is Similar to Licensing Software | Except Deeper
+  #
+  # Deriving the identity string follows similar principles to licensing
+  # software that attempts to determine whether the operating environment
+  # is the same or different. But it goes deeper than licensing software
+  # as it is not only concerned about the <b>same workstation</b> - it is
+  # also concerned about <b>the same shell or command line interface</b>.
+  #
+  # == Known Issues
+  #
+  # The dependent macaddr gem is known to fail in scenarios where a
+  # VPN tunnel is active and a tell tale sign is the ifconfig command
+  # returning the tun0 interface rather than "eth0" or something that
+  # resembles "ensp21".
+  #
+  # This is one of the error messages resulting from such a case.
+  #
+  #     macaddr.rb:86 from_getifaddrs undefined method pfamily (NoMethodError)
+  #
+  class KeyIdent
+
+    # This method returns a plaintext string hat is guaranteed to be the same
+    # whenever called within the same shell for the same user on the same
+    # workstation, virtual machine, container or SSH session and different whenever
+    # a new shell is acquired.
+    #
+    # What is really important is that the <b>shell identity string changes</b> when
+    #
+    # - the <b>command shell</b> changes
+    # - the user <b>switches to another workstation user</b>
+    # - the <b>workstation or machine host</b> is changed
+    # - the user <b>SSH's</b> into another shell
+    #
+    # <b>Unchanged | When Should it Remain Unchanged?</b>
+    #
+    # Remaining <b>unchanged</b> is a feature that is as important and this must
+    # be so when and/or after
+    #
+    # - the <b>user returns to a command shell</b>
+    # - the user <b>switches back to using a domain</b>
+    # - the user exits their <b>remote SSH session</b>
+    # - <b>sudo is used</b> to execute the commands
+    # - the user comes back to their <b>workstation</b>
+    # - the clock ticks into another day, month, year ...
+    #
+    # @param use_grandparent_pid [Boolean]
+    #
+    #    Optional boolean parameter. If set to true the PID (process ID) used
+    #    as part of an obfuscator key and normally acquired from the parent
+    #    process should now be acquired from the grandparent's process.
+    #
+    #    Set to true when accessing the safe's credentials from a sub process
+    #    rather than directly through the logged in shell.
+    #
+    # @return [String]
+    #    Return a one line textual shell identity string.
+    #
+    #    As key derivation algorithms enforcing a maximum length may be length may
+    #    be applied, each character must add value so non-alphanumerics (mostly hyphens)
+    #    are cleansed out before returning.
+    def self.derive_shell_identifier( use_grandparent_pid = false )
+
+      require 'socket'
+
+      # -- Ensure that the most significant data points
+      # -- come first just like with numbers.
+
+      identity_text =
+      [
+        get_ancestor_pid( use_grandparent_pid ),
+        get_bootup_id(),
+        Etc.getlogin(),
+        Socket.gethostname()
+      ].join
+
+      return identity_text.to_alphanumeric
+
+    end
+
+
+    # Return an ancestor process ID meaning return either the parent process
+    # ID or the grandparent process ID. The one returned depends on the paremeter
+    # boolean value.
+    #
+    # == Command Used to find the grandparent process ID.
+    #
+    #     $ ps -fp 31870 | awk "/tty/"' { print $3 } '
+    #     $ ps -fp 31870 | awk "/31870/"' { print $3 } '
+    #
+    # The one liner finds the parental process ID of the process with the given
+    # parameter process ID.
+    #
+    #     $ ps -fp 31870
+    #
+    #     UID        PID  PPID  C STIME TTY          TIME CMD
+    #     joe      31870  2618  0 12:55 tty2     00:01:03 /usr/bin/emacs25
+    #
+    # The ps command outputs two (2) lines and **awk** is employed to select the
+    # line containing the already known ID. We then print the 3rd string in the
+    # line which we expect to be the parent PID of the PID.
+    #
+    # == Warning | Do Not Use $PPID
+    #
+    # Using $PPID is fools gold because the PS command itself runs as another
+    # process so $PPID is this (calling) process ID and the number returned is
+    # exactly the same as the parent ID of this process - which is actually the
+    # grandparent of the invoked ps process.
+    #
+    # @param use_grandparent_pid [Boolean]
+    #    Set to true if the grandparent process ID is required and false if
+    #    only the parent process ID should be returned.
+    #
+    # @return [String]
+    #    Return ancestor process ID that belongs to either the parent process
+    #    or the grandparent process.
+    def self.get_ancestor_pid( use_grandparent_pid )
+
+      parental_process_id = Process.ppid.to_s()
+      grandparent_pid_cmd = "ps -fp #{parental_process_id} | awk \"/#{parental_process_id}/\"' { print $3 } '"
+      raw_grandparent_pid = %x[#{grandparent_pid_cmd}]
+      the_grandparent_pid = raw_grandparent_pid.chomp
+
+      log.debug(x) { "QQQQQ ~> QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ" }
+      log.debug(x) { "QQQQQ ~> Request Bool Use GPPID is ~> [[ #{use_grandparent_pid} ]]" }
+      log.debug(x) { "QQQQQ ~> Main Parent Process ID is ~> [[ #{parental_process_id} ]]" }
+      log.debug(x) { "QQQQQ ~> GrandParent Process ID is ~> [[ #{the_grandparent_pid} ]]" }
+      log.debug(x) { "QQQQQ ~> QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ" }
+
+      return ( use_grandparent_pid ? the_grandparent_pid : parental_process_id )
+
+    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
+
+
+    # If you need to know whether a Linux computer has been rebooted or
+    # you need an identifier that stays the same until the computer reboots,
+    # look no further than the read only (non sudoer accessible) **boot id**.
+    #
+    # 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 bootup ID hash value
+    def self.get_bootup_id
+
+      bootup_id_cmd = "cat /proc/sys/kernel/random/boot_id"
+      bootup_id_str = %x[ #{bootup_id_cmd} ]
+      return bootup_id_str.chomp
+
+    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
+
+
+    # If the system was rebooted on April 23rd, 2018 at 22:00:16 we
+    # expect this method not to return <b>2018-04-23 22:00:16</b>, but
+    # to return the <b>8 least significant digits</b> bootup time
+    # digits which in this case are <b>23220016</b>.
+    #
+    # Investigate all Linux flavours to understand whether this command
+    # works (or is it just Ubuntu). Also does Docker return a sensible
+    # value here?
+    #
+    # This method is not production ready. Not only is the time within
+    # a small range, also the most significant digit can fluctuate up
+    # or down randomly (in  a non-deterministic manner.
+    #
+    # @return [String] the time when the system was booted.
+    def self.get_bootup_time_digits
+
+      boot_time_cmd = "uptime -s"
+      uptime_string = %x[ #{boot_time_cmd} ]
+      return uptime_string.chomp.to_alphanumeric[ 6 .. -1 ]
+
+    end
+
+
+  end
+
+
+end

data/lib/keytools/key.iv.rb

@@ -0,0 +1,107 @@
+#!/usr/bin/ruby
+
+module SafeDb
+
+  # Create and deliver representations of a random initialization vector
+  # suitable for the AES symmetric encryption algorithm which demands a
+  # 18 byte binary string.
+  #
+  # The initialization vector is sourced from {SecureRandom} which provides
+  # a highly random (and secure) byte sequence usually sourced from udev-random.
+  #
+  #   + ------------------ + -------- + ------------ + ------------------- +
+  #   | Random IV Format   | Bits     | Bytes        | Base64              |
+  #   | ------------------ | -------- | ------------ | ------------------- |
+  #   | Random IV Stored   | 192 Bits | 24 bytes     | 32 characters       |
+  #   | Random IV Binary   | 128 Bits | 16 bytes     | (not stored)        |
+  #   + ------------------ + -------- + ------------ + ------------------- +
+  #
+  # This table shows that the initialization vector can be represented by
+  # both a <b>32 character base64 string</b> suitable for storage and a
+  # <b>18 byte binary</b> for feeding the algorithm.
+  class KeyIV
+
+
+    # The 24 random bytes is equivalent to 192 bits which when sliced into 6 bit
+    # blocks (one for each base64 character) results in 32 base64 characters.
+    NO_OF_BASE64_CHARS = 32
+
+    # We ask for 24 secure random bytes that are individually created to ensure
+    # we get exactly the right number.
+    NO_OF_SOURCE_BYTES = 24
+
+    # We truncate the source random bytes so that 16 bytes are returned for the
+    # random initialization vector.
+    NO_OF_BINARY_BYTES = 16
+
+
+    # Initialize an initialization vector from a source of random bytes
+    # which can then be presented in both a <b>(base64) storage</b> format
+    # and a <b>binary string</b> format.
+    #
+    #   + ------------------ + -------- + ------------ + ------------------- +
+    #   | Random IV Format   | Bits     | Bytes        | Base64              |
+    #   | ------------------ | -------- | ------------ | ------------------- |
+    #   | Random IV Stored   | 192 Bits | 24 bytes     | 32 characters       |
+    #   | Random IV Binary   | 128 Bits | 16 bytes     | (not stored)        |
+    #   + ------------------ + -------- + ------------ + ------------------- +
+    #
+    # We ask for 24 secure random bytes that are individually created to ensure
+    # we get exactly the right number.
+    #
+    # If the storage format is requested a <b>32 character base64 string</b> is
+    # returned but if the binary form is requested the <b>first 16 bytes</b> are
+    # issued.
+    def initialize
+      @bit_string = Key.to_random_bits( NO_OF_SOURCE_BYTES )
+    end
+
+
+    # When the storage format is requested a <b>32 character base64 string</b> is
+    # returned - created from the initialized 24 secure random bytes.
+    #
+    #   + ---------------- + -------- + ------------ + ------------------- +
+    #   | Random IV Stored | 192 Bits | 24 bytes     | 32 characters       |
+    #   + ---------------- + -------- + ------------ + ------------------- +
+    #
+    # @return [String]
+    #    a <b>32 character base64 formatted string</b> is returned.
+    def for_storage
+      return Key64.from_bits( @bit_string )
+    end
+
+
+    #
+    #   + ---------------- + -------- + ------------ + ------------------- +
+    #   | Random IV Binary | 128 Bits | 16 bytes     | (not stored)        |
+    #   + ---------------- + -------- + ------------ + ------------------- +
+    #
+    # @param iv_base64_chars [String]
+    #    the 32 characters in base64 format that will be converted into a binary
+    #    string (24 byte) representation and then truncated to 16 bytes and outputted
+    #    in binary form.
+    #
+    # @return [String]
+    #    a <b>16 byte binary string</b> is returned.
+    #
+    # @raise [ArgumentError]
+    #    if a <b>32 base64 characters</b> are not presented in the parameter.
+    def self.in_binary iv_base64_chars
+
+      b64_msg = "Expected #{NO_OF_BASE64_CHARS} base64 chars not #{iv_base64_chars.length}."
+      raise ArgumentError, b64_msg unless iv_base64_chars.length == NO_OF_BASE64_CHARS
+
+      binary_string = Key.to_binary_from_bit_string( Key64.to_bits( iv_base64_chars ) )
+
+      bin_msg = "Expected #{NO_OF_SOURCE_BYTES} binary bytes not #{binary_string.length}."
+      raise RuntimeError, bin_msg unless binary_string.length == NO_OF_SOURCE_BYTES
+
+      return binary_string[ 0 .. ( NO_OF_BINARY_BYTES - 1 ) ]
+
+    end
+
+
+  end
+
+
+end