Concepts and Terminology

Using keys

There are two ways other modules can make use of the Key mode.

Direct Integration

Direct integration would typically present itself to the end user in the form of a select field that lists available keys and allows the user to choose one. This could appear, for instance, on the integrating module's configuration page.

Overriding Configuration

The Drupal 8 version of Key provides the ability to override any configuration value with a key. This allows site administrators to store configuration values in a more secure method than in the database or in settings.php.

Key configuration overrides can be created at /admin/config/development/configuration/key-overrides/add.

• Enter a name for the override
• Select the specific configuration item you wish to override
• Select an existing key that provides the value to be used; if the key doesn't exist, you'll need to create it
• Check "Clear overridden value" to clear any existing value for the overridden configuration item; this is important to make sure potentially sensitive data is removed from the configuration; if for some reason, you don't want to clear the value, uncheck this field
• Click "Save"

Key types

A key type can be selected for a key in order to indicate the purpose of the key. Key types are responsible for the following:

• Filtering: A list of keys, in a select field for instance, can be filtered to only include keys of a certain type. (Example: a module that performs encryption could limit a list to only include keys flagged with the "Encryption" key type.)
• Validation: A key type can provide validation on form submission to insure that the key value meets certain requirements. (Example: a module that performs encryption could validate that a key value is the proper length for the encryption algorithm being used.)
• Generation: A key type can provide the ability to generate a key of that type. (Example: a module that performs encryption could generate a random key of the required length.)
• Value Input: A key type can indicate which input method should be used for submitting a key value, if the selected Key Provider accepts a key value.

Key includes four key types:

• 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.
• Authentication (Multivalue): A generic key type to use for an authentication key that contains multiple values. The value of this key must be a JSON object representing desired key/value pairs.
• User/password: A key type to store a user/password pair. This is an extension of the Authentication (Multivalue) key type that enforces the presence of the keys username and password in the JSON object.
• Encryption: A generic key type to use for an encryption key that does not belong to any other defined key type. This key type has a field for the user to select a key size. The key size is validated based on the selection.

Key types are native Drupal 8 plugins so new types can easily be defined.

Key providers

A key provider is the means by which the key value is stored and/or provided when needed. Key providers are responsible for the following:

• Getting Value: The key provider retrieves the key value.
• Value Input: A key provider can indicate that it can accept a key value for setting.
• Setting Value: If a key value is submitted, the key provider sets it.
• Obscuring Value: A key provider can perform alterations to the key value in order to obscure it when editing.
• Deleting Value: If a key is deleted or the key provider is changed, the provider can delete the key value.
• Filtering: A list of keys, in a select field for instance, can be filtered to only include keys that use a certain provider.

Key includes three key providers:

• Configuration: Stores the key value in Drupal configuration settings. The key value can be set, edited, and viewed through the administrative interface, making it useful during site development. However, for better security on production websites, keys should 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 value in a file, which can be anywhere in the file system, as long as it's readable by the user that runs the web server. Storing the key in a file outside of the web root is generally more secure than storing it in the database.
• Environment: Allows the key value to be stored in an environmental variable.

Key inputs

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. Key inputs are responsible for the following:

• Value Input: The key input defines the field (or fields) used to enter the key value.
• Processing Value: The key input processes the submitted value to prepare it, before it can be set by the key provider. The key value is also processed when a key is being edited, in order to prepare it for presentation to the user.

Key includes four key inputs:

• None: This input is used by default when the selected key provider does not accept a key value.
• Text Field: This input provides a basic text field for submitting a key value. The generic Authentication and Encryption key types use this key 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. The Authentication (Multivalue) and User/password key types use this key input.
• Generate: This input generates a key based on the selected key type and its settings.

The Text Field and Textarea Field input plugins support the submission of keys that are Base64-encoded.

Key inputs are native Drupal 8 plugins so new inputs can easily be defined.