Spec

Implementation

Package Structure

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

Responsibility

1. Key Provider
   1. encrypt/decrypt data
   2. encapsulate detail of integrating external key management service
2. Key Manager
   1. retrieve available encryption key
      1. encrypt/decrypt encryption key through key provider
3. Model Trait
   1. retrieve encryption key thought key manager to encrypt/decrypt model data
   2. update model blind index
   3. define relationship with encryption key
   4. register model observer
4. Model Observer
   1. listen model event
      1. retrieved event
         1. encrypt data
      2. saving event
         1. encrypt data
      3. saved event
         1. 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.