一个用于轻松集成 Vault 秘密的 Rails 插件
Vault is the official Rails plugin for interacting with Vault by HashiCorp.
If you're viewing this README from GitHub on the master branch, know that it may contain unreleased features or
different APIs than the most recently released version. Please see the Git tag that corresponds to your version of the
Vault Rails plugin for the proper documentation.
Add to your Gemfile:
gem "vault-rails", require: false and then run the bundle command to install.
Create an initializer:
…For more customization, such as custom SSL certificates, please see the
[Vault Ruby documentation](https://github.com/hashicorp/vault-ruby).Add Vault to the model you want to encrypt:
class Person true
person.ssn_encrypted #=> "vault:v0:EE3EV8P5hyo9h..."ssn in the case above)The following section details some of the more advanced configuration options for vault-rails. As a general rule, you should try to use vault-rails without these options until absolutely necessary.
By default, the name of the encrypted column is #{column}_encrypted. This is customizable by setting the :encrypted_column option when declaring the attribute:
vault_attribute :credit_card,
encrypted_column: :cc_encryptedBy default, the name of the key in Vault is #{app}_#{table}_#{attribute}. This is customizable by setting the :key option when declaring the attribute:
vault_attribute :credit_card,
key: "pci-data"Vault Transit supports key derivation, which allows the same key to be used for multiple purposes by deriving a new key based on a context value.
The context can be specified as a string, symbol, or proc. Symbols (an instance method on the model) and procs are called for each encryption or decryption request, and should return a string.
With a string, all records will use the same context for this attribute:
vault_attribute :credit_card,
context: "user-cc"When using a symbol, a method will be called on the record to compute the context:
belongs_to :user
vault_attribute :credit_card,
context: :encryption_context
def encryption_context
"user_#{user.id}"
endGiven a proc, it will be called each time to compute the context:
belongs_to :user
vault_attribute :credit_card,
context: ->(record) { "user_#{record.user.id}" }The proc must take a single argument for the record.
An attribute can specify a default value, which will be set on initialization (.new) or after loading the value from the database. The default will be set if the value is nil.
vault_attribute :access_level,
default: "readonly"
vault_attribute :metadata,
serialize: :json,
default: {}By default, the path to the transit backend in Vault is transit/. This is customizable by setting the :path option when declaring the attribute:
vault_attribute :credit_card,
path: "transport"By default, vault-rails will decrypt a record’s encrypted attributes on that record’s initialization. You can configure an encrypted model to decrypt attributes lazily, which will prevent communication with Vault until an encrypted attribute’s getter method is called, at which point all of the record’s encrypted attributes will be decrypted. This is useful if you do not always need access to encrypted attributes. For example:
class Person "123-45-6789"
# With vault_lazy_decrypt:
person = Person.find(id)
person.ssn # Vault communication happens here
# => "123-45-6789"By default, vault-rails will decrypt all encrypted attributes on that record’s initialization on a class by class basis. You can configure an encrypted model to decrypt attributes lazily and and individually. This will prevent vault from loading all vault_attributes defined on a class the moment one attribute is requested.
class Person "123-45-6789"
# With vault_single_decrypt:
person = Person.find(id)
person.ssn # Vault communication happens here, fetches only ssn
# => "123-45-6789"
person.email # Vault communication happens here, fetches only email
# => "foobar@baz.com"By default, all values are assumed to be "text" fields in the database. Sometimes it is beneficial for your application to work with a more flexible data structure (such as a Hash or Array). Vault-rails can automatically serialize and deserialize these structures for you:
vault_attribute :details,
serialize: :json,
default: {}It is recommended to set a default matching type that you're serializing.
For customized solutions, you can also pass a module to the :serializer key. This module must have the following API:
module MySerializer
# @param [String, nil] raw
# @return [String, nil]
def self.encode(raw); end
# @param [String, nil] raw
# @return [String, nil]
def self.decode(raw); end
endYour class must account for nil and "empty" values if necessary. Then specify the class as the serializer:
vault_attribute :details,
serialize: MySerializerIf a custom serializer seems too heavy, you can declare an :encode and :decode proc when declaring the attribute. Both options must be given:
vault_attribute :address,
encode: ->(raw) { raw.to_s.upcase },
decode: ->(raw) { raw.to_s }The Vault Rails plugin does not automatically mount a backend. It is assumed the proper backend is mounted and accessible by the given token. You can mount a transit backend like this:
$ vault mount transitIf you are running Vault 0.2.0 or later, the Vault Rails plugin will automatically create keys in the transit backend if it has permission. Here is an example policy to grant permissions:
# Allow renewal of leases for secrets
path "sys/renew/*" {
policy = "write"
}
# Allow renewal of token leases
path "auth/token/renew/*" {
policy = "write"
}
path "transit/encrypt/myapp_*" {
policy = "write"
}
path "transit/decrypt/myapp_*" {
policy = "write"
}Note that you will need to have an out-of-band process to renew your Vault token.
For lower versions of Vault, the Vault Rails plugin does not automatically create transit keys in Vault. Instead, you should create keys for each column you plan to encrypt using a different policy, out-of-band from the Rails application. For example:
$ vault write transit/keys/ create=1Unless customized, the name of the key will always be:
__So for the example above, the key would be:
my_app_people_ssnNormally, vault-rails will wait until the after_save callback to encrypt changed
values before updating them. If you'd like to encrypt changed attributes without
saving, call vault_encrypt_attributes!
p = Person.new(ssn: "123-45-6789")
p.ssn_encrypted
=> nil
p.vault_encrypt_attributes!
p.ssn_encrypted
=> "vault:dev:flu/yp9oeYYFgjcZH2hVBA=="
p.persisted?
=> falseBecause each column is uniquely encrypted, it is not possible to search for a
particular plain-text value. For example, if the ssn attribute is encrypted,
the following will NOT work:
Person.where(ssn: "123-45-6789")This is because the database is unaware of the plain-text data (which is part of the security model).
Important Notes:
暂无开放 Issues,或尚未同步最近议题。