Age Encryption (Age)
Age encrypts a document, or part of one, so only the holder of a specific key or passphrase can read it back. It uses the age format, and it's available everywhere Stof runs, including JavaScript.
Age keys encrypt; Key keys sign. They're separate keys for separate jobs, and they work together. An identity from Age::generate lives on an object as Data<Age>: its secret never prints, but it's part of the object, so exporting the object (as bstf) carries it. Where an identity is taken, its secret key as a string works too (AGE-SECRET-KEY-1..., Ex. passed in by your app).
Age::generate(context: obj = self) -> Data<Age>
Generates a new identity — a public/private keypair — attached to the given object.
#[main]
fn main() {
const identity = Age::generate();
pln(Age::public(identity).len() > 0);
}Age::public(age: Data<Age> | str) -> str
The public half of an identity — safe to share, since it can only encrypt, not decrypt.
#[main]
fn main() {
const identity = Age::generate();
pln(Age::public(identity));
}Age::blobify(recipients: str | list | Data<Age>, format: str = 'stof', context?: obj) -> blob
Like Std.blobify, but encrypted to one or more recipients' public keys — only the matching private key can read the result back.
secret: "the launch codes"
#[main]
fn main() {
const identity = Age::generate();
const pubkey = Age::public(identity);
const encrypted = Age::blobify(pubkey);
pln(encrypted.len() > 0);
}Age::parse(age: Data<Age> | str, bin: blob, context: obj = self, format: str = "stof") -> bool
The other half of Age.blobify — decrypts using the matching identity, then parses the result into context the same way Std.parse would:
secret: "the launch codes"
#[main]
fn main() {
const identity = Age::generate();
const pubkey = Age::public(identity);
const encrypted = Age::blobify(pubkey);
const decrypted = new {};
const ok = Age::parse(identity, encrypted, decrypted);
pln(ok, ' ', decrypted.secret);
}Age::pass_blobify(passphrase: str, format: str = 'stof', context?: obj) -> blob
The simpler alternative to Age.blobify — a shared passphrase instead of a generated identity, when there's no real recipient to manage keys for.
secret: "the launch codes"
#[main]
fn main() {
const encrypted = Age::pass_blobify("correct-horse-battery-staple");
pln(encrypted.len() > 0);
}Age::pass_parse(passphrase: str, bin: blob, context: obj = self, format: str = "stof") -> bool
Decrypts what Age.pass_blobify produced — the same passphrase in, the original document back out:
secret: "the launch codes"
#[main]
fn main() {
const encrypted = Age::pass_blobify("correct-horse-battery-staple");
const decrypted = new {};
const ok = Age::pass_parse("correct-horse-battery-staple", encrypted, decrypted);
pln(ok, ' ', decrypted.secret);
}With Key
Age makes sure only the reader can open something; a signature makes sure the reader knows who sent it. Encrypt to the reader, then sign what you encrypted:
message: { text: 'meet at noon' }
#[main]
fn main() {
const reader = Age::generate();
const sender = Key::generate();
const box = Age::blobify(Age::public(reader), 'json', self.message);
const signature = Key::sign(sender, 'messages/v1', box);
// the reader: check who sent it, then open it
if (Key::verify(Key::public(sender), 'messages/v1', box, signature)) {
const opened = new {};
Age::parse(reader, box, opened, 'json');
pln(opened.text);
drop(opened);
}
}To keep a secret (a signing key, say) in a document at rest, encrypt it with a passphrase: Age::pass_blobify(passphrase, 'bstf', self.keys).