From 4f4796643f82fb1c9adb5532cb0896e6f1c43ce9 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Tim=20D=C3=BCsterhus?= <duesterhus@woltlab.com>
Date: Thu, 17 Dec 2020 10:57:17 +0100
Subject: [PATCH] Document the addition of paragonie/constant_time_encoding
 (#108)

See #91

Co-authored-by: Matthias Schmidt <gravatronics@live.com>
---
 .../wsc-53/migration_wsc-53_libraries.md      | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/pages/migration/wsc-53/migration_wsc-53_libraries.md b/pages/migration/wsc-53/migration_wsc-53_libraries.md
index 3231d54e..a35a5bb6 100644
--- a/pages/migration/wsc-53/migration_wsc-53_libraries.md
+++ b/pages/migration/wsc-53/migration_wsc-53_libraries.md
@@ -25,3 +25,33 @@ Refer to the [Emogrifier CHANGELOG](https://github.com/MyIntervals/emogrifier/bl
 
 If you only use Emogrifier indirectly by sending HTML mail via the email subsystem then you might notice unexpected visual changes due to the improved CSS support.
 Double check your CSS declarations and particularly the specificity of your selectors in these cases.
+
+## Constant Time Encoder
+
+WoltLab Suite 5.4 ships the [`paragonie/constant_time_encoding` library](https://github.com/paragonie/constant_time_encoding).
+It is recommended to use this library to perform encoding and decoding of secrets to prevent leaks via cache timing attacks.
+Refer to [the library author’s blog post](https://paragonie.com/blog/2016/06/constant-time-encoding-boring-cryptography-rfc-4648-and-you) for more background detail.
+
+For the common case of encoding the bytes taken from a CSPRNG in hexadecimal form, the required change would look like the following:
+
+Previously:
+
+```php
+<?php
+$encoded = hex2bin(random_bytes(16));
+```
+
+Now:
+
+```php
+<?php
+use ParagonIE\ConstantTime\Hex;
+
+// For security reasons you should add the backslash
+// to ensure you refer to the `random_bytes` function
+// within the global namespace and not a function
+// defined in the current namespace.
+$encoded = Hex::encode(\random_bytes(16));
+```
+
+Please refer to the documentation and source code of the `paragonie/constant_time_encoding` library to learn how to use the library with different encodings (e.g. base64).
-- 
2.20.1