Merge pull request #97 from uktrade/docs/be-more-specific-about-ae-2

docs: be more specific about the limitations of AE-2

docs/advanced-usage.md

@@ -45,7 +45,7 @@ This is useful to keep the total number of bytes down as much as possible. This
 
 ## Password protection / encryption
 
-The data of ZIP files can be password protected / encrypted by passing a password as the `password` parameter to `stream_zip`.
+The data of ZIP files can be password protected / encrypted by passing a password as the `password` parameter to `stream_zip`. This encrypts the data with AES-256, adhering to the [WinZip AE-2 specification](https://www.winzip.com/en/support/aes-encryption/).
 
 ```python
 import secrets
@@ -54,10 +54,18 @@ password = secrets.token_urlsafe(32)
 encrypted_zipped_chunks = stream_zip(member_files(), password=password)
 ```
 
-Notes:
-
-1. This encrypts the data with AES-256, adhering to the [WinZip AE-2 specification](https://www.winzip.com/en/support/aes-encryption/).
-
-2. This is seen as more secure than ZipCrypto, the original mechanism of password protecting ZIP files, but fewer clients can open such ZIP files.
-
-3. While a step forward from ZipCrypto, it has flaws that you should be aware of before using it. See ["Attacking and Repairing the WinZip Encryption Scheme" by Tadayoshi Kohno](https://homes.cs.washington.edu/~yoshi/papers/WinZip/winzip.pdf) and [fgrieu's answer to a question about WinZip's AE-1 and AE-2 on Crytography Stack Exchange](https://crypto.stackexchange.com/a/109269/113464).
+You should use a long and random password, for example one generated by the [Python secrets module](https://docs.python.org/3/library/secrets.html).
+
+> ### Warnings
+>
+> While AE-2 is seen as more secure than ZipCrypto, the original mechanism of password protecting ZIP files, fewer clients support AE-2 than ZipCrypto.
+>
+> More importantly, AE-2 has flaws. These include:
+>
+> - Not encrypting metadata, for example member file names, modification times, permissions, and sizes.
+>
+> - Not including sufficient mechanisms to alert recipients if data or metadata has been intercepted and changed. This can itself lead to information leakage.
+>
+> - A higher risk of information leakage when there's a higher number of member files in the ZIP encrypted with the same password, as stream-zip and most other ZIP writers do.
+>
+> See ["Attacking and Repairing the WinZip Encryption Scheme" by Tadayoshi Kohno](https://homes.cs.washington.edu/~yoshi/papers/WinZip/winzip.pdf) and [fgrieu's answer to a question about WinZip's AE-1 and AE-2 on Crytography Stack Exchange](https://crypto.stackexchange.com/a/109269/113464) for more information.