Home / Docs / Guides

Labels and information flow

Release v0.4.0

Every type may carry a label: a level, public (the default), internal, confidential, secret or restricted, and categories declared in una.toml, as in secret[PII] Text. Values flow up, never down: the result of an operation joins its operands' labels; branching on a labeled value raises the program counter, so what the branches produce is labeled too, and they may not fail; each operation argument is a sink bounded by its accepts (Console.print accepts public). Env.get and Files.read return internal text. A label labels one position of a type: in internal Option[Int] which variant the value is, Some or None, is internal, but the Int inside is public, so a function that returns a labeled element writes internal Option[internal Int].

Printing what you read from Env or Files takes a policy. That text, and anything computed from it, even its length, is internal, so printing it is U4003, as in the second block below. No label of your program can be lowered to fix that: declassify the value through a policy in a trusted module, as the journal package after it does, and call the policy where you print. una explain U4003 shows the same pattern for a name read from Env. Whether a variable is set is public, though, since Env.get returns a public Option: treat which variables are set as public configuration, and never encode a secret in it.

Writes to a labeled path make file failures labeled. The files a run finds depend on where earlier writes landed, in this run or an earlier one. So when a package writes to an internal path, or writes under an internal condition, the failure of every Files.read and Files.write in it is internal: handle it with attempt or if error use, not if error pass (U4002). A package whose writes go to public paths, at a public program counter, keeps public failures (S-14).

una
module demo

pub kind Note
  day: Int
  body: secret Text

pub kind Mood = Calm | Busy

--- The answer depends on the text, so it is as secret as the text.
pub mood(note: Note) -> secret Mood = if note.body.len > 280 then Busy else Calm
una
-- fails with U4003
module demo

pub main() -> Unit
  uses @console: Console[print]
  uses @env: Env[get]
=
  let name = @env.get("USER")
    if none use "nobody"
  @console.print("hello {name}")

Labels go down only through a policy in a module that its header and una.toml both mark trusted. The policy is the only entry to its private via function, and every call of it is listed in the build report with its purpose and owner:

una.tomltoml
[package]
name = "journal"
version = "0.1.0"
edition = "0.2"

[labels]
categories = ["Private"]

[trusted]
modules = ["release"]
src/release.unauna
trusted module 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
src/show.unauna
module show

import release (length_band)

pub size(text: confidential[Private] Text) -> Nat = length_band(text)

A generic function may decide something by comparing values of a type parameter. It must not hand the decided value to a function value it was given, because that function value was checked only against values of T passed through, and its result, effects or failures would reveal the comparison. The checker rejects the call where the decided value meets the function value, here at each: k, whether a prelude function such as map, filter, first_where or fold calls it or a generic function of the program does (U4001):

una
-- fails with U4001
module demo

pub capability Log
  op write(n: Int) -> Unit

count_chosen[T: Eq](a: T, b: T, p: T, q: T, k: fn(T) -> Int) -> Unit
  uses @log: Log[write]
=
  let ns = [if a == b then p else q].map(each: k)
  @log.write(ns.sum())

Pass the values of T through unchanged ([p, q].map(each: k) is accepted), or give the decision to the caller as a Bool result. Edition 0.1 reports the same U4001 at each: k, and also the code where the decision would come out, U4003 at the sink or U4002 at a call with effects (#346, #350, #354). A written annotation that mentions T cannot hold such a value either; see section 13.