A Silverstripe module for storing private string values, optionally encrypted.
To update the value, add the plain text secret to the relevant field and save the record, the old value will be overwritten.
The stored value can be cleared using the supplied checkbox.
The only supported method of installing this module is via composer:
composer require codem/silverstripe-onetimeUse the following configuration values with your project config to manage partial value display in supporting fields
---
Name: app-onetime
After:
- '#onetime'
---
Codem\OneTime\PartialValue:
min_characters_replaced : 6
max_characters_replaced : 18
percent_cleared : 80
replacement_character: '*'In your site/module .yml configuration, assign the HasSecrets extension to the relevant DataObjects. Once applied and flushed, these dataobjects will be able to access the methods for encryption/decryption provided by the extension.
MyOrg\MyDataObject:
extensions:
- 'Codem\OneTime\HasSecrets'
MyOrg\AnotherDataObject:
extensions:
- 'Codem\OneTime\HasSecrets'In the relevant DataObjects, set up a configuration schema to mark certain fields as being handled by the module:
<?php
namespace MyOrg;
use Codem\OneTime\PartialValue;
use SilverStripe\ORM\DataObject;
//...
class MyDataObject extends DataObject {
/**
* Example schema for 3 fields
*/
private static $onetime_field_schema = [
'SecretValue' => [
'provider' => 'Local',
'partial' => true, // default partial value view
'tab' => 'Secrets' // on this CMS tab
],
'SecretValueSmall' => [
'provider' => 'Local',
'partial' => true, // default partial value view
'tab' => 'Secrets' // on this CMS tab
],
'SecretValueNoPartial' => [
'provider' => 'Local',
'partial' => false, // default partial value view
'tab' => 'MoreSecrets' // on a different CMS tab
]
];
private static $db = [
// other fields
// ...
'SecretValue' => 'Text',// a Textarea - no partial display for these even if partial is true
'SecretValueSmall' => 'Varchar',// a TextField
'SecretValueNoPartial' => 'Varchar'// a TextField with no partial value displayed
];
// etc
}The above config will look something like this. The 2nd field has a value saved.
There are two providers currently supported
The values are stored in the local database in plain text but are not displayed in the relevant fields.
⚠️ This provider only helps to avoid users with certain CMS/Admin seeing secret values.
The values are stored encrypted in the local database and are not shown in the relevant fields. Encryption and decryption is handled via the AWS client.
You can use the decrypted values in your application, for instance submitting a consumer secret to an API.
AmazonKMS requires an AWS Key, Secret Key, Key ID and AWS Region value to be available, add them to your site's configuration YML like so:
Codem\OneTime\Provider\AmazonKMS:
access_key: 'access_key'
secret: 'secret'
aws_region: 'an-aws-region'
key_id: 'a-kms-keyid'OR
You may also not provide the access_key & secret and instead rely on other authentication methods provided by AWS (e.g ~/.aws/credentials)
The IAM user with the relevant access_key and secret must have encrypt/decrypt privileges set up. You should not use your AWS root/admin user for this.
Encryption Context is optional and assists with logging of encrypt/decrypt requests.
If you want to use this option, add it to the above configuration like so or in your environment:
Codem\OneTime\Provider\AmazonKMS:
access_key: 'access_key'
secret: 'secret'
aws_region: 'an-aws-region'
key_id: 'a-kms-keyid'
encryption_context:
AContextKey: 'some_context_value'Read Encryption Context documentation at AWS for more information.
When you wish to get the field value back, simply call decrypt() on your DataObject. The argument is the field name.
$instance = MyDataObject::get()->byId(1);
$plaintext = $instance->decrypt('SomeFieldNameWithEncryptedValue');You can then use that value in your application, e.g by passing it to an API.
- Values you enter will be visible when entered into the field
- If your admin/website is not hosted over an HTTPS connection (!) data will be visible in transit
Encrypted values will be longer than the plain text version entered into the field.
If your field is set as a Varchar field, you may experience truncation of the encrypted value when the database insert occurs. Rather than this module automatically changing your field types, it's highly recommended that you specify "Text" as the field type for the relevant fields.
You can then use a TextField instead of a TextareaField in your DataObject's getCmsFields, if required.
BSD-3-Clause
Codem