Home / Docs / Language guide / Information flow
trusted modules
What it does
A trusted module may hold declassification policies: declared releases of data to a lower label, the only code that lowers a label (marks data as less sensitive). A module is trusted only when two places agree: its header says trusted module, and the package lists it under [trusted] modules in una.toml. The rest of its code is checked as usual. una report lists trusted modules and their line counts under tcb (the trusted computing base: the parts the guarantees rely on, which people review), so reviewers know exactly what to read.
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.
module_header = [ "trusted" ] "module" module_path NEWLINE ;In una.toml, [trusted] modules is an array of module paths, each one of the package whose header says trusted module.
Examples
The header alone does not make a module trusted:
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"
[labels]
categories = ["Private"]-- fails with U7005
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 / 100Without both, a policy has no place to live:
[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
Further rules:
- Everything else is checked. Only the
viafunctions of policies skip label checks; every other declaration of a trusted module is checked normally, and every obligation of aviafunction is proven. - Reported.
una reportlists each trusted module with its line count undertcb.
Reading the trust report
Read the report fields separately:
provengives the number of proven obligations assemantic;securityandauthorityare"by typing". A proof shows that the program keeps its contracts, not that the contracts capture the whole requirement or that an external system behaves as declared.assumptionslists every capability the package declares, with its operations and theirensuresclauses; those clauses are assumed of the implementation, not proven.escapes.checkedlists every module that useschecked, with its count and its budget.tcblists the trusted modules with their line counts, the host capabilities, the solver and the proof cache with its key. Line counts locate the code to review; they do not say whether a policy's purpose is appropriate.out_of_modellists the channels outside the information-flow guarantee, such as timing, termination and divergence, resource consumption, hard links, and external systems beyond their declared signatures.
A review of the report still compares each policy's purpose and owner with the requirement, and reads the assumptions and the excluded channels. These fields are defined in spec/13 §6; the information-flow scope is in spec/07 §1.
Diagnostics
- U4004: a policy in a module that is not trusted.
- U7005: a module trusted in its header or in
una.toml, but not in both.
Edition
Trusted modules are the same in editions 0.1 and 0.2. From edition 0.3, a preview, the language adds boundaries (groups of modules whose authority una.toml, or from edition 0.4 ita.una, caps): a module inside a boundary is never trusted, and a call into a boundary that could reach a policy call is rejected. See [boundaries] and A ceiling for a module: boundaries.
Normative source
- spec/07 §6: trusted modules, and from edition
0.3, boundary modules that are never trusted; spec/07 §5: policies. - spec/02 §1: the module header.
- spec/13 §6: the build report and its
tcb; spec/13 §7:[trusted] modules. - Decision record: ADR 0093, for boundaries.