Home / Learn / 17 Information flow
17.5 Releasing data: policies and trusted modules
Page 6 of 11
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 is internal. The report wants only how many SKUs it holds. Try to count them into a public Int:
--- 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")[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:
--- 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:
[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).
17.5.5 Releasing a count
The program reads the list, which is internal, and prints only what the policy releases:
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 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:
2 SKUs to reorder17.5.6 What the build report shows
una report . prints the build report (chapter 18): what the package was proven to do, and what it trusts. Two of its sections are about releases:
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 labelinformation:lists every call of a policy, with its place, its purpose and its owner. Two calls are in the policy's examples, inrelease.una, and one inmain.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).
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:
--- 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")[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 reveallist.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:
--- 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 == 3error 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 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 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
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) |
| One decision, such as whether to fail | one Bool (exercise 3) |
| The data itself, to a service | no policy: an accepts clause on that service (section 17.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:
--- 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?
Show the answer
No:
[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:
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 == 3What does line_count return for that text, and does the example pass?
Show the answer
It returns 3, and the example passes:
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 failedcount_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.