Key provides the ability to manage keys, which can be employed by other
modules. It gives site administrators the ability to define how and
where keys are stored, which allows the option of a high level of
security and allows sites to meet regulatory or compliance
requirements.
Examples of the types of keys that could be managed with Key are:
- A password or API key for connecting to an external service, such as
PayPal, MailChimp, Authorize.net, UPS, an SMTP mail server, or Amazon
Web Services - A key used for encrypting data
Installation
Install Key using a standard method for installing a contributed Backdrop
module.
Configuration
Key provides an administration page where users with the "administer
keys" permission can add, edit, and delete keys.
Key type
A key type can be selected for a key in order to indicate the purpose
of the key. The following key types are included with Key:
- Authentication: A generic key type to use for a password or API
key that does not belong to any other defined key type. This is the
default. - Encryption: Can be used for encrypting and decrypting data. This
key type has a field for selecting a key size, which is used to
validate the size of the key value. By default the encryption key value is
generated automatically. If you wish to use a pre-existing key value, see the section on "Generating a Random Encryption Key".
Key types are plugins, so new types can be defined easily.
Key provider
A key provider is the means by which the key value is stored and/or
provided when needed. The following key providers are included with
Key:
Configuration: Stores the key in Backdrop configuration settings.
The key value can be set, edited, and viewed through the administrative
interface, making it useful during site development. There are ways to make this
relatively more secure by putting configuration directories outside the webroot.
And ensure that any configuration backups or version control artifacts are
protected.
However, for better security on production websites, keys should generally not
be stored in configuration. Keys using the Configuration provider are not obscured
when editing, making it even more important that this provider not be
used in a production environment.
File: Stores the key in a file, which will be created in the Private file
system path. This is the most secure option outside of using a cloud service. If
needing to reference a pre-existing file, use the commandline bee key-save
instead, so as long as it's readable by the user that runs the web server.
For more info, use the command bee key-save --help.
Settings: The settings key provider allows a key to be retrieved from the
Backdrop settings file
which usually resides in the webroot or in sites/*/default. The variable should
be in this format: $settings['my_private_key'] = '';.
State: The State key provider uses a key stored in the Backdrop state system.
The state system stores values in the database, so keys stored this way should be
considered to have the same security properties as database-stored configuration.
This provider is suitable for development keys, API tokens with limited permissions,
or other keys where database storage is acceptable. Meant to be used with a state
variable set by another module, or with the commandline tool, Bee.
Environment: References a key in an environment variable. Some hosts provide
a UI for setting environment variables which are available during runtime. Some
local development tools, such as Lando, also allow setting environment variables.
Another approach is to put the keys in a .env file. This will require some
more advanced technical skills. You'll then need to install the
Symfony Dotenv package using Composer:
composer require symfony/dotenv
and then putting this into
settings.php:
include __DIR__ . '/../vendor/autoload.php'; use Symfony\Component\Dotenv\Dotenv; (new Dotenv())->usePutenv()->bootEnv(BACKDROP_ROOT . '/../.env', 'dev', ['test'], TRUE);
Key providers are plugins, so new providers can be defined easily.
Base64 encoding
The provider plugins support storing and retrieving the key with Base64 encoding.
Base64 is used here to encode arbitrary bytes which are known to be safe to send
without getting corrupted.
Strip line breaks
Some of the provider plugins support removing any trailing line breaks from the
key value. This option only affects retrieving the value and not when saving.
About key input
When adding or editing a key, if the selected key provider accepts a
key value, a key input is automatically selected, as defined by the key
type, in order to submit a key value. The following key inputs are
included with Key:
- None: This input is used by default when the selected key
provider does not accept a key value. The File key provider uses this
input. - Text Field: This input provides a basic text field for submitting
a key value. The Configuration key provider uses this input. - Textarea Field: This input is the same as the text field input,
except it uses a textarea HTML element, so it's useful for longer keys,
such as SSH keys. - Generated: This input generates a key value automatically based on the
provider's criteria.
The Text Field, Textarea Field and Generated input plugins support the submission
of keys that are Base64-encoded.
Key inputs are plugins, so new inputs can be defined easily.
Integrating Modules
The following modules have not been ported to Backdrop at this time, but allow
keys to be stored on a designated external key management server:
For Developers
Integrate with other modules
Creating a key will have no effect unless another module makes use of
it. That integration would typically present itself to the end user in
the form of a field that lists available keys and allows the user to
choose one. This could appear, for instance, on the integrating
module's configuration page.
Modules can add a key field to a form using the key_select API element,
which behaves like a select element, but is populated with available
keys as options.
$form['secret_key'] = array( '#type' => 'key_select', '#title' => t('Secret key'), );
There are a couple of additional properties that can be used:
-
#key_filtersAn array of filters to apply to the list of keys.
Currently, filtering is quite basic, though it will be improved. You can
filter on key type and/or key provider. Examples:#key_filters = ['type' => 'mailchimp']This would only display
MailChimp keys.#key_filters = ['provider' => 'file']This would only display keys
that use the File key provider.#key_filters = ['type' => 'mailchimp', 'provider' => 'file']
This would only display MailChimp keys that use the File key provider.
-
#key_descriptionThis is a boolean value that determines if information
about keys is added to the element's description. It is TRUE by default
and it prepends the description with the following text (with a link to
the add key form), which can be disabled by setting #key_description to
FALSE:Choose an available key. If the desired key is not listed, create a new
key.
Modules can retrieve configuration for all keys, configuration for a specific
key or the value of a specific key:
Get all key configurations
key_get_keys()
Get a specific key configuration
key_get_key($key_id)
Get a specific key value
key_get_key_value($key_id)
Generating a custom Encryption Key
The default encryption key size is 256 bits, with 8 bits per byte. For example,
a string like 12345678901234567890123456789012 has 32 characters/bytes or 256
bits. There is also an option for specifying if the key was Base64-encoded.
By default, encryption keys will be generated automatically based on the selected
key size. Though if you wish to manually generate a key, one way is to use an
online service to generate one that matches the number of bits, and optionally,
also base64 encode it.
Another way is to create a key file by entering the commands in a Unix
environment. To output to the screen:
cat /dev/urandom | head -c 32
This will display a random 256-bit key. For a 128-bit key, change the 32 to 16
in the command. For simplification, consider the "bs" (byte) to equal a character.
Or base64 encode it:
cat /dev/urandom | head -c 32 | base64 -i
Or create binary file (changing the path and file name to suit your needs):
dd if=/dev/urandom bs=32 count=1 > /path/to/secret.key
To use base64 encoding when generating the key, use:
dd if=/dev/urandom bs=32 count=1 | base64 -i - > path/to/secret.key
License
This project is GPL v2 software. See the LICENSE.txt file in this directory for
complete text.
Maintainers
Credits
Ported to Backdrop by Herb v/d Dool and
Justin Keiser.
Drupal version currently maintained by: