paragonie/ciphersweet

New Feature: If you use a StaticBlindIndexKeyProvider interface for your Key Providers, you can now designate a specific "tenant" identifier to be static and used for Blind Index root key derivation. This works with EncryptedRow and EncryptedMultiRows.

What's Changed

• fix(issue-107): explicit nullable type by @GErpeldinger in #108
• Allow multi-tenant providers to use static blind index keys by @paragonie-security in #110

New Contributors

• @GErpeldinger made their first contribution in #108

Full Changelog: v4.7.0...v4.8.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.

• Allow constant_time_encoding v3

What's Changed

• Update CI configuration by @paragonie-security in #100

Full Changelog: v4.5.1...v4.6.0

More helpful exception message on NULL values. See #95, #92, #93.

If you do not declare a field optional, it generally will not accept NULL as a value on encrypt. Boolean is the exception to this rule (for backwards compat).

However, non-optional fields (even booleans) must have a ciphertext on the decrypt path.

Encrypt:
  TYPE_BOOLEAN + (null) -> ciphertext
  TYPE_OPTIONAL_BOOLEAN + (null) -> ciphertext

Decrypt:
  TYPE_BOOLEAN + (null) -> TypeError
  TYPE_OPTIONAL_BOOLEAN + (null) -> null

Booleans are the weird ones, though.

Encrypt:
  TYPE_TEXT + (null) -> TypeError
  TYPE_OPTIONAL_TEXT + (null) -> null

Decrypt:
  TYPE_TEXT + (null) -> TypeError
  TYPE_OPTIONAL_BOOLEAN + (null) -> null

Every other type doesn't tolerate null implicitly. This behavior is because of a very early design decision with boolean types.

What's Changed

• #92 Explicit support for optional field types
• #88 Support json field map templating

Full Changelog: v4.4.0...v4.5.0

What's Changed

• Feature: Extension Keys in #86

Full Changelog: v4.3.0...v4.4.0

What's Changed

• [v3.x] Update CI configuration, dependencies by @paragonie-security in #101

Full Changelog: v3.4.0...v3.4.1