enveloperb 0.1.0

data/README.md

@@ -0,0 +1,126 @@
+Ruby bindings for the [envelopers](https://github.com/cipherstash/enveloper) envelope encryption library.
+
+Envelope encryption is a mechanism by which a plaintext is encrypted into a ciphertext using a single-use key (known as the "data key"), and then that data key is encrypted with a second key (known as the "wrapping key", or "key-encryption key", or sometimes "KEK").
+The encrypted data key is then stored alongside the ciphertext, so that all that is needed for decryption is the key-encryption key and the ciphertext/encrypted data key bundle.
+
+The benefits of this mechanism are:
+
+1. Compromise of the key used to encrypt a plaintext (say, by short-term penetration of a process performing decryption) does not compromise all data;
+
+2. The key-encryption key can be stored securely and entirely separate from any plaintext data, in an HSM (Hardware Security Module) or other hardened environment;
+
+3. The entity operating the key-encryption key environment never has (direct) access to plaintexts (as would be the case if you sent the plaintext to the HSM for encryption);
+
+4. Large volumes of data can be encrypted efficiently on a local machine, and only the small data key needs to be sent over a slow network link to be encrypted.
+
+As you can see, the benefits of envelope encryption mostly center around environments where KEK material is HSM-managed.
+Except for testing purposes, it is not common to use envelope encryption in situations where the KEK is provided directly to the envelope encryption system.
+
+
+# Installation
+
+In order to build the `enveloperb` gem, you must have Rust 1.31.0 or later installed.
+On an ARM-based platform, you must use Rust nightly, for SIMD intrinsics support.
+
+With that available, you should be able to install it like any other gem:
+
+    gem install enveloperb
+
+There's also the wonders of [the Gemfile](http://bundler.io):
+
+    gem 'enveloperb'
+
+If you're the sturdy type that likes to run from git:
+
+    bundle install
+    rake install
+
+Or, if you've eschewed the convenience of Rubygems entirely, then you
+presumably know what to do already.
+
+
+# Usage
+
+First off, load the library:
+
+```ruby
+require "enveloperb"
+```
+
+Then create a new cryptography engine, using your choice of wrapping key provider.
+For this example, we'll use the "simple" key provider, which takes a 16 byte *binary* string as the key-encryption-key.
+
+```ruby
+require "securerandom"
+kek = SecureRandom.bytes(16)
+
+engine = Enveloperb::Simple.new(kek)
+```
+
+Now you can encrypt whatever data you like:
+
+```ruby
+ct = engine.encrypt("This is a super-important secret")
+```
+
+This produces an `Enveloperb::EncryptedRecord`, which can be turned into a (binary) string very easily:
+
+```ruby
+File.binwrite("/tmp/ciphertext", ct1.to_s)
+```
+
+To turn a binary string back into a ciphertext, just create a new `EncryptedRecord` with it:
+
+```ruby
+ct_new = Enveloperb::EncryptedRecord.new(File.binread("/tmp/ciphertext"))
+```
+
+Then you can decrypt it again:
+
+```ruby
+engine.decrypt(ct_new)  # => "This ia super-important secret"
+```
+
+
+## AWS KMS Key Provider
+
+When using a locally-managed wrapping key, the benefits over direct encryption aren't significant.
+The real benefits come when using a secured key provider for the wrapping key, such as AWS KMS.
+
+To use an AWS KMS key as the wrapping key, you use an `Enveloperb::AWSKMS` instance as the cryptography engine, like so:
+
+```ruby
+engine = Enveloperb::AWSKMS.key(keyid, profile: "example", region: "xx-example-1", credentials: { ... })
+```
+
+While `keyid` is mandatory, `profile`, `region` and `credentials` are all optional.
+If not specified, they will be extracted from the usual places (environment, metadata service, etc) as specified in [the AWS SDK for Rust documentation](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html).
+Yes, the Rust SDK -- `enveloperb` is just a thin wrapper around a Rust library.
+We are truly living in the future.
+
+Once you have your AWS KMS cryptography engine, its usage is the familiar `#encrypt` / `#decrypt` cycle.
+
+
+# Contributing
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+
+# Licence
+
+Unless otherwise stated, everything in this repo is covered by the following
+copyright notice:
+
+    Copyright (C) 2022  CipherStash Inc.
+
+    This program is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License version 3, as
+    published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/enveloperb.gemspec

@@ -0,0 +1,40 @@
+begin
+  require 'git-version-bump'
+rescue LoadError
+  nil
+end
+
+Gem::Specification.new do |s|
+  s.name = "enveloperb"
+
+  s.version = GVB.version rescue "0.0.0.1.NOGVB"
+  s.date    = GVB.date    rescue Time.now.strftime("%Y-%m-%d")
+
+  s.platform = Gem::Platform::RUBY
+
+  s.summary  = "Ruby bindings for the envelopers envelope encryption library"
+
+  s.authors  = ["Matt Palmer"]
+  s.email    = ["matt@cipherstash.com"]
+  s.homepage = "https://github.com/cipherstash/enveloperb"
+
+  s.files = `git ls-files -z`.split("\0").reject { |f| f =~ /^(\.|G|spec|Rakefile)/ }
+
+  s.extensions = ["ext/Rakefile"]
+  s.require_paths = ["lib", "target"]
+
+  s.required_ruby_version = ">= 2.7.0"
+
+  s.add_runtime_dependency "rutie", "~> 0.0.4"
+
+  s.add_development_dependency 'bundler'
+  s.add_development_dependency 'gem-compiler'
+  s.add_development_dependency 'github-release'
+  s.add_development_dependency 'guard-rspec'
+  s.add_development_dependency 'rake', '~> 10.4', '>= 10.4.2'
+  s.add_development_dependency 'rb-inotify', '~> 0.9'
+  s.add_development_dependency 'redcarpet'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'yard'
+end

data/ext/Rakefile

@@ -0,0 +1,5 @@
+task :build do
+  sh "cargo build --release"
+end
+
+task default: :build

data/lib/enveloperb/awskms.rb

@@ -0,0 +1,58 @@
+module Enveloperb
+  # An Enveloperb cryptography engine using AWS KMS as a wrapping key provider.
+  #
+  class AWSKMS
+    def self.new(keyid, aws_access_key_id: nil, aws_secret_access_key: nil, aws_session_token: nil, aws_region: nil)
+      unless keyid.is_a?(String) && keyid.encoding == Encoding::find("UTF-8") && keyid.valid_encoding?
+        raise ArgumentError, "Key ID must be a valid UTF-8 string"
+      end
+
+      unless aws_access_key_id.nil? && aws_secret_access_key.nil? && aws_session_token.nil? && aws_region.nil?
+        validate_string(aws_access_key_id, :aws_access_key_id)
+        validate_string(aws_secret_access_key, :aws_secret_access_key)
+        validate_string(aws_region, :aws_region)
+        validate_string(aws_session_token, :aws_session_token, allow_nil: true)
+      end
+
+      _new(
+        keyid,
+        {
+          access_key_id: aws_access_key_id,
+          secret_access_key: aws_secret_access_key,
+          session_token: aws_session_token,
+          region: aws_region,
+        }
+      )
+    end
+
+    def encrypt(s)
+      unless s.is_a?(String)
+        raise ArgumentError, "Can only encrypt strings"
+      end
+
+      _encrypt(s)
+    end
+
+    def decrypt(er)
+      unless er.is_a?(EncryptedRecord)
+        raise ArgumentError, "Can only decrypt EncryptedRecord objects; you can make one from a string with EncryptedRecord.new"
+      end
+
+      _decrypt(er)
+    end
+
+    class << self
+      private
+
+      def validate_string(s, var, allow_nil: false)
+        if s.nil? && !allow_nil
+          raise ArgumentError, "#{var.inspect} option to Enveloperb::AWSKMS.new() cannot be nil"
+        end
+
+        unless s.is_a?(String) && s.encoding == Encoding.find("UTF-8") && s.valid_encoding?
+          raise ArgumentError, "#{var.inspect} option passed to Enveloperb::AWSKMS.new() must be a valid UTF-8 string"
+        end
+      end
+    end
+  end
+end

data/lib/enveloperb/encrypted_record.rb

@@ -0,0 +1,31 @@
+module Enveloperb
+  # An envelope encrypted record.
+  class EncryptedRecord
+    # Create an encrypted record from a serialized form.
+    #
+    # Encrypted records can be serialized (using #to_s), and then deserialized by passing them into this constructor.
+    #
+    # @param s [String] the serialized encrypted record.
+    #   This must be a `BINARY` encoded string.
+    #
+    # @raises [ArgumentError] if something other than a binary string is provided, or if the string passed as the serialized encrypted record is not valid.
+    #
+    def self.new(s)
+      unless s.is_a?(String) && s.encoding == Encoding::BINARY
+        raise ArgumentError, "Serialized encrypted record must be a binary string"
+      end
+
+      _new(s)
+    end
+
+    # Serialize an encrypted record into a string.
+    #
+    # @return [String]
+    #
+    # @raise [RuntimeError] if something goes spectacularly wrong with the serialization process.
+    #
+    def to_s
+      _serialize
+    end
+  end
+end

data/lib/enveloperb/simple.rb

@@ -0,0 +1,35 @@
+module Enveloperb
+  # An Enveloperb cryptography engine using an unprotected string as the wrapping key.
+  #
+  # @note this class is not intended for general-purpose use.
+  #
+  class Simple
+    def self.new(k)
+      unless k.is_a?(String) && k.encoding == Encoding::BINARY
+        raise ArgumentError, "Key must be a binary string"
+      end
+
+      unless k.bytesize == 16
+        raise ArgumentError, "Key must be 16 bytes"
+      end
+
+      _new(k)
+    end
+
+    def encrypt(s)
+      unless s.is_a?(String)
+        raise ArgumentError, "Can only encrypt strings"
+      end
+
+      _encrypt(s)
+    end
+
+    def decrypt(er)
+      unless er.is_a?(EncryptedRecord)
+        raise ArgumentError, "Can only decrypt EncryptedRecord objects; you can make one from a string with EncryptedRecord.new"
+      end
+
+      _decrypt(er)
+    end
+  end
+end

data/lib/enveloperb.rb

@@ -0,0 +1,9 @@
+require "rutie"
+
+module Enveloperb
+  Rutie.new(:enveloperb).init 'Init_enveloperb', __dir__
+end
+
+require_relative "./enveloperb/encrypted_record"
+require_relative "./enveloperb/awskms"
+require_relative "./enveloperb/simple"

data/src/lib.rs

@@ -0,0 +1,195 @@
+#[macro_use]
+extern crate rutie;
+
+#[macro_use]
+extern crate lazy_static;
+
+// I have deliberately not used more-specific symbols inside the aws_* crates because the
+// names are quite generic, and in the near future when we have more providers, we'll
+// almost certainly end up with naming clashes.
+use aws_config;
+use aws_sdk_kms;
+use aws_types;
+use enveloper::{EncryptedRecord, EnvelopeCipher, KMSKeyProvider, SimpleKeyProvider};
+use std::borrow::Cow;
+use tokio::runtime::Runtime;
+use rutie::{Class, Encoding, Hash, Module, Object, RString, Symbol, VerifiedObject, VM};
+
+module!(Enveloperb);
+class!(EnveloperbSimple);
+class!(EnveloperbAWSKMS);
+class!(EnveloperbEncryptedRecord);
+
+impl VerifiedObject for EnveloperbEncryptedRecord {
+    fn is_correct_type<T: Object>(object: &T) -> bool {
+        let klass = Module::from_existing("Enveloperb").get_nested_class("EncryptedRecord");
+        klass.case_equals(object)
+    }
+
+    fn error_message() -> &'static str {
+        "Error converting to Enveloperb::EncryptedRecord"
+    }
+}
+
+pub struct SimpleCipher {
+    cipher: EnvelopeCipher<SimpleKeyProvider>,
+    runtime: Runtime,
+}
+
+pub struct AWSKMSCipher {
+    cipher: EnvelopeCipher<KMSKeyProvider>,
+    runtime: Runtime,
+}
+
+wrappable_struct!(SimpleCipher, SimpleCipherWrapper, SIMPLE_CIPHER_WRAPPER);
+wrappable_struct!(AWSKMSCipher, AWSKMSCipherWrapper, AWSKMS_CIPHER_WRAPPER);
+wrappable_struct!(EncryptedRecord, EncryptedRecordWrapper, ENCRYPTED_RECORD_WRAPPER);
+
+methods!(
+    EnveloperbSimple,
+    rbself,
+
+    fn enveloperb_simple_new(rbkey: RString) -> EnveloperbSimple {
+        let mut key: [u8; 16] = Default::default();
+
+        key.clone_from_slice(rbkey.unwrap().to_bytes_unchecked());
+
+        let provider = SimpleKeyProvider::init(key);
+        let cipher = EnvelopeCipher::init(provider);
+
+        let klass = Module::from_existing("Enveloperb").get_nested_class("Simple");
+        return klass.wrap_data(SimpleCipher{ cipher: cipher, runtime: Runtime::new().unwrap() }, &*SIMPLE_CIPHER_WRAPPER);
+    }
+
+    fn enveloperb_simple_encrypt(rbtext: RString) -> EnveloperbEncryptedRecord {
+        let cipher = rbself.get_data(&*SIMPLE_CIPHER_WRAPPER);
+        let er_r = cipher.runtime.block_on(async {
+            cipher.cipher.encrypt(rbtext.unwrap().to_bytes_unchecked()).await
+        });
+        let er = er_r.map_err(|e| VM::raise(Class::from_existing("RuntimeError"), &format!("Failed to perform encryption: {:?}", e))).unwrap();
+
+        let klass = Module::from_existing("Enveloperb").get_nested_class("EncryptedRecord");
+        return klass.wrap_data(er, &*ENCRYPTED_RECORD_WRAPPER);
+    }
+
+    fn enveloperb_simple_decrypt(rbrecord: EnveloperbEncryptedRecord) -> RString {
+        let cipher = rbself.get_data(&*SIMPLE_CIPHER_WRAPPER);
+        let e_record = rbrecord.unwrap();
+        let record = e_record.get_data(&*ENCRYPTED_RECORD_WRAPPER);
+
+        let vec_r = cipher.runtime.block_on(async {
+            cipher.cipher.decrypt(record).await
+        });
+        let vec = vec_r.map_err(|e| VM::raise(Class::from_existing("RuntimeError"), &format!("Failed to perform decryption: {:?}", e))).unwrap();
+
+        return RString::from_bytes(&vec, &Encoding::find("BINARY").unwrap());
+    }
+);
+
+methods!(
+    EnveloperbAWSKMS,
+    rbself,
+
+    fn enveloperb_awskms_new(rbkey: RString, rbcreds: Hash) -> EnveloperbAWSKMS {
+        let raw_creds = rbcreds.unwrap();
+        let rt = Runtime::new().unwrap();
+
+        let kmsclient_config = if raw_creds.at(&Symbol::new("access_key_id")).is_nil() {
+            rt.block_on(async {
+                aws_config::load_from_env().await
+            })
+        } else {
+            let rbregion = raw_creds.at(&Symbol::new("region")).try_convert_to::<RString>().unwrap();
+            let region   = Some(aws_types::region::Region::new(rbregion.to_str().to_owned()));
+
+            let rbkey_id = raw_creds.at(&Symbol::new("access_key_id")).try_convert_to::<RString>().unwrap();
+            let key_id   = rbkey_id.to_str();
+
+            let rbsecret = raw_creds.at(&Symbol::new("secret_access_key")).try_convert_to::<RString>().unwrap();
+            let secret   = rbsecret.to_str();
+
+            let token = match raw_creds.at(&Symbol::new("session_token")).try_convert_to::<RString>() {
+                Ok(str) => Some(str.to_string()),
+                Err(_)  => None
+            };
+
+            let aws_creds = aws_types::Credentials::from_keys(key_id, secret, token);
+            let creds_provider = aws_types::credentials::SharedCredentialsProvider::new(aws_creds);
+
+            aws_types::sdk_config::SdkConfig::builder().region(region).credentials_provider(creds_provider).build()
+        };
+
+        let kmsclient = aws_sdk_kms::Client::new(&kmsclient_config);
+        let provider = KMSKeyProvider::new(kmsclient, rbkey.unwrap().to_string());
+        let cipher = EnvelopeCipher::init(provider);
+
+        let klass = Module::from_existing("Enveloperb").get_nested_class("AWSKMS");
+        return klass.wrap_data(AWSKMSCipher{ cipher: cipher, runtime: rt }, &*AWSKMS_CIPHER_WRAPPER);
+    }
+
+    fn enveloperb_awskms_encrypt(rbtext: RString) -> EnveloperbEncryptedRecord {
+        let cipher = rbself.get_data(&*AWSKMS_CIPHER_WRAPPER);
+        let er_r = cipher.runtime.block_on(async {
+            cipher.cipher.encrypt(rbtext.unwrap().to_bytes_unchecked()).await
+        });
+        let er = er_r.map_err(|e| VM::raise(Class::from_existing("RuntimeError"), &format!("Failed to perform encryption: {:?}", e))).unwrap();
+
+        let klass = Module::from_existing("Enveloperb").get_nested_class("EncryptedRecord");
+        return klass.wrap_data(er, &*ENCRYPTED_RECORD_WRAPPER);
+    }
+
+    fn enveloperb_awskms_decrypt(rbrecord: EnveloperbEncryptedRecord) -> RString {
+        let cipher = rbself.get_data(&*AWSKMS_CIPHER_WRAPPER);
+        let e_record = rbrecord.unwrap();
+        let record = e_record.get_data(&*ENCRYPTED_RECORD_WRAPPER);
+
+        let vec_r = cipher.runtime.block_on(async {
+            cipher.cipher.decrypt(record).await
+        });
+        let vec = vec_r.map_err(|e| VM::raise(Class::from_existing("RuntimeError"), &format!("Failed to perform decryption: {:?}", e))).unwrap();
+
+        return RString::from_bytes(&vec, &Encoding::find("BINARY").unwrap());
+    }
+);
+
+methods!(
+    EnveloperbEncryptedRecord,
+    rbself,
+
+    fn enveloperb_encrypted_record_new(serialized_record: RString) -> EnveloperbEncryptedRecord {
+        let s = serialized_record.unwrap().to_vec_u8_unchecked();
+        let ct = EncryptedRecord::from_vec(s).map_err(|e| VM::raise(Class::from_existing("ArgumentError"), &format!("Failed to decode encrypted record: {:?}", e))).unwrap();
+
+        let klass = Module::from_existing("Enveloperb").get_nested_class("EncryptedRecord");
+        return klass.wrap_data(ct, &*ENCRYPTED_RECORD_WRAPPER);
+    }
+
+    fn enveloperb_encrypted_record_serialize() -> RString {
+        let record = rbself.get_data(&*ENCRYPTED_RECORD_WRAPPER);
+
+        return RString::from_bytes(&record.to_vec().map_err(|e| VM::raise(Class::from_existing("RuntimeError"), &format!("Failed to encode encrypted record: {:?}", e))).unwrap(), &Encoding::find("BINARY").unwrap());
+    }
+);
+
+#[allow(non_snake_case)]
+#[no_mangle]
+pub extern "C" fn Init_enveloperb() {
+    Module::from_existing("Enveloperb").define(|envmod| {
+        envmod.define_nested_class("Simple", None).define(|klass| {
+            klass.singleton_class().def_private("_new", enveloperb_simple_new);
+            klass.def_private("_encrypt", enveloperb_simple_encrypt);
+            klass.def_private("_decrypt", enveloperb_simple_decrypt);
+        });
+
+        envmod.define_nested_class("AWSKMS", None).define(|klass| {
+            klass.singleton_class().def_private("_new", enveloperb_awskms_new);
+            klass.def_private("_encrypt", enveloperb_awskms_encrypt);
+            klass.def_private("_decrypt", enveloperb_awskms_decrypt);
+        });
+
+        envmod.define_nested_class("EncryptedRecord", None).define(|klass| {
+            klass.singleton_class().def_private("_new", enveloperb_encrypted_record_new);
+            klass.def_private("_serialize", enveloperb_encrypted_record_serialize);
+        });
+    });
+}