journal
A private journal: it reads today's entry from a file and prints how long it is, never what it says.
This is the example of information flow. Data carries a label, such as confidential[Private], and the checker follows the label through every computation, branch and failure. Data reaches a place with a lower label only through a declared policy, in a trusted module, and the build report lists every such release with its purpose and owner. The journal prints one fact about the entry, its length band, and the checker rejects every other flow from the entry to the console.
What it demonstrates:
- labels and a label category,
Private; - a
policythat releases one fact, in atrusted module; - a capability whose operation
acceptslabeled data; - the host capabilities
FilesandEnv, with a file grant limited to one directory (grants); - why a failure can reveal data, and how the program handles it with
if error use.
Run it
From this directory:
una check . # copy examples/journal
una test .
una report .
una run .
una build .
./target/una/journal-exampleuna run . and the native executable print:
today's entry runs to about 2 hundred charactersThe entry, entries/today.txt, has a little over 200 characters, and the program shows only the whole hundreds. una test . runs the examples of src/journal/entries.una:
example journal.entries "an entry is kept" ... ok
example journal.entries "a full diary reports it" ... ok
example journal.entries "a short entry is a calm day" ... ok
3 examples: 3 passed, 0 failedSet JOURNAL_COPY to copy the entry as well: with JOURNAL_COPY=copy.txt, the run also writes entries/copy.txt. The grant confines writes to entries/, so a path such as ../outside.txt is refused, and the program ignores the refusal.
How it works
The package has three modules: journal.entries, the data and the diary; journal.release, the trusted module with the policy; and journal.main, the program.
The manifest
[labels]
categories = ["Private"]
[trusted]
modules = ["journal.release"]
[run]
entry = "journal.main"
grants = ["console", "env", "files:entries:read,write"][labels]declares the categories that the package's labels may name.[trusted]lists the modules that may hold policies. A module is trusted only when the manifest lists it and its header saystrusted module, so neither file alone can make it so.files:entries:read,writegrants reading and writing underentries/and nowhere else. Paths in the code are relative to that directory:@files.read("today.txt")readsentries/today.txt.
Labeled data
pub kind Entry
day: Int
body: confidential[Private] Text
...
pub capability Diary
op keep(entry: Entry) -> Unit
fails DiaryError
accepts confidential[Private]The body of an entry is confidential, in the category Private. A capability operation states the highest label it accepts. Console.print accepts only public data, so an entry cannot be printed. Diary.keep accepts confidential[Private], so entries can be kept.
Labels spread to everything computed from labeled data:
pub mood(entry: Entry) -> confidential[Private] Mood = if entry.body.len > 280 then Busy else Calmmood returns only Calm or Busy, but which one depends on the body, so the answer is as private as the body. The checker would reject Mood without the label: a branch on private data raises the label of what it chooses.
Releasing one fact: the policy
trusted module journal.release
...
pub policy length_band
from confidential[Private] Text
to public Nat
via hundreds
purpose "show how much was written without showing what"
owner journal_owner
hundreds(text: confidential[Private] Text) -> public Nat = text.len / 100A policy is the only way to lower a label. It names the types before and after, the private function that computes the release (via), why the release exists (purpose) and who answers for it (owner). Code calls the policy like a function, length_band(text). It cannot call hundreds directly: the via function is private, and the policy is its only entry point. To review every release in the package, you read the trusted modules, which una report . lists with their size.
The program, and a failure that would reveal
let text = @files.read("today.txt")
if error use ""
let hundreds = length_band(text)
@console.print("today's entry runs to about {hundreds} hundred characters")Files.read returns internal Text: the content of a file is never public. length_band accepts it, since internal is below confidential[Private], and returns a public Nat, which may be printed.
The read can fail, and here a failure must not leave main. The program also writes a copy to the path that JOURNAL_COPY names, and that path is internal data. Where the package's writes land decides which files exist in this run and in later ones, so in this package every Files failure carries the label internal. Passing it on with if error pass would let an observer learn something about internal data from whether the program failed. if error use "" keeps the outcome inside the program: a missing entry counts as empty. The comment in main gives the same reason.
What una check proves
writereturns an entry for the day it was given (ensures result.day == day).hundredsnever returns a negative number.- The entry's text reaches the console only as its length band, through
length_band. Printing the text itself is an error (U4003), and so is printingmood's answer, which depends on a private body.
The guarantee is noninterference: two runs whose entries differ only in their private text print the same thing, unless a policy released the difference. una report . shows each release, and what the guarantee rests on. Among its lines:
...
information:
journal.release.length_band at src/journal/main.una:18:18, purpose "show how much was written without showing what", owner journal_owner
...and, in the trusted base:
...
trusted modules: journal.release (11 lines)
host capabilities: Console, Env, Files
...Common mistakes
Printing the private text
Change the print line of main to @console.print("today: {text}"):
[U4003] Error: `@console.print` accepts `public` data, and this argument is `internal`
╭─[ src/journal/main.una:19:18 ]
│
19 │ @console.print("today: {text}")
│ ───────┬───────
│ ╰───────── `@console.print` accepts `public` data, and this argument is `internal`
│
│ Help 1: repair 1: send `@console.print` only data labeled `public` or lower, or send this value to an operation that accepts `internal`
│
│ Help 2: repair 2 (escape: trusted; the guarantee then rests on trusted code, whose labels are not checked: a policy releases the data, or a module joins the trusted base; it is listed in the build report and needs review): declassify the value through a policy of a trusted module
│
│ Note: run `una explain U4003` for an explanation
────╯Interpolation keeps the label of what it interpolates, so the whole line is internal. Repair 2 is the design that this example uses: a policy that releases only what may be shown.
Passing on a failure that depends on internal data
Change if error use "" after the read to if error pass:
[U4002] Error: `if error pass` depends on `internal` data, so its failure would reveal it; return a labeled value instead of failing
╭─[ src/journal/main.una:17:5 ]
│
16 │ let text = @files.read("today.txt")
│ ────────────┬───────────
│ ╰───────────── the labeled condition
17 │ if error pass
│ ──────┬──────
│ ╰──────── `if error pass` depends on `internal` data, so its failure would reveal it; return a labeled value instead of failing
│
│ Note: run `una explain U4002` for an explanation
────╯Whether a function fails is observable, like a printed line. A failure is allowed only where the decision to fail is public.
Important
Remove the copy to JOURNAL_COPY and the same if error pass checks: a package whose writes go to public paths keeps public file failures. Information flow depends on what the whole package does with files, not on the one line.
Extend it
- Show the mood. Import
Entryandmoodfromjournal.entriesintojournal.main. Inmain, computemood(Entry(day: 1, body: text)), turn it into"calm"or"busy"with awhen, and print that text.una check .reports U4003 with the labelconfidential[Private]: the text was chosen by a private value. Then add a second policy tojournal.release, which needsimport journal.entries (Mood):day_mood, fromconfidential[Private] Moodtopublic Mood, through a private function that returns its argument, with its own purpose. Applyday_moodbefore thewhen.una check .is then clean, the program prints the mood, anduna report .lists two releases. - A diary on disk. Add a handler that keeps entries in a file:
handler file_diary() for Diary, withuses @files: Files[write]andop keep(entry) = @files.write("kept.txt", content: entry.body).una check .rejects it twice. U3007:writecan fail, and the operation must handle that. U4003:Files.writeacceptsinternaldata, and a handler ofkeepis checked for its worst caller, one that passesconfidential[Private]data. SoFilescannot holdconfidential[Private]data: a store for private data needs a capability whose operation accepts that label, asDiary.keepdoes. - A finer band. Make
hundredsdivide by 10, and change the message inmainto saytens of characters. The program printstoday's entry runs to about 24 tens of characters. The release changes in one trusted function, which is where a reviewer looks for it.
Learn more
- Construct pages: labels,
policy,trusted module,capability,handler,fails,if error,example. - Configuration:
categories, trustedmodules,grants. - Learn, the tutorial on the Una website: "Information flow" (
/learn/information-flow/). - Specification: the guarantee (spec/07 §1), labels (spec/07 §2), typing rules (spec/07 §3), sinks (spec/07 §4), policies (spec/07 §5), trusted modules (spec/07 §6), host capabilities (spec/14 §3).
Edition
Edition 0.1 (edition). The record Entry would need another name in edition 0.2, where Entry is the built-in type of map entries.
Files
[package]
name = "journal-example"
version = "0.1.0"
edition = "0.1"
[labels]
categories = ["Private"]
[trusted]
modules = ["journal.release"]
[run]
entry = "journal.main"
grants = ["console", "env", "files:entries:read,write"]Planted tomatoes along the south fence and watered the beans. Read two chapters of the novel from the library. The rain stopped by noon, so the afternoon went to fixing the gate latch and sorting seeds into labeled envelopes for next spring.module journal.entries
--- A day's entry. Its text is private to the writer.
pub kind Entry
day: Int
body: confidential[Private] Text
pub kind Mood = Calm | Busy
pub kind DiaryError = | Unavailable
--- Where entries are kept. They hold private text, so the store accepts it.
pub capability Diary
op keep(entry: Entry) -> Unit
fails DiaryError
accepts confidential[Private]
--- A long entry means a busy day. The answer depends on the text, so it is as private.
pub mood(entry: Entry) -> confidential[Private] Mood = if entry.body.len > 280 then Busy else Calm
--- Writes an entry for `day` and keeps it.
pub write(day: Int, body: confidential[Private] Text) -> Entry
ensures result.day == day
uses @diary: Diary[keep]
fails DiaryError
=
let entry = Entry(day, body)
@diary.keep(entry)
if error pass
entry
--- A diary kept in memory for the examples.
handler memory_diary() for Diary
op keep(entry) = unit
--- A diary with no room left.
handler full_diary() for Diary
op keep(entry) = fail Unavailable
example "an entry is kept"
given @diary = memory_diary()
do write(1, body: "Planted tomatoes.")
expect result.day == 1
expect performed @diary.keep
example "a full diary reports it"
given @diary = full_diary()
do write(2, body: "Read two chapters.")
expect fails Unavailable
example "a short entry is a calm day"
do mood(Entry(day: 3, body: "Quiet."))
expect result is Calmmodule journal.main
import journal.release (length_band)
--- Prints how long today's entry is, never what it says, and copies it where
--- `JOURNAL_COPY` names when that is set and the grant allows writing.
pub main() -> Unit
uses @console: Console[print]
uses @files: Files[read, write]
uses @env: Env[get]
fails FileError
=
-- The copy below writes where `JOURNAL_COPY` says, which is `internal`, so whether a file
-- exists is `internal` too, in this run and later ones: the read's failure is not passed
-- on, and a missing entry counts as empty.
let text = @files.read("today.txt")
if error use ""
let hundreds = length_band(text)
@console.print("today's entry runs to about {hundreds} hundred characters")
let copy_to = @env.get("JOURNAL_COPY")
if none use ""
if copy_to == ""
unit
else
@files.write(copy_to, content: text)
if error use unittrusted module journal.release
--- How long a text is, in whole hundreds of characters, and nothing of what it says.
pub policy length_band
from confidential[Private] Text
to public Nat
via hundreds
purpose "show how much was written without showing what"
owner journal_owner
hundreds(text: confidential[Private] Text) -> public Nat = text.len / 100