[feature] Add crypto:hash for EXPath spec completeness

joewiz · claude · joewiz · commit 6a170e474a03 · 2026-03-20T21:09:35.000-04:00
Implements crypto:hash($data, $algorithm) and crypto:hash($data,
$algorithm, $encoding) per the EXPath Cryptographic Module spec.
Accepts string, binary, and node input. Supports MD5, SHA-1, SHA-256,
SHA-384, SHA-512 with base64 (default) or hex output.

For new code, fn:hash() (XQuery 4.0) or util:hash() are preferred.
crypto:hash is provided for backward compatibility and cross-engine
portability (BaseX also implements it).

11 new tests (46 total), CI smoke test added.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/exist.yml b/.github/workflows/exist.yml
@@ -57,6 +57,18 @@ jobs:
           sleep 5
 
       # Smoke test: verify module loads and functions work
+      - name: Test crypto:hash with known SHA-256 vector
+        run: |
+          result=$(curl -sf -u admin: -H "Content-Type: application/xml" --data '
+          <query xmlns="http://exist.sourceforge.net/NS/exist">
+            <text><![CDATA[
+              import module namespace crypto = "http://expath.org/ns/crypto";
+              crypto:hash("test", "SHA-256", "hex")
+            ]]></text>
+          </query>' "http://localhost:8080/exist/rest/db")
+          echo "$result"
+          echo "$result" | grep -q "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" || (echo "FAIL: SHA-256 hash mismatch" && exit 1)
+
       - name: Test crypto:hmac with SHA256 hex output
         run: |
           result=$(curl -sf -u admin: -H "Content-Type: application/xml" --data '
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # EXPath Crypto Module for eXist-db
 
-A standalone XAR package implementing the [EXPath Cryptographic Module](http://expath.org/spec/crypto) for eXist-db 7.0+. Provides HMAC authentication, symmetric encryption/decryption, and XML digital signatures using Java's built-in JCE (Java Cryptography Extension) — no external dependencies.
+A standalone XAR package implementing the [EXPath Cryptographic Module](http://expath.org/spec/crypto) for eXist-db 7.0+. Provides cryptographic hashing, HMAC authentication, symmetric encryption/decryption, and XML digital signatures using Java's built-in JCE (Java Cryptography Extension) — no external dependencies.
 
 ## Install
 
@@ -14,6 +14,8 @@ xst package install exist-crypto-1.0.0.xar
 
 | Function | Description |
 |----------|-------------|
+| `crypto:hash($data, $algorithm)` | Cryptographic hash with Base64 output |
+| `crypto:hash($data, $algorithm, $encoding)` | Cryptographic hash with specified encoding (`base64` or `hex`) |
 | `crypto:hmac($data, $key, $algorithm)` | HMAC with Base64 output |
 | `crypto:hmac($data, $key, $algorithm, $encoding)` | HMAC with specified encoding (`base64` or `hex`) |
 | `crypto:encrypt($data, $type, $key, $algorithm)` | Symmetric encryption (AES or DES) |
@@ -23,6 +25,22 @@ xst package install exist-crypto-1.0.0.xar
 
 **Module namespace:** `http://expath.org/ns/crypto`
 
+### Hash
+
+```xquery
+import module namespace crypto = "http://expath.org/ns/crypto";
+
+(: Base64 output (default) :)
+crypto:hash("data", "SHA-256")
+
+(: Hex output :)
+crypto:hash("data", "SHA-256", "hex")
+```
+
+**Algorithms:** MD5, SHA-1, SHA-256, SHA-384, SHA-512
+
+For new code, prefer `fn:hash()` (XQuery 4.0) or `util:hash()`. `crypto:hash` is provided for backward compatibility with the EXPath spec and cross-engine portability (BaseX also implements it).
+
 ### HMAC
 
 ```xquery
@@ -74,7 +92,7 @@ This package is a clean-room replacement for the legacy [`expath-crypto-module`]
 | **Java version** | Java 8+ | Java 21+ |
 | **Dependencies** | External `crypto-java` library (ro.kuberam) | Zero — uses Java's built-in JCE |
 | **Parent POM** | `exist-apps-parent` 1.11.0 | `exist-apps-parent` 2.0.0 |
-| **`crypto:hash`** | Yes (2–3 arity) | No (use XQuery 4.0's built-in `fn:hash` instead) |
+| **`crypto:hash`** | Yes (2–3 arity) | Yes (2–3 arity, compatible) |
 
 ### Upgrade steps
 
@@ -104,7 +122,7 @@ The module namespace is identical, so **import statements require no changes**:
 import module namespace crypto = "http://expath.org/ns/crypto";
 ```
 
-Calls to `crypto:hmac` and `crypto:validate-signature` are compatible as-is for the most common usage patterns.
+Calls to `crypto:hash`, `crypto:hmac`, and `crypto:validate-signature` are compatible as-is for the most common usage patterns.
 
 #### `crypto:hmac` — return type changed
 
@@ -144,23 +162,16 @@ The 6-argument form is compatible. The XPath subsetting (7-arg), certificate (8-
 
 **If you used XPath subsetting or certificates:** These features are not yet available. File an issue if you need them.
 
-#### `crypto:hash` — removed
-
-The legacy module provided `crypto:hash($data, $algorithm)` for basic hashing. This function is not included because eXist-db's XQuery 4.0 Functions branch provides the standard `fn:hash()`:
-
-```xquery
-(: Legacy :)
-crypto:hash("data", "SHA-256")
+#### `crypto:hash` — return type changed
 
-(: New — use fn:hash from XQuery 4.0 :)
-fn:hash("data", "SHA-256")
-```
+| | Legacy | New |
+|---|---|---|
+| **Parameter types** | `$data as item()*` | `$data as item()` |
+| **Return type** | `xs:byte*` | `xs:string` |
 
-If you are on an eXist-db version without `fn:hash`, you can use `util:hash()` which has been available since eXist-db 4.x:
+The legacy module returned a byte sequence. The new module returns a string (Base64 or hex encoded). The function signatures and algorithm names are otherwise compatible.
 
-```xquery
-util:hash("data", "SHA-256")
-```
+For new code, prefer `fn:hash()` (XQuery 4.0) or `util:hash()`. `crypto:hash` is provided for backward compatibility with the EXPath Cryptographic Module specification and cross-engine portability (BaseX also implements it).
 
 ### Package identity comparison
 
diff --git a/src/main/java/org/exist/xquery/modules/crypto/CryptoModule.java b/src/main/java/org/exist/xquery/modules/crypto/CryptoModule.java
@@ -54,6 +54,8 @@ public class CryptoModule extends AbstractInternalModule {
                     EncryptFunction.FS_ENCRYPT),
             functionDefs(GenerateSignatureFunction.class,
                     GenerateSignatureFunction.FS_GENERATE_SIGNATURE),
+            functionDefs(HashFunction.class,
+                    HashFunction.FS_HASH),
             functionDefs(HmacFunction.class,
                     HmacFunction.FS_HMAC),
             functionDefs(ValidateSignatureFunction.class,
diff --git a/src/main/java/org/exist/xquery/modules/crypto/HashFunction.java b/src/main/java/org/exist/xquery/modules/crypto/HashFunction.java
@@ -0,0 +1,161 @@
+/*
+ * eXist-db Open Source Native XML Database
+ * Copyright (C) 2001 The eXist-db Authors
+ *
+ * info@exist-db.org
+ * http://www.exist-db.org
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+package org.exist.xquery.modules.crypto;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.util.Base64;
+import java.util.HexFormat;
+
+import org.exist.xquery.BasicFunction;
+import org.exist.xquery.FunctionSignature;
+import org.exist.xquery.XPathException;
+import org.exist.xquery.XQueryContext;
+import org.exist.xquery.value.BinaryValue;
+import org.exist.xquery.value.Item;
+import org.exist.xquery.value.NodeValue;
+import org.exist.xquery.value.Sequence;
+import org.exist.xquery.value.StringValue;
+import org.exist.xquery.value.Type;
+
+import static org.exist.xquery.FunctionDSL.*;
+
+/**
+ * Implements {@code crypto:hash()} — cryptographic hashing.
+ *
+ * <p>Two arities:</p>
+ * <ul>
+ *   <li>{@code crypto:hash($data, $algorithm)} — Base64 output (default)</li>
+ *   <li>{@code crypto:hash($data, $algorithm, $encoding)} — hex or base64</li>
+ * </ul>
+ *
+ * <p>Accepts string, binary, and node input. Nodes are serialized to their
+ * string value before hashing.</p>
+ *
+ * <p>For new code, prefer {@code fn:hash()} (XQuery 4.0) or {@code util:hash()}.
+ * {@code crypto:hash} is provided for backward compatibility with the EXPath
+ * Cryptographic Module specification and cross-engine portability (BaseX also
+ * implements it).</p>
+ *
+ * <p>Supported algorithms: MD5, SHA-1, SHA-256, SHA-384, SHA-512.</p>
+ */
+public class HashFunction extends BasicFunction {
+
+    private static final String FS_HASH_NAME = "hash";
+
+    public static final FunctionSignature[] FS_HASH = functionSignatures(
+            CryptoModule.qname(FS_HASH_NAME),
+            "Computes the hash of the given data using the specified algorithm. " +
+                    "For new code, prefer fn:hash() (XQuery 4.0) or util:hash(). " +
+                    "crypto:hash is provided for backward compatibility and cross-engine portability.",
+            returns(Type.STRING, "the hash value as a base64 or hex string"),
+            arities(
+                    arity(
+                            param("data", Type.ITEM, "The data to hash " +
+                                    "(xs:string, xs:base64Binary, xs:hexBinary, or node)."),
+                            param("algorithm", Type.STRING,
+                                    "The hash algorithm: MD5, SHA-1, SHA-256, SHA-384, or SHA-512.")
+                    ),
+                    arity(
+                            param("data", Type.ITEM, "The data to hash " +
+                                    "(xs:string, xs:base64Binary, xs:hexBinary, or node)."),
+                            param("algorithm", Type.STRING,
+                                    "The hash algorithm: MD5, SHA-1, SHA-256, SHA-384, or SHA-512."),
+                            param("encoding", Type.STRING,
+                                    "The output encoding: 'base64' (default) or 'hex'.")
+                    )
+            )
+    );
+
+    public HashFunction(final XQueryContext context, final FunctionSignature signature) {
+        super(context, signature);
+    }
+
+    @Override
+    public Sequence eval(final Sequence[] args, final Sequence contextSequence) throws XPathException {
+        if (args[0].isEmpty()) {
+            return Sequence.EMPTY_SEQUENCE;
+        }
+
+        final Item data = args[0].itemAt(0);
+        final String algorithm = args[1].getStringValue();
+        final String encoding = getArgumentCount() == 3 ? args[2].getStringValue() : "base64";
+
+        final String jceAlgorithm = toJceAlgorithm(algorithm);
+
+        try {
+            final MessageDigest digest = MessageDigest.getInstance(jceAlgorithm);
+            final byte[] input = itemToBytes(data);
+            final byte[] hash = digest.digest(input);
+
+            final String encoded;
+            if ("hex".equalsIgnoreCase(encoding)) {
+                encoded = HexFormat.of().formatHex(hash);
+            } else if ("base64".equalsIgnoreCase(encoding)) {
+                encoded = Base64.getEncoder().encodeToString(hash);
+            } else {
+                throw new XPathException(this,
+                        "Unsupported encoding: " + encoding + ". Use 'base64' or 'hex'.");
+            }
+
+            return new StringValue(this, encoded);
+        } catch (final NoSuchAlgorithmException e) {
+            throw new XPathException(this, "Unsupported hash algorithm: " + algorithm, e);
+        }
+    }
+
+    /**
+     * Converts an XQuery item to a byte array for hashing.
+     */
+    private byte[] itemToBytes(final Item item) throws XPathException {
+        return switch (item.getType()) {
+            case Type.BASE64_BINARY, Type.HEX_BINARY -> {
+                try (final InputStream is = ((BinaryValue) item).getInputStream()) {
+                    yield is.readAllBytes();
+                } catch (final IOException e) {
+                    throw new XPathException(this, "Failed to read binary data: " + e.getMessage(), e);
+                }
+            }
+            default -> item.getStringValue().getBytes(StandardCharsets.UTF_8);
+        };
+    }
+
+    /**
+     * Normalizes the user-supplied algorithm name to a JCE MessageDigest identifier.
+     * Accepts both hyphenated (SHA-256) and bare (SHA256) forms.
+     */
+    private String toJceAlgorithm(final String algorithm) throws XPathException {
+        return switch (algorithm.toUpperCase().replace("-", "")) {
+            case "MD5" -> "MD5";
+            case "SHA1" -> "SHA-1";
+            case "SHA256" -> "SHA-256";
+            case "SHA384" -> "SHA-384";
+            case "SHA512" -> "SHA-512";
+            default -> throw new XPathException(this,
+                    "Unsupported hash algorithm: " + algorithm +
+                            ". Supported: MD5, SHA-1, SHA-256, SHA-384, SHA-512.");
+        };
+    }
+}
diff --git a/src/test/java/org/exist/xquery/modules/crypto/CryptoModuleTest.java b/src/test/java/org/exist/xquery/modules/crypto/CryptoModuleTest.java
@@ -194,6 +194,108 @@ public void validateTamperedSignatureFails() throws XMLDBException {
                 "false", result.getResource(0).getContent().toString());
     }
 
+    // ===== crypto:hash tests =====
+
+    @Test
+    public void hashSha256Base64() throws XMLDBException {
+        final ResourceSet result = existEmbeddedServer.executeQuery(
+                CRYPTO_IMPORT + "crypto:hash('test', 'SHA-256')");
+        final String hash = result.getResource(0).getContent().toString();
+        assertTrue("SHA-256 base64 hash should be non-empty", hash.length() > 0);
+        // SHA-256 base64 is always 44 characters (32 bytes -> 44 base64 chars with padding)
+        assertEquals("SHA-256 base64 should be 44 chars", 44, hash.length());
+    }
+
+    @Test
+    public void hashSha256Hex() throws XMLDBException {
+        final ResourceSet result = existEmbeddedServer.executeQuery(
+                CRYPTO_IMPORT + "crypto:hash('test', 'SHA-256', 'hex')");
+        final String hash = result.getResource(0).getContent().toString();
+        assertEquals("SHA-256 hex should be 64 chars", 64, hash.length());
+        assertTrue("Should be hex chars only", hash.matches("[0-9a-f]+"));
+        // Known test vector: SHA-256("test") = 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
+        assertEquals("SHA-256 of 'test' should match known vector",
+                "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", hash);
+    }
+
+    @Test
+    public void hashMd5Hex() throws XMLDBException {
+        final ResourceSet result = existEmbeddedServer.executeQuery(
+                CRYPTO_IMPORT + "crypto:hash('test', 'MD5', 'hex')");
+        assertEquals("MD5 hex should be 32 chars", 32,
+                result.getResource(0).getContent().toString().length());
+    }
+
+    @Test
+    public void hashSha1Hex() throws XMLDBException {
+        final ResourceSet result = existEmbeddedServer.executeQuery(
+                CRYPTO_IMPORT + "crypto:hash('test', 'SHA-1', 'hex')");
+        assertEquals("SHA-1 hex should be 40 chars", 40,
+                result.getResource(0).getContent().toString().length());
+    }
+
+    @Test
+    public void hashSha384Hex() throws XMLDBException {
+        final ResourceSet result = existEmbeddedServer.executeQuery(
+                CRYPTO_IMPORT + "crypto:hash('test', 'SHA-384', 'hex')");
+        assertEquals("SHA-384 hex should be 96 chars", 96,
+                result.getResource(0).getContent().toString().length());
+    }
+
+    @Test
+    public void hashSha512Hex() throws XMLDBException {
+        final ResourceSet result = existEmbeddedServer.executeQuery(
+                CRYPTO_IMPORT + "crypto:hash('test', 'SHA-512', 'hex')");
+        assertEquals("SHA-512 hex should be 128 chars", 128,
+                result.getResource(0).getContent().toString().length());
+    }
+
+    @Test
+    public void hashAcceptsBareAlgorithmName() throws XMLDBException {
+        // Accept "SHA256" without hyphen
+        final ResourceSet result = existEmbeddedServer.executeQuery(
+                CRYPTO_IMPORT + "crypto:hash('test', 'SHA256', 'hex')");
+        assertEquals("SHA256 (no hyphen) should work same as SHA-256",
+                "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
+                result.getResource(0).getContent().toString());
+    }
+
+    @Test
+    public void hashDefaultEncodingIsBase64() throws XMLDBException {
+        final ResourceSet explicit = existEmbeddedServer.executeQuery(
+                CRYPTO_IMPORT + "crypto:hash('data', 'SHA-256', 'base64')");
+        final ResourceSet defaultEnc = existEmbeddedServer.executeQuery(
+                CRYPTO_IMPORT + "crypto:hash('data', 'SHA-256')");
+        assertEquals("Default encoding should be base64",
+                explicit.getResource(0).getContent().toString(),
+                defaultEnc.getResource(0).getContent().toString());
+    }
+
+    @Test
+    public void hashNodeInput() throws XMLDBException {
+        // Hashing a node uses its string value
+        final ResourceSet result = existEmbeddedServer.executeQuery(
+                CRYPTO_IMPORT + "crypto:hash(<data>test</data>, 'SHA-256', 'hex')");
+        assertEquals("Hashing node should use its string value",
+                "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
+                result.getResource(0).getContent().toString());
+    }
+
+    @Test
+    public void hashEmptyStringProducesResult() throws XMLDBException {
+        final ResourceSet result = existEmbeddedServer.executeQuery(
+                CRYPTO_IMPORT + "crypto:hash('', 'SHA-256', 'hex')");
+        assertEquals("SHA-256 of empty string should be e3b0c44...",
+                "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+                result.getResource(0).getContent().toString());
+    }
+
+    @Test(expected = XMLDBException.class)
+    public void hashUnsupportedAlgorithmThrows() throws XMLDBException {
+        existEmbeddedServer.executeQuery(
+                CRYPTO_IMPORT + "crypto:hash('test', 'INVALID')");
+    }
+
     // ===== HMAC known test vectors =====
 
     @Test
