https://github.com/exist-db/expath-crypto-module
expath
https://github.com/exist-db/expath-crypto-module
exist-db expath
Last synced: 5 days ago
JSON representation
expath
- Host: GitHub
- URL: https://github.com/exist-db/expath-crypto-module
- Owner: eXist-db
- License: lgpl-2.1
- Created: 2016-02-04T10:37:04.000Z (over 10 years ago)
- Default Branch: main
- Last Pushed: 2025-07-21T03:47:16.000Z (11 months ago)
- Last Synced: 2025-08-06T04:37:22.029Z (10 months ago)
- Topics: exist-db, expath
- Language: Java
- Homepage:
- Size: 245 KB
- Stars: 2
- Watchers: 15
- Forks: 11
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/eXist-db/expath-crypto-module/actions?query=workflow%3ACI)
[](https://app.codacy.com/gh/eXist-db/expath-crypto-module/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
# eXist-db implementation for EXPath Cryptographic Module
This is an eXist-db implementation of the [EXPath HTTP Crypto Module specification](http://expath.org/spec/crypto).
## Building from source
Requires:
* Java 21 or newer
* Maven 3.9 or newer
```bash
$ git clone https://github.com/eXist-db/expath-crypto-module.git
$ cd expath-crypto-module
$ mvn clean package
```
This will create a "expath-crypto-module-.xar" file in the target folder. The .xar file can be uploaded to any eXist-db version > 7.0.0-SNAPSHOT via the Dashboard.
### Currently implemented functions
* crypto:hash()
* crypto:hmac() (only for xs:string data for now)
* crypto:encrypt() (only for xs:string data and symmetric encryption for now)
* crypto:decrypt() (only for xs:string data and symmetric decryption for now)
* crypto:generate-signature() (only for XML data for now)
* crypto:validate-signature() (only for XML data for now)
### Currently implemented algorithms
* For crypto:hash(): "MD5", "SHA-1", "SHA-256", "SHA-384", "SHA-512".
* For crypto:hmac(): "HMAC-MD5", "HMAC-SHA-1", "HMAC-SHA-256", "HMAC-SHA-384", "HMAC-SHA-512".
### Documentation
For the latest version of the specification for this module see [http://expath.org/spec/crypto/editor](http://expath.org/spec/crypto/editor).
The implementation follows this specification.
### Security considerations
The crypto module is a security-sensitive library and operates on XML documents
that may come from untrusted sources. A few things to know when deploying or
auditing it:
* **XXE protection lives in this module, not in `conf.xml`.** eXist-db's
`` configuration in `conf.xml` controls catalog resolution and
validation mode, not entity processing. eXist hardens its *own* parsers by
calling `setFeature("...external-general-entities", false)` etc. at each call
site in Java code. The crypto module uses its own `DocumentBuilderFactory` /
`SAXParserFactory` instances (centralised in
`org.expath.exist.crypto.utils.SecureXmlParsers`), and **does not inherit**
those settings. Both signature paths now refuse DOCTYPE declarations
outright (`disallow-doctype-decl=true`), which is the OWASP-recommended
baseline. A strict `conf.xml` does not, on its own, protect callers of
`crypto:generate-signature` or `crypto:validate-signature` against XXE.
The doctype gate is currently hardcoded — we're being conservative for
this hardening round — and is open to follow-on PRs that expose an
opt-out (for example, an extra parameter or a module-level toggle) for
callers who legitimately need to validate signed documents that carry a
DOCTYPE declaration.
* **Signature algorithms are limited to SHA-1-based xmldsig methods**
(`RSA_SHA1`, `DSA_SHA1`) by the underlying `crypto-java` library, which has
not been updated to support SHA-256. JDK 17+ rejects these by default under
`org.jcp.xml.dsig.secureValidation` — see the
[JDK XML Signature security guide](https://docs.oracle.com/en/java/javase/21/security/java-xml-digital-signature-api-overview-and-tutorial.html)
for the policy. Don't sign new documents with these algorithms in production.
* **Symmetric encryption uses CBC (or unprefixed `AES`, which defaults to ECB)
without authentication.** There is no AEAD (e.g. AES-GCM) support, and the
module performs no HMAC-then-encrypt or encrypt-then-HMAC pairing. Ciphertext
integrity is the caller's responsibility — without it, CBC is vulnerable to
padding-oracle attacks, and ECB leaks plaintext structure.
* **Constant-time comparison is the caller's responsibility.** XQuery's `=`
operator is *not* constant-time. When comparing HMAC outputs or signature
values, an attacker who can measure timing can recover bytes. There is no
`crypto:verify-hmac` helper that compares in constant time; callers should
treat HMAC verification as a known sharp edge.
If you find what you believe is a security issue, please follow the
[eXist-db security policy](https://github.com/eXist-db/exist/security/policy)
rather than opening a public issue.
### Unit Tests
Unit Tests use [XQSuite](https://exist-db.org/exist/apps/doc/xqsuite) and can be found in the [src/test/xquery/crypto folder](src/test/xquery/crypto/).
To run tests:
```bash
$ mvn verify
```