52 lines
1.9 KiB
Markdown
52 lines
1.9 KiB
Markdown
|
Upgrading From Version 1.2
|
||
|
|
===========================
|
||
|
|
|
||
|
|
With version 2.0.0 of this library came major changes to the ciphertext format,
|
||
|
|
algorithms used for encryption, and API.
|
||
|
|
|
||
|
|
In version 1.2, keys were represented by 16-byte string variables. In version
|
||
|
|
2.0.0, keys are represented by objects, instances of the `Key` class. This
|
||
|
|
change was made in order to make it harder to misuse the API. For example, in
|
||
|
|
version 1.2, you could pass in *any* 16-byte string, but in version 2.0.0 you
|
||
|
|
need a `Key` object, which you can only get if you're "doing the right thing."
|
||
|
|
|
||
|
|
This means that for all of your old version 1.2 keys, you'll have to:
|
||
|
|
|
||
|
|
1. Generate a new version 2.0.0 key.
|
||
|
|
2. For all of the ciphertexts encrypted under the old key:
|
||
|
|
1. Decrypt the ciphertext using the old version 1.2 key.
|
||
|
|
2. Re-encrypt it using the new version 2.0.0 key.
|
||
|
|
|
||
|
|
Use the special `Crypto::legacyDecrypt()` method to decrypt the old ciphertexts
|
||
|
|
using the old key and then re-encrypt them using `Crypto::encrypt()` with the
|
||
|
|
new key. Your code will look something like the following. To avoid data loss,
|
||
|
|
securely back up your keys and data before running your upgrade code.
|
||
|
|
|
||
|
|
```php
|
||
|
|
<?php
|
||
|
|
|
||
|
|
// ...
|
||
|
|
|
||
|
|
$legacy_ciphertext = // ... get the ciphertext you want to upgrade ...
|
||
|
|
$legacy_key = // ... get the key to decrypt this ciphertext ...
|
||
|
|
|
||
|
|
// Generate the new key that we'll re-encrypt the ciphertext with.
|
||
|
|
$new_key = Key::createNewRandomKey();
|
||
|
|
// ... save it somewhere ...
|
||
|
|
|
||
|
|
// Decrypt it.
|
||
|
|
try {
|
||
|
|
$plaintext = Crypto::legacyDecrypt($legacy_ciphertext, $legacy_key);
|
||
|
|
} catch (Defuse\Crypto\Exception\WrongKeyOrModifiedCiphertextException $ex)
|
||
|
|
{
|
||
|
|
// ... TODO: handle this case appropriately ...
|
||
|
|
}
|
||
|
|
|
||
|
|
// Re-encrypt it.
|
||
|
|
$new_ciphertext = Crypto::encrypt($plaintext, $new_key);
|
||
|
|
|
||
|
|
// ... replace the old $legacy_ciphertext with the new $new_ciphertext
|
||
|
|
|
||
|
|
// ...
|
||
|
|
```
|