porky_lib 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b964b025bbd159e92a88fc03d261abad2903ed7b
-  data.tar.gz: 15a5a4ef61f2e8db2658cd568379811fcc5d9725
+  metadata.gz: 122bad0bf114af2bb03c6aa0373fc443dfe3d9c4
+  data.tar.gz: 7f0b09d966c20ba1c223323b8203461f0ca34d5c
 SHA512:
-  metadata.gz: 89c5545701a0a866e738dddd32d66ba7c54e0d44e241d261478c5b4fdd94225f1128d7d4dd8d964b8b3fb90f86986291e8db0fbc9a18fb174221f420136502f4
-  data.tar.gz: 3ec18c9b4aad75e4bb9ca466858c3aa18288e391001bc6ed89050d07e429d68405a061f59a924a2b32079fceae6e46d580ce4f4d2c8df17a84af33a915c837c8
+  metadata.gz: 5ad09fc08eb7c6fb8637a29b4805b2fa58ef71716abbad1067ef135b2782737f61ff039988eb7f7dafb647fe3aea76795e96a406bdbab9e0e1bfa56b5259087e
+  data.tar.gz: 59bdd3b28bb1d8c24c889749924e4f035971a67427cc3507b7705339b64c5a812218eafcc4ec4a459b2ea62df6d17ebd8311d16ef0eb234915c29dc62eeaf259

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    porky_lib (0.1.1)
+    porky_lib (0.1.2)
       aws-sdk-kms
       msgpack
       rbnacl-libsodium

data/README.md

@@ -71,8 +71,9 @@ To encrypt data:
 ```ruby
 # Where data is the data to encrypt
 # cmk_key_id is the AWS key ID, Amazon Resource Name (ARN) or alias for the CMK to use to generate the data encryption key (DEK)
+# ciphertext_dek is an optional parameter to specify the data encryption key to use to encrypt the data. If not provided, a new data encryption key will be generated. Default is nil.
 # encryption_context is an optional parameter to provide additional authentication data for encrypting the DEK. Default is nil.
-[ciphertext_dek, ciphertext, nonce] = PorkyLib::Symmetric.instance.encrypt(data, cmk_key_id, encryption_context)
+[ciphertext_dek, ciphertext, nonce] = PorkyLib::Symmetric.instance.encrypt(data, cmk_key_id, ciphertext_dek, encryption_context)
 ```
 
 ### Decrypting Data
@@ -85,6 +86,29 @@ To decrypt data:
 plaintext_data = PorkyLib::Symmetric.instance.decrypt(ciphertext_dek, ciphertext, nonce, encryption_context)
 ```
 
+### Generating Data Encryption Keys
+To generate a new data encryption key:
+```ruby
+# Where cmk_key_id is the AWS key ID, Amazon Resource Name (ARN) or alias for the CMK to use to generate the data encryption key (DEK)
+# encryption_context is an optional parameter to provide additional authentication data for encrypting the DEK. Default is nil.
+plaintext_key, ciphertext_key = PorkyLib::Symmetric.instance.generate_data_encryption_key(cmk_key_id, encryption_context)
+```
+
+### Decrypting Data Encryption Keys
+To decrypt an existing ciphertext data encryption key:
+```ruby
+# Where ciphertext_key is the data encryption key, encrypted by a CMK within your AWS environment.
+# encryption_context is an optional parameter to provide additional authentication data for encrypting the DEK. Default is nil.
+plaintext_key = PorkyLib::Symmetric.instance.generate_data_encryption_key(ciphertext_key, encryption_context)
+```
+
+### Securely Deleting Plaintext Key From Memory
+To securely delete the plaintext key from memory:
+```ruby
+# Where length is the number of bytes of the plaintext key (i.e. plaintext_key.bytesize)
+plaintext_key = PorkyLib::Symmetric.instance.secure_delete_plaintext_key(plaintext_key.bytesize) 
+```
+
 ## Development
 
 Development on this project should occur on separate feature branches and pull requests should be submitted. When submitting a

data/lib/porky_lib/symmetric.rb

@@ -40,25 +40,35 @@ class PorkyLib::Symmetric
     client.create_alias(target_key_id: key_id, alias_name: key_alias)
   end
 
-  def encrypt(data, cmk_key_id, encryption_context = nil)
-    return if data.nil? || cmk_key_id.nil?
-
-    # Generate a new data encryption key
+  def generate_data_encryption_key(cmk_key_id, encryption_context = nil)
     PorkyLib::Config.logger.info('Generating new data encryption key')
-
     resp = {}
     resp = client.generate_data_key(key_id: cmk_key_id, key_spec: SYMMETRIC_KEY_SPEC, encryption_context: encryption_context) if encryption_context
     resp = client.generate_data_key(key_id: cmk_key_id, key_spec: SYMMETRIC_KEY_SPEC) unless encryption_context
 
-    plaintext_key = resp.to_h[:plaintext]
-    ciphertext_key = resp.to_h[:ciphertext_blob]
+    [resp.to_h[:plaintext], resp.to_h[:ciphertext_blob]]
+  end
+
+  def decrypt_data_encryption_key(ciphertext_key, encryption_context = nil)
+    PorkyLib::Config.logger.info('Decrypting data encryption key')
+
+    return client.decrypt(ciphertext_blob: ciphertext_key, encryption_context: encryption_context).to_h[:plaintext] if encryption_context
+    client.decrypt(ciphertext_blob: ciphertext_key).to_h[:plaintext]
+  end
+
+  def encrypt(data, cmk_key_id, ciphertext_dek = nil, encryption_context = nil)
+    return if data.nil? || cmk_key_id.nil?
+
+    # Generate a new data encryption key or decrypt existing key, if provided
+    plaintext_key = decrypt_data_encryption_key(ciphertext_dek, encryption_context) if ciphertext_dek
+    ciphertext_key = ciphertext_dek if ciphertext_dek
+    plaintext_key, ciphertext_key = generate_data_encryption_key(cmk_key_id, encryption_context) unless ciphertext_dek
 
     # Initialize the box
     secret_box = RbNaCl::SecretBox.new(plaintext_key)
 
-    # rubocop:disable Lint/UselessAssignment
-    plaintext_key = "\0" * plaintext_key.bytesize
-    # rubocop:enable Lint/UselessAssignment
+    # Securely delete the plaintext value from memory
+    plaintext_key.replace(secure_delete_plaintext_key(plaintext_key.bytesize))
 
     # First, make a nonce: A single-use value never repeated under the same key
     # The nonce isn't secret, and can be sent with the ciphertext.
@@ -76,23 +86,20 @@ class PorkyLib::Symmetric
     return if ciphertext.nil? || ciphertext_dek.nil? || nonce.nil?
 
     # Decrypt the data encryption key
-    PorkyLib::Config.logger.info('Decrypting data encryption key')
-
-    resp = {}
-    resp = client.decrypt(ciphertext_blob: ciphertext_dek, encryption_context: encryption_context) if encryption_context
-    resp = client.decrypt(ciphertext_blob: ciphertext_dek) unless encryption_context
-
-    plaintext_key = resp.to_h[:plaintext]
+    plaintext_key = decrypt_data_encryption_key(ciphertext_dek, encryption_context)
 
     secret_box = RbNaCl::SecretBox.new(plaintext_key)
 
-    # rubocop:disable Lint/UselessAssignment
-    plaintext_key = "\0" * plaintext_key.bytesize
-    # rubocop:enable Lint/UselessAssignment
+    # Securely delete the plaintext value from memory
+    plaintext_key.replace(secure_delete_plaintext_key(plaintext_key.bytesize))
 
     PorkyLib::Config.logger.info('Beginning decryption')
     result = secret_box.decrypt(nonce, ciphertext)
     PorkyLib::Config.logger.info('Decryption complete')
     result
   end
+
+  def secure_delete_plaintext_key(length)
+    "\0" * length
+  end
 end

data/lib/porky_lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PorkyLib
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: porky_lib
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Greg Fletcher
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-07-13 00:00:00.000000000 Z
+date: 2018-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler