easy_crypt 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a3936f18965419a36551cd0cc5b5e4d8acd6bdd3afe1ba39dc9879869fb1f649
+  data.tar.gz: 852d38340c89b75221b884eb9e12d2475f06e441e19abad17e9f5ca216a13024
+SHA512:
+  metadata.gz: 3b84dd63f38fe9b6802a5ca667f38800b346e8b52040147967872db726f2e4e23de37702259a5744fc421b1c228deab46757d7b8b8966af9e4724b8dd7c50007
+  data.tar.gz: d3769217d764e084b035785d6a7d7a1e52df286ad1de46a374d3ca115d36f1d1f110c6e75d040a5ed0dd196f5e7ee940b699578778ac927dce538e950070afac

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## [1.0.0] - 2025-01-27
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders 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, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Benjamin Bouchet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,248 @@
+# EasyCrypt
+
+EasyCrypt is a Ruby utility that provides secure and flexible encryption and decryption capabilities for Ruby on Rails applications. It is built on top of Rails’ ActiveSupport::MessageEncryptor, allowing you to securely and easily encrypt and decrypt data.
+
+## Features
+
+- Multiple secrets providers support (currently _Rails credentials_ and _env variables_).
+- Simple, purpose-based encryption/decryption API.
+- Configurable encryption cipher.
+- Minimal configuration required.
+- Built-in encryption signatures to ensure data integrity.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+  - [Secrets Provider Configuration](#secrets-provider-configuration)
+  - [Encrypting Data](#encrypting-data)
+  - [Decrypting Data](#decrypting-data)
+  - [Dynamic Method Calls](#dynamic-method-calls)
+  - [Error Handling](#error-handling)
+  - [Customizing the Cipher](#customizing-the-cipher)
+- [Advanced Topics](#advanced-topics)
+  - [Message Expiration](#message-expiration)
+  - [Performance Considerations](#performance-considerations)
+  - [Security Best Practices](#security-best-practices)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code of Conduct](#code-of-Conduct)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'easy_crypt'
+```
+
+Then execute:
+
+```ruby
+bundle install
+```
+
+Or install it yourself:
+
+```ruby
+gem install easy_crypt
+```
+
+## Configuration
+
+Create an initializer in your Rails application (e.g., `config/initializers/easy_crypt.rb`).
+Configure EasyCrypt to specify how secrets are stored and which cipher to use:
+
+```ruby
+EasyCrypt.configure do |config|
+  # Choose your secrets provider. Currently supports :rails_credentials or :env_vars
+  # Default is :rails_credentials
+  config.secrets_provider = :rails_credentials
+
+  # Set your default cipher
+  # Default is identical to ActiveSupport::MessageEncryptor.default_cipher,
+  # commonly 'aes-256-gcm' or 'aes-256-cbc', depending on your Rails configuration
+  config.default_cipher = 'aes-256-gcm'
+end
+```
+
+## Usage
+
+EasyCrypt expects you to define secrets for multiple "purposes". This means that if you’re encrypting user data, you can set up one pair of secret and salt for the "user_data" purpose. If you’re encrypting tokens for session authentication, you might use the "authentication" purpose with a different pair of secret and salt, and so on.
+
+### Secrets Provider Configuration
+
+EasyCrypt currently supports two types of secrets providers: environment variables (`:env_vars`) and Rails credentials (`:rails_credentials`).
+
+#### Using Rails Credentials
+
+With Rails credentials, you can define secrets for each purpose in `config/credentials.yml.enc`:
+
+```yaml
+easy_crypt:
+  authentication:
+    salt: "auth-salt"
+    secret: "auth-secret"
+  user_data:
+    salt: "user-data-salt"
+    secret: "user-data-secret"
+```
+
+This structure allows you to define multiple purposes under the `easy_crypt` key, each with its own `salt` and `secret`. EasyCrypt will automatically retrieve the corresponding values when encrypting or decrypting using the corresponding purpose.
+
+The example above defines "authentication" and "user_data" purpose, but you are free to pick the names that make sense for the purposes you need, as long as you follow the same structure.
+
+#### Using Environment Variables
+
+If you prefer using environment variables, define the salt and secret for each purpose in your `.env` file or directly in the environment. The format is:
+
+```env
+EASY_CRYPT_<PURPOSE>_SALT=your-salt
+EASY_CRYPT_<PURPOSE>_SECRET=your-secret
+```
+
+For example:
+
+```env
+EASY_CRYPT_AUTHENTICATION_SALT=auth-salt
+EASY_CRYPT_AUTHENTICATION_SECRET=auth-secret
+EASY_CRYPT_USER_DATA_SALT=user-data-salt
+EASY_CRYPT_USER_DATA_SECRET=user-data-secret
+```
+
+You can then encrypt or decrypt data for these purposes.
+
+### Encrypting Data
+
+To encrypt a piece of data with the "user_data" purpose:
+
+```ruby
+encrypted_value = EasyCrypt.encrypt_user_data("Sensitive Information")
+```
+
+Internally, EasyCrypt automatically retrieves the secret and salt for the "user_data" purpose, using your configured secrets provider. It uses `ActiveSupport::MessageEncryptor` to encrypt and sign the data.
+
+### Decrypting Data
+
+To decrypt the data you just encrypted, call:
+
+```ruby
+decrypted_value = EasyCrypt.decrypt_user_data(encrypted_value)
+
+if decrypted_value
+  puts "Decrypted successfully: #{decrypted_value}"
+else
+  puts "Invalid or expired data."
+end
+```
+
+If anything goes wrong in the decryption process (e.g., invalid signature or message expiration when using time-based encryption), EasyCrypt returns `nil` rather than raising an exception.
+
+### Dynamic Method Calls
+
+EasyCrypt uses `method_missing` to allow dynamic encrypt/decrypt methods for different purposes, following this pattern:
+
+```ruby
+encrypt_<purpose>
+decrypt_<purpose>
+```
+
+For example, if you want data to be encrypted with a "passwords" purpose:
+
+```ruby
+encrypted_pw = EasyCrypt.encrypt_passwords("super_secret")
+decrypted_pw = EasyCrypt.decrypt_passwords(encrypted_pw)
+```
+
+Given that you have properly defined the secret and salt for the "passwords" purpose in your secrets provider.
+
+### Error Handling
+
+When decryption fails (e.g., altered data or expired message), EasyCrypt returns `nil` to avoid exposing decryption errors.
+
+For method names that don't match the `encrypt_<purpose>` or `decrypt_<purpose>` naming pattern, a `NoMethodError` will be raised.
+
+If your secrets provider returns invalid or missing credentials, such as when `salt` or `secret` are missing, EasyCrypt raises a `MissingSecretsConfigurationError`.
+
+### Customizing the Cipher
+
+EasyCrypt uses by default the cipher returned by `ActiveSupport::MessageEncryptor.default_cipher`, which depends on your application configuration.
+
+You can override the gem’s default cipher through EasyCrypt configuration:
+
+```ruby
+EasyCrypt.configure do |config|
+  # Choose a different cipher if desired
+  config.default_cipher = 'aes-128-gcm'
+end
+```
+
+Secrets Providers can also specify cipher for a particular purpose.
+
+#### Using Rails Credentials
+
+In `config/credentials.yml.enc`:
+
+```yaml
+easy_crypt:
+  data_in_transit:
+    cipher: "aes-128-gcm"
+    salt: "auth-salt"
+    secret: "auth-secret"
+```
+
+Here, the `data_in_transit` purpose will use the `aes-128-gcm` cipher, overriding the default cipher.
+
+### Using Environment Variables
+
+You can set the cipher for a purpose using an environment variable:
+
+```env
+EASY_CRYPT_DATA_IN_TRANSIT_CIPHER=aes-128-gcm
+EASY_CRYPT_DATA_IN_TRANSIT_SALT=auth-salt
+EASY_CRYPT_DATA_IN_TRANSIT_SECRET=auth-secret
+```
+
+Here, the `data_in_transit` purpose will use the `aes-128-gcm` cipher, overriding the default cipher.
+
+## Advanced Topics
+
+### Message Expiration
+
+EasyCrypt supports passing `expires_at` or `expires_in` to the underlying `encrypt_and_sign` method as described in [Rails' documentation](ActiveSupport::MessageEncryptor.default_cipher). If provided, the data becomes invalid after that time:
+
+```ruby
+encrypted = EasyCrypt.encrypt_user_data("Sensitive Info", expires_in: 1.hour)
+```
+
+### Performance Considerations
+
+If you need to handle large data encryption, consider compressing it before calling the encrypt methods. Also, avoid redundant encryption in tight loops for better performance.
+
+### Security Best Practices
+
+This list is not exhaustive:
+
+- __Use Strong Algorithms__: Choose encryption methods wisely, AES-256 for symmetric and RSA-2048+ or elliptic curves for asymmetric encryption.
+- __Hashing for Validation__: Use secure hashing algorithms (e.g., bcrypt, Argon2) to validate secrets you don't need to store, like passwords.
+- __Sign for Integrity__: Sign data to prevent tampering (e.g., with RSA or ECDSA).
+- __Store Secrets Securely__: Use secret management tools (e.g., HashiCorp Vault).
+- __Rotate Secrets Periodically__: Regularly update keys and credentials to limit exposure.
+- __Avoid Exposing Secrets__: Never log sensitive information or hardcode secrets in code or repositories.
+- __Encrypt Everywhere__: Encrypt data at rest, in transit, and even on trusted networks.
+- __Rely on Proven Libraries__: Avoid building custom encryption; use trusted libraries (e.g., OpenSSL, EasyCrypt). Note: EasyCrypt uses OpenSSL under the hood.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/randoum/easy_crypt. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/randoum/easy_crypt/blob/main/CODE_OF_CONDUCT.md).
+
+Adding a rotation feature could be a good contribution, if you feel like doing so.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the EasyCrypt project's codebases and issue trackers is expected to follow the [code of conduct](https://github.com/randoum/easy_crypt/blob/main/CODE_OF_CONDUCT.md).

data/lib/easy_crypt/exception.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module EasyCrypt
+  # Exception raised when the requested secrets provider does not exist
+  class InvalidSecretsProvider < StandardError
+    def initialize(str)
+      super("Unknown secrets provider `#{str}`")
+    end
+  end
+
+  # Exception raised when secrets are missing for the requested purpose
+  class MissingSecretsConfigurationError < StandardError
+    def initialize(purpose, missing_attributes)
+      super("Missing required secret configuration for '#{purpose}': #{missing_attributes.join(', ')}")
+    end
+  end
+end

data/lib/easy_crypt/secrets_provider/base.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module EasyCrypt
+  class SecretsProvider
+    # Base class for all secret providers. Implements the interface that
+    # concrete providers must follow.
+    #
+    # This abstract base class defines the structure for secrets providers, including
+    # required methods for retrieving encryption configuration values such as `salt`,
+    # `secret`, and `cipher`. Subclasses are expected to implement these methods based
+    # on their respective sources (e.g., environment variables, Rails credentials).
+    #
+    # @abstract Subclass and override {#secret}, {#salt}, and {#cipher} to implement
+    #   a custom secrets provider.
+    class Base
+      # @return [Symbol] The purpose of the credential being accessed
+      attr_reader :purpose
+
+      # Initialize a new secrets provider
+      #
+      # @param purpose [Symbol] The purpose of the credential (e.g., :authentication)
+      def initialize(purpose)
+        @purpose = purpose
+      end
+
+      # Validates the presence of required attributes for the secrets provider.
+      #
+      # Checks if the attributes `salt`, and `secret` are defined.
+      # Raises a `MissingSecretsConfigurationError` error if any of these attributes are missing.
+      #
+      # @raise [MissingSecretsConfigurationError] If any required attribute is missing.
+      def validate_attributes!
+        missing_attributes = %w[salt secret].reject { |attr| send(attr) }
+        raise MissingSecretsConfigurationError.new(purpose, missing_attributes) if missing_attributes.any?
+      end
+
+      # Returns the encryption cipher.
+      #
+      # @abstract
+      # @return [String, nil] The encryption cipher.
+      # @raise [NotImplementedError] If not implemented in the subclass.
+      def cipher
+        raise NotImplementedError, 'Subclasses must implement #cipher'
+      end
+
+      # Returns the salt value for key generation
+      #
+      # @abstract
+      # @return [String] The salt value
+      # @raise [NotImplementedError] If the subclass doesn't implement this method
+      def salt
+        raise NotImplementedError, 'Subclasses must implement #salt'
+      end
+
+      # Returns the secret key for encryption
+      #
+      # @abstract
+      # @return [String] The secret key
+      # @raise [NotImplementedError] If the subclass doesn't implement this method
+      def secret
+        raise NotImplementedError, 'Subclasses must implement #secret'
+      end
+    end
+  end
+end

data/lib/easy_crypt/secrets_provider/env_provider.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module EasyCrypt
+  class SecretsProvider
+    # Provider that fetches encryption configuration from environment variables
+    #
+    # Multiple credential purposes can be configured using environment variables.
+    # Each credential purpose requires three environment variables following this pattern:
+    #
+    # EASY_CRYPT_[PURPOSE]_CIPHER   - (optional) Cipher to use for the encryption
+    #                                 falls back to EasyCrypt.default_cipher is not set
+    # EASY_CRYPT_[PURPOSE]_SALT     - Salt value for the encryption
+    # EASY_CRYPT_[PURPOSE]_SECRET   - Secret key for the encryption
+    #
+    # Where [PURPOSE] is the uppercase version of the credential purpose
+    #
+    # @example Using authentication credentials
+    #   # In .env file or environment:
+    #   EASY_CRYPT_AUTHENTICATION_CIPHER=aes128
+    #   EASY_CRYPT_AUTHENTICATION_SALT=your-salt-value
+    #   EASY_CRYPT_AUTHENTICATION_SECRET=your-secret-key
+    #
+    #   provider = EnvProvider.new(:authentication)
+    #   provider.cipher  #=> "aes128"
+    #   provider.salt    #=> "your-salt-value"
+    #   provider.secret  #=> "your-secret-key"
+    #
+    # @example Using user_data credentials
+    #   # In .env file or environment:
+    #   EASY_CRYPT_USER_DATA_SALT=different-salt
+    #   EASY_CRYPT_USER_DATA_SECRET=different-secret
+    #
+    #   provider = EnvProvider.new(:user_data)
+    #   provider.cipher  #=> nil
+    #   provider.salt    #=> "different-salt"
+    #   provider.secret  #=> "different-secret"
+    #
+    # You can set these variables in your .env file:
+    #   echo "EASY_CRYPT_AUTHENTICATION_CIPHER=aes128" >> .env
+    #   echo "EASY_CRYPT_AUTHENTICATION_SALT=your-salt" >> .env
+    #   echo "EASY_CRYPT_AUTHENTICATION_SECRET=your-secret" >> .env
+    #
+    # Or export them directly in your environment:
+    #   export EASY_CRYPT_AUTHENTICATION_CIPHER=aes128
+    #   export EASY_CRYPT_AUTHENTICATION_SALT=your-salt
+    #   export EASY_CRYPT_AUTHENTICATION_SECRET=your-secret
+    class EnvProvider < Base
+      # @return [String, nil] The encryption cipher from environment variable
+      def cipher
+        credentials('CIPHER')
+      end
+
+      # @return [String, nil] The salt value from environment variable
+      def salt
+        credentials('SALT')
+      end
+
+      # @return [String, nil] The secret key from environment variable
+      def secret
+        credentials('SECRET')
+      end
+
+      private
+
+      def credentials(key)
+        ENV.fetch("EASY_CRYPT_#{purpose.to_s.upcase}_#{key}", nil)
+      end
+    end
+  end
+end

data/lib/easy_crypt/secrets_provider/rails_credentials_provider.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module EasyCrypt
+  class SecretsProvider
+    # Provider that fetches encryption configuration from Rails credentials
+    #
+    # Configuration should be structured in credentials.yml.enc as:
+    #
+    # easy_crypt:                     # EasyCrypt purposes configuration parent key
+    #   authentication:               # Credential for the "authentication" purpose
+    #     cipher: "aes128"            # (optional) Cipher to use for the encryption
+    #                                 #   falls back to EasyCrypt.default_cipher is not set
+    #     salt: "your-salt-value"     # Salt value for the encryption
+    #     secret: "your-secret-key"   # Secret key for the encryption
+    #   user_data:                    # Credential for the "user data" purpose
+    #     salt: "different-salt"      # Salt value for the encryption
+    #     secret: "different-secret"  # Secret key for the encryption
+    #
+    # You can define multiple credential purposes under the `easy_crypt` namespace,
+    # each with its own configuration. The credential purpose is specified when
+    # initializing the provider.
+    #
+    # To edit credentials.yml.enc, you can use one of these commands:
+    #
+    # With Visual Studio Code:
+    #   EDITOR="code --wait" bin/rails credentials:edit
+    #
+    # With Vim:
+    #   EDITOR="vim" bin/rails credentials:edit
+    #
+    # With Sublime Text:
+    #   EDITOR="subl --wait" bin/rails credentials:edit
+    #
+    # With Nano:
+    #   EDITOR="nano" bin/rails credentials:edit
+    #
+    # @example Configuration in credentials.yml.enc
+    #   easy_crypt:
+    #     authentication:
+    #       cipher: aes128
+    #       salt: "salt for the authentication purpose"
+    #       secret: "secret for the authentication purpose"
+    #     user_data:
+    #       salt: "different-salt"
+    #       secret: "different-secret"
+    #
+    # @example Accessing credentials
+    #   # Using authentication credentials
+    #   provider = RailsCredentialsProvider.new(:authentication)
+    #   provider.cipher  #=> "aes128"
+    #   provider.salt    #=> "salt for the authentication purpose"
+    #   provider.secret  #=> "secret for the authentication purpose"
+    #
+    #   # Using user_data credentials
+    #   provider = RailsCredentialsProvider.new(:user_data)
+    #   provider.cipher  #=> nil
+    #   provider.salt    #=> "different-salt"
+    #   provider.secret  #=> "different-secret"
+    class RailsCredentialsProvider < Base
+      # @return [String, nil] The encryption cipher from Rails credentials
+      def cipher
+        credentials&.cipher
+      end
+
+      # @return [String] The salt value from Rails credentials
+      def salt
+        credentials&.salt
+      end
+
+      # @return [String] The secret key from Rails credentials
+      def secret
+        credentials&.secret
+      end
+
+      private
+
+      def credentials
+        Rails.application.credentials.easy_crypt[purpose]
+      end
+    end
+  end
+end

data/lib/easy_crypt/secrets_provider.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'secrets_provider/base'
+require_relative 'secrets_provider/env_provider'
+require_relative 'secrets_provider/rails_credentials_provider'
+
+module EasyCrypt
+  # The SecretsProvider class serves as a factory for creating secret providers
+  # that supply encryption configuration values from different sources.
+  #
+  # @example Creating a provider for Rails credentials and for the authentication purpose
+  #   provider = SecretsProvider.build(:rails_credentials, :authentication)
+  #
+  # @example Creating a provider for environment variables and for the user_data purpose
+  #   provider = SecretsProvider.build(:env_vars, :user_data)
+  class SecretsProvider
+    # Available secrets providers and their corresponding classes
+    PROVIDERS = {
+      env_vars: EnvProvider,
+      rails_credentials: RailsCredentialsProvider
+    }.freeze
+
+    # Builds a new secrets provider instance based on the specified provider
+    #
+    # This method acts as a factory for instantiating a secrets provider that fetches
+    # encryption configurations (e.g., secret keys, salts) for a given purpose from
+    # the selected source. The method ensures the specified provider exists and validates
+    # the configuration values.
+    #
+    # @param provider [Symbol] The secrets provider to use (:env_vars or :rails_credentials).
+    #   - `:env_vars`: To fetch secrets from environment variables.
+    #   - `:rails_credentials`: To fetch secrets from Rails credentials.
+    # @param purpose [Symbol] The purpose of the credential (e.g., :authentication, :user_data).
+    #   This links the encryption secrets to a set of credentials (such as secret key and salt).
+    #
+    # @example Building a provider for Rails credentials with the `authentication` purpose
+    #   provider = SecretsProvider.build(:rails_credentials, :authentication)
+    #
+    # @example Building a provider for environment variables with the `user_data` purpose
+    #   provider = SecretsProvider.build(:env_vars, :user_data)
+    #
+    # @raise [InvalidSecretsProvider] If the specified secrets provider is not recognized.
+    #
+    # @return [Base] An instance of the appropriate provider class.
+    def self.build(provider, purpose)
+      provider = PROVIDERS
+        .fetch(provider.to_sym) { raise InvalidSecretsProvider, provider }
+        .new(purpose)
+      provider.validate_attributes!
+      provider
+    end
+  end
+end

data/lib/easy_crypt/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EasyCrypt
+  VERSION = '1.0.0'
+end

data/lib/easy_crypt.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require 'rails'
+require 'active_support/message_encryptor'
+require 'active_support/key_generator'
+
+require_relative 'easy_crypt/exception'
+require_relative 'easy_crypt/secrets_provider'
+
+# EasyCrypt
+# =========
+#
+# EasyCrypt is a Ruby utility that provides secure and flexible encryption/decryption capabilities
+# for Ruby on Rails applications.
+#
+# Features
+# --------
+# * Multiple secrets providers support (environment variables and Rails credentials)
+# * Configurable encryption cipher
+# * Purpose-based encryption/decryption
+# * Built on top of Rails' ActiveSupport::MessageEncryptor
+# * Simple and intuitive API
+#
+# Installation
+# ------------
+# Add this line to your application's Gemfile:
+#     gem 'easy_crypt'
+#
+# Then execute:
+#     $ bundle install
+#
+# Or install it yourself as:
+#     $ gem install easy_crypt
+#
+# Configuration
+# -------------
+#
+# Create an initializer at config/initializers/easy_crypt.rb:
+#
+# ```ruby
+# EasyCrypt.configure do |config|
+#   # Choose your secrets provider. Currently supports :rails_credentials or :env_vars.
+#   # Default to :rails_credentials
+#   config.secrets_provider = :rails_credentials
+#
+#   # Set your default cipher (optional)
+#   # Default to `ActiveSupport::MessageEncryptor.default_cipher` which is set to
+#   # 'aes-256-gcm' or 'aes-256-cbc' as of now, depending on your application configuration.
+#   # See `use_authenticated_message_encryption` configuration option for more information.
+#   # See `OpenSSL::Cipher.ciphers` for a list of accepted values.
+#   config.default_cipher = 'aes-256-gcm'
+# end
+#
+# Usage
+# ---
+#
+# First, you need to configure a secret and a salt for a specific purpose.
+# To do so, you'll need to use one of the supported secrets providers (currently
+# Rails credentials and env vars) and define a purpose and its credentials.
+#
+# See `EasyCrypt::SecretsProvider` subclasses for more information on how
+# to configure the secrets provider of your choice.
+#
+# Given that you provided a secret and a salt for the "user_data" purpose,
+# you are able to call the `encrypt_user_data` and `decrypt_user_data` methods
+# to directly use the credentials of the "user_data" purpose.
+#
+# ```ruby
+# # Encrypt a value
+# encrypted = EasyCrypt.encrypt_user_data("sensitive information")
+#
+# # Decrypt a value
+# decrypted = EasyCrypt.decrypt_user_data(encrypted)
+# ```
+#
+module EasyCrypt
+  # @return [String] The default cipher used for encryption/decryption operations
+  @default_cipher = ActiveSupport::MessageEncryptor.default_cipher
+
+  # @return [Symbol] The provider used for retrieving encryption secrets
+  @secrets_provider = :rails_credentials
+
+  class << self
+    attr_accessor :default_cipher, :secrets_provider
+
+    # Configures the EasyCrypt module with custom settings
+    #
+    # @example
+    #   EasyCrypt.configure do |config|
+    #     config.secrets_provider = :env_vars
+    #     config.default_cipher = 'aes-128-gcm'
+    #   end
+    #
+    # @yieldparam config [EasyCrypt] The configuration object
+    # @return [void]
+    def configure
+      yield self
+    end
+
+    # Handles dynamic encryption/decryption method calls
+    #
+    # This method allows dynamically calling encryption or decryption methods for specific purposes
+    # by embedding the purpose directly in the method name. The pattern for such method names is:
+    # `encrypt_<purpose>` for encryption and `decrypt_<purpose>` for decryption.
+    #
+    # For instance:
+    # - Calling `EasyCrypt.encrypt_authentication(value)` will encrypt the provided value using the
+    #   credentials configured for the `authentication` purpose.
+    # - Calling `EasyCrypt.decrypt_user_data(encrypted_value)` will decrypt the given value using the
+    #   credentials for the `user_data` purpose.
+    #
+    # This dynamic approach enables simple and intuitive APIs without requiring explicit method
+    # definitions for each purpose.
+    #
+    # @example Encrypting a value for the "authentication" purpose
+    #   encrypted = EasyCrypt.encrypt_authentication("my_secret_data")
+    #
+    # @example Decrypting a value for the "user_data" purpose
+    #   decrypted = EasyCrypt.decrypt_user_data(encrypted_data)
+    #
+    # @note If the method name does not match the expected pattern, `method_missing` will defer to
+    #   the superclass implementation, raising a `NoMethodError` if the method is undefined.
+    #
+    # @return [Object, String, nil] The encrypted or decrypted value, or nil if decryption fails
+    def method_missing(method_name, *args)
+      if /^(?<action>encrypt|decrypt)_(?<purpose>[a-z_]+)$/ =~ method_name
+        send(action, *args.unshift(purpose.to_sym))
+      else
+        super
+      end
+    end
+
+    # Checks if a method is supported by the module
+    def respond_to_missing?(method_name, include_private)
+      /^(encrypt|decrypt)_[a-z_]+$/ =~ method_name || super
+    end
+
+    private
+
+    # Encrypts and signs a value for a specific purpose
+    #
+    # @param purpose [Symbol] The purpose for which the value is being encrypted, e.g., :user_data
+    # @param value [Object] The value to encrypt (must be serializable)
+    # @param options [Hash] Additional options for encryption
+    #
+    # @example Encrypting a value for the "user_data" purpose
+    #   EasyCrypt.encrypt_user_data("sensitive information")
+    #
+    # @return [String] The encrypted and signed value
+    def encrypt(purpose, value, options = {})
+      options.merge!(purpose: purpose)
+      encryptor(purpose).encrypt_and_sign(value, **options)
+    end
+
+    # Decrypts a value that was encrypted for a specific purpose
+    #
+    # @param purpose [Symbol] The purpose for which the value was encrypted, e.g., :user_data
+    # @param encrypted_data [String] The encrypted data to decrypt
+    #
+    # @example Decrypting a value for the "user_data" purpose
+    #   EasyCrypt.decrypt_user_data(encrypted_value)
+    #
+    # @return [Object, nil] The decrypted value, or nil if decryption fails
+    def decrypt(purpose, encrypted_data)
+      encryptor(purpose).decrypt_and_verify(encrypted_data, purpose: purpose)
+    rescue ActiveSupport::MessageEncryptor::InvalidMessage
+      nil
+    end
+
+    # Creates a new MessageEncryptor instance for a specific purpose
+    #
+    # @param purpose [Symbol] The purpose for which to create the encryptor, e.g., :user_data
+    #
+    # @example Creating an encryptor configured for the "user_data" purpose
+    #   encryptor = EasyCrypt.send(:encryptor, :user_data)
+    #
+    # @return [ActiveSupport::MessageEncryptor] The configured encryptor instance
+    def encryptor(purpose)
+      provider = SecretsProvider.build(secrets_provider, purpose)
+
+      cipher = provider.cipher || default_cipher
+
+      len = ActiveSupport::MessageEncryptor.key_len(cipher)
+      key = ActiveSupport::KeyGenerator.new(provider.secret).generate_key(provider.salt, len)
+      ActiveSupport::MessageEncryptor.new(key, cipher: cipher)
+    end
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: easy_crypt
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Benjamin Bouchet
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-01-27 00:00:00.000000000 Z
+dependencies: []
+description: |2-
+
+      Encryption and decryption for Rails applications, based on ActiveSupport::MessageEncryptor, using
+      multiple secrets providers, and defining a simple, purpose-based encryption/decryption API.
+email: randoum@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- lib/easy_crypt.rb
+- lib/easy_crypt/exception.rb
+- lib/easy_crypt/secrets_provider.rb
+- lib/easy_crypt/secrets_provider/base.rb
+- lib/easy_crypt/secrets_provider/env_provider.rb
+- lib/easy_crypt/secrets_provider/rails_credentials_provider.rb
+- lib/easy_crypt/version.rb
+homepage: https://github.com/randoum/easy_crypt
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/randoum/easy_crypt
+  documentation_uri: https://rubydoc.info/github/randoum/easy_crypt
+  changelog_uri: https://github.com/randoum/easy_crypt/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/randoum/easy_crypt
+  bug_tracker_uri: https://github.com/randoum/easy_crypt/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.8.11
+requirements: []
+rubygems_version: 3.1.2
+signing_key:
+specification_version: 4
+summary: Secure and flexible encryption for Ruby on Rails applications.
+test_files: []