Experimental and unaudited. HIDE is hybrid post-quantum (X25519 + ML-KEM-768, Ed25519 + ML-DSA-65). See the security policy.
Java binding, through the Foreign Function & Memory API (Java 22+), to the same
Rust core (crates/hide-ffi) that the CLI and every other HIDE SDK use. This
package contains no cryptography of its own and needs no JNI glue.
Not on Maven Central yet. Build from source:
cargo build --release -p hide-ffi # produces the native core
cd sdk/java && mvn install # installs org.hide-protocol:hide at the version in pom.xmlThe version is the <version> of pom.xml, which is the HIDE
release the checkout is at; use that value in your own build:
<dependency>
<groupId>org.hide-protocol</groupId>
<artifactId>hide</artifactId>
<version><!-- the <version> in sdk/java/pom.xml --></version>
</dependency>The jar does not bundle the native library, and the binding must be told where it is: either copy it into the directory that holds the jar, or point at your build with the environment pair or the system-property pair — both halves are required (see Native library):
export HIDE_LIBRARY="$PWD/target/release/libhide_ffi.so" # hide_ffi.dll / libhide_ffi.dylib
export HIDE_ALLOW_LIBRARY_OVERRIDE=1
# or
java -Dhide.library=/path/to/libhide_ffi.so -Dhide.allowLibraryOverride=true ...The library must be the same release as the binding: at load the binding
compares hide_version() with its own version (exact major.minor.patch) and
throws UnsatisfiedLinkError on a mismatch, because a stale core would load
and silently lack whatever the newer release enforces.
Run with --enable-native-access=ALL-UNNAMED (or grant it to the module) to
silence the FFM restricted-method warning.
import org.hideprotocol.*;
import java.nio.charset.StandardCharsets;
import java.util.List;
try (SecretKey secret = SecretKey.generate()) {
byte[] box = Hide.encrypt("hello".getBytes(StandardCharsets.UTF_8),
List.of(secret.publicKey()), "note.txt", null);
Hide.Decrypted opened = Hide.decrypt(box, secret);
System.out.println(new String(opened.data(), StandardCharsets.UTF_8) + " " + opened.filename());
// hello note.txt
byte[] tampered = box.clone();
tampered[tampered.length - 1] ^= 1;
try {
Hide.decrypt(tampered, secret);
} catch (HideException.Authentication e) {
System.out.println("refused: " + e.getMessage());
// refused: authentication failed; the data was altered
}
}Hide.encrypt(plaintext, recipients, filename, mediaType) takes 1..64
recipient public keys, each exactly Hide.PUBLIC_KEY_LEN (1216) bytes;
metadata may be null. Hide.decrypt returns a Hide.Decrypted record with
data(), filename() and mediaType(); nothing is returned unless the whole
payload authenticates. The filename is attacker-controlled: never use it to
build an output path.
Keys on disk: secret.protect(passphrase) returns a sealed key file
(Hide.MIN_PASSPHRASE_LEN is 8, and there is no escrow); SecretKey.load(data, passphrase) opens one; Hide.inspectKey(data) reports "raw" or
"protected" without the passphrase. Hide.armorPublicKey /
Hide.dearmorPublicKey give a public key a pasteable text form.
Errors: every failure is a HideException (unchecked) — nested subclasses
HideException.Authentication (altered, or not a container), its subclass
HideException.Malformed (did not decode at all), WrongPassphrase,
NoMatchingRecipient, NotAKey, ChallengeExpired, ChallengeReplayed,
ChallengeAudience. Arguments this binding rejects before calling the core
throw IllegalArgumentException.
Text arguments must not contain a NUL character. Passphrases, the
filename, the media type, the challenge audience, armored key text and the
checkpoint origin cross the C boundary NUL-terminated, so a String carrying
'\0' would be silently cut at it: a key would be sealed under the part of the
passphrase before the NUL. Such a string throws IllegalArgumentException
instead. byte[] arguments (plaintext, context, message, keys) may contain any
byte.
One seed backs both encryption and signing, so there is a single thing to back up.
byte[] sealed = SigningIdentity.generate("correct horse battery"); // store this
try (SigningIdentity signer = SigningIdentity.load(sealed, "correct horse battery");
// The record answers for this verifier's name, and must outlive one request.
SpentNonces spent = new SpentNonces("app.example")) {
byte[] context = "myapp/v1 release".getBytes(StandardCharsets.UTF_8);
byte[] message = "payload".getBytes(StandardCharsets.UTF_8);
byte[] signature = signer.sign(context, message); // 3373 bytes
Hide.verify(signer.publicKey(), context, message, signature); // void; throws on failure
// Challenge/response: good once, here, now.
long now = System.currentTimeMillis() / 1000;
byte[] challenge = Hide.newChallenge("app.example", now, 60);
byte[] answer = signer.answer(challenge);
spent.accept(challenge, answer, signer.publicKey(), now);
spent.accept(challenge, answer, signer.publicKey(), now); // HideException.ChallengeReplayed
}context separates uses of one identity so a signature made for one purpose
cannot be replayed as another; never let a remote party choose it.
Hide.verify returns void and throws HideException.Authentication on
failure rather than returning a boolean a caller could forget to check.
Hide.sign(identity, context, message) is a static alias for signer.sign. A
key file written before signatures existed carries no signing seed and throws
HideException.NotAKey.
The nonce record must be built with the name this verifier answers to — the
same audience passed to Hide.newChallenge — because an answer minted for a
different audience is refused with HideException.ChallengeAudience, so a
challenge relayed from another service cannot be answered here. A record built
with an empty audience accepts nothing.
| Method | Returns |
|---|---|
Hide.verifyIdentity(log, recoveryKey) |
int — how many devices the log trusts now |
Hide.identityTrustsDevice(log, recoveryKey, devicePublicKey) |
boolean — membership, after verifying the log |
Hide.identityHead(log, recoveryKey) |
32 bytes naming this exact history |
Hide.verifyIdentityPinned(log, recoveryBinding, pinnedRoot) |
int — devices trusted now, only if the log is the pinned identity |
Hide.verifyEpochChain(chain) |
int — how many epochs it holds |
Hide.verifyEpochChainBound(log, recoveryBinding, pinnedRoot, chain, epochBinding) |
int — epochs, only if a device the pinned log trusts signed this chain |
Hide.epochPublicKey(chain, long epoch) |
the public key to encrypt to for epoch |
Hide.verifyInclusion(leaf, long index, long size, path, root) |
void |
Hide.verifyConsistency(long oldSize, long newSize, path, oldRoot, newRoot) |
void |
Hide.verifyCheckpoint(note, String origin, logPublicKey) |
Hide.Checkpoint(long size, byte[] root) of a signed checkpoint |
A cryptographic verify throws on failure (HideException.Malformed if the
bytes did not decode, HideException.Authentication if they decoded but did
not verify) and never returns false. The one boolean is
identityTrustsDevice: the log is verified first, so false means "not a
member", never "did not verify".
The core is always loaded from an absolute path, found in this order:
-Dhide.library=<path>, thenHIDE_LIBRARY, if it names a file and either-Dhide.allowLibraryOverride=trueorHIDE_ALLOW_LIBRARY_OVERRIDE=1is also set. Without the opt-in both are ignored, whatever they name;hide_ffi.dll/libhide_ffi.dylib/libhide_ffi.soin the directory that holds the jar (or, when the classes run unpacked, in the class directory itself).
If neither finds it, loading fails with an UnsatisfiedLinkError that says
what was tried. The library is never looked up by name through the system
loader: java.library.path, PATH, LD_LIBRARY_PATH / DYLD_LIBRARY_PATH
and the working directory are not searched, because whoever controls one of
those would otherwise choose the cryptographic core.
The jar does not carry a copy. The override is for development only: it replaces the entire cryptographic core, so a single settable property or environment variable must not be enough to redirect it.
Every static method of Hide is safe to call from any number of threads.
SpentNonces is safe for concurrent use: accept and close are
synchronized, so one record can be shared by every request thread, and an
answer presented by many threads at once is accepted by exactly one of them.
The record is in-process memory: it is not shared between JVMs and does not
survive a restart, so replay protection across several server instances needs
the accepted nonces in shared storage as well.
SecretKey and SigningIdentity may be used from several threads at once
(the core only reads them), but close() must not race with a call in flight
on the same object: close a handle only when nothing else is using it.
SecretKey, SigningIdentity and SpentNonces are opaque handles
implementing AutoCloseable. The seed bytes stay in the native library and
this SDK exposes no accessor for them; toString() shows only whether the
handle is open. Release with close() or try-with-resources. A closed handle
throws IllegalStateException on use.
- Unaudited. Do not protect data you cannot afford to lose or expose.
- An identity is a key, not a person: a verified signature proves possession of a seed, nothing about who holds it.
- Full threat model: docs/threat-model.md.
- Repository: https://github.com/hide-protocol/hide
- Documentation: docs/
- Specification: spec/hide-1.md
- CHANGELOG