From c6e7e28de5dbd181d17332852c3b85604fc0aef1 Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <dgustafsson@postgresql.org>
Date: Tue, 5 Mar 2024 11:32:11 +0100
Subject: [PATCH v3 2/2] pgcrypto: Document deprecation notices against
 algorithms

Many of the algorithms supported by pgcrypto have since pgcrypto was
first included been deprecated and/or found to be vulnerable.  List
deprecation notices and links to further reading to inform our users
about the available algorithms.

Discussion: https://postgr.es/m/29070C1D-9E91-47FB-9250-C5135FA269BC@yesql.se
---
 doc/src/sgml/pgcrypto.sgml | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml
index e66d60878f..d0bbb20bc8 100644
--- a/doc/src/sgml/pgcrypto.sgml
+++ b/doc/src/sgml/pgcrypto.sgml
@@ -1086,6 +1086,39 @@ gen_random_uuid() returns uuid
     ciphertexts of a given size.
    </para>
   </sect3>
+
+  <sect3 id="pgcrypto-notes-disallowed">
+   <title>Deprecated Algorithms</title>
+
+   <para>
+    <filename>pgcrypto</filename> supports a number of algorithms which are
+    known to be vulnerable to attacks, and are widely advised against to be
+    used for new applications.
+   </para>
+   <para>
+    DES and 3DES cipher algorithms, are listed as disallowed for encryption in
+    <ulink url="https://doi.org/10.6028/NIST.SP.800-131Ar2">NIST SP800-131A</ulink>.
+    In order to be compliant with NIST guidelines, these algorithms should
+    only be used for decryption of already encrypted data.
+   </para>
+   <para>
+    <ulink url="https://datatracker.ietf.org/doc/html/rfc6151">RFC6151</ulink>
+    documents why MD5 should not be used for digital signatures.
+   </para>
+   <para>
+    Blowfish is vulnerable to the <ulink url="https://sweet32.info/">SWEET32</ulink>
+    birthday attack and is adviced against for new applications.
+   </para>
+   <para>
+    SHA-1 was deprecated for digital signature generation in
+    <ulink url="https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-107r1.pdf">
+    NIST SP800-107</ulink> and later disallowed in
+    <ulink url="https://doi.org/10.6028/NIST.SP.800-131Ar2">NIST SP800-131A</ulink>.
+    In order to be compliant with NIST guidelines, SHA-1 should only be used
+    for validating digital signatures.
+   </para>
+  </sect3>
+
  </sect2>
 
  <sect2 id="pgcrypto-author">
-- 
2.32.1 (Apple Git-133)

