From bfdf9e2236376b2b569631d5e01eb4717aac385f Mon Sep 17 00:00:00 2001
From: Paul Schaub <vanitasvitae@fsfe.org>
Date: Tue, 7 May 2024 12:17:07 +0200
Subject: [PATCH] Document HashAlgorithmTags

---
 .../bouncycastle/bcpg/HashAlgorithmTags.java  | 123 +++++++++++++++---
 1 file changed, 102 insertions(+), 21 deletions(-)

diff --git a/pg/src/main/java/org/bouncycastle/bcpg/HashAlgorithmTags.java b/pg/src/main/java/org/bouncycastle/bcpg/HashAlgorithmTags.java
index eb0a114344..2a6b987838 100644
--- a/pg/src/main/java/org/bouncycastle/bcpg/HashAlgorithmTags.java
+++ b/pg/src/main/java/org/bouncycastle/bcpg/HashAlgorithmTags.java
@@ -1,32 +1,113 @@
 package org.bouncycastle.bcpg;
 
 /**
- * basic tags for hash algorithms
+ * Basic tags for hash algorithms.
+ *
+ * @see <a href="https://www.rfc-editor.org/rfc/rfc4880.html#section-9.4">
+ *     RFC4880 - Hash Algorithms</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-koch-librepgp-00.html#name-hash-algorithms">
+ *     LibrePGP - Hash Algorithms</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-hash-algorithms">
+ *     Crypto-Refresh - Hash Algorithms</a>
  */
 public interface HashAlgorithmTags 
 {
-    int MD5 = 1;          // MD5
-    int SHA1 = 2;         // SHA-1
-    int RIPEMD160 = 3;    // RIPE-MD/160
-    int DOUBLE_SHA = 4;   // Reserved for double-width SHA (experimental)
-    int MD2 = 5;          // MD2
-    int TIGER_192 = 6;    // Reserved for TIGER/192
-    int HAVAL_5_160 = 7;  // Reserved for HAVAL (5 pass, 160-bit)
-    
-    int SHA256 = 8;       // SHA-256
-    int SHA384 = 9;       // SHA-384
-    int SHA512 = 10;      // SHA-512
-    int SHA224 = 11;      // SHA-224
-    int SHA3_256 = 12;    // SHA3-256
-    int SHA3_512 = 14;    // SHA3-512
+    /**
+     * MD5.
+     * Implementations MUST NOT use this to generate signatures.
+     * Implementations MUST NOT use this as a hash function in ECDH KDFs.
+     * Implementations MUST NOT generate packets with this hash function in an S2K KDF.
+     * Implementations MUST NOT use this hash function in an S2K KDF to decrypt v6+ packets.
+     */
+    int MD5 = 1;
+    /**
+     * SHA-1.
+     * Implementations MUST NOT use this to generate signatures.
+     * Implementations MUST NOT use this as a hash function in ECDH KDFs.
+     * Implementations MUST NOT generate packets with this hash function in an S2K KDF.
+     * Implementations MUST NOT use this hash function in an S2K KDF to decrypt v6+ packets.
+     */
+    int SHA1 = 2;
+    /**
+     * RIPEMD-160.
+     * Implementations MUST NOT use this to generate signatures.
+     * Implementations MUST NOT use this as a hash function in ECDH KDFs.
+     * Implementations MUST NOT generate packets with this hash function in an S2K KDF.
+     * Implementations MUST NOT use this hash function in an S2K KDF to decrypt v6+ packets.
+     */
+    int RIPEMD160 = 3;
+    /**
+     * Reserved for double-width SHA (experimental).
+     */
+    int DOUBLE_SHA = 4;
+    /**
+     * Reserved for MD2.
+     */
+    int MD2 = 5;
+    /**
+     * Reserved for TIGER/192.
+     */
+    int TIGER_192 = 6;
+    /**
+     * Reserved for HAVAL (5 pass, 160-bit).
+     */
+    int HAVAL_5_160 = 7;
+    /**
+     * SHA2-256.
+     * Compliant implementations MUST implement.
+     */
+    int SHA256 = 8;
+    /**
+     * SHA2-384.
+     */
+    int SHA384 = 9;
+    /**
+     * SHA2-512.
+     */
+    int SHA512 = 10;
+    /**
+     * SHA2-224.
+     */
+    int SHA224 = 11;
+    /**
+     * SHA3-256.
+     */
+    int SHA3_256 = 12;
+    /**
+     * SHA3-512.
+     */
+    int SHA3_512 = 14;
 
+    /**
+     * Reserved for MD4.
+     * @deprecated non-standard
+     */
     int MD4 = 301;
-    int SHA3_224 = 312; // SHA3-224
-    int SHA3_256_OLD = 313; //SHA3-256
-    int SHA3_384 = 314; // SHA3-384
-    int SHA3_512_OLD = 315; // SHA3-512
+    /**
+     * Reserved for SHA3-224.
+     * @deprecated non-standard
+     */
+    int SHA3_224 = 312;
+    /**
+     * Reserved for SHA3-256.
+     * @deprecated non-standard
+     */
+    int SHA3_256_OLD = 313;
+    /**
+     * Reserved for SHA3-384.
+     * @deprecated non-standard
+     */
+    int SHA3_384 = 314;
+    /**
+     * Reserved for SHA3-512.
+     * @deprecated non-standard
+     */
+    int SHA3_512_OLD = 315;
 
-
-    int SM3 = 326; // SM3
+    /**
+     * Reserved for SM3.
+     * @deprecated non-standard
+     */
+    int SM3 = 326;
 
 }