Home / Docs / Language guide / Information flow
policy: declassification
What it does
Labels only rise, except through a policy: a declared, named release of data from one label to a lower one, through a function that the policy names. Lowering a label this way is called declassification. A policy lives in a trusted module (a module that una.toml lists as allowed to declare policies, and that una report lists for review), and every call of it is listed by una report with its purpose and owner. So every place where data goes down is visible and reviewed.
Learn more: Releasing data: policies and trusted modules.
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"
[labels]
categories = ["Private"]
[trusted]
modules = ["shop.release"]trusted module shop.release
pub policy length_band
from confidential[Private] Text
to public Nat
via hundreds
purpose "show how long a customer note is without showing it"
owner support
hundreds(text: confidential[Private] Text) -> public Nat = text.len / 100module shop.notes
import shop.release (length_band)
pub note_size(note: confidential[Private] Text) -> Nat = length_band(note)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.
policy_decl = [ "pub" ] "policy" lower_ident NEWLINE INDENT
"from" type NEWLINE
"to" type NEWLINE
"via" lower_ident NEWLINE
"purpose" text_lit NEWLINE
"owner" lower_ident NEWLINE
DEDENT ;fromandto: the types before and after the release. Theviafunction takes afromand returns ato, with the same types except for labels.via: the private function of the trusted module that computes the release.purposeandowner: why the release exists and who answers for it.una reportlists them at every call.
A policy p is called as a function, p(v), with the uses and fails of its via function.
Examples
Above, note_size hands its caller a public number computed from confidential text: only the length band leaves, through length_band, and the note stays labeled.
A policy is allowed only in a trusted module:
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"
[labels]
categories = ["Private"]-- fails with U4004
module shop.release
pub policy length_band
from confidential[Private] Text
to public Nat
via hundreds
purpose "show how long a customer note is without showing it"
owner support
hundreds(text: confidential[Private] Text) -> public Nat = text.len / 100Edge cases
The via function is private. The policy is its only entry point, so no other code can call it with labeled data:
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"
[labels]
categories = ["Private"]
[trusted]
modules = ["shop.release"]-- fails with U4005
trusted module shop.release
pub policy length_band
from confidential[Private] Text
to public Nat
via hundreds
purpose "show how long a customer note is without showing it"
owner support
pub hundreds(text: confidential[Private] Text) -> public Nat = text.len / 100No requires on via. A policy call checks its argument against from only, so the via body may assume nothing more:
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"
[labels]
categories = ["Private"]
[trusted]
modules = ["shop.release"]-- fails with U4005
trusted module shop.release
pub policy length_band
from confidential[Private] Text
to public Nat
via hundreds
purpose "show how long a customer note is without showing it"
owner support
hundreds(text: confidential[Private] Text) -> public Nat
requires text.len > 0
=
text.len / 100No release under a labeled program counter. At a call p(v), the program counter (the label of the conditions that decided whether this line runs; see Branches and failures: implicit flows) must be below the to label. Choosing whether to release by a secret condition would reveal it:
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"
[labels]
categories = ["Private"]
[trusted]
modules = ["shop.release"]trusted module shop.release
pub policy length_band
from confidential[Private] Text
to public Nat
via hundreds
purpose "show how long a customer note is without showing it"
owner support
hundreds(text: confidential[Private] Text) -> public Nat = text.len / 100-- fails with U4002
module shop.notes
import shop.release (length_band)
pub note_size(note: confidential[Private] Text, flag: secret Bool) -> secret Nat = if flag then length_band(note) else 0Further rules:
- Inside
via, labels are not checked. Theviafunction is part of the trusted code thatuna reportlists undertcb; its refinements, preconditions and postconditions are still proven. - Only through its policy. Any use of a
viafunction other than through its policy is U4005. - Labeled failures. The failure of a policy call is labeled by its
tolabel joined with the program counter, soif error passandif error failon it are U4002 when that label is abovepublic. One exception: aviafunction whose only failures areKeys.hmaccalls with a literal key name, at the top level of its body and handled byif error passorif error failwithout a payload, decides nothing from the released value, so its policy's failure is labeled by the program counter alone. - Keys. The result of
Keys.hmacis labeledinternaljoined with every label of its data; lowering it further takes a policy, such as one fromsecret[PII] Phonetointernal Hashedwhoseviafunction computes the HMAC of a phone number.
Diagnostics
- U4002: a policy call under a program counter above its
tolabel, orif error passorif error failon a policy failure labeled abovepublic. - U4004: a policy outside a trusted module.
- U4005: a
viafunction that is public, has arequiresclause, is used other than through its policy, or whose types do not match the policy's.
Edition
Policies are the same in editions 0.1 and 0.2.
Normative source
- spec/07 §5: declassification policies, rules 1 to 6; spec/07 §6: trusted modules.
- spec/02 §4: the grammar.
- spec/13 §6: the build report.
- spec/14 §3:
Keys.hmacand its labels. - spec/10 §13.4: a
viafunction whose failure reveals nothing. - Decision record: ADR 0039, for the labels of
Keys.hmac.