diff --git a/guides/source/active_record_encryption.md b/guides/source/active_record_encryption.md index 5153df4eef093..006163264d47c 100644 --- a/guides/source/active_record_encryption.md +++ b/guides/source/active_record_encryption.md @@ -407,30 +407,53 @@ article.encrypted_attribute?(:title) You can configure Active Record Encryption options in your `application.rb` (most common scenario) or in a specific environment config file `config/environments/.rb` if you want to set them on a per-environment basis. -All the config options are namespaced in `active_record.encryption.config`. For example: +WARNING: It's recommended to use Rails built-in credentials support to store keys. If you prefer to set them manually via config properties, make sure you don't commit them with your code (e.g. use environment variables). -```ruby -config.active_record.encryption.key_provider = ActiveRecord::Encryption::EnvelopeEncryptionKeyProvider.new -config.active_record.encryption.store_key_references = true -config.active_record.encryption.extend_queries = true -``` -The available config options are: - -| Key | Value | -| ------------------------------------------------------------ | ------------------------------------------------------------ | -| `support_unencrypted_data` | When true, unencrypted data can be read normally. When false, it will raise errors. Default: false. | -| `extend_queries` | When true, queries referencing deterministically encrypted attributes will be modified to include additional values if needed. Those additional values will be the clean version of the value (when `support_unencrypted_data` is true) and values encrypted with previous encryption schemes, if any (as provided with the `previous:` option). Default: false (experimental). | -| `encrypt_fixtures` | When true, encryptable attributes in fixtures will be automatically encrypted when loaded. Default: false. | -| `store_key_references` | When true, a reference to the encryption key is stored in the headers of the encrypted message. This makes for faster decryption when multiple keys are in use. Default: false. | -| `add_to_filter_parameters` | When true, encrypted attribute names are added automatically to the [list of filtered params](https://guides.rubyonrails.org/configuring.html#rails-general-configuration) and won't be shown in logs. Default: true. | -| `excluded_from_filter_parameters` | You can configure a list of params that won't be filtered out when `add_to_filter_parameters` is true. Default: []. | -| `validate_column_size` | Adds a validation based on the column size. This is recommended to prevent storing huge values using highly compressible payloads. Default: true. | -| `primary_key` | The key or lists of keys used to derive root data-encryption keys. The way they are used depends on the key provider configured. It's preferred to configure it via a credential `active_record_encryption.primary_key`. | -| `deterministic_key` | The key or list of keys used for deterministic encryption. It's preferred to configure it via a credential `active_record_encryption.deterministic_key`. | -| `key_derivation_salt` | The salt used when deriving keys. It's preferred to configure it via a credential `active_record_encryption.key_derivation_salt`. | -| `forced_encoding_for_deterministic_encryption` | The default encoding for attributes encrypted deterministically. You can disable forced encoding by setting this option to `nil`. It's `Encoding::UTF_8` by default. | - -NOTE: It's recommended to use Rails built-in credentials support to store keys. If you prefer to set them manually via config properties, make sure you don't commit them with your code (e.g. use environment variables). +#### `config.active_record.encryption.support_unencrypted_data` + +When true, unencrypted data can be read normally. When false, it will raise errors. Default: `false`. + +#### `config.active_record.encryption.extend_queries` + +When true, queries referencing deterministically encrypted attributes will be modified to include additional values if needed. Those additional values will be the clean version of the value (when `config.active_record.encryption.support_unencrypted_data` is true) and values encrypted with previous encryption schemes, if any (as provided with the `previous:` option). Default: `false` (experimental). + +#### `config.active_record.encryption.encrypt_fixtures` + +When true, encryptable attributes in fixtures will be automatically encrypted when loaded. Default: `false`. + +#### `config.active_record.encryption.store_key_references` + +When true, a reference to the encryption key is stored in the headers of the encrypted message. This makes for faster decryption when multiple keys are in use. Default: `false`. + +#### `config.active_record.encryption.add_to_filter_parameters` + +When true, encrypted attribute names are added automatically to [`config.filter_parameters`][] and won't be shown in logs. Default: `true`. + +[`config.filter_parameters`]: configuring.html#config-filter-parameters + +#### `config.active_record.encryption.excluded_from_filter_parameters` + +You can configure a list of params that won't be filtered out when `config.active_record.encryption.add_to_filter_parameters` is true. Default: `[]`. + +#### `config.active_record.encryption.validate_column_size` + +Adds a validation based on the column size. This is recommended to prevent storing huge values using highly compressible payloads. Default: `true`. + +#### `config.active_record.encryption.primary_key` + +The key or lists of keys used to derive root data-encryption keys. The way they are used depends on the key provider configured. It's preferred to configure it via the `active_record_encryption.primary_key` credential. + +#### `config.active_record.encryption.deterministic_key` + +The key or list of keys used for deterministic encryption. It's preferred to configure it via the `active_record_encryption.deterministic_key` credential. + +#### `config.active_record.encryption.key_derivation_salt` + +The salt used when deriving keys. It's preferred to configure it via the `active_record_encryption.key_derivation_salt` credential. + +#### `config.active_record.encryption.forced_encoding_for_deterministic_encryption` + +The default encoding for attributes encrypted deterministically. You can disable forced encoding by setting this option to `nil`. It's `Encoding::UTF_8` by default. ### Encryption Contexts