Skip to content
Snippets Groups Projects

Improve README example code

Merged Patrick Kenny requested to merge issue/encrypt-2764427:README_improve_example_code into 8.x-3.x
1 file
+ 30
22
Compare changes
  • Side-by-side
  • Inline
+ 30
22
# Encrypt Module for Drupal 8
This module provides a global encryption service that can be invoked via the
This module provides a global encryption service that can be invoked via the
services interface.
## Architecture
Encrypt leverages the Drupal 8 Plugin API for Encryption Methods. It also
leverages the Key module for maintenance of encryption Keys.
Encrypt leverages the Drupal 8 Plugin API for Encryption Methods. It also
leverages the Key module for maintenance of encryption Keys.
Plugins allow for extensibility for customized needs.
Plugins allow for extensibility for customized needs.
## Settings
The service is configured through the settings form, found at
The service is configured through the settings form, found at
`/admin/config/system/encryption`.
It requires a key, which is provided by the Key module. To manage keys, visit
It requires a key, which is provided by the Key module. To manage keys, visit
`/admin/config/system/keys`.
## Best practices
In order to provide real security, it is highly recommended to follow these
In order to provide real security, it is highly recommended to follow these
best practices:
### Encryption method
Use a high-quality, modern security library for encrypting your data.
The Real AES module (https://www.drupal.org/project/real_aes) provides
The Real AES module (https://www.drupal.org/project/real_aes) provides
integration with the recommended Defuse PHP Encryption library.
Read the README.txt document provided by the Real AES module for detailed
security information and best practices, as well as further background
Read the README.txt document provided by the Real AES module for detailed
security information and best practices, as well as further background
information.
Encrypt RSA module (https://www.drupal.org/project/encrypt_rsa) provides
@@ -48,27 +48,35 @@ Make sure to store your keys in an appropriately secure place. Keep your keys
out of the database, out of the web root and on a different server, if possible.
The "Configuration" key provider (as defined by the Key module) should only be
used for testing purposes. Never use this key provider in a production
environment, or any environment where security is required.
used for testing purposes. Never use this key provider in a production
environment, or any environment where security is required.
## Use of Services
## Using the service
After configuring the service, the service provides the ability to encrypt and
After configuring the service, the service provides the ability to encrypt and
decrypt using your encryption profile (machine name).
### Get the service
```
/** @var \Drupal\encrypt\EncryptServiceInterface $encrypt_service */
$encrypt_service = Drupal::service('encryption');
$profile_id = 'example_machine_name';
/** @var \Drupal\encrypt\EncryptionProfileInterface $encryption_profile */
$encryption_profile = \Drupal::entityTypeManager()
->getStorage('encryption_profile')->load($profile_id);
```
### Encrypt
```
use Drupal\encrypt\Entity\EncryptionProfile;
$encryption_profile = EncryptionProfile::load($instance_id);
Drupal::service('encryption')->encrypt($string, $encryption_profile);
$encrypted_string = $encrypt_service->encrypt($string_to_encrypt, $encryption_profile);
```
### Decrypt
```
use Drupal\encrypt\Entity\EncryptionProfile;
$encryption_profile = EncryptionProfile::load($instance_id);
Drupal::service('encryption')->decrypt($string, $encryption_profile);
$decrypted_string = $encrypt_service->decrypt($string_to_decrypt, $encryption_profile);
```
### Note
@@ -87,8 +95,8 @@ data! [Read more about symmetric and asymmetric cryptography.](https://en.wikipe
## Writing your own EncryptionMethod plugin
In you want to write your own encryption method plugin, you should extend the
EncryptionMethodBase class and implement the methods defined by the
EncryptionMethodInterface. See the TestEncryptionMethod class in the
EncryptionMethodBase class and implement the methods defined by the
EncryptionMethodInterface. See the TestEncryptionMethod class in the
encrypt_test module bundled in the "tests" directory of this module.
Optionally, your encryption method plugin can provide a configuration form, that
Loading