Concept

Trust and verification

HexaEight provides a specific, well-defined set of trust properties. Knowing exactly what the SDK guarantees — and what it does not — is essential when designing a secure application. This page is a reference you can return to when reasoning about edge cases.

What HexaEight guarantees

The sender of a successfully decrypted message is who they claim to be

When DecryptEnvelopeAsync succeeds and returns a message with a populated Sender field, that sender identity is cryptographically verified. Producing that message required access to key material that only that specific identity could have obtained from the platform. The sender name in the decrypted payload cannot be forged by any other identity.

The content of a successfully decrypted message is unmodified

The encryption layer uses authenticated encryption. If any part of the encrypted payload has been altered in transit, the decrypt fails and the SDK throws an exception. There is no scenario in which the SDK accepts a decrypted message whose contents have been tampered with.

Encryption and decryption happen locally

You do not send your message data to the HexaEight platform for encryption or decryption. Both operations run inside the SDK, on your machine, using key material the platform issued at activation time and on key-derivation requests. The platform participates in key issuance only — not in the encrypted-message data path.

The full algorithm is published as a reference implementation. You can read the source, audit it, or run a working example yourself:

• Reference implementation: github.com/HexaEightTeam/deaddrop-encryption
• Run it in a browser sandbox: dotnetfiddle.net/p8GYS9

Authorisation rules apply to every message

When automatic enforcement is enabled (the default), every encrypted outbound message and every decrypted inbound message is checked against the policy file. There is no code path that bypasses this check while automatic enforcement is on.

SDK self-verification

HexaEight does not rely on traditional code-signing certificates to attest that an SDK binary is genuine. Instead, the SDK ships with its own verification capability built into the platform protocol. A repackaged or modified SDK is not able to operate against the platform. The internal mechanism is intentionally not documented in detail.

What HexaEight does NOT guarantee

The SDK provides cryptographic identity, end-to-end encryption, and policy enforcement at the message level. Several things are outside that boundary — they remain the application's or the operator's concern. This section is honest about those limits.

Operational compromise of an endpoint

The cryptographic guarantees apply to messages exchanged between well-behaved endpoints running unmodified SDK binaries. They do not protect against the following endpoint-side compromises:

• A human gaining control of a legitimate identity — if an attacker physically obtains a user's phone with their Authenticator app, or gains operator-level control of a machine where an agent identity has been activated, they can impersonate that identity. The SDK cannot distinguish actions taken by the legitimate operator from actions taken by an attacker who has displaced them. This is a general property of any identity system and is outside the SDK's threat model.
• Tampered application code — the application that calls the SDK is part of the trust boundary. If an attacker replaces your application binary with a modified one, they control what the SDK is asked to do on your behalf.

The semantic meaning of a message

The SDK verifies who sent a message. It does not interpret what the message says. If a message decrypts to "transfer all funds" and is correctly attributed to the sender, the SDK has done its job — whether the recipient should act on it is an application decision.

Claims that the sender's application supplies itself

Some payload fields are populated by the HexaEight platform during encryption — the Sender field is the canonical example. Other fields are populated by the sender's application code (FinalRecipient and OriginalSender in relay scenarios, and any application-defined data carried in the body).

The platform-set fields are cryptographically guaranteed. The application-set claims are only as trustworthy as the application that produced them. If an application embeds the claim "I am acting on behalf of [email protected]," the SDK does not independently verify that user-a has actually authorised the sender. Authorisation rules can reference these claims, but a rule that grants permission based on an unverified claim is implicitly trusting the claiming application. Use such rules with awareness.

Delivery guarantees

The SDK produces and consumes envelopes. It does not deliver them. Whether a message reaches its destination — and whether it does so exactly once, in order, durably — is determined by the transport you choose (HTTP, message queue, file drop, ntfy notification, etc.). The SDK has no opinion on delivery semantics.

The structure of the message body

The body of a message is an opaque string from the SDK's perspective. It could be JSON, plain text, binary, or anything else. The SDK does not parse it. The format of the body, the protocol it implies, and what behaviour the recipient should exhibit on receipt are entirely the application's responsibility.

Verification you can perform yourself

Content signatures inside the body

If you want a stronger property than "the message was sent by this identity" — for example, "this message was authored by this identity and survived any number of relays unmodified" — you can ask the sending application to embed a HexaEight content signature inside the body. The signature is independent of the encryption layer; it travels through any number of relay agents unchanged. Any recipient who knows the original sender's identity can verify it.

Auditing the policy file

The policy file is a plain CSV (when stored locally) or a HexaEight-encrypted CSV (when stored in a swarm). It is human-readable in both cases (when decrypted) and can be reviewed, version-controlled, or audited like any other configuration artifact.

Auditing the SDK's logs

The SDK writes audit log entries through the standard logging system. Every authorisation decision, every policy change, every state transition (such as enabling swarm mode) produces a log entry. These logs can be aggregated using whatever observability platform your application already uses.

Operational responsibilities

The SDK is not a complete security system; it is one layer in a larger stack. The following responsibilities remain with the application or the operator:

• Secure storage of hexaeight.mac and env-file credentials on each machine
• Secure distribution of the Swarm Key when running in swarm mode
• Authentication of the user supplying input to the agent (if the agent acts on user input)
• Validation of the message body (parsing, schema checks, content moderation)
• Operational monitoring, alerting, and incident response