Version 4.7.0

Enhanced AAD

• Added a new AAD class, which allows users to bind an encrypted field to the contents of multiple plaintext fields. This class can be used in the same place where a field name or literal value was used previously.
• EncryptedFile now accepts an optional AAD param, which binds the file's contents to the AAD value.
• Improved test coverage.
• EncryptedRow now allows you to automatically bind fields to their context (i.e. primary key).
• EncryptedMultiRows now allows you to enable auto-binding mode, which ensures that all fields are explicitly bound (via the AAD parameter) to, at minimum, the database row primary key, table name, and field name.

Here's a quick example of the old API, then a diff to use the new AAD features:

<?php
use ParagonIE\CipherSweet\CipherSweet;
use ParagonIE\CipherSweet\EncryptedMultiRows;
/** @var CipherSweet $engine */

$multiRowEncryptor = new EncryptedMultiRows($engine);
$multiRowEncryptor
    ->addTextField('table1', 'field1')
    ->addIntegerField('table1', 'field2')
    ->addFloatField('table1', 'field3')
    ->addOptionalBooleanField('table1', 'field4')
    ->addTextField('table2', 'foo')
    ->addTextField('table3', 'bar');

$encrypted = $multiRowEncryptor->encryptManyRows([
  'table1' => ['field1' => 'hello world', 'field2' => 42, 'field3' => 3.1416],
  'table2' => ['id' => 3, 'foo' => 'joy'],
  'table3' => ['foo' => 'coy'],
]);

And here's how to easily enable to new features:

  $multiRowEncryptor = new EncryptedMultiRows($engine);
  $multiRowEncryptor
+     ->setAutoBindContext(true)
+     ->setPrimaryKeyColumn('table2', 'id')
      ->addTextField('table1', 'field1')

With this change, every encrypted field is explicitly cryptographically bound to its context (table name, field name) with no further action needed from the developer.

Additionally, table2 is cryptographically bound to its primary key (id). This has two consequences:

1. You cannot copy ciphertexts between rows and decrypt successfully. This is a good thing.
2. However, you must know the primary key when inserting new records, in order to provide it to CipherSweet.

That second point is the main reason why we are not enabling it by default. (Also, we'd kind of need to know your primary key naming convention, which we cannot know for everyone that uses this library.)

We will update the documentation as soon as possible.