Home / Docs / Language guide / Information flow

trusted modules

Release v0.4.0Edition 0.1 and laterU4004U7005

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.

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

[labels]
categories = ["Private"]

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

ebnf
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:

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

[labels]
categories = ["Private"]
src/shop/release.unauna
-- 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 / 100

Without both, a policy has no place to live:

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

[labels]
categories = ["Private"]
src/shop/release.unauna
-- 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 / 100

Edge cases

Further rules:

Reading the trust report

Read the report fields separately:

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

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