Spec

Implementation

Package Structure

• src
  • Contracts
    • KeyManager
    • KeyProvider
    • Securable
  • Models
    • EncrpytionKey
  • Traits
    • Securable
  • Observers
    • ModelObserver
  • KeyProviders
    • AwsKmsKeyProvider
  • KeyManager
  • SecurityModelServiceProvider

Responsibility

1. Key Provider
   1. manage master key
   2. encrypt/decrypt data key
   3. encapsulate detail of integrating external key management service
2. Key Manager
   1. retrieve available encryption key
   2. encrypt/decrypt encryption key
3. Encrypter
   1. encapsulate detail of underlying data encryption
4. Model Trait
   1. encrypt/decrypt model data
   2. update model blind index
   3. define relationship with encryption key
   4. register model observer
5. Model Observer
   1. listen on model event
      1. retrieved event
         1. encrypt data
      2. saved event
         1. encrypt data
         2. decrypt data

Blind index planning

to achieve searching on encrypted fields, we use a strategy called blind indexing. its idea is to store a hash value of the plaintext in a separate column and would it will be used for searching.

• Plan A: Create a polymorphism table for storing all blind indexes
  • Pros
    • developer wouldn’t need to create migration to add blind index column for every table
    • package wouldn’t need to handle customization（ex. blind index column name）
  • Cons
    • encryption on multiple tables would create a huge amount of data in the blind index table, and that might cause potential performance issue
    • developer should need make sure the updating operation across the model table and index table is at the same transaction to avoid race condition
• Plan B: Create an additional column on the original table for storing the blind index
  • Pros
    • implementation is simpler for unique index
    • searching and updating on the same table/B-tree would make performance better
    • can make sure an updating operation of raw value and hash value is consistent & atomic
  • Cons
    • need to create many additional columns for each searchable column. (email_bidx, phone_bidx, address_bidx, etc...)

we choose to use Plan B because we should highly consider performance issues when developing this package.