Summary#
Crypto.SealToHost lets a page take a credential — an API token, a password — and hand it to one host without
the server in between ever holding it. The browser seals it to the host's public key; the server only ever sees the
sealed text, which it can store or pass on but cannot open.
| what it is | |
|---|---|
publicKey | the host's P-256 public key, as base64 SPKI (or PEM) |
host, kind, name | what the sealed text is FOR — it opens only as these three, so it cannot be replayed as another credential |
fromField: | the name of a password input on the page, which must have no value: binding |
| the answer | the sealed text, fcs1.… |
Signature#
string sealedText = Crypto.SealToHost(hostKey, "ft-mini", "github", "GH_TOKEN", fromField: "token");Description#
A page that hands a host a token#
string HostKey() {
return ""; // the host's published P-256 public key, base64 SPKI
}
void Store(string sealedText) {
Log.Information("stored a sealed credential of {Length} characters", sealedText.Length);
}
[Route("/credential")]
[AllowAnonymous]
component Credential() {
action Save() {
string sealedText = Crypto.SealToHost(HostKey(), "ft-mini", "github", "GH_TOKEN", fromField: "token");
Store(sealedText);
}
render {
Input(type: "password", name: "token"); // NO `value:` — the verb reads it, seals it, and empties it
Button("Save", onPress: Save);
}
}Why the value is a field NAME and not an argument#
When an action awaits a server function — Store above — the page hands the server a continuation: the action's
locals, so the server can resume it. A trace records the same locals. If the value were an argument, a local or a
bound component field, it would ride that continuation to the server. Naming the input keeps the plaintext in the
input until it is sealed, and nowhere after.
So the verb refuses a bound input (Input(value: draft, …)) with a message saying why — a binding has already
copied every keystroke into component state — and the compiler refuses a value handed to it directly:
Crypto.SealToHost(key, "h", "k", "n", "ghp_…") does not compile. The input is emptied once it has been read, whether
the seal succeeded or not.
A page that is wrong — no input by that name, two of them, a bound one, an empty one, a key that is not a P-256
public key, a host, kind or name that is empty or contains | — throws an InvalidOperationException, and
nothing is sealed.
The format#
fcs1.<eph>.<nonce>.<ciphertext> each part base64url, no padding| part | what it is |
|---|---|
eph | the SPKI of a fresh ephemeral P-256 key — a new one for every seal |
| key | HKDF-SHA256 over the ECDH shared secret (the x-coordinate) of eph and the host's key; salt = eph's SPKI bytes, info = factory-credential-v1, 32 bytes |
nonce | 12 random bytes |
ciphertext | AES-256-GCM of the UTF-8 value under that key and nonce, with the 16-byte tag appended, and the additional data below |
The additional data is the UTF-8 of fcs1|host|kind|name — which is why none of the three may contain |.
The host opens it with its private key: ECDH with eph, the same HKDF, and AES-GCM with the same additional data. In
.NET that is ECDiffieHellman.DeriveRawSecretAgreement, HKDF.DeriveKey and AesGcm.Decrypt. Opened as any other
host, kind or name, the tag does not verify and nothing is returned. Sealing the same value twice gives different text.
See also#
- Crypto.Encrypt and Crypto.Decrypt — encryption under your own app's key, on the server
- Setting a secret from a page — the value goes from the browser to each zone — the same input-by-name rule, for a zone's secret
- component — actions, and where a client verb is called from