Home / Docs / Language guide / Information flow

policy: declassification

Release v0.4.0Edition 0.1 and laterU4002U4004U4005

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.

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
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 ;

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:

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

The via function is private. The policy is its only entry point, so no other code can call it with labeled data:

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

[labels]
categories = ["Private"]

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

No requires on via. A policy call checks its argument against from only, so the via body may assume nothing more:

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

[labels]
categories = ["Private"]

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

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

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
-- 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 0

Further rules:

Diagnostics

Edition

Policies are the same in editions 0.1 and 0.2.

Normative source