Skip to main content

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.

generate.stofPlayground ↗
#[main]
fn main() {
  const identity = Age::generate();
  pln(Age::public(identity).len() > 0);
}
Output

Age::public(age: Data<Age> | str) -> str​

The public half of an identity — safe to share, since it can only encrypt, not decrypt.

public.stofPlayground ↗
#[main]
fn main() {
  const identity = Age::generate();
  pln(Age::public(identity));
}
Output

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.

blobify.stofPlayground ↗
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);
}
Output

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:

parse.stofPlayground ↗
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);
}
Output

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.

pass-blobify.stofPlayground ↗
secret: "the launch codes"

#[main]
fn main() {
  const encrypted = Age::pass_blobify("correct-horse-battery-staple");
  pln(encrypted.len() > 0);
}
Output

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:

pass-parse.stofPlayground ↗
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);
}
Output

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:

sign-and-encrypt.stofPlayground ↗
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);
  }
}
Output

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).