|
| 1 | +# Using the CipherSweet adapter for Doctrine |
| 2 | + |
| 3 | +This guide will walk you through using the adapter in your Doctrine-based apps. |
| 4 | + |
| 5 | +## Installation |
| 6 | + |
| 7 | +```bash |
| 8 | +composer require paragonie/doctrine-ciphersweet |
| 9 | +``` |
| 10 | + |
| 11 | +## Configuration |
| 12 | + |
| 13 | +First, you need a `ParagonIE\CipherSweet\CipherSweet` object. Please refer to |
| 14 | +[the CipherSweet docs](https://ciphersweet.paragonie.com/php/setup) for more information. |
| 15 | + |
| 16 | +```php |
| 17 | +use ParagonIE\CipherSweet\CipherSweet; |
| 18 | +use ParagonIE\CipherSweet\KeyProvider\StringProvider; |
| 19 | + |
| 20 | +$keyProvider = new StringProvider(random_bytes(32)); |
| 21 | +$engine = new CipherSweet($keyProvider); |
| 22 | +``` |
| 23 | + |
| 24 | +Next, create an `EncryptedFieldSubscriber` and register it with your `EntityManager`. |
| 25 | + |
| 26 | +```php |
| 27 | +use ParagonIE\DoctrineCipher\Event\EncryptedFieldSubscriber; |
| 28 | + |
| 29 | +$subscriber = new EncryptedFieldSubscriber($engine); |
| 30 | +$entityManager->getEventManager()->addEventSubscriber($subscriber); |
| 31 | +``` |
| 32 | + |
| 33 | +### Symfony Configuration |
| 34 | + |
| 35 | +If you're using Symfony, you can configure the subscriber in your `services.yaml` file. |
| 36 | + |
| 37 | +First, make sure you have a `CIPHERSWEET_KEY` environment variable defined in your `.env` file. |
| 38 | +It must be a 64-character hexadecimal string. |
| 39 | + |
| 40 | +```env |
| 41 | +# .env |
| 42 | +CIPHERSWEET_KEY=your-64-character-hexadecimal-key |
| 43 | +``` |
| 44 | + |
| 45 | +Then, configure the services in `config/services.yaml`: |
| 46 | + |
| 47 | +```yaml |
| 48 | +# config/services.yaml |
| 49 | +parameters: |
| 50 | + env(CIPHERSWEET_KEY): '' |
| 51 | + |
| 52 | +services: |
| 53 | + ParagonIE\CipherSweet\KeyProvider\StringProvider: |
| 54 | + factory: ['App\Factory\CipherSweetKeyProviderFactory', 'create'] |
| 55 | + arguments: |
| 56 | + - '%env(CIPHERSWEET_KEY)%' |
| 57 | + |
| 58 | + ParagonIE\CipherSweet\CipherSweet: |
| 59 | + arguments: |
| 60 | + - '@ParagonIE\CipherSweet\KeyProvider\StringProvider' |
| 61 | + |
| 62 | + ParagonIE\DoctrineCipher\Event\EncryptedFieldSubscriber: |
| 63 | + arguments: |
| 64 | + - '@ParagonIE\CipherSweet\CipherSweet' |
| 65 | + tags: |
| 66 | + - { name: doctrine.event_subscriber, connection: default } |
| 67 | +``` |
| 68 | +
|
| 69 | +You will also need to create a factory to create the `StringProvider` from the hexadecimal key |
| 70 | +in your `.env` file. |
| 71 | + |
| 72 | +```php |
| 73 | +// src/Factory/CipherSweetKeyProviderFactory.php |
| 74 | +<?php |
| 75 | +declare(strict_types=1); |
| 76 | +namespace App\Factory; |
| 77 | +
|
| 78 | +use ParagonIE\CipherSweet\KeyProvider\StringProvider; |
| 79 | +
|
| 80 | +final class CipherSweetKeyProviderFactory |
| 81 | +{ |
| 82 | + public static function create(string $key): StringProvider |
| 83 | + { |
| 84 | + return new StringProvider(hex2bin($key)); |
| 85 | + } |
| 86 | +} |
| 87 | +``` |
| 88 | + |
| 89 | +## Usage |
| 90 | + |
| 91 | +Once the above steps are complete, you can use the `#[Encrypted]` attribute on your entity properties. |
| 92 | + |
| 93 | +```php |
| 94 | +use Doctrine\ORM\Mapping as ORM; |
| 95 | +use ParagonIE\DoctrineCipher\Attribute\Encrypted; |
| 96 | +
|
| 97 | +#[ORM\Entity] |
| 98 | +class Message |
| 99 | +{ |
| 100 | + #[ORM\Id] |
| 101 | + #[ORM\Column(type: 'integer')] |
| 102 | + #[ORM\GeneratedValue] |
| 103 | + private int $id; |
| 104 | +
|
| 105 | + #[ORM\Column(type: 'text')] |
| 106 | + #[Encrypted] |
| 107 | + private string $text; |
| 108 | +
|
| 109 | + public function __construct(string $text) |
| 110 | + { |
| 111 | + $this->text = $text; |
| 112 | + } |
| 113 | +
|
| 114 | + // ... getters and setters |
| 115 | +} |
| 116 | +``` |
| 117 | + |
| 118 | +When you persist an entity, the `EncryptedFieldSubscriber` will automatically encrypt the properties that have the |
| 119 | +`#[Encrypted]` attribute. |
| 120 | + |
| 121 | +```php |
| 122 | +$message = new Message('This is a secret message.'); |
| 123 | +$entityManager->persist($message); |
| 124 | +$entityManager->flush(); |
| 125 | +``` |
| 126 | + |
| 127 | +When you retrieve an entity, the encrypted properties will be automatically decrypted. |
| 128 | + |
| 129 | +```php |
| 130 | +$message = $entityManager->find(Message::class, 1); |
| 131 | +echo $message->getText(); // "This is a secret message." |
| 132 | +``` |
| 133 | + |
| 134 | +### Blind Indexes |
| 135 | + |
| 136 | +You can also use blind indexes for searchable encryption. To do this, add a `blindIndexes` argument to the |
| 137 | +`#[Encrypted]` attribute. |
| 138 | + |
| 139 | +```php |
| 140 | +use Doctrine\ORM\Mapping as ORM; |
| 141 | +use ParagonIE\DoctrineCipher\Attribute\Encrypted; |
| 142 | +
|
| 143 | +#[ORM\Entity] |
| 144 | +class Message |
| 145 | +{ |
| 146 | + #[ORM\Id] |
| 147 | + #[ORM\Column(type: 'integer')] |
| 148 | + #[ORM\GeneratedValue] |
| 149 | + private int $id; |
| 150 | +
|
| 151 | + #[ORM\Column(type: 'text')] |
| 152 | + #[Encrypted(blindIndexes: ['insensitive' => 'case-insensitive'])] |
| 153 | + private string $text; |
| 154 | +
|
| 155 | + #[ORM\Column(type: 'string', length: 255, nullable: true)] |
| 156 | + private ?string $textBlindIndexInsensitive; |
| 157 | +
|
| 158 | + public function __construct(string $text) |
| 159 | + { |
| 160 | + $this->text = $text; |
| 161 | + } |
| 162 | +
|
| 163 | + // ... getters and setters |
| 164 | +} |
| 165 | +``` |
| 166 | + |
| 167 | +Observe the attribute: `#[Encrypted(blindIndexes: ['insensitive' => 'case-insensitive'])]`. |
| 168 | + |
| 169 | +In order for this to succeed, you need to register a transformer for the blind index. |
| 170 | + |
| 171 | +```php |
| 172 | +use ParagonIE\CipherSweet\Transformation\Lowercase; |
| 173 | +
|
| 174 | +$subscriber->addTransformer('case-insensitive', Lowercase::class); |
| 175 | +``` |
| 176 | + |
| 177 | +If you're using Symfony, you can add the transformer to your `services.yaml` file. |
| 178 | + |
| 179 | +```yaml |
| 180 | +# config/services.yaml |
| 181 | +services: |
| 182 | + ParagonIE\DoctrineCipher\Event\EncryptedFieldSubscriber: |
| 183 | + # ... |
| 184 | + calls: |
| 185 | + - ['addTransformer', ['case-insensitive', 'ParagonIE\CipherSweet\Transformation\Lowercase']] |
| 186 | +``` |
| 187 | + |
| 188 | +## Complete Example |
| 189 | + |
| 190 | +Now you can query the blind index. To do so, you must first calculate the blind index for your search term. |
| 191 | + |
| 192 | +```php |
| 193 | +use ParagonIE\CipherSweet\BlindIndex; |
| 194 | +use ParagonIE\CipherSweet\EncryptedField; |
| 195 | +
|
| 196 | +// First, you need to get the blind index for your search term. |
| 197 | +// Note: The EncryptedField must be configured exactly as it is for the entity. |
| 198 | +$encryptedField = new EncryptedField($engine, 'messages', 'text'); |
| 199 | +$encryptedField->addBlindIndex(new BlindIndex('insensitive', [new Lowercase()])); |
| 200 | +
|
| 201 | +$searchTerm = 'this is a secret message.'; |
| 202 | +$blindIndex = $encryptedField->getBlindIndex($searchTerm, 'insensitive'); |
| 203 | +
|
| 204 | +// Now you can use this blind index to query the database. |
| 205 | +$repository = $entityManager->getRepository(Message::class); |
| 206 | +$message = $repository->findOneBy(['textBlindIndexInsensitive' => $blindIndex]); |
| 207 | +``` |
| 208 | + |
| 209 | +## Example App |
| 210 | + |
| 211 | +The [example](example) directory contains an example Symfony application that uses the Doctrine-CipherSweet adapter. |
| 212 | +This example app is tested as part of our CI/CD pipeline, so the code there is guaranteed to work if the build passes. |
0 commit comments