README

This module provides a way to store sensitive data securely using the Vault service (specifically the Transit API).

Requirements

SilverStripe ^4 || ^5
PHP ^7.4 || ^8.0
Vault Server with Transit API enabled

Installation

Install the module using composer.

composer require violet88/silverstripe-vault

Configuration

Vault

The module requires transit to be enabled on the Vault server. The following policy can be used to enable transit.

path "transit/*" {
    capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

The transit engine can be enabled using the following command.

vault secrets enable transit

SilverStripe

Configuration File

The module requires a Vault server to be configured. The server can be configured in the vault.yml file.

---
name: vault
---
Violet88/VaultModule/VaultClient:
    vault_token: # Vault Authorization Token
    vault_url: # Vault URL
    vault_transit_path: # Transit Path, defaults to 'transit'

Additionally, a default key can be configured in the vault.yml file.

Violet88/VaultModule/VaultKey:
    name: # Key Name
    type: # Key Type, e.g. aes256-gcm96

If no key is configured, the module will use the following defaults.

Violet88/VaultModule/VaultKey:
    name: "silverstripe"
    type: "aes256-gcm96"

Keys will be created automatically if they do not exist, be sure to set Vault permissions accordingly.

Environment Variables

Along with the vault.yml file, the module supports the following environment variables.

VAULT_TOKEN="s.1234567890abcdef"
VAULT_URL="https://vault.example.com"
VAULT_TRANSIT_PATH="transit"

Setting these environment variables will override the corresponding values set in the vault.yml file.

Usage

The module provides an Encrypted field type that automatically encrypts and decrypts data when it is saved and retrieved from the database.

<?php

class MyDataObject extends DataObject
{
    private static $db = [
        'MyEncryptedField' => 'Encrypted',
    ];
}

The datatype supports automatic casting, to use it simply pass the cast type as well as any of it's parameters.

<?php

class MyDataObject extends DataObject
{
    private static $db = [
        'MyEncryptedIntegerField' => 'Encrypted("Int")',
        'MyEncryptedEnumField' => 'Encrypted("Enum", "value1,value2,value3")',
    ];
}

Filtering

The module provides an EncryptedSearch that can be used to filter data by encrypted fields. Keep in mind that the filter will only return exact matches.

<?php

class MyDataObject extends DataObject
{
    private static $searchable_fields = [
        'MyEncryptedField' => 'EncryptedSearch',
    ];
}

Tasks

The module provides tasks for encrypting and decrypting all data and rotating the default key.

# Encrypt all data
vendor/bin/sake dev/tasks/EncryptDBTask

# Decrypt all data
vendor/bin/sake dev/tasks/DecryptDBTask

# Rotate keys
vendor/bin/sake dev/tasks/RotateKeyTask

Disclaimers

Violet88 is not responsible for any loss of data or other damages caused by the use of this module. Use at your own risk.

violet88 / silverstripe-vault

Maintainers

Details