enveloperb 0.0.0.1.ENOTAG-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e3e70342eb82d9180b0c2ae84572fd7d2ae86859b4b1fd5de454c9b321eb1bcc
+  data.tar.gz: 94bfad96f4b9159c5e233237e2854dad8af4e6c64a253a69964d5b9da7366ab8
+SHA512:
+  metadata.gz: e5fa4c552cdd4544b7117bf5d0c0ef0d569bbed6c0840ef48516ef1c590517051ab32317d8e16454304deea612bfdbd8583d11161339f7790960a9b75c724e3e
+  data.tar.gz: bd65653c503249d1195e4a07759305cc6a0025e46fe5f3a0dd0b6cc7eed5ed1873d7c7a970d59b5af32f96eb650169265dfaf0cc8f64b8f9c25b2d1c2bb848c3

data/CODEOWNERS

@@ -0,0 +1,2 @@
+*    @cipherstash/ruby
+*.rs @cipherstash/rust

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at team@cipherstash.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/CONTRIBUTING.md

@@ -0,0 +1,10 @@
+* If you have found a discrepancy in documented and observed behaviour, that
+  is a bug.  Feel free to [report it as an
+  issue](https://github.com/cipherstash/enveloperb/issues), providing
+  sufficient detail to reproduce the problem.
+
+* If you would like to add new behaviour, please submit a well-tested and
+  well-documented [pull
+  request](https://github.com/cipherstash/enveloperb/pulls).
+
+* At all times, abide by the Code of Conduct (CODE_OF_CONDUCT.md).

data/LICENSE

@@ -0,0 +1,124 @@
+CipherStash Client Library Licence Agreement
+
+0. Background
+
+This licence sets out the terms on which you are permitted to use client side
+components of software provided by CipherStash to query encrypted databases
+(CipherStash Client Software).The operation of the CipherStash Client Software
+is dependent on encryption keys generated by server software operated or
+licensed by CipherStash.
+
+1. Definitions
+
+1.1 In these terms the following terms have the following meanings:
+    (a) Authorised Purpose in relation to the CipherStash Source Code has the
+        meaning given to it in clause 2.4;
+    (b) CipherStash Source Code means human readable code of the CipherStash
+        Client Software;
+    (c) CipherStash Executable means the machine executable code of the
+        CipherStash Client Software as made available by CipherStash from
+        time to time;
+    (d) CipherStash Client Software has the meaning given to it in the
+        Background;
+    (e) Licensed Query means a query on a database that:
+        (i)  uses an encryption key generated by a key server operated or
+             licensed by CipherStash for all encryption of the content of that
+             query or of results returned in response to that query (excluding
+             encryption in the transport layer for communications between
+             servers); and
+        (ii) uses a valid token provided by CipherStash in the course of
+             acquiring the key referred to in the previous paragraph;
+    (f) Your Applications means applications that you create that rely on any
+        part of the CipherStash Client Software in the course of their
+        operation.
+1.2 In these terms, unless the context requires otherwise, references to:
+    (a) encryption includes decryption;
+    (b) keys are references to data used for encryption, not data indicating a
+        row in a database table.
+
+2. Grant of Licence
+
+2.1 This licence permits you to do the following in relation to the CipherStash
+    Client Software:
+    (a) use the CipherStash Executables in the course of developing and testing
+        Your Applications;
+    (b) deploy and use copies of the CipherStash Executables for the purpose of
+        executing Licensed Queries, including as part of one or more of Your
+        Applications; and
+    (c) use the CipherStash Source Code solely for an Authorised Purpose.
+2.2 Subject to clause 2.4(c), you must not make any modifications to the
+    CipherStash Client Software.
+2.3 This licence specifically excludes any use of any part of the CipherStash
+    Client Software to execute any queries other than Licensed Queries on any
+    database.
+2.4 CipherStash makes the CipherStash Source Code available for the sole purpose
+    of allowing third parties to verify the operation, integrity and security
+    of the CipherStash Client Software (Authorised Purpose). This licence
+    permits you to do the following solely for an Authorised Purpose:
+    (a) download and review the CipherStash Source Code;
+    (b) build executable versions of the CipherStash Source Code to verify
+        correspondence between it and its associated CipherStash Executable;
+    (c) make configuration changes to the CipherStash Source Code solely to the
+        extent necessary to build a working executable version under paragraph
+        (b).
+
+3. Warranties and Liability
+
+3.1 To the extent permitted by law, CipherStash excludes all warranties,
+    guarantees and conditions that would otherwise be implied into this
+    agreement by law. Where CipherStash is not able to exclude such a warranty,
+    guarantee or condition, CipherStash limits, to the extent permitted by law,
+    its liability for a breach of that warranty, guarantee or condition to one
+    or more of the following at its option:
+    (a) in the case of goods, any one or more of the following:
+        (i)   the replacement of the goods or the supply of equivalent goods;
+        (ii)  the repair of the goods;
+        (iii) the payment of the cost of replacing the goods or of acquiring
+              equivalent goods;
+        (iv)  the payment of the cost of having the goods repaired; and
+    (b) in the case of services:
+        (i) the supplying of the services again; or
+        (ii) the payment of the cost of having the services supplied again.
+3.2 CipherStash has no liability to any person arising under or in relation to
+    this agreement (whether in tort, contract, equity or otherwise) for any
+    loss in the nature of consequential or economic loss. In particular,
+    CipherStash has no liability to any person for any: lost profits; loss of
+    savings, income or revenue; revenue not meeting targets or certain levels;
+    uptime or availability of internet connectivity or of the ability of third
+    parties to access a website, loss of opportunity; or loss of or corruption
+    of data. The exclusions in this clause 3.2 apply even in respect of loss or
+    damage that was foreseeable or about which either or both of the parties
+    were aware was likely to arise.
+
+4. Dispute Resolution
+
+4.1 Prior to commencing any action in any court or any action in any other form
+    of judicial or quasi-judicial forum you must comply with the requirements
+    of this clause 4.
+4.2 Where you believe there is a dispute between you and CipherStash in respect
+    of a matter the subject of this agreement you must notify CipherStash in
+    writing of the nature of that dispute and for a period of 120 days
+    following CipherStash’s receipt of that notification, make reasonable
+    attempts to resolve that dispute with CipherStash.
+
+5. General and Interpretation
+
+5.1 Except where expressly set out to the contrary, nothing in this agreement
+    grants the Customer any rights over any intellectual property rights
+    (including copyright, patents, and rights to the registration of such
+    rights) held by CipherStash at any time.
+5.2 No provision of this agreement may be construed against a party because
+    that party drafted that term.
+5.3 A waiver of rights under this agreement can only occur in writing signed by
+    the party granting the waiver. Except to the extent set out in the waiver,
+    a waiver is only effective in relation to the specific facts and rights set
+    out in it and does not operate to waive any other rights or to waive the
+    same rights in respect of different facts or circumstances.
+5.4 Where a part of this agreement is held by a court to be illegal or
+    otherwise unenforceable, and the unenforceability of that part does not
+    substantially alter the character of the bargain that would have been in
+    existence between the parties had that part been enforceable, that part is
+    severed and the balance of this agreement will continue unaffected.
+5.5 This contract is governed by the laws in force in the State of New South
+    Wales, Australia. Each party submits to the non-exclusive jurisdiction of
+    the courts of that State.

data/README.md

@@ -0,0 +1,124 @@
+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
+
+For the most common platforms, we provide "native" gems (which have the shared object that provides the cryptographic primitives pre-compiled).
+At present, we provide native gems for:
+
+* Linux `x86_64` and `aarch64`
+* macOS `x86_64` and `arm64`
+
+On these platforms, you can just install the `enveloperb` gem via your preferred method, and it should "just work".
+If it doesn't, please [report that as a bug](https://github.com/cipherstash/enveloperb/issues).
+
+For other platforms, you will need to install the source gem, which requires that you have Rust 1.57.0 or later installed.
+On ARM-based platforms, you must use Rust nightly, for SIMD intrinsics support.
+
+## Installing from Git
+
+If you have a burning need to install directly from a checkout of the git repository, you can do so by running `bundle install && rake install`.
+As this is a source-based installation, you will need to have Rust installed, as described above.
+
+
+# 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,50 @@
+begin
+  require 'git-version-bump'
+rescue LoadError
+  nil
+end
+
+Gem::Specification.new do |s|
+  s.name = "enveloperb"
+
+  s.version = ENV.fetch("GVB_VERSION_OVERRIDE") { 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://cipherstash.com"
+
+  s.files = `git ls-files -z`.split("\0").reject { |f| f =~ /^(\.|G|spec|Rakefile)/ }
+
+  s.extensions = ["ext/enveloperb/extconf.rb"]
+
+  s.required_ruby_version = ">= 2.7.0"
+
+  s.metadata["homepage_uri"] = s.homepage
+  s.metadata["source_code_uri"] = "https://github.com/cipherstash/enveloperb"
+  s.metadata["changelog_uri"] = "https://github.com/cipherstash/enveloperb/releases"
+  s.metadata["bug_tracker_uri"] = "https://github.com/cipherstash/enveloperb/issues"
+  s.metadata["documentation_uri"] = "https://rubydoc.info/gems/enveloperb"
+  s.metadata["mailing_list_uri"] = "https://discuss.cipherstash.com"
+
+  unless ENV.key?("GVB_VERSION_OVERRIDE")
+    s.add_runtime_dependency 'rb_sys', '~> 0.1'
+  end
+
+  s.add_development_dependency 'bundler'
+  s.add_development_dependency 'github-release'
+  s.add_development_dependency 'guard-rspec'
+  s.add_development_dependency 'rake', '~> 13.0'
+  s.add_development_dependency 'rake-compiler', '~> 1.2'
+  s.add_development_dependency 'rake-compiler-dock', '~> 1.2'
+  s.add_development_dependency 'rb-inotify', '~> 0.9'
+  s.add_development_dependency 'rb_sys', '~> 0.1'
+  s.add_development_dependency 'redcarpet'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'yard'
+end

data/ext/enveloperb/.gitignore

@@ -0,0 +1,4 @@
+/target
+# Cargo.lock is deliberately *not* ignored; despite *technically* being a
+# library package, it is not a Rust library that is built into other projects,
+# but rather a standalone binary object that should be built reproducibly.