safedb 0.01.0001

data/lib/logging/gem.logging.rb

@@ -0,0 +1,132 @@
+require "logger"
+require "session/user.home"
+
+# [MIXIN] magic is deployed to hand out DevOps quality logging
+# features to any class that includes the logging module.
+#
+# When logging facilities are not ready we need to log just to
+# stdout but when they are we need to use them.
+#
+# mixin power enables one class to give the logfile path and all
+# classes will suddenly retrieve a another logger and use that.
+#
+#   include Logging
+#   def doImportant
+#     log.warn(x) "unhappy about doing this"
+#     do_anyway
+#     log.debug(x) "all good it was okay"
+#   end
+#
+# So what are Mixins?
+#
+# Refer to the below link for excellent coverage of mixins.
+# @see http://ruby-doc.com/docs/ProgrammingRuby/html/tut_modules.html
+#
+module OpenLogger
+
+  @@gem_name = "safedb.net"
+  @@gem_base = File.join OpenSession::Home.dir, ".#{@@gem_name}"
+  FileUtils.mkdir_p @@gem_base unless File.exists? @@gem_base
+  @@log_path = File.join @@gem_base, "safedb.net-cli.log"
+
+
+  # Classes that include (MIXIN) this logging module will
+  # have access to this logger method.
+  #
+  # [memoization] is implemented here for performance and
+  # will only initiate a logger under 2 circumstances
+  #
+  #   [1] - the first call (returns a STDOUT logger)
+  #   [2] - the call after the logfile path is set
+  #          (returns a more sophisticated logger)
+  def log
+
+    @@log_class ||= get_logger
+
+  end
+
+
+  # This Ruby behavioural snippet allows the logger to print 3 crucial
+  # pieces of information for the troubleshooter (detective) so that they
+  # may ascertain
+  #
+  # - the [module] the logging call came from
+  # - the [method] the logging call came from
+  # - line number origins of the logging call
+  #
+  # To use this method you can make calls like this
+  #
+  # - log.info(x) { "Log many things about where I am now." }
+  # - log.warn(x) { "Log many things about where I am now." }
+  #
+  def x
+
+    module_name = File.basename caller_locations(1,1).first.absolute_path, ".rb"
+    method_name = caller_locations(1,1).first.base_label
+    line_number = caller_locations(1,1).first.lineno
+
+    "#{module_name} | #{method_name} | (line #{line_number}) "
+
+  end
+
+
+  # This method returns an initialized logger.
+  #
+  # The logger returned may write to
+  #
+  # - a simple file
+  # - a service like fluentd
+  # - a message queue
+  # - a nosql database
+  # - all of the above
+  #
+  # Not that [memoization] should be used so that this method
+  # gets called ideally just once although in practise it may
+  # turn out to be a handful of times.
+  #
+  # @return [Logger] return an initialized logger object
+  def get_logger
+
+    file_logger = Logger.new @@log_path
+    original_formatter = Logger::Formatter.new
+
+    file_logger.formatter = proc { |severity, datetime, progname, msg|
+      original_formatter.call( severity, datetime, progname, msg.dump.chomp.strip )
+    }
+
+    return file_logger
+
+  end
+
+
+  # Overtly long file paths in the log files sometimes hamper readability
+  # and this method improves the situation by returning just the two
+  # immediate ancestors of the file (or folder) path.
+  #
+  # @example A really long input like
+  #          <tt>/home/joe/project/degrees/math/2020</tt>
+  #          is reduced to
+  #          <tt>degrees/math/2020</tt>
+  #
+  # So this method returns the name of the grandparent folder then parent folder
+  # and then the most significant file (or folder) name.
+  #
+  # When this is not possible due to the filepath being colisively near the
+  # filesystem's root, it returns the parameter name.
+  # 
+  # @param object_path [String] overtly long path that will be made more readable
+  # @return [String] the (separated) three most significant path name segments
+  def nickname object_path
+
+    object_name   = File.basename object_path
+    parent_folder = File.dirname  object_path
+    parent_name   = File.basename parent_folder
+    granny_folder = File.dirname  parent_folder
+    granny_name   = File.basename granny_folder
+
+    return [granny_name,parent_name,object_name].join("/")
+
+  end
+
+
+end

data/lib/modules/README.md

@@ -0,0 +1,43 @@
+
+
+In order for data to be secured for storage or transmission, it must be transformed in such a manner that it would be difficult for an unauthorized individual to be able to discover its true meaning. To do this, certain mathematical equations are used, which are very difficult to solve unless certain strict criteria are met. The level of difficulty of solving a given equation is known as its intractability. These types of equations form the basis of cryptography.
+
+Some of the most important are:
+
+== The Discrete Logarithm Problem
+
+The best way to describe this problem is first to show how its inverse concept works. The following applies to Galois fields (groups). Assume we have a prime number P (a number that is not divisible except by 1 and itself, P). This P is a large prime number of over 300 digits. Let us now assume we have two other integers, a and b. Now say we want to find the value of N, so that value is found by the following formula:
+
+N = ab mod P, where 0 <= N <= (P · 1)
+
+(meaning a to the power b mod P)
+(learn to do powers in markdown)!
+
+
+This is known as discrete exponentiation and is quite simple to compute. However, the opposite is true when we invert it. If we are given P, a, and N and are required to find b so that the equation is valid, then we face a tremendous level of difficulty.
+
+
+This problem forms the basis for a number of public key infrastructure algorithms, such as Diffie-Hellman and EIGamal. This problem has been studied for many years and cryptography based on it has withstood many forms of attacks.
+
+== The Integer Factorization Problem
+
+This is simple in concept. Say that one takes two prime numbers, P2 and P1, which are both "large" (a relative term, the definition of which continues to move forward as computing power increases). We then multiply these two primes to produce the product, N. The difficulty arises when, being given N, we try and find the original P1 and P2. The Rivest-Shamir-Adleman public key infrastructure encryption protocol is one of many based on this problem. To simplify matters to a great degree, the N product is the public key and the P1 and P2 numbers are, together, the private key.
+
+This problem is one of the most fundamental of all mathematical concepts. It has been studied intensely for the past 20 years and the consensus seems to be that there is some unproven or undiscovered law of mathematics that forbids any shortcuts. That said, the mere fact that it is being studied intensely leads many others to worry that, somehow, a breakthrough may be discovered.
+
+== The Elliptic Curve Discrete Logarithm Problem
+
+This is a new cryptographic protocol based upon a reasonably well-known mathematical problem. The properties of elliptic curves have been well known for centuries, but it is only recently that their application to the field of cryptography has been undertaken.
+
+First, imagine a huge piece of paper on which is printed a series of vertical and horizontal lines. Each line represents an integer with the vertical lines forming x class components and horizontal lines forming the y class components. The intersection of a horizontal and vertical line gives a set of coordinates (x,y). In the highly simplified example below, we have an elliptic curve that is defined by the equation:
+
+y2 + y = x3 · x2 (this is way too small for use in a real life application, but it will illustrate the general idea)
+
+For the above, given a definable operator, we can determine any third point on the curve given any two other points. This definable operator forms a "group" of finite length. To add two points on an elliptic curve, we first need to understand that any straight line that passes through this curve intersects it at precisely three points. Now, say we define two of these points as u and v: we can then draw a straight line through two of these points to find another intersecting point, at w. We can then draw a vertical line through w to find the final intersecting point at x. Now, we can see that u + v = x. This rule works, when we define another imaginary point, the Origin, or O, which exists at (theoretically) extreme points on the curve. As strange as this problem may seem, it does permit for an effective encryption system, but it does have its detractors.
+
+On the positive side, the problem appears to be quite intractable, requiring a shorter key length (thus allowing for quicker processing time) for equivalent security levels as compared to the Integer Factorization Problem and the Discrete Logarithm Problem. On the negative side, critics contend that this problem, since it has only recently begun to be implemented in cryptography, has not had the intense scrutiny of many years that is required to give it a sufficient level of trust as being secure.
+
+This leads us to more general problem of cryptology than of the intractability of the various mathematical concepts, which is that the more time, effort, and resources that can be devoted to studying a problem, then the greater the possibility that a solution, or at least a weakness, will be found.
+
+
+

data/lib/modules/cryptology/aes-256.rb

@@ -0,0 +1,154 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module SafeDb
+
+  module ToolBelt
+
+
+  # Aes256 is a symmetric encryption cipher which inherits extends the
+  # {SafeDb::Cipher} base class in order to implement plug and play
+  # symmetric encryption.
+  #
+  # == Aes256 Symmetric Encrypt/Decrypt
+  #
+  # To facilitate decryption - this cipher produces a key/value pair
+  # dictionary which will be stored along with the ciphertext itself.
+  # The dictionary includes
+  #
+  # - <b>symmetric.cipher</b> - the algorithm used to encrypt and decrypt
+  # - <b>encryption.key</b> - hex encoded key for encrypting and decrypting
+  # - <b>initialize.vector</b> - the initialization vector known as a IV (four)
+  #
+  # == Aes256 Implemented Methods
+  #
+  # This cipher brings the cryptographic mathematics and implementation algorithms
+  # for the 256Bit Advanced Encryption Standard. No serious practical (nor theoretical)
+  # challenge has ever been mounted against this algorithm (or this implementation).
+  #
+  # This class implements the below methods
+  #
+  # - <b>do_symmetric_encryption(plain_text)</b> - resulting in ciphertext
+  # - <b>do_symmetric_decryption(ciphertext, encryption_dictionary)</b> &raquo; plaintext
+  #
+  # and it also sets the <b>@dictionary</b> hash (map) of pertinent
+  # key/value pairs including the +encryption algorithm+ and +encryption key+.
+  #
+  # That's It. Cipher children can rely on the {SafeDb::Cipher} parent to
+  # do the nitty gritty of file-handling plus managing stores and paths.
+
+  class Aes256
+
+    # Use the AES 256 bit block cipher and a robust strong random key plus
+    # initialization vector (IV) to symmetrically encrypt the plain text.
+    #
+    # <b>Cryptographic Properties</b>
+    #
+    # This encrypt event populates key/value pairs to the hash (dictionary) instance
+    # given in the parameter.
+    #
+    # A crypt properties dictionary acts as <b>output from every encryption event</b>
+    # and <b>input to every decryption event</b>. The most common properties include
+    #
+    # - the symmetric key used for the encryption and decryption
+    # - the iv (initialization vector) that adds another dimension of strength
+    # - authorization data that thwarts switch attacks by tying context to content
+    # - the cipher algorithm, its implementation and its encryption strength
+    # - the digest of the original message for validation purposes
+    #
+    # @param e_properties [Hash]
+    #    instantiated hash map in which the encrryption properties will
+    #    be stuffed.
+    #
+    # @param plain_text [String] the plain (or base64 encoded) text to encrypt
+    # @return [String] the symmetrically encrypted cipher text
+    def self.do_encrypt e_properties, plain_text
+
+      crypt_cipher = OpenSSL::Cipher::AES256.new(:CBC)
+      crypt_cipher.encrypt
+      plain_text_digest = Digest::SHA256.digest plain_text
+
+      e_properties[CryptIO::DICT_CIPHER_NAME] = crypt_cipher.class.name
+      e_properties[CryptIO::DICT_CRYPT_KEY]   = Base64.urlsafe_encode64 crypt_cipher.random_key
+      e_properties[CryptIO::DICT_CRYPT_IV]    = Base64.urlsafe_encode64 crypt_cipher.random_iv
+      e_properties[CryptIO::DICT_TEXT_DIGEST] = Base64.urlsafe_encode64 plain_text_digest
+
+      return crypt_cipher.update( plain_text ) + crypt_cipher.final
+
+    end
+
+
+    # Use the AES 256 bit block cipher together with the encryption key,
+    # initialization vector (iv) and other data found within the decryption
+    # properties dictionary to symmetrically decrypt the cipher text.
+    #
+    # This encrypt event in {self.do_encrypt} populated the property dictionary
+    # that was presumably serialized, stored, retrieved then deserialized and
+    # (at last) presented in the first parameter.
+    #
+    # <b>Cryptographic Properties</b>
+    #
+    # A crypt properties dictionary is the <b>output from every encryption event</b>
+    # and <b>input to every decryption event</b>. The most common properties include
+    #
+    # - the symmetric key used for the encryption and decryption
+    # - the iv (initialization vector) that adds another dimension of strength
+    # - authorization data that thwarts switch attacks by tying context to content
+    # - the cipher algorithm, its implementation and its encryption strength
+    # - the digest of the original message for validation purposes
+    #
+    # @param d_properties [Hash]
+    #    the crypt properties dictionary is the <b>output from every encryption event</b>
+    #    and (as in this case) <b>input to every decryption event</b>.
+    #
+    # @param cipher_text [String]
+    #    the (already decoded) cipher text for decryption by this method using the
+    #    encryption properties setup during the past encrypt event.
+    #
+    # @return [String]
+    #    the plain text message originally given to be encrypted. If the message digest
+    #    is provided within the decryption properties dictionary a sanity check will
+    #    occur.
+    #
+    # @raise [RuntimeError]
+    #    if decryption fails or the recalculated message digest fails an equivalence test.
+    def self.do_decrypt d_properties, cipher_text
+
+      decode_cipher = OpenSSL::Cipher::AES256.new(:CBC)
+      decode_cipher.decrypt
+
+      decode_cipher.key = Base64.urlsafe_decode64( d_properties[CryptIO::DICT_CRYPT_KEY] )
+      decode_cipher.iv  = Base64.urlsafe_decode64( d_properties[CryptIO::DICT_CRYPT_IV]  )
+
+      plain_text = decode_cipher.update( cipher_text ) + decode_cipher.final
+      assert_digest_equivalence( d_properties[CryptIO::DICT_TEXT_DIGEST], plain_text )
+
+      return plain_text
+
+    end
+
+
+    private
+
+
+    def self.assert_digest_equivalence( digest_b4_encryption, plain_text_message )
+
+      plain_text_digest = Base64.urlsafe_encode64( Digest::SHA256.digest( plain_text_message ) )
+      return if digest_b4_encryption.eql? plain_text_digest
+
+      msg1 = "\nEquivalence check of original and decrypted plain text digests failed.\n"
+      msg2 = "Digest before encryption => #{digest_b4_encryption}\n"
+      msg3 = "Digest after decryption  => #{plain_text_digest}\n"
+      error_message = msg1 + msg2 + msg3
+      raise RuntimeError, error_message
+
+    end
+
+
+  end
+
+
+  end
+
+
+end

data/lib/modules/cryptology/amalgam.rb

@@ -0,0 +1,70 @@
+#!/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/blowfish.rb

@@ -0,0 +1,130 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module SafeDb
+
+  module ToolBelt
+
+    # Blowfish is a symmetric encryption cipher which inherits extends the
+    # {SafeDb::Cipher} base class in order to implement plug and play
+    # symmetric encryption.
+    #
+    # Blowfish is still uncrackable - however its successor (TwoFish) has
+    # been reinforced to counter the growth of super-computer brute force
+    # resources.
+    class Blowfish
+
+      # The blowfish cipher id constant is used to +initialize+
+      # an {OpenSSL::Cipher} class instance.
+      BLOWFISH_CIPHER_ID = "BF-ECB"
+
+
+      # Blowfish constrains the length of +incoming plain text+ forcing it
+      # to be a multiple of eight (8).
+      BLOWFISH_BLOCK_LEN = 8
+
+
+      # Encrypt the (plain) text parameter using the symmetric encryption key
+      # specified in the second parameter and return the base64 encoded
+      # representation of the cipher text.
+      #
+      # Blowfish is a block cipher meaning it needs both the key and the plain
+      # text inputted to conform to a divisible block length.
+      #
+      # Don't worry about this block length requirement as this encrption method
+      # takes care of it and its sister method {self.decryptor} will also perform
+      # the correct reversal activities to give you back the original plain text.
+      #
+      # {Base64.urlsafe_encode64} facilitates the ciphertext encoding returning text that
+      # is safe to write to a file.
+      #
+      # @param plain_text [String]
+      #    This parameter should be the non-nil text to encrypt using Blowfish.
+      #    Before encryption the text will be padded using a text string from
+      #    the {SafeDb::Cipher::TEXT_PADDER} constant until it results in
+      #    a string with the required block length.
+      #
+      # @param encryption_key [String]
+      #    send a long strong unencoded key which does not have to be a multiple of
+      #    eight even though the algorithm demands it. Before the encryption this key
+      #    will be passed through a digest using behaviour from {Digest::SHA256.digest}
+      #
+      #    This behaviour returns a key whose length is a multiple of eight.
+      #
+      # @return [String] base64 representation of blowfish crypted ciphertext
+      #
+      # @raise [OpenSSL::Cipher::CipherError]
+      #    An (encryption) <tt>key length too short</tt> error is raised for short keys.
+      def self.encryptor plain_text, encryption_key
+
+        shortkey_msg = "The #{encryption_key.length} character encryption key is too short."
+        raise ArgumentError, shortkey_msg unless encryption_key.length > 8
+        log.info(x) { "os blowfish request to encrypt plain text with provided key." }
+
+        block_txt = plain_text
+        block_txt += CryptIO::TEXT_PADDER until block_txt.bytesize % BLOWFISH_BLOCK_LEN == 0
+        raw_stretched_key = Digest::SHA256.digest(encryption_key)
+
+        blowfish_encryptor = OpenSSL::Cipher.new(BLOWFISH_CIPHER_ID).encrypt
+        blowfish_encryptor.key = raw_stretched_key
+        return blowfish_encryptor.update(block_txt) << blowfish_encryptor.final
+
+      end
+
+
+      # Decrypt the cipher text parameter using the symmetric decryption key
+      # specified in the second parameter. The cipher text is expected to have
+      # already been decoded if necessary.
+      #
+      # Its okay to use a bespoke encryptor - just ensure you encode the result
+      # and override the padding constant.
+      #
+      # Blowfish is a block cipher meaning it needs both the key and the plain
+      # text inputted to conform to a divisible block length.
+      #
+      # Don't worry about this block length requirement as this decrption method
+      # takes care of the reversing the activities carried out by {self.encryptor}.
+      #
+      # @param cipher_text [String]
+      #    This incoming cipher text should already be encoded but it
+      #    will <b>chomped and stripped upon receipt</b> followed by
+      #    decryption using the Blowfish algorithm.
+      #
+      # @param decryption_key [String]
+      #    Send the same key that was used during the encryption phase. The encryption
+      #    phase passed the key through the {Digest::SHA256.digest} digest so here
+      #    the decryption does the exact same thing.
+      #
+      #    The digest processing guarantees a symmetric key whose length conforms to
+      #    the multiple of eight block length requirement.
+      #
+      # @return [String]
+      #    After decoding and decryption the plain text string will still be padded,
+      #    +but not with spaces+. The unlikely to occur padding string constant used
+      #    is the {SafeDb::Cipher::TEXT_PADDER}.
+      #
+      #    If the plaintext ended with spaces these would be preserved. After padder
+      #    removal any trailing spaces will be preserved in the returned plain text.
+      #
+      def self.decryptor cipher_text, decryption_key
+
+        digested_key = Digest::SHA256.digest decryption_key
+
+        decrypt_tool = OpenSSL::Cipher.new(BLOWFISH_CIPHER_ID).decrypt
+        decrypt_tool.key = digested_key
+
+        padded_plaintxt = decrypt_tool.update(cipher_text) << decrypt_tool.final
+        pad_begin_index = padded_plaintxt.index CryptIO::TEXT_PADDER
+        return padded_plaintxt if pad_begin_index.nil?
+        return padded_plaintxt[ 0 .. (pad_begin_index-1) ]
+
+      end
+
+
+    end
+
+
+  end
+
+
+end