---
title: "17.5 Releasing data: policies and trusted modules"
url: https://una-lang.org/en/learn/information-flow/releasing-data-policies-and-trusted-modules/
release: v0.4.0
edition: "0.2"
---

# 17.5 Releasing data: policies and trusted modules

## 17.5.1 What a policy is

Some flows to a lower label are the point of the program. A report must say how many lines a file has. A log should say which customer a notice went to, without the address. Lowering a label on purpose is called **declassifying**, or **releasing**, the data.

In a well-run office, a confidential document leaves the building only through one desk, which redacts it, signs a form that says why, and files a copy. A **policy** is that desk. It is a declaration that names what it accepts, what it gives, the function that computes the released value, why the release is needed and who answers for it. Calling the policy is the only way to lower a label.

## 17.5.2 Why a release needs a declared place

The reorder list of [section 17.2](https://una-lang.org/en/learn/information-flow/sinks-where-labeled-data-may-go/#s17-2) is `internal`. The report wants only how many SKUs it holds. Try to count them into a public `Int`:

```diff include="steps/31-policy..steps/32-unreleased-count:src/reorder.una" context="1" title="src/reorder.una"
--- a/src/reorder.una
+++ b/src/reorder.una
@@ -1,4 +1,2 @@
 module reorder
-
-import release (line_count)
 
@@ -12,2 +10,3 @@
     if error use ""
-  @console.print("{line_count(list)} SKUs to reorder")
+  let count: Int = list.split(on: "\n").filter(keep: fn(line) -> line.len > 0).len
+  @console.print("{count} SKUs to reorder")
```

```text include="steps/32-unreleased-count/expected/rendered.txt#L1-L6"
[U4001] Error: `count` is `Int`, and this value is `internal Int`: a flow from `internal` to `public`
    ╭─[ src/reorder.una:11:20 ]
    │
 11 │   let count: Int = list.split(on: "\n").filter(keep: fn(line) -> line.len > 0).len
    │                    ───────────────────────────────┬───────────────────────────────
    │                                                   ╰───────────────────────────────── `count` is `Int`, and this value is `internal Int`: a flow from `internal` to `public`
```

The count is computed from the list, so it is `internal`, and the annotation says `Int`, which is `public`. The checker is right: a count is something about the list. Here it is also a harmless thing to show, and the program has no way to say so. If any line could lower a label, every label would be only as strong as the least careful line of the program. A policy puts each release in one place, with a reason, where a reviewer can find it.

## 17.5.3 How to write a policy

A policy has five lines, all required, and a function that it names:

```una include="steps/31-policy/src/release.una#line_count..count_lines" title="steps/31-policy/src/release.una"
--- Releases how many lines a list has, and nothing of what they say.
pub policy line_count
  from internal Text
  to Int
  via count_lines
  purpose "report the size of the reorder list"
  owner purchasing

count_lines(list: internal Text) -> Int = list.split(on: "\n").filter(keep: fn(line) -> line.len > 0).len
```

| Line | Says |
| --- | --- |
| `pub policy line_count` | The name callers use, like a function's |
| `from internal Text` | What it accepts, with its label |
| `to Int` | What it gives, with the lower label: here `public`, since there is none |
| `via count_lines` | The function that computes the released value |
| `purpose "…"` | Why the release is needed, in words a reviewer reads |
| `owner purchasing` | Who answers for it, such as a team: a name that starts with a small letter and holds only small letters, digits and `_`, as a function's name does |

### 17.5.3.1 `from` and `to`

`from` and `to` are types with their labels. Apart from the labels, they must match the `via` function's parameter and result exactly. `to` may keep some label, such as `internal`, and may drop categories: a policy from `secret[PII] Text` to `secret Text` drops only the category.

### 17.5.3.2 `via`

The `via` function takes one parameter, of the type of `from`, and returns the type of `to`. It is a private function of the same module, with no `pub`, so the policy is the only way to call it.

### 17.5.3.3 `purpose` and `owner`

They are not checked against the code: they are for people. The build report prints them next to every call, so a reviewer reads, in one list, every release the program makes and why.

## 17.5.4 Trusted modules

A policy may live only in a **trusted module**: a module whose code the guarantee relies on, and which a reviewer reads with care. A module is trusted only when it says so twice: `trusted module` in its header, and its name under `[trusted] modules` in `una.toml`:

```toml include="steps/31-policy/una.toml" title="steps/31-policy/una.toml"
[package]
name = "reorder"
version = "0.1.0"
edition = "0.2"

[trusted]
modules = ["release"]

[run]
entry = "reorder"
grants = ["console", "files:src:read,write"]
```

The rest of a trusted module's code is checked as usual. Only the bodies of its `via` functions are not checked for labels ([Inside `via`, labels are not checked](#inside-via-labels-are-not-checked)).

## 17.5.5 Releasing a count

The program reads the list, which is `internal`, and prints only what the policy releases:

```una include="steps/31-policy/src/reorder.una" title="steps/31-policy/src/reorder.una" verified="check, run"
module reorder

import release (line_count)

pub main() -> Unit
  uses @console: Console[print]
  uses @files: Files[read, write]
=
  @files.write("reorder.csv", content: "LAMP-01,20\nDESK-02,5\n")
    if error use unit
  let list = @files.read("reorder.csv")
    if error use ""
  @console.print("{line_count(list)} SKUs to reorder")
```

`import release (line_count)` brings the policy from the module `release` into this one. An import names the module and, in parentheses, the names it uses from it; [chapter 11](https://una-lang.org/en/learn/packages/pub-and-import/#s11-2) covers imports. The call `line_count(list)` looks like a function call, and it is one: `list` flows into `from internal Text`, and the result is a public `Int`.

`una run .` prints:

```text include="steps/31-policy/expected/output.txt"
2 SKUs to reorder
```

## 17.5.6 What the build report shows

`una report .` prints the build report ([chapter 18](https://una-lang.org/en/learn/tools/the-build-report/#s18-4)): what the package was proven to do, and what it trusts. Two of its sections are about releases:

```text include="steps/31-policy/expected/commands/report.txt#L2,L11-L14,L24-L25,L40"
package reorder 0.1.0
information:
  release.line_count at src/release.una:14:6, purpose "report the size of the reorder list", owner purchasing
  release.line_count at src/release.una:18:6, purpose "report the size of the reorder list", owner purchasing
  release.line_count at src/reorder.una:13:20, purpose "report the size of the reorder list", owner purchasing
tcb:
  trusted modules: release (19 lines)
out of model: timing, termination and divergence, resource consumption and allocation, stack exhaustion, external systems beyond declared signatures, races between the check and the use of a file path, hard links, order of effects across concurrent tasks, the time of a host stop, interference of the host's load with the timing of an expression, uncatchable termination, waits at limits and at `start`, which branch of `first of` wins, beyond its label
```

- **`information:`** lists every call of a policy, with its place, its purpose and its owner. Two calls are in the policy's examples, in `release.una`, and one in `main`.
- **`tcb:`**, the *trusted computing base*, lists the code the guarantee trusts. `trusted modules: release (19 lines)` is the code a reviewer must read line by line.
- **`out of model:`** lists what the guarantee does not cover, such as timing and termination ([What the checker promises](https://una-lang.org/en/learn/information-flow/labels-and-how-they-follow-data/#what-the-checker-promises)).

Adding a trusted module is a change to the manifest, and each new release adds a line to `information:`, so both show in review.

## 17.5.7 How a policy behaves

### 17.5.7.1 A policy call obeys the program counter

A policy call is allowed only where the program counter is at or below the policy's `to` label. A policy's result may be lower than what it read, so a call under a branch on data above `to` would reveal the condition through that result. For a policy to `public`, such as `line_count`, that means a path that public data alone decides. Call the policy only when the list is not empty:

```diff include="steps/31-policy..steps/33-release-under-branch:src/reorder.una" context="1" title="src/reorder.una"
--- a/src/reorder.una
+++ b/src/reorder.una
@@ -12,2 +12,3 @@
     if error use ""
-  @console.print("{line_count(list)} SKUs to reorder")
+  let shown = if list.len > 0 then line_count(list) else 0
+  @console.print("{shown} SKUs to reorder")
```

```text include="steps/33-release-under-branch/expected/rendered.txt#L1-L8"
[U4002] Error: policy `line_count` lowers data to `public`, and it is called under an `internal` condition, which its result would reveal
    ╭─[ src/reorder.una:13:36 ]
    │
 13 │   let shown = if list.len > 0 then line_count(list) else 0
    │                  ──────┬─────      ────────┬───────
    │                        ╰───────────────────────────── the labeled condition
    │                                            │
    │                                            ╰───────── policy `line_count` lowers data to `public`, and it is called under an `internal` condition, which its result would reveal
```

`list.len > 0` is `internal`, so the call runs under an `internal` condition, and U4002 points at both. The second diagnostic of the same run, U4003 at the print, follows from the first: `shown` was chosen by the condition. Call each release to `public` on a path that public data alone decides. A policy whose `to` keeps a label, such as `internal Int`, may be called under a branch on data up to that label.

### 17.5.7.2 A policy needs a trusted module

Remove `trusted` from the header of `release`:

```diff include="steps/31-policy..steps/34-untrusted-header:src/release.una" context="1" title="src/release.una"
--- a/src/release.una
+++ b/src/release.una
@@ -1,2 +1,2 @@
-trusted module release
+module release
 
@@ -11,9 +11 @@
 count_lines(list: internal Text) -> Int = list.split(on: "\n").filter(keep: fn(line) -> line.len > 0).len
-
-example "a list of two SKUs has two lines"
-  do line_count("LAMP-01,20\nDESK-02,5\n")
-  expect result == 2
-
-example "a list of three SKUs, with a blank line between two of them"
-  do line_count("LAMP-01,20\n\nMUG-03,40\nDESK-02,5")
-  expect result == 3
```

```text include="steps/34-untrusted-header/expected/diagnostics.txt"
error U4004 at src/release.una:4:12: policy `line_count` is declared in module `release`, which is not trusted
error U7005 at una.toml:7:12: [trusted] modules lists `release`, whose header does not say `trusted module`
```

Two diagnostics, one for each half of the double declaration. U4004 says the policy is in a module that is not trusted. U7005 says the manifest lists a module whose header does not agree. Both halves must say `trusted`.

### 17.5.7.3 Inside `via`, labels are not checked

Inside a `via` function the checker does not check labels, since lowering one is its job. Types, refinements and proofs are still checked.

That makes a `via` function trusted code, and it covers what the function does and how it fails, as well as what it returns. A `via` function may declare `uses`, and the policy then has the same `uses`. Its operations stay within those `uses`, but nothing checks the labels of what it sends through them: a `via` function that holds a console could print the raw value it receives, and `una check` would pass. So keep every function of a trusted module small, keep each `via` function pure, with no `uses`, unless the release needs one, such as a keyed hash, and review it line by line. [Reference](https://una-lang.org/en/learn/information-flow/recap-and-reference/#reference) links the rules of the specification that say so.

### 17.5.7.4 The `via` function's own rules

The `via` function must be private, used only through its policy, of the same types as `from` and `to` apart from labels, and without a `requires` clause, since a policy call checks its argument against `from` only. Each is U4005 otherwise; [a public `via` function](https://una-lang.org/en/learn/information-flow/common-mistakes/#a-public-via-function-u4005) shows one.

> [!WARNING]
> A policy is trusted code: the guarantee holds only if the `via` function releases what its purpose says and nothing more, through its result, its failures or its effects. Release the least you can, such as a count, a first letter or one yes-or-no answer, and keep `via` functions short enough to review line by line.

## 17.5.8 What to release

:::decide
**Which to use:**

| The program needs… | Release |
| --- | --- |
| How much data there is | a count, as `line_count` does |
| To tell values apart in a log, without showing them | a masked form, such as a first letter and a domain ([section 17.6](https://una-lang.org/en/learn/information-flow/day-to-day-shipping-notices-with-labels/#s17-6)) |
| One decision, such as whether to fail | one `Bool` ([exercise 3](https://una-lang.org/en/learn/information-flow/exercises/#exercise-3-a-blocked-domain)) |
| The data itself, to a service | no policy: an `accepts` clause on that service ([section 17.2](https://una-lang.org/en/learn/information-flow/sinks-where-labeled-data-may-go/#s17-2)) |
:::

## 17.5.9 What the U4 codes mean

| Code | Typical cause | Usual repair |
| --- | --- | --- |
| U4001 | A value flowing into a declared type with a lower label: a return, a parameter, a field, an annotated `let` | Raise the declared label, or lower the value through a policy |
| U4002 | A failure, or a call that may fail or act, under a branch on labeled data; a policy call under a branch on data above its `to` label | Return a labeled value instead of failing, or release before the branch |
| U4003 | An argument of an operation above the operation's `accepts`, or an operation under a branch on data above it | Send less, or send it to a place that accepts it, or act outside the branch |
| U4004 | A policy in a module that is not trusted | Move it into a trusted module |
| U4005 | A policy whose `via` function is public, used directly, of the wrong types, or has a `requires` clause | Make `via` private, match the types, drop `requires`, and call the policy |
| U4007 | A category that `una.toml` does not declare | Declare it, or correct its name |

## 17.5.10 Check yourself: policies

First, the main idea. Someone thinks the policy is too much ceremony, drops the import, and writes the counting function in `reorder` itself:

```diff include="steps/31-policy..steps/35-plain-function:src/reorder.una" context="1" title="src/reorder.una"
--- a/src/reorder.una
+++ b/src/reorder.una
@@ -2,3 +2,4 @@
 
-import release (line_count)
+--- How many lines a list has.
+count_lines(list: internal Text) -> Int = list.split(on: "\n").filter(keep: fn(line) -> line.len > 0).len
 
@@ -12,2 +13,2 @@
     if error use ""
-  @console.print("{line_count(list)} SKUs to reorder")
+  @console.print("{count_lines(list)} SKUs to reorder")
```

Does `una check .` pass?

:::answer Show the answer
No:

```text include="steps/35-plain-function/expected/rendered.txt#L1"
[U4001] Error: the result of `count_lines` is `Int`, and this value is `internal Int`: a flow from `internal` to `public`
```

The body is the same as `count_lines` in `release.una`, but here it is an ordinary function, so its labels are checked: a count of an `internal` list is `internal`, and the header says `Int`. Only a `via` function, reached through a policy of a trusted module, may lower a label.
:::

Second, a detail of this policy. `release.una` ends with two examples of the policy. The second gives it a list with a blank line between two SKUs:

```una include="steps/31-policy/src/release.una#L17-L19" title="steps/31-policy/src/release.una"
example "a list of three SKUs, with a blank line between two of them"
  do line_count("LAMP-01,20\n\nMUG-03,40\nDESK-02,5")
  expect result == 3
```

What does `line_count` return for that text, and does the example pass?

:::answer Show the answer
It returns 3, and the example passes:

```text include="steps/31-policy/expected/commands/test.txt#L2-L5"
example release "a list of two SKUs has two lines" ... ok
example release "a list of three SKUs, with a blank line between two of them" ... ok

2 examples: 2 passed, 0 failed
```

`count_lines` splits the text at each line break, which gives four pieces, one of them empty, then keeps only the pieces that are not empty. A blank line is not a SKU, so it is not counted. That is a choice of the `via` function, and an example is how you pin it down: the checker does not look inside `via`.
:::
