CipherSweet

• PHP
• Node.js

Using CipherSweet (PHP)

Table of Contents

• Using CipherSweet
  • Table of Contents (You are here)
  • Understanding CipherSweet's Features and Limitations
  • Installing CipherSweet
  • Setting up CipherSweet at Run-Time
    • Select Your Backend
    • Define your Key Provider
      • Cloud Key Management Integration
    • Start Your Engines
  • Basic CipherSweet Usage
    • Enhanced AAD
    • EncryptedField
      • EncryptedField with AAD
    • EncryptedRow
      • EncryptedRow with a CompoundIndex using a custom Transform of Multiple Fields
      • EncryptedRow with AAD
    • EncryptedMultiRows
      • EncryptedMultiRows with AAD
      • EncryptedMultiRows with Automatic Context Binding
  • Blind Index Planning
  • Key/Backend Rotation
    • FieldRotator
    • RowRotator
    • MultiRowsRotator
  • EncryptedFile
• Security Properties and Thread Model for CipherSweet
• CipherSweet Internals (Look here if you seek to port CipherSweet to another language)
  • Key Hierarchy
  • Packing
  • Field-Level Encryption
  • Blind Indexing
  • File Encryption

Understanding CipherSweet's Features and Limitations

CipherSweet is an implementation of PIE's searchable encryption design, which combines semantically secure authenticated encryption with "blind indexes" of the plaintext.

At a super high level overview:

• Ciphertexts (encrypted messages) are indistinguishable from each other.
• Blind indexes offer limited searching capabilities.
  • They don't support LIKE operators or regular expressions.
  • They don't support inequalities.
• Each blind index is one-way (a.k.a. irreversible) and can be created on the plaintext itself, or a transformation of the plaintext. Example transformations include:
  • Last four numeric digits of the plaintext
  • First letter of the plaintext
  • All-lowercase representation of the plaintext
• CipherSweet also supports compound indexes, which combine multiple fields together before applying the cryptographic hash function.
  • This allows you to create an index on "first initial" + "last name".
  • It's recommended to use compound indexes for sensitive boolean fields.
    • For example: Indexing your users' HIV status by itself would be a huge HIPAA violation risk. However, if you index "HIV status + last 4 digits of social security number", an attacker can't just look at the blind indexes and immediately deduce the value of this boolean field.
• If you add too many blind indexes to your data, you may allow attackers who know some plaintexts to be able to deduce facts about the decrypted value of other ciphertexts.
  • We refer to these deductive strategies as "crossword puzzle attacks" because the same sort of analytical skills used to solve crossword puzzles can be employed to learn facts about the unencryptable data.
  • Solution: Use blind indexes sparingly.
• Each blind index is intended to be truncated and used as a Bloom filter when searching.
  • How much you truncate each index depends on how many duplicates / false positives you wish your application to tolerate.
  • Shorter indexes will result in more duplicates, but will be less useful for attackers trying to perform crossword puzzle attacks on the blind indexes.
• It's okay to only encrypt some fields and not create blind indexes on them, so long as your application doesn't need to use those values in SELECT queries.

Installing CipherSweet

We recommend using Composer to manage PHP dependencies, especially CipherSweet.

composer require paragonie/ciphersweet:^4

The source code for CipherSweet is available on Github.

Next: Setting up CipherSweet at Run-Time