(Grav GitSync) Automatic Commit from smokephil

plugins/git-sync/vendor/defuse/php-encryption/docs/UpgradingFromV1.2.md

@@ -0,0 +1,51 @@
+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
+
+    // ...
+```