Home / Learn / 17 Information flow

Release v0.4.0Edition 0.2

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:

src/reorder.unadiff
--- 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")
Diagnostic
[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:

steps/31-policy/src/release.unauna
--- 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:

steps/31-policy/una.tomltoml
[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:

steps/31-policy/src/reorder.unacheckrununa
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:

Output
2 SKUs to reorder

17.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:

Output
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

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:

src/reorder.unadiff
--- 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")
Diagnostic
[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:

src/release.unadiff
--- 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
Diagnostic
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 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:

src/reorder.unadiff
--- 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:

Diagnostic
[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:

steps/31-policy/src/release.unauna
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?

Show the answer

It returns 3, and the example passes:

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

Next:17.6 Day-to-day: shipping notices with labels