Home / Docs / Language guide / Information flow
Labels
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.
module shop
pub keep(balance: secret Int) -> secret Int = balance + 1
pub flag(age: secret Int) -> secret Int = if age > 17 then 1 else 0Forms
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.
type = [ label ] type_core [ "in" range ] ;
label = level [ "[" upper_ident { "," upper_ident } "]" ] ;
level = "public" | "internal" | "confidential" | "secret" | "restricted" ;- Levels, in order:
public<internal<confidential<secret<restricted. A type without a label ispublic. - Categories, in brackets:
secret[PII] Phone. They are declared per package inuna.toml, under[labels] categories. - Order. A label is below another when its level is not higher and its categories are a subset.
- Position. A label covers one position of a type:
internal Option[internal Int]labels the option and its payload; a flow compares the labels at every position.
Examples
A value flows only upward. Returning secret data as public is rejected:
-- fails with U4001
module shop
pub show_balance(balance: secret Int) -> Int = balanceBranching 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:
-- fails with U4001
module shop
pub flag(age: secret Int) -> Int = if age > 17 then 1 else 0A 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:
-- 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:
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"
[labels]
categories = ["PII"]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_yearValidating 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:
-- 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 ErrThe 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:
-- 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 NonPositiveEdge cases
An undeclared category is rejected:
-- fails with U4007
module shop
pub tagged(birth_year: secret[PII] Int) -> secret[PII] Int = birth_yearNo failure that reveals. Whether a function fails is observable, so fail is allowed only under a public program counter:
-- 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 balanceFurther rules:
- Raising is free. An
internalvalue may flow wheresecretis expected. - Lowering needs a policy in a trusted module. See
policyand trusted modules. - Fields. Reading a field joins the record's label with the field's declared label.
- Effects under the program counter. A call is allowed under a raised program counter only when every effect it may perform accepts that label, and the function cannot fail (U4002).
- Examples are exempt.
expectlines observe values for the test harness and are not sinks. - Outside the model. Timing, termination, resource consumption and the order of effects across concurrent tasks, among others, are not covered, and
una reportlists them underout_of_model. The normative source gives the full list.
Diagnostics
- U4001: a flow from a higher label to a lower one.
- U4002: a failure, or a call that may fail or act, under a labeled program counter.
- U4003: an argument above the label its operation accepts.
- U4007: a category not declared in
una.toml.
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
- spec/07 §1: the guarantee and its scope; spec/07 §2: labels; spec/07 §3: typing rules; spec/07 §4: sinks.
- spec/07 §7 rule 2: flows at every position; spec/03 §5: labeled types.
- spec/02 §2: the grammar; spec/13 §7:
[labels] categories. - Decision record: ADR 0067, for the labels of a generic function's result.