From b72f63786fd3d8a3dcbf389bde5b8e1e4482fbb3 Mon Sep 17 00:00:00 2001
From: Michael Vorburger <mike@vorburger.ch>
Date: Sat, 4 Jan 2025 17:45:21 +0100
Subject: [PATCH] clean(docs): Clarify supported MAC Hash Functions for
 Resource Integrity

---
 docs/use/fetch/index.md                       | 12 ++++--
 .../common/io/hashbrown/Multihashes.java      | 40 ++++++++++++++++---
 .../common/io/resource/IPFSResource.java      |  3 +-
 learn/jbang/digests.java                      | 27 +++++++++++++
 4 files changed, 72 insertions(+), 10 deletions(-)
 create mode 100644 learn/jbang/digests.java

diff --git a/docs/use/fetch/index.md b/docs/use/fetch/index.md
index 0edee1496..64e17e46e 100644
--- a/docs/use/fetch/index.md
+++ b/docs/use/fetch/index.md
@@ -170,9 +170,10 @@ the Charset from the Media Type (if any) or any HTTP header like mechanisms.
 
 ### Integrity
 
-Add `?integrity=...` verifies resource integrity via a [cryptographic digest ("hash")])(https://docs.ipfs.tech/concepts/hashing/)
-using a [Multiformats's Multibase encoded Multihash](https://www.multiformats.io), this works for all schemes:
-(Similarly e.g. to [HTML's Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity).)
+Adding `?integrity=...` verifies resources via a [cryptographic digest ("hash")](https://docs.ipfs.tech/concepts/hashing/)
+using a [Multiformats's Multibase encoded Multihash](https://www.multiformats.io).
+(This is similar e.g. to [HTML's Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity).)
+It works for all schemes:
 
 ```bash cd ../.././..
 $ ./enola fetch "/tmp/hi.txt?integrity=z8VxiEEn4n7uuGrVQjeoH2KYypytUHttCubqN7rr65xSH3wjLDjHciXuTyTHkoRuJT1Njghj68RQdynADQt9vzLgyEs"
@@ -187,13 +188,16 @@ $ ./enola fetch --http-scheme "https://www.vorburger.ch/hello.md?integrity=z8Vtt
 ```
 
 In order to find the expected Multibase encoded Multihash,
-it's simplest to once use a wrong one, and then replace it with the correct one shown by the error message:
+it's simplest to once use a wrong one, and then replace it with the correct one which is shown by the error message:
 
 ```bash $? cd ../.././..
 $ ./enola fetch --http-scheme "https://www.vorburger.ch/hello.md?integrity=z8VsnXyGnRwJpnrQXB8KcLstvgFYGZ2f5BCm3DVndcNZ8NswtkCqsut69e7yd1FKNtettjgy669GNVt8VSTGxkAiJaB"
 ...
 ```
 
+Note that while [Multihash](https://www.multiformats.io/multihash/) defines codes for [various hash functions](https://github.com/multiformats/multicodec/blob/master/table.csv),
+Enola (currently) [intentionally](https://github.com/google/guava/issues/5990#issuecomment-2571350434) only actually supports `sha2-256` & `sha2-512`.
+
 <!-- TODO ?cache from OptionalCachingResourceProvider (current un-used) -->
 
 <!--
diff --git a/java/dev/enola/common/io/hashbrown/Multihashes.java b/java/dev/enola/common/io/hashbrown/Multihashes.java
index f58199928..de7cfca9d 100644
--- a/java/dev/enola/common/io/hashbrown/Multihashes.java
+++ b/java/dev/enola/common/io/hashbrown/Multihashes.java
@@ -29,14 +29,44 @@ public final class Multihashes {
     public static HashFunction toGuavaHashFunction(Multihash multihash) {
         var type = multihash.getType();
         return switch (type) {
-            // @Deprecated case md5 -> Hashing.md5();
-            // @Deprecated case sha1 -> Hashing.sha1();
+            // NB: Please BEWARE of what types are added here; the (sub)selection is intentional!
+
+            // TODO Support murmur3-x64-64, https://github.com/multiformats/java-multihash/pull/43
+            //   case murmur3_x64_128 ->  Hashing.murmur3_128();
+            // PS: Not suitable, as it's too tiny: case murmur3 -> Hashing.murmur3_32_fixed();
+
+            // TODO Support AES-CMAC https://developers.google.com/tink/supported-key-types#mac ?
+            //   Pending https://github.com/multiformats/multicodec/issues/368
+            //   Using https://developers.google.com/tink/protect-data-from-tampering#java
+
             case sha2_256 -> Hashing.sha256();
             case sha2_512 -> Hashing.sha512();
-            // Not suitable, as it's tiny: case murmur3 -> Hashing.murmur3_32_fixed();
 
-            // TODO What about all other supported types?!
-            //   See https://github.com/multiformats/java-multihash/issues/41 ...
+            // TODO Add additional external libraries for other supported types?
+            //   See https://github.com/multiformats/java-multihash/blob/master/README.md#usage
+            //   from https://github.com/multiformats/java-multihash/pull/42/files
+            //   for https://github.com/multiformats/java-multihash/issues/41.
+
+            // See https://github.com/google/guava/issues/5990#issuecomment-2571350434 ...
+            // SHA-224 (sha2-224) available in JDK, not available in Multibase table; so N/A
+            // SHA-384 (sha2-384) available in JDK (but not Guava), and Multibase table, not API
+            // SHA-512/224 (sha2-512-224) available in JDK (but not Guava), and Multibase table !API
+            // SHA-512/256 (sha2-512-256) available in JDK (but not Guava), and Multibase table !API
+            // NB https://github.com/google/guava/issues/5990
+            // NB https://github.com/google/guava/issues/938
+            //
+            // NB https://github.com/google/guava/issues/3960
+            // SHA3-224
+            // SHA3-256
+            // SHA3-384
+            // SHA3-512
+            // Note "sha3 not being a very good choice" on
+            // https://github.com/google/guava/issues/3960#issuecomment-1080775346;
+            // and https://developers.google.com/tink/protect-data-from-tampering#java
+            // "recommend the HMAC_SHA256" (=sha2-256).
+
+            // @Deprecated case md5 -> Hashing.md5();
+            // @Deprecated case sha1 -> Hashing.sha1();
 
             default -> throw new IllegalArgumentException("Unsupported Multihash type: " + type);
         };
diff --git a/java/dev/enola/common/io/resource/IPFSResource.java b/java/dev/enola/common/io/resource/IPFSResource.java
index 19a0377c0..7b65e7f55 100644
--- a/java/dev/enola/common/io/resource/IPFSResource.java
+++ b/java/dev/enola/common/io/resource/IPFSResource.java
@@ -30,7 +30,8 @@
  *
  * <ol>
  *   <li>Support IPLD <=> Thing API bridge; see https://github.com/enola-dev/enola/issues/777.
- *   <li>Support writing - via a WritableResource, or (probably) a separate API?
+ *   <li>Support writing - via a WritableResource, or (probably) a separate API? Probably using
+ *       https://github.com/ipfs-shipyard/java-ipfs-http-client
  *   <li>Support ipns://
  * </ol>
  */
diff --git a/learn/jbang/digests.java b/learn/jbang/digests.java
new file mode 100644
index 000000000..7652733d2
--- /dev/null
+++ b/learn/jbang/digests.java
@@ -0,0 +1,27 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Copyright 2025 The Enola <https://enola.dev> Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+//JAVA 21+
+//PREVIEW
+
+import java.security.Security;
+import java.security.MessageDigest;
+
+void main() {
+     var messageDigests = Security.getAlgorithms("MessageDigest");
+     messageDigests.forEach(System.out::println);
+}