Home / Docs / Examples

journal

Release v0.4.0

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:

Run it

From this directory:

sh
una check .   # copy examples/journal
una test .
una report .
una run .
una build .
./target/una/journal-example

una run . and the native executable print:

una run .Output
today's entry runs to about 2 hundred characters

The 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:

una test .Output
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 failed

Set 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

una.tomltoml
[labels]
categories = ["Private"]

[trusted]
modules = ["journal.release"]

[run]
entry = "journal.main"
grants = ["console", "env", "files:entries:read,write"]

Labeled data

src/journal/entries.unauna
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:

src/journal/entries.unauna
pub mood(entry: Entry) -> confidential[Private] Mood = if entry.body.len > 280 then Busy else Calm

mood 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

src/journal/release.unauna
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 / 100

A 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

src/journal/main.unauna
  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

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:

una report .Output
...
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:

una report .Output
...
  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}"):

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

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

  1. Show the mood. Import Entry and mood from journal.entries into journal.main. In main, compute mood(Entry(day: 1, body: text)), turn it into "calm" or "busy" with a when, and print that text. una check . reports U4003 with the label confidential[Private]: the text was chosen by a private value. Then add a second policy to journal.release, which needs import journal.entries (Mood): day_mood, from confidential[Private] Mood to public Mood, through a private function that returns its argument, with its own purpose. Apply day_mood before the when. una check . is then clean, the program prints the mood, and una report . lists two releases.
  2. A diary on disk. Add a handler that keeps entries in a file: handler file_diary() for Diary, with uses @files: Files[write] and op keep(entry) = @files.write("kept.txt", content: entry.body). una check . rejects it twice. U3007: write can fail, and the operation must handle that. U4003: Files.write accepts internal data, and a handler of keep is checked for its worst caller, one that passes confidential[Private] data. So Files cannot hold confidential[Private] data: a store for private data needs a capability whose operation accepts that label, as Diary.keep does.
  3. A finer band. Make hundreds divide by 10, and change the message in main to say tens of characters. The program prints today'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

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

una.tomltoml
[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"]
entries/today.txt
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.
src/journal/entries.unauna
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 Calm
src/journal/main.unauna
module 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 unit
src/journal/release.unauna
trusted 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