# Age Encryption (Age)

[Age](https://crates.io/crates/age) is a simple, modern, and secure file encryption library. Within Stof, it enables distributed & embedded Age encryption for sensitive data, in the form of a complete document or sections of a Stof document in the format of choice.

This is useful when you have a portion of a Stof document that you want to encrypt before sending to someone else (Ex. distributed systems, collaborative AI, etc.).

The API itself is a simple extension of the [standard library (Std)](/libraries/standard-library-std.md) parse & blobify functions.

* To encrypt, use the `Age.blobify` function with Age public key(s) (recipients) as the first argument.
* To decrypt, use the `Age.parse` function with a `Data<Age>` component associated with one of the public keys used to encrypt as the first argument.
* Generate a new Age data component with `Age.generate` and retrieve its public key via `Age.public`.

## Example

{% hint style="success" %}
The Age library is included in the JS bindings, so copy the below example into the [playground](https://play.stof.dev/) to see it work!
{% endhint %}

<pre class="language-rust"><code class="lang-rust">/// Receiver in real life will most likely be a remote system.
/// Public keys could come from DB, HTTP, etc.
Receiver: {
    #[private]
    const passport: Age.generate()

    fn key() -> str {
        self.passport.public()
    }

    fn receive(encrypted: blob) -> str {
        const dest = new {};
<strong>        Age.parse(self.passport, encrypted, dest, "bstf");
</strong><strong>        ?dest.speak();
</strong>        dest.message ?? "none"
    }
}


#[main]
fn sending_sensitive() {
    // Create a binary blob of encrypted data that only the receiver can use
    const encrypted: blob = {
        // Create the payload, including Stof functions/APIs
        const payload = new { message: "hey there, this is secret" };
<strong>        parse(r#"fn speak() { pln('Speaking: ', self.message); }"#, payload, "stof");
</strong>
        // Can use one or more receivers Data&#x3C;Age> or str public keys (list for multiple)
<strong>        const res = Age.blobify(self.Receiver.key(), "bstf", payload);
</strong>        drop(payload);
        res
    };

    // Now have the receiver do what it wants with it
<strong>    const msg = self.Receiver.receive(encrypted);
</strong>    assert_eq(msg, "hey there, this is secret");
}
</code></pre>

#### Output

```
> stof run example.stof
Speaking: hey there, this is secret
```

## Age.blobify(recipients: str | list | Data\<Age>, format: str = 'stof', context?: obj) -> blob

Std.blobify, but with age public-key recipients. The resulting blob can only be parsed by a recipient's private key.

## Age.generate(context: obj = self) -> Data\<Age>

Generate a new Age Identity (Data) on the given context object (default is self).

## Age.parse(age: Data\<Age>, bin: blob, context: obj = self, format: str = "stof") -> bool

Parse an age-encrypted binary. Similar to Std.parse, but requires an Age identity (secret private key).

## Age.public(age: Data\<Age>) -> str

Get the public key for a given age identity.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stof.dev/libraries/age-encryption-age.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.