{"id":19166407,"url":"https://github.com/cipherstash/enveloperb","last_synced_at":"2025-05-07T13:22:02.099Z","repository":{"id":39759936,"uuid":"485629868","full_name":"cipherstash/enveloperb","owner":"cipherstash","description":"Ruby bindings for the envelopers envelope-encryption library","archived":false,"fork":false,"pushed_at":"2023-02-04T01:58:13.000Z","size":138,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-19T22:34:07.302Z","etag":null,"topics":["cipherstash","cryptography","encryption","envelope-encryption","ruby"],"latest_commit_sha":null,"homepage":"https://cipherstash.com","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cipherstash.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null}},"created_at":"2022-04-26T04:13:30.000Z","updated_at":"2023-01-27T09:00:22.000Z","dependencies_parsed_at":"2023-02-18T12:55:13.522Z","dependency_job_id":null,"html_url":"https://github.com/cipherstash/enveloperb","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipherstash%2Fenveloperb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipherstash%2Fenveloperb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipherstash%2Fenveloperb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipherstash%2Fenveloperb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cipherstash","download_url":"https://codeload.github.com/cipherstash/enveloperb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252883536,"owners_count":21819193,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cipherstash","cryptography","encryption","envelope-encryption","ruby"],"created_at":"2024-11-09T09:32:39.652Z","updated_at":"2025-05-07T13:22:02.075Z","avatar_url":"https://github.com/cipherstash.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"Ruby bindings for the [envelopers](https://github.com/cipherstash/enveloper) envelope encryption library.\n\nEnvelope 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\").\nThe 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.\n\nThe benefits of this mechanism are:\n\n1. Compromise of the key used to encrypt a plaintext (say, by short-term penetration of a process performing decryption) does not compromise all data;\n\n2. 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;\n\n3. 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);\n\n4. 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.\n\nAs you can see, the benefits of envelope encryption mostly center around environments where KEK material is HSM-managed.\nExcept for testing purposes, it is not common to use envelope encryption in situations where the KEK is provided directly to the envelope encryption system.\n\n\n# Installation\n\nFor the most common platforms, we provide \"native\" gems (which have the shared object that provides the cryptographic primitives pre-compiled).\nAt present, we provide native gems for:\n\n* Linux `x86_64` and `aarch64`\n* macOS `x86_64` and `arm64`\n\nOn these platforms, you can just install the `enveloperb` gem via your preferred method, and it should \"just work\".\nIf it doesn't, please [report that as a bug](https://github.com/cipherstash/enveloperb/issues).\n\nFor other platforms, you will need to install the source gem, which requires that you have Rust 1.57.0 or later installed.\nOn ARM-based platforms, you must use Rust nightly, for SIMD intrinsics support.\n\n## Installing from Git\n\nIf you have a burning need to install directly from a checkout of the git repository, you can do so by running `bundle install \u0026\u0026 rake install`.\nAs this is a source-based installation, you will need to have Rust installed, as described above.\n\n\n# Usage\n\nFirst off, load the library:\n\n```ruby\nrequire \"enveloperb\"\n```\n\nThen create a new cryptography engine, using your choice of wrapping key provider.\nFor this example, we'll use the \"simple\" key provider, which takes a 16 byte *binary* string as the key-encryption-key.\n\n```ruby\nrequire \"securerandom\"\nkek = SecureRandom.bytes(16)\n\nengine = Enveloperb::Simple.new(kek)\n```\n\nNow you can encrypt whatever data you like:\n\n```ruby\nct = engine.encrypt(\"This is a super-important secret\")\n```\n\nThis produces an `Enveloperb::EncryptedRecord`, which can be turned into a (binary) string very easily:\n\n```ruby\nFile.binwrite(\"/tmp/ciphertext\", ct1.to_s)\n```\n\nTo turn a binary string back into a ciphertext, just create a new `EncryptedRecord` with it:\n\n```ruby\nct_new = Enveloperb::EncryptedRecord.new(File.binread(\"/tmp/ciphertext\"))\n```\n\nThen you can decrypt it again:\n\n```ruby\nengine.decrypt(ct_new)  # =\u003e \"This ia super-important secret\"\n```\n\n\n## AWS KMS Key Provider\n\nWhen using a locally-managed wrapping key, the benefits over direct encryption aren't significant.\nThe real benefits come when using a secured key provider for the wrapping key, such as AWS KMS.\n\nTo use an AWS KMS key as the wrapping key, you use an `Enveloperb::AWSKMS` instance as the cryptography engine, like so:\n\n```ruby\nengine = Enveloperb::AWSKMS.key(keyid, profile: \"example\", region: \"xx-example-1\", credentials: { ... })\n```\n\nWhile `keyid` is mandatory, `profile`, `region` and `credentials` are all optional.\nIf 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).\nYes, the Rust SDK -- `enveloperb` is just a thin wrapper around a Rust library.\nWe are truly living in the future.\n\nOnce you have your AWS KMS cryptography engine, its usage is the familiar `#encrypt` / `#decrypt` cycle.\n\n\n# Contributing\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcipherstash%2Fenveloperb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcipherstash%2Fenveloperb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcipherstash%2Fenveloperb/lists"}