opensecret 0.0.960 → 0.0.962

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b95962b0946200185b87257ef12fbfab9e689ecd
-  data.tar.gz: 40eb3bb6b0a401192e33a92b23053d35755f7c51
+  metadata.gz: 06aed72d992d1b8f9ae2533681c47e20d9974e05
+  data.tar.gz: 04b41b862706f7f98d95f78bdbc18405c0e5b80a
 SHA512:
-  metadata.gz: 8e6c1c61a35e114c6e20e5d8192c3d1a2b996fb6bb65ebd58858f268d2839d5d629824883b2efc8ef8e50faf064f13efcf77e850986313baa168fb0ea06caf10
-  data.tar.gz: 8f511f4f83d18d85a3891ef504bef7b60a8f8bcb59e427d86f24acf928315d765132be999a0aa63a2aec4cd818e7b96ab61df59346fc6753c94c30fa4bc14b66
+  metadata.gz: 993f8128c462a648fb3599326cac9ee378a17d8bbaea620aee11223a6b10584205df2c2c68b2856223befccb2a0e02207188ddbd80dfe3e0bd615c6f1d95a66f
+  data.tar.gz: 6684892e42493e09e13549591ef8b048ad95d0b586c4a8f1226e4d1f063fc42401241326a814c35c78699aa2a2d441fceb9f69ea9ce050c909eed090258168dd

data/lib/notepad/{blow.rb → scratch.pad.rb}

@@ -19,7 +19,7 @@ class Trial
 
   end
 
-Trial.ciphername
+####### ======> Trial.ciphername
 
 
   def self.certify

data/lib/opensecret.rb

@@ -65,21 +65,52 @@ class CliInterpreter < Thor
   end
 
 
-  # Description of the open "wake-up" call.
-  desc "open CONTEXT_PATH", "CONTEXT_PATH context path to the family of secrets to be created."
+  # Description of the open use case command.
+  desc "open OUTER_PATH", "OUTER_PATH to envelope of secrets to stuff and then lock."
 
   # Open up a conduit from which we can add, subtract, update and list secrets
   # before they are committed (and pushed) into permanent locked storage.
   #
-  # @param context_path [String] the path to USB key for storing encrypted keys
-  def open context_path
+  # @param outer_path [String] the path to USB key for storing encrypted keys
+  def open outer_path
 
     open_uc = OpenSecret::Open.new
-    open_uc.context_path = context_path
+    open_uc.outer_path = outer_path
     open_uc.flow_of_events
 
   end
 
+  # Description of the unlock use case command.
+  desc "unlock OUTER_PATH", "OUTER_PATH to locked secrets to open for reading or stuffing."
+
+  # If confident that command history cannot be exploited to gain the human password
+  # or if the agent running opensecret is itself a script, the <tt>with</tt> option can
+  # be used to convey the password.
+  option :with
+
+  # Unlock a secrets envelope at the specified outer path so that we can read, put
+  # and discard secrets.
+  #
+  # This use case requires the human (agent) password unless the <tt>--no-human-password</tt>
+  # flag was posted along with the <tt>init</tt> command.
+  #
+  # There are two ways to provide the password (for the <b><em>my/gadgets</em></b> group)
+  #
+  # - <tt>opensecret unlock my/gadgets</tt> and respond to the password prompt (or)
+  # - <tt>opensecret unlock my/gadgets --with="hUM4n-0pen$3cr3t"</tt>
+  #
+  # If providing the password on the command line, one must be confident that the shell's
+  # command history cannot be exploited to capture it.
+  #
+  # @param outer_path [String] the path to the (previously) locked secrets in frozen storage.
+  def unlock outer_path
+
+    unlock_uc = OpenSecret::Unlock.new
+    unlock_uc.outer_path = outer_path
+    unlock_uc.master_p4ss = options[:with] if options[:with]
+    unlock_uc.flow_of_events
+
+  end
 
   # Description of the put secret command.
   desc "put <secret_id> <secret_value>", "put secret like login/username into opened context."

data/lib/plugins/cipher.rb

@@ -28,6 +28,50 @@ module OpenSecret
   # with a powerful symmetric encryption algorithm which could be any one of the
   # leading ciphers such as TwoFish or the Advanced Encryption Standard (AES).
   #
+  # == Ciphers at 3 Levels
+  #
+  # Ciphers are implemented at three distinct levels.
+  #
+  # <b>Low Level Ciphers</b>
+  #
+  # Low level ciphers are given text to encrypt and an instantiated dictionary
+  # in which to place the encryption parameters such as keys and initialization
+  # vectors (iv)s.
+  #
+  # Some more specific ciphers can handle authorization data for example the
+  # Galois Counter Mode (GCM) cipher.
+  #
+  # Low level ciphers know nothing about text IO nor reading and writing to
+  # persistence structures like files, queues and databases.
+  #
+  # <b>Mid Level Ciphers</b>
+  #
+  # Mid level ciphers talk to the low level ciphers and bring in input and output
+  # textual formats like OpenSecret's two-part block structures.
+  #
+  # Mid level ciphers still know nothing of persistence structures like files,
+  # queues and databases.
+  #
+  # <b>Use Case Level Ciphers</b>
+  #
+  # The ciphers operating at the use case level talk to mid level ciphers. They
+  # interact with the <b>opensecret store API</b> which brings persistence
+  # functions such as <b>read/write</b> as well as remoting functions such as
+  # <b>push/pull</b>.
+  #
+  # Use Case level ciphers interact with the latest crypt technologies due to
+  # interface separation. Also they talk classes implementing persistence stores
+  # allowing assets liek Git, S3, DropBox, simple files, SSH filesystems, Samba
+  # to hold locked key and material crypts.
+  #
+  # Databases stores will be introduced soon allowing opensecret to plug in and
+  # exploit database managers like Mongo, Hadoop, MySQL, Maria, and PostgreSQL.
+  #
+  # Plugging into DevOps orchestration platforms like Terraform, Ansible, Chef
+  # and Puppet will soon be available. Add this with integrations to other credential
+  # managers like HashiCorp's Vault, Credstash, Amazon KMS, Git Secrets, PGP,
+  # LastPass, KeePass and KeePassX.
+  #
   # == How to Implement a Cipher
   #
   # Extend this base class to inherit lots of +unexciting+ functionality
@@ -40,7 +84,6 @@ module OpenSecret
   # - handles +exceptions+ and +malicious input detection+ and incubation
   # - +_performs the asymmetric encryption_+ of the cipher's symmetrically encrypted output
   #
-  #
   # == What Behaviour Must Ciphers Implement
   #
   # Ciphers bring the cryptographic mathematics and implementation algorithms
@@ -57,80 +100,10 @@ module OpenSecret
   # do the nitty gritty of file-handling plus managing stores and paths.
   class Cipher
 
-    # Many ciphers (like Blowfish) constrains plain text lengths to multiples
-    # of 8 (or 16) and a common +right pad with spaces+ strategy is employed
-    # as a workaround. opensecret does it diferently.
-    #
-    # == Why isn't Space Padding Used?
-    #
-    # If opensecret padded plaintext (ending in one or more spaces) with
-    # spaces, the decrypt phase (after right stripping spaces) would return
-    # plain text string +shorter than the original+.
-    #
-    # == So How is Padding Done?
-    #
-    # Instead of single space padding - opensecret uses an unlikely 7 character
-    # padder which is repeated until the multiple is reached.
-    #
-    # <tt><-|@|-></tt>
-    #
-    # == So How is Padding Done?
-    #
-    # The +padder length must be a prime number+ or infinite loops could occur.
-    #
-    #    If the padder string is likely to occur in the plain text, another
-    #    padder (or strategy) should and could be employed.
-    #
-    TEXT_PADDER = "<-|@|->"
-
-
-    # An unusual string that glues together an encryption dictionary and
-    # a chunk of base64 encoded and encrypted ciphertext.
-    # The string must be unusual enough to ensure it does not occur within
-    # the dictionary metadata keys or values.
-    INNER_GLUE_STRING = "\n<-|@| <  || opensecret inner crypt material axis ||  > |@|->\n\n"
-
-
-    # An unusual string that glues together the asymmetrically encrypted outer
-    # encryption key  with the outer crypted text.
-    OUTER_GLUE_STRING = "\n<-|@| <  || opensecret outer crypt material axis ||  > |@|->\n\n"
-
-
-    # Text header for key-value pairs hash map that will be serialized.
-    DICTIONARY = "dictionary"
-
-    # Name for the class of cipher employed.
-    DICT_CIPHER_NAME = "cipher.class"
-
-    # Name for the {Base64} encoded symmetric (lock/unlock) crypt key.
-    DICT_CRYPT_KEY = "encryption.key"
-
-    # Name for the {Base64} encoded plain text digest.
-    DICT_PLAINTEXT_DIGEST = "plaintext.digest"
-
-    # Name for the {Base64} encoded crypt material digest.
-    DICT_MATERIAL_DIGEST = "cipher.digest"
-
-    # Name for the plain text initialization vector (iv).
-    DICT_INIT_VECTOR = "crypt.init.vector"
-
-    # Name for the {Base64} encoded crypted cipher text.
-    DICT_CIPHER_TEXT = "cipher.text"
-
-
-    # The cipher constructor instantiates the encryption dictionary which
-    # will be collaboratively added to by the parent and child ciphers.
-    def initialize
-
-      @dictionary = {}
-
-    end
-
-
-    # Ciphers use +symmetric algorithms+ to encrypt the given text, which
-    # is then wrapped up along with the encryption key and other +metadata+
+    # Ciphers use <b>symmetric algorithms</b> to encrypt the given text, which
+    # is then wrapped up along with the encryption key and other <b>metadata</b>
     # pertinent to the algorithm, they then encrypt this bundle with the
-    # +public key+ provided and return the text that can safely be stored in
+    # <b>public key</b> provided and return the text that can safely be stored in
     # a text file.
     #
     # Ciphers should never interact with the filesystem which makes them
@@ -142,158 +115,84 @@ module OpenSecret
     # Every component in the pipeline bears the responsibility for nullifying
     # and rejecting malicious content.
     #
-    # @param public_key_text [String] textual portion of an {OpenSSL::PKey::RSA}
-    #    public key. There is no need for an asymmetric encryption agent to know
-    #    the asymmetic private key.
+    # @param public_key [OpenSSL::PKey::RSA]
+    #    an {OpenSSL::PKey::RSA} public key. The unique selling point of
+    #    asymmetric encryption is it can be done without recourse to the heavily
+    #    protected private key. Thus the encryption process can continue with
+    #    just a public key as long as its authenticity is assured.
     #
-    # @param payload_text [String] plaintext (or base64 encoded) text to encrypt
+    # @param payload_text [String]
+    #    plaintext (or base64 encoded) text to encrypt
     #
     # @return [String] doubly (symmetric and asymmetric) encrypted cipher text
-    def encrypt_it public_key_text, payload_text
-
-      crypted_payload = do_symmetric_encryption payload_text
+    def self.encrypt_it public_key, payload_text
 
-#########      puts JSON.pretty_generate(@dictionary)
+      crypt_data = {}
+      crypted_payload = Base64.encode64( Aes256.do_encrypt( crypt_data, payload_text ) )
+      unified_material = CryptIO.inner_crypt_serialize crypt_data, crypted_payload
 
-      unified_material = unify_hash_and_text crypted_payload
       outer_crypt_key = OpenSecret::Engineer.strong_key( 128 )
-      crypted_cryptkey = do_asymmetric_encryption public_key_text, outer_crypt_key
-      crypted_material = Base64.encode64(Blowfish.new.encryptor unified_material, outer_crypt_key)
-      locked_ciphertxt = unify_text_and_text crypted_cryptkey, crypted_material
-
-      return locked_ciphertxt
+      crypted_cryptkey = Base64.encode64( public_key.public_encrypt( outer_crypt_key ) )
 
-    end
-
-
-    # This method takes the textual public key lacking the private key portion
-    # as it is not needed, and encrypts the secret text with it.
-    # It returns a Base64 encoded version of they encrypted text.
-    #
-    # The public key text must be compatible with {OpenSSL::PKey::RSA} as the
-    # class will be instantiated using the public key text.
-    #
-    # @param public_key_text [String] the textual portion of an RSA public key
-    # @param secret_text [String] secret text to encrypt with the public key
-    #
-    # @return [String] a Base64 encoded version of the encrypted secret text
-    def do_asymmetric_encryption public_key_text, secret_text
+      crypted_material = Base64.encode64(Blowfish.new.encryptor unified_material, outer_crypt_key)
 
-      asymmetric_encrypt_key = OpenSSL::PKey::RSA.new public_key_text
-      Base64.encode64( asymmetric_encrypt_key.public_encrypt( secret_text[0..1012] ) )
+      return CryptIO.outer_crypt_serialize( crypted_cryptkey, crypted_material )
 
     end
 
 
-    # The decrypted cipher-text is actually a two part bundle consisting of
-    # a dictionary and then more cipher-text which is then decrypted using
-    # the symmetric key held within the dictionary.
+    # This method takes and <b><em>opensecret formatted</em></b> cipher-text block
+    # generated by {self.encrypt_it} and returns the original message that has effectively
+    # been doubly encrypted using a symmetric and asymmetric cipher. This type of
+    # encryption is standard best practice when serializing secrets.
     #
-    # The private key revealed a dictionary holding the symmetric encryption
-    # key and other details pertinent to the cipher's encrypt/decrypt process.
-    # This data is used to work on the cipher text, eventually revealing the
-    # original plain text (which half the time is actually a private key).
+    # opensecret cipher-text blocks <b><em>look like a two(2) part bundle</em></b>
+    # but they are <b><em>actually a three(3) part bundle</em></b> because the second
+    # part is in itself an amalgam of two distinct objects, serialized as text blocks.
     #
-    # Ciphers should never interact with the filesystem which makes them
-    # reusable in API and remote store scenarios.
+    # <b>The 3 OpenSecret Blocks</b>
     #
-    # @param private_key [String] reveals the dictionary and more ciphertext
-    # @param cipher_text [String] the crypted (base64 encoded) text bundle
+    # Even though the incoming text <b><em>appears to contain two (2) blocks</em></b>,
+    # it <b><em>actually contains three (3)</em></b>.
     #
-    # @return [String] the plain or encoded text first pushed into the cipher
-    def decrypt_it private_key, cipher_text
-
-      paraphernalia = do_asymmetric_decryption private_key, cipher_text
-      return do_symmetric_decryption get_dictionary(paraphernalia), get_crypt(paraphernalia)
-
-    end
-
-
-    # Serialize and then unite a hash map and a textual chunk using
-    # a known but unusual separator string in a manner that protects
-    # the content integrity during the serialize and extraction phases.
-    #
-    # == Why an Unusual Separator String
+    # - a massive symmetric encryption key (locked by an asymmetric keypair)
+    # - a dictionary denoting the algorithm and parameters used to encrypt the 3rd block
+    # - the true message whose encryption is parametized by the dictionary (in 2nd block)
     #
-    # The separator string must be unusual to make it unlikely for it
-    # to occur in any of the map's key value pairs nor indeed the chunk
-    # of text being glued. Were this to happen, the separate and reconstitute
-    # phase may not accurately return the same two entities we are employed
-    # to unite.
+    # The second and third block are only revealed by asymmetrically decrypting
+    # the key in the first block and using it to symmetrically decrypt what appears
+    # to be a unified second block.
     #
-    # == Hash (Map) Contents
+    # @param private_key [OpenSSL::PKey::RSA]
+    #    the <b>asymmetric private key</b> whose corresponding public key was
+    #    employed during the encryption of a super-strong 128 character symmetric
+    #    key embalmed by the first ciphertext block.
     #
-    # The map contents will effectively be serialized in a simplistic
-    # manner therefore the keys should all be strings and the value
-    # types restricted to
+    # @param os_block_text [String]
+    #    the locked cipher text is the opensecret formatted block which comes
+    #    in two main chunks. First is the <b>long strong</b> symmetric encryption
+    #    key crypted with the public key portion of the private key in the first
+    #    parameter.
     #
-    # - strings
-    # - integers and/or floating point numbers
-    # - booleans
+    #    The second chunk is the symmetrically crypted text that was locked with
+    #    the encryption key revealed in the first chunk.
     #
-    # Binary text is not allowed neither in the map or the text chunk.
-    # Any binary should be base64 encoded before being passed to us.
-    #
-    # @param text_chunk [String] the text chunk to be glued at the bottom
-    #
-    # @return [String] serialized and glued together result of map plus text
-    def unify_hash_and_text text_chunk
-
-      nil_or_empty_hash = @dictionary.nil? || @dictionary.empty?
-      raise ArgumentError, "Cannot unify nil or empty metadata." if nil_or_empty_hash
-
-      ini_map = IniFile.new
-      ini_map[ DICTIONARY ] = @dictionary
-
-      return ini_map.to_s + INNER_GLUE_STRING + text_chunk
-
-    end
-
-
-
-    # Using an outer divider (glue) - attach the asymmetrically encrypted outer
-    # encryption key  with the outer encrypted text.
-    #
-    # @param crypt_material_x [String] asymmetrically encrypted (encoded) outer encryption key
-    # @param crypt_material_y [String] symmetrically encrypted inner metadata and payload crypt
-    #
-    # @return [String] concatenated result of the two crypt materials and divider string
-    def unify_text_and_text crypt_material_x, crypt_material_y
-
-      return crypt_material_x + OUTER_GLUE_STRING + crypt_material_y
-
-    end
-
-
-
-    def encrypt_usecase public_key, secret_path, stores, plain_text
-
-      key_pair = KeyPair.new
-
-      secret_bundle_crypt = encrypt_it key_pair.public_key, plain_text
-      stores[1].write_path( secret_path, secret_bundle_crypt )
-
-      secret_key_crypt = encrypt_it public_key, key_pair.private_key
-      stores[0].write_path( secret_path, secret_key_crypt )
-
-    end
-
-
-
-    def decrypt_usecase private_key, public_key, secret_path, stores
-
-      inner_private_key = decrypt_it( private_key, stores[0].read_path(secret_path) )
-      secret_text = decrypt_it( inner_private_key, stores[1].read_path(secret_path) )
-
-      encrypt_usecase public_key, secret_path, stores, secret_text
-      return secret_text
-
-    end
+    # @return [String]
+    #    the doubly encrypted plain text that is locked by a symmetric key and
+    #    that symmetric key itself locked using the public key portion of the
+    #    private key whose crypted form is presented in the first parameter.
+    def self.decrypt_it private_key, os_block_text
 
+      first_block = Base64.decode64( CryptIO.outer_crypt_deserialize os_block_text, true  )
+      trail_block = Base64.decode64( CryptIO.outer_crypt_deserialize os_block_text, false )
 
+      decrypt_key = private_key.private_decrypt first_block
+      inner_block = Blowfish.new.decryptor( trail_block, decrypt_key )
 
-    def rekey_usecase old_private_key, new_public_key, secret_path, store
+      crypt_props = Hash.new
+      cipher_text = CryptIO.inner_crypt_deserialize( crypt_props, inner_block )
 
+      return Aes256.do_decrypt( crypt_props, cipher_text )
 
     end
 

data/lib/plugins/ciphers/aes-256.rb

@@ -13,9 +13,9 @@ module OpenSecret
   # dictionary which will be stored along with the ciphertext itself.
   # The dictionary includes
   #
-  # - <tt>symmetric.cipher</tt> - the algorithm used to encrypt and decrypt
-  # - <tt>encryption.key</tt> - hex encoded key for encrypting and decrypting
-  # - <tt>initialize.vector</tt> - the initialization vector known as a IV (four)
+  # - <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
   #
@@ -25,137 +25,121 @@ module OpenSecret
   #
   # This class implements the below methods
   #
-  # - <tt>do_symmetric_encryption(plain_text)</tt> - resulting in ciphertext
-  # - <tt>do_symmetric_decryption(ciphertext, encryption_dictionary)</tt> &raquo; plaintext
+  # - <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 <tt>@dictionary</tt> hash (map) of pertinent
+  # 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 {OpenSecret::Cipher} parent to
   # do the nitty gritty of file-handling plus managing stores and paths.
 
-  class Aes256 < OpenSecret::Cipher
-
-    @@initialize_vector_keyname = "initialize.vector"
+  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.
     #
-    # Add these key/value pairs to @dictionary instance map.
+    # <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
     #
-    # - <tt>symmetric.cipher</tt> - the algorithm used to encrypt and decrypt
-    # - <tt>encryption.key</tt> - hex encoded key for encrypting and decrypting
-    # - <tt>initialize.vector</tt> - the initialization vector known as a IV (four)
+    # - 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 do_symmetric_encryption plain_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
 
-      @dictionary[DICT_CIPHER_NAME] = crypt_cipher.class.name
-      @dictionary[DICT_CRYPT_KEY] = Base64.urlsafe_encode64 crypt_cipher.random_key
-      @dictionary[DICT_INIT_VECTOR] = Base64.urlsafe_encode64 crypt_cipher.random_iv
-      @dictionary[DICT_PLAINTEXT_DIGEST] = Base64.urlsafe_encode64(Digest::SHA256.digest(plain_text))
-
-      cipher_text = crypt_cipher.update( plain_text ) + crypt_cipher.final
+      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
 
-      @dictionary[DICT_CIPHER_TEXT] = Base64.urlsafe_encode64( cipher_text )
-      @dictionary[DICT_MATERIAL_DIGEST] = Base64.urlsafe_encode64(Digest::SHA256.digest(cipher_text))
-
-      return cipher_text
+      return crypt_cipher.update( plain_text ) + crypt_cipher.final
 
     end
 
 
-    # Use the AES 256 bit block cipher together with the encryption key
-    # and initialization vector (iv) sitting in the encryption_dictionary,
-    # to symmetrically decrypt the parameter cipher text.
+    # 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
     #
-    # == Pre-Condition | Encryption ...
+    # - 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
     #
-    # This method requires the <tt>@dictionary</tt> instance
-    # variable to have been set and to contain (amongst others)
+    # @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>.
     #
-    # - the <tt>encryption.key</tt> - hex encoded key for encrypting and decrypting
-    # - and <tt>initialize.vector</tt> - the initialization vector known as a IV (four)
+    # @param cipher_text [String]
+    #    the (already decoded) cipher text for decryption by this method using the
+    #    encryption properties setup during the past encrypt event.
     #
-    # @param cipher_text [String] the base64 encoded cipher text to decrypt
-    # @return [String] decrypted plain text from symmetric key and cipher text
-    def do_symmetric_decryption cipher_text
+    # @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]  )
 
-      abort "Implement AES 256 decryption in aes-256"
+      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
+
 
-=begin
-encode_cipher = OpenSSL::Cipher.new('aes-256-cbc')
-encode_cipher.encrypt # We are encrypting
-key = encode_cipher.random_key
-iv = encode_cipher.random_iv
-hex_key = key.unpack("H*").first
-hex_iv = iv.unpack("H*").first
-
-line1 = "1>> This is secret number one over here with at @ and squiggle~ and round brakets().\n"
-line2 = "2>> secret number two with colon and semi :; angular <> qmarks ??.\n"
-line3 = "3>> secret number 3 fwd slash / and backslash twice \\ and pipe || and excla !!\n"
-line4 = "4>> secret 4 with pound ££ dollar $$ percent %% hat ^^ ampr && stars **\n"
-line5 = "5>> secret 5 with hyphens - and underscore __ and plus ++ and equal == and sqBs [[]].\n"
-line6 = "6>> secret 6 with double quote \"from here to here\" and \' single quotes\'.\n"
-line7 = "7>> secret 7 with periods .... and hashes #####\n"
-
-crypt_text = ""
-crypt_text += encode_cipher.update line1
-crypt_text += encode_cipher.update line2
-crypt_text += encode_cipher.update line3
-crypt_text += encode_cipher.update line4
-crypt_text += encode_cipher.update line5
-crypt_text += encode_cipher.update line6
-crypt_text += encode_cipher.update line7
-crypt_text += encode_cipher.final
-coded_crypt_text = Base64.urlsafe_encode64(crypt_text)
-
-puts ""
-puts "The key is #{hex_key}"
-puts "The IV is #{hex_iv}"
-puts "========================"
-puts "The Cipher Text is Below"
-puts "========================"
-puts coded_crypt_text
-puts "========================"
-puts crypt_text
-puts "========================"
-puts "========================"
-puts "========================"
-puts line1 + line2 + line3 + line4 + line5 + line6 + line7
-puts "========================"
-puts "========================"
-puts "========================"
-puts ""
-puts ""
-
-unencoded_crypt_text = Base64.urlsafe_decode64(coded_crypt_text)
-decode_cipher = OpenSSL::Cipher.new('aes-256-cbc')
-
-decode_cipher.decrypt
-decode_cipher.key = [hex_key].pack("H*")
-decode_cipher.iv = [hex_iv].pack("H*")
-first_part = decode_cipher.update( Base64.urlsafe_decode64(coded_crypt_text) )
-second_part = ""
-second_part << decode_cipher.final
-
-puts "========================"
-puts "Decrypted Text is Below"
-puts "========================"
-puts first_part
-puts "========================"
-puts second_part
-puts "========================"
-puts ""
-=end
+    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