Home / Docs / Language guide / Information flow

Labels

Release v0.4.0Edition 0.1 and laterU4001U4002U4003U4007

What it does

A label classifies data by how sensitive it is: a level, and optional categories (named kinds of data, such as personal data). The checker follows labels through every computation and every branch, and rejects any flow of data to a place that its label does not allow. The guarantee is termination-insensitive noninterference (data can influence what a reader sees only through a declared release, leaving aside whether the program finishes at all): an observer at a label sees the same values and effects in two runs that differ only in data labeled above it, unless a policy released it. It covers the channels the model observes: timing, termination, resource use and the other channels it leaves out are listed under out_of_model by una report, and flows inside the via functions of a trusted module are, but for one timing rule of edition 0.4, not checked. The checker enforces it by its rules; the formal model in Lean proves it for a fragment of the language only (see Known limits).

Learn more: Labels and how they follow data, and Sinks: where labeled data may go.

una
module shop

pub keep(balance: secret Int) -> secret Int = balance + 1

pub flag(age: secret Int) -> secret Int = if age > 17 then 1 else 0

Forms

In the grammar below, each rule gives a name, =, what the name stands for and ;, quoted words are written as shown, NEWLINE, INDENT and DEDENT stand for a line break and for one more or one less level of indentation, [ ] marks an optional part, { } a part that may repeat, | separates alternatives, ( ) groups them, and (* *) holds a comment.

ebnf
type            = [ label ] type_core [ "in" range ] ;
label           = level [ "[" upper_ident { "," upper_ident } "]" ] ;
level           = "public" | "internal" | "confidential" | "secret" | "restricted" ;

Examples

A value flows only upward. Returning secret data as public is rejected:

una
-- fails with U4001
module shop

pub show_balance(balance: secret Int) -> Int = balance

Branching raises the program counter (the label of the conditions that decided whether a line runs; see Branches and failures: implicit flows). A value chosen by a secret condition is secret, even when the branches are constants:

una
-- fails with U4001
module shop

pub flag(age: secret Int) -> Int = if age > 17 then 1 else 0

A capability operation is a sink (a place where data leaves the program), and accepts arguments only up to its label: Console.print accepts public. Interpolation keeps the label of what it interpolates:

una
-- fails with U4003
module shop

pub print_balance(balance: secret Int) -> Unit
  uses @console: Console[print]
=
  @console.print("{balance}")

Categories are declared in the package:

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

[labels]
categories = ["PII"]
src/shop.unauna
module shop

pub tagged(birth_year: secret[PII] Int) -> secret[PII] Int = birth_year

pub wider(birth_year: secret[PII] Int) -> restricted[PII] Int = birth_year

Validating sensitive data without revealing validity

A validator can return a Result whose success payload and outer result are labeled internal, while keeping the error variant public. This lets a caller process the result without making a secret-dependent failure observable:

una
-- edition 0.3
module demo

pub kind Positive = Int where it > 0

pub kind ValidationError = | NonPositive

pub validate(value: internal Int) -> internal Result[internal Positive, ValidationError] = if value > 0 then Ok(value) else Err(NonPositive)

test "valid"
  do validate(3)
  expect result is Ok

test "invalid"
  do validate(0)
  expect result is Err

The success payload is constrained at its own position; the error type stays public, and the enclosing Result is internal. Returning Err on the invalid branch avoids a secret-dependent fail. The contrasting implementation below fails with U4002 because failure itself reveals the internal condition:

una
-- fails with U4002
module demo

pub kind Positive = Int where it > 0

pub kind ValidationError = | NonPositive

pub validate(value: internal Int) -> internal Positive
  fails ValidationError
=
  if value > 0 then value else fail NonPositive

Edge cases

An undeclared category is rejected:

una
-- fails with U4007
module shop

pub tagged(birth_year: secret[PII] Int) -> secret[PII] Int = birth_year

No failure that reveals. Whether a function fails is observable, so fail is allowed only under a public program counter:

una
-- fails with U4002
module shop

pub kind CreditError = | OverLimit

pub spend(balance: secret Int) -> secret Int
  fails CreditError
=
  if balance > 100 then fail OverLimit else balance

Further rules:

Diagnostics

Edition

Labels are the same in editions 0.1 and 0.2, except at calls of generic functions: edition 0.2 raises only the positions of the result that can carry each type argument's labels, and edition 0.1 raises every position. Editions 0.3, 0.4 and 0.5 keep the rules of edition 0.2 and add rules of their own, among them: from edition 0.3, the answer of an operation carries the label that its header's gives names, and a boundary module never releases (spec/13 §7); from edition 0.4, deadlines and races have timing labels, and a deadline or race outcome reaches the result of a via function only when its concurrent label is public.

Normative source