@piiano/typeorm-encryption

This package extends the typeorm package to provide support for encrypting and decrypting entity properties using a Piiano Vault server.

Note:

This package is compatible with Vault version 1.11.2. For a version compatible with other versions of Vault, check other versions of this package.

Requirements

• typeorm version 0.3.12 or higher.
• Vault server version 1.3.1 or higher. If this is your first time using Vault, you can get started here.

Installation

To install the package using npm:

npm install @piiano/typeorm-encryption

To install the package using yarn:

yarn add @piiano/typeorm-encryption

Usage

To register the automatic encryption and decryption of entity properties, first import the registerVaultEncryption function into your project:

import registerVaultEncryption from '@piiano/typeorm-encryption';

Then call the registerVaultEncryption function with the DataSource object:

import {DataSource} from "typeorm";
import registerVaultEncryption from '@piiano/typeorm-encryption';

async function main() {
  const dataSource = new DataSource({
    type: "sqlite",
    synchronize: true,
    logging: false,
    database: "app.db",
    entities: [Customer],
  });

  registerVaultEncryption(dataSource, {
    vaultURL: 'https://vault.example.com:8123',
    apiKey: 'vaultApiKey',
  });

  await dataSource.initialize();
}

Note: The registerVaultEncryption function must be called before call to DataSource.initialize().

If not declared registerVaultEncryption options default to:

const defaultOptions = {
  vaultURL: "http://localhost:8123",
  apiKey: "pvaultauth",
}

Entity

To encrypt and decrypt entity properties, the encrypt: true column option must be set:

@Entity()
export class Customer extends BaseEntity {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({encrypt: true})
  name: string;

  @Column({encrypt: true})
  email: string;

  @Column({encrypt: true})
  phone: string;

  @Column({encrypt: true})
  ssn: string;
  
  @Column()
  state: string;
}

In the example above, the name, email, phone, and ssn properties will be encrypted and decrypted automatically.

Querying encrypted properties

Querying on encrypted properties is handled automatically when identifying encrypted properties in a where clause without the need to decrypt the data first.

The encryption algorithm used by the Piiano Vault server is deterministic, meaning that the same value will always be encrypted to the same ciphertext in the database which makes querying possible.

Note

Using this approach, limits the ability to query on encrypted properties to the = and != operators. Other operators such as >, <, >=, <=, LIKE, BETWEEN, etc. are not supported.

For example, the following query will work as expected on the encrypted email property:

const customers = await Customer.find({
  where: {
    email: '[email protected]',
  }
});

Using Vault transformations

The Piiano Vault server supports the use of transformations.

Transformations provide a mechanism to present sensitive data in a way that reduces data exposure.

For example, the email property in the example above could be masked using the mask transformation to return s********@example.com instead of the actual email address.

To use a transformation, append the transformation name to the column name in the select clause:

Vault transformation is performed on the Vault server and the result is returned to the client meaning the sensitive data never leaves the Vault server but only the transformed result.

import {withTransformations} from '@piiano/typeorm-encryption';

const customers = await withTransformations(Customer).find({
  select: { 'email.mask': true },
});

// returns:
// [
//   { 'email.mask': 's********@example.com' },
// ]

Note The withTransformations function is a wrapper that extends the type of the given entity class to allow selecting on the transformation properties. It is not required to use the withTransformations function but it is recommended to allow proper type checking.

Development

To build and test the project:

yarn
yarn build
yarn test

License

This project is licensed under the MIT License - see the LICENSE file for details

Known Limitations

• Encryption is supported only for string columns.
• Querying using the array notation don't of the same property in a transformed and untransformed form will return only the transformed value. Examples: Using select: ['email', 'email.mask'] will result in only email.mask being returned. While using select: {'email.mask': true, 'email': true} will result in both email and email.mask being returned. Selecting using the array notation is deprecated by TypeORM and is not recommended.

About Piiano Vault

Piiano Vault is the secure home for sensitive personal data. It allows you to safely store sensitive personal data in your own cloud environment with automated compliance controls.

Vault is deployed within your own architecture, next to other DBs used by the applications, and should be used to store the most critical sensitive personal data, such as credit cards and bank account numbers, names, emails, national IDs (e.g. SSN), phone numbers, etc.

The main benefits are:

• Field level encryption, including key rotation.
• Searchability is allowed over the encrypted data.
• Full audit log for all data accesses.
• Granular access controls.
• Easy masking and tokenization of data.
• Out of the box privacy compliance functionality.

More details can be found on our website and on the developers portal.