HashiConf 2024 Now streaming live from Boston! Attend for free
HVD Home
HVD Home

Appendix

While the previous use cases cover common applications of the Transit and Transform engines, the following examples demonstrate the breadth and depth of scenarios where these powerful tools can be applied. These use cases span various industries and compliance requirements, highlighting the versatility and effectiveness of Vault's data protection capabilities.

Database column-level encryption with the Transit engine

To implement database column-level encryption using HashiCorp Vault's Transit engine, we recommend following the Vault Transit Rewrap tutorial. This hands-on tutorial demonstrates:

  • Enabling the Transit Engine: Set up and configure the Transit secrets engine for encryption operations.
  • Enabling Data Before Storage: Use the Transit API to encrypt sensitive data before inserting it into your database.
  • Decrypting Data After Retrieval: Decrypt data retrieved from the database securely using the Transit engine.
  • Performing Key Rotation and Data Rewrapping: Regularly rotate encryption keys and rewrap existing data to maintain strong security practices.

Securing sensitive healthcare data with the Transform engine

Healthcare organizations often need to perform analytics on sensitive patient data while maintaining compliance with regulations like HIPAA. The Transform engine's format preserving encryption (FPE) capabilities allow for the encryption of sensitive data in a way that preserves its format, enabling analytics while protecting patient privacy.

  1. Enable the Transform Engine

    vault secrets enable -path=healthcare-transform transform

  2. Configure Templates

    ## Create the SSN template
$ vault write healthcare-transform/template/ssn \
    type=regex \
    pattern='(\d{3})-(\d{2})-(\d{4})' \
    alphabet=builtin/numeric

## Create MRN template (10-digit format)
$ vault write healthcare-transform/template/mrn \
    type=regex \
    pattern='(\d{10})' \
    alphabet=builtin/numeric

  3. Create Transformations

    ## Configure SSN transformation
$ vault write healthcare-transform/transformation/ssn-fpe \
    type=fpe \
    template=ssn \
    tweak_source=internal \
    allowed_roles=healthcare-analytics

## Configure MRN transformation
$ vault write healthcare-transform/transformation/mrn-fpe \
    type=fpe \
    template=mrn \
    tweak_source=internal \ 
    allowed_roles=healthcare-analytics

  4. Create a Role

    ## Create a role with access to both transformations
$ vault write healthcare-transform/role/healthcare-analytics \
    transformations=ssn-fpe,mrn-fpe

  5. Transform Data

    ## Encrypt SSN
$ vault write healthcare-transform/encode/healthcare-analytics \
    transformation=ssn-fpe \
    value="123-45-6789"

## Encrypt MRN
$ vault write healthcare-transform/encode/healthcare-analytics \
    transformation=mrn-fpe \
    value="1234567890"

## Decrypt transformed SSN (when necessary)
$ vault write healthcare-transform/decode/healthcare-analytics \
    transformation=ssn-fpe \
    value="<encoded-value-from-previous-step>"

  6. Configure Access Control

    ## Create a policy for the Transform operation
$ vault policy write transform-healthcare-policy - <<EOF
path "healthcare-transform/encode/healthcare-analytics" {
    capabilities = ["create", "update"]
}

path "healthcare-transform/decode/healthcare-analytics" {
    capabilities = ["create", "update"]
}
EOF

Example outputs

## Sample SSN transformation
$ vault write healthcare-transform/encode/healthcare-analytics \
    transformation=ssn-fpe \
    value="123-45-6789"

Key              Value
---              -----
encoded_value    891-24-3567

## Sample MRN transformation
$ vault write healthcare-transform/encode/healthcare-analytics \
    transformation=mrn-fpe \
    value="1234567890"

Key              Value
---              -----
encoded_value    8915673421

You can monitor the Transform FPE operations through Vault's audit logs by tracking request to the configured mount path (healthcare-transform/). For comprehensive guidance on configuring audit logging, refer to the Vault Operating Guide for Adoption.

Key metrics to monitor:

  • Success and failure rates of transformation operations.
  • Access patterns to specific transformations.
  • Response times for FPE operations.

Implementing GDPR compliance using Transform tokenization

The General Data Protection Regulation (GDPR) requires organizations to implement appropriate measures to protect personal data. Vault's Transform engine provides tokenization capabilities that can replace personally identifiable information (PII) with secure tokens while maintaining data usability. This section demonstrates how to implement tokenization for GDPR compliance.

  1. Enable the Transform Engine

    $ vault secrets enable -path=gdpr-transform transform

  2. Create Templates

    ## Create template for names
$ vault write gdpr-transform/template/name \
    type=regex \
    pattern='([A-Za-z]+)( [A-Za-z]+)*' \
    alphabet=builtin/alphalower

## Create template for email addresses
$ vault write gdpr-transform/template/email \
    type=regex \
    pattern='([A-Za-z0-9._%+-]+)@([A-Za-z0-9.-]+\.[A-Za-z]{2,})' \
    alphabet=builtin/alphanumeric

  3. Configure Transformations

    ## Create transformation for names
$ vault write gdpr-transform/transformation/name-tokenization \
    type=tokenization \
    template=name \
    allowed_roles=gdpr-admin \
    max_ttl="720h"

## Create transformation for email addresses
$ vault write gdpr-transform/transformation/email-tokenization \
    type=tokenization \
    template=email \
    allowed_roles=gdpr-admin \
    max_ttl="720h"

  4. Create a Role

    ## Create a role with access to both transformations
$ vault write gdpr-transform/role/gdpr-admin \
    transformations=name-tokenization,email-tokenization

  5. Tokenize PII Data

    ## Tokenize a name
$ vault write gdpr-transform/encode/gdpr-admin \
    transformation=name-tokenization \
    value="Matt Black"

## Tokenize an email address
$ vault write gdpr-transform/encode/gdpr-admin \
    transformation=email-tokenization \
    value="matt.black@aol.com"

  6. Retrieve Original Data

    ## Retrieve original name when needed
$ vault write gdpr-transform/decode/gdpr-admin \
    transformation=name-tokenization \
    value="<tokenized-name-value>"

## Retrieve original email when needed
$ vault write gdpr-transform/decode/gdpr-admin \
    transformation=email-tokenization \
    value="<tokenized-email-value>"

Using curl with Vault's API

## Set your Vault token and address
$ export VAULT_TOKEN="your-token"
$ export VAULT_ADDR="https://vault.example.com:8200"

## Tokenize data
$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data '{"transformation": "name-tokenization", "value":"John Doe"}' \
    $VAULT_ADDR/v1/gdpr-transform/encode/gdpr-admin

## Retrieve original data
$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data '{"transformation": "name-tokenization", "value": "<tokenized-value>"}' \
    $VAULT_ADDR/v1/gdpr-transform/decode/gdpr-admin

Example Outputs

## Tokenizing a name
$ vault write gdpr-transform/encode/gdpr-admin \
    transformation=name-tokenization \
    value="Matt Black"

Key              Value
---              -----
encoded_value    tok_Gl8qH4hJns9QR3U

## Retrieving original name
$ vault write gdpr-transform/decode/gdpr-admin \
    transformation=name-tokenization \
    value="tok_Gl8qH4hJns9QR3U"

Key              Value
---              -----
decoded_value    Matt Black

Benefits

  • GDPR Compliance: Helps meet GDPR requirements for data protection and tokenization through secure tokenization of personal data and comprehensive audit capabilities.
  • Data Protection: Enhances security by storing tokens instead of original PII in databases, with options for external token storage.
  • Data Usability: Enables data processing on tokenized data without exposing personal information, maintaining functionality while protecting privacy.
  • Access Control: Provides granular control through separate roles for encode and decode operations, allowing organizations to limit access based on specific business needs.
Previous

Transit and Transform secrets engines