Home / Learn / 17 Information flow
17.1 Labels and how they follow data
Page 2 of 11
17.1.1 What a label is
An office stamps some folders "confidential" and some "for internal use only". The stamp travels with the folder, and anyone who copies a page from it copies the stamp too. A clerk at the front desk sees the stamp and knows that the folder stays behind the counter.
A label is that stamp, on a value. It says how sensitive the value is, and who may see it. In Una a label is part of a value's type, the description of what the value is (chapter 2): Int is a whole number, and confidential Int is a whole number that is confidential. The checker reads the label wherever the value goes.
A label has a level. Una has five, from least to most sensitive:
| Level | Meant for |
|---|---|
public |
anyone, such as a price on the shelf |
internal |
the store's own systems, such as a file the program read |
confidential |
business data, such as what the store pays its supplier |
secret |
data about people, such as a phone number |
restricted |
the most sensitive data, such as credentials |
A type with no label is public. A label may also name categories, which say what kind of data a value is, such as secret[PII] Text for personal data. Section 17.4 covers categories; until then, a label is just a level.
The checker knows only the order of the levels: public is below internal, which is below confidential, and so on up to restricted. What each level is meant for, in the right-hand column, is a convention you choose for your store, not a rule of the language.
17.1.2 Why a program needs labels
Each example of this chapter is a package, made as chapter 2 explains, and the chapter's download, 17-information-flow.tar.gz, holds them all.
Here is a catalog with no labels. The store sells each product at its price, and pays its supplier its cost. The difference, the margin, is business data the store would rather not show to customers:
module pricing
--- A product of the catalog: its SKU, the price customers pay, and what the store pays its supplier.
kind Product
sku: Text
price: Int
cost: Int
--- The margin of a product, in cents.
margin(product: Product) -> Int = product.price - product.cost
pub main() -> Unit
uses @console: Console[print]
=
let catalog = [Product(sku: "LAMP-01", price: 4990, cost: 2100), Product(sku: "DESK-02", price: 18900, cost: 12600)]
let margins = catalog.map(each: margin)
@console.print("margins: {margins}")una run . prints:
margins: [2890, 6300]The program checks, runs, and prints every margin to the console. Nothing in it says that cost is sensitive, so nothing can stop the margins from going out. In a real store this line could be a debug print, a line in a log that a support team reads, or a field in a web page. A comment on cost would not help: the checker does not read comments, and the person who adds the print may never see it.
A label makes the rule part of the program. Once cost is confidential Int, every value computed from it is confidential too, and the console refuses it. You will see that refusal in Printing a confidential value.
17.1.3 How to write a label
You write a label in front of the type it applies to: confidential Int, secret Text. A label goes anywhere a type goes. The next step shows each place, one function per form, and checks every one with an example.
17.1.3.1 On a field
A field of a kind (chapter 4) can carry a label. Every value of the kind then holds a labeled value in that field, next to its unlabeled ones:
--- What the store pays its supplier for one unit of a SKU. A label on a field: the amount is
--- confidential.
kind UnitCost
sku: Text
cents: confidential Intsku is public and cents is confidential, in the same record.
17.1.3.2 On a parameter and on the result
A parameter's label says what the function receives; the result's label says what the caller gets back:
--- A label on a parameter and on the result: the cost of a unit once freight is paid.
landed(cost: confidential Int, freight: Int) -> confidential Int = cost + freightfreight has no label, so it is public. The header says the result is confidential Int, which is what cost + freight is.
17.1.3.3 On an annotated let
A let may state the type of the value it names, after a colon. That type can carry a label:
--- A label on an annotated `let`: what a batch of units costs the store.
batch(item: UnitCost, quantity: Int) -> confidential Int
=
let total: confidential Int = item.cents * quantity
totallet total: confidential Int says, at that line, that total is confidential. Without the annotation, total would take the type of its value, confidential Int, anyway.
17.1.3.4 Inside another type
A label may stand inside a type that holds other types, such as a list. List[confidential Int] is a list whose elements are confidential:
--- A label inside a type: the list is public, and each element is confidential.
cost_list(items: List[UnitCost]) -> List[confidential Int] = items.map(each: fn(item) -> item.cents)The elements are confidential, and the list itself is not: how many costs there are is public.
17.1.3.5 On a whole list
A label in front of List labels the list as a whole, its length included:
--- A label on the whole list: which SKUs the store is renegotiating with its supplier.
renegotiating() -> confidential List[Text] = ["DESK-02"]Which SKUs the store is renegotiating is confidential, and so is how many there are.
17.1.3.6 public, written out
public is a level like the others, and you may write it. It means the same as no label:
--- `public` written out, which means the same as no label.
shelf_name(item: UnitCost) -> public Text = item.skuWrite it where a reader might wonder, such as on the result of a function that takes labeled data and gives a public answer. Section 17.5 does that.
17.1.3.7 Running the label forms
main prints only public facts: the SKUs, and how many costs are on file. The examples look at the labeled values themselves. An expect line of an example may compare a labeled value, since a test is the author looking at their own data (Examples are not sinks says more):
example "a lamp that costs 21.00, with 3.50 of freight"
do landed(2100, freight: 350)
expect result == 2450
example "three desks"
do batch(UnitCost(sku: "DESK-02", cents: 12600), quantity: 3)
expect result == 37800
example "the costs of two SKUs, in order"
do cost_list([UnitCost(sku: "LAMP-01", cents: 2100), UnitCost(sku: "DESK-02", cents: 12600)])
expect result == [2100, 12600]
example "one SKU is being renegotiated"
do renegotiating()
expect result.len == 1una run . prints:
LAMP-01 and DESK-02: 2 costs on fileand una test . prints:
example pricing "a lamp that costs 21.00, with 3.50 of freight" ... ok
example pricing "three desks" ... ok
example pricing "the costs of two SKUs, in order" ... ok
example pricing "one SKU is being renegotiated" ... ok
4 examples: 4 passed, 0 failed17.1.4 A catalog with a confidential cost
Now the catalog of Why a program needs labels, with its cost labeled. The price of a product is public. What the store pays its supplier is confidential, and so is anything computed from it:
module pricing
--- A product of the catalog. What the store pays its supplier is confidential.
kind Product
sku: Text
price: Int
cost: confidential Int
--- The margin of a product, in cents. It is computed from the cost, so it is confidential too.
margin(product: Product) -> confidential Int = product.price - product.cost
--- The tag on the shelf. It reads only public fields, so it is public.
price_tag(product: Product) -> Text = "{product.sku}: {product.price} cents"
pub main() -> Unit
uses @console: Console[print]
=
let catalog = [Product(sku: "LAMP-01", price: 4990, cost: 2100), Product(sku: "DESK-02", price: 18900, cost: 12600)]
for product in catalog
@console.print(price_tag(product))
let margins = catalog.map(each: margin)
@console.print("{margins.len} margins computed")Walkthrough:
cost: confidential Int. A field can carry a label. EveryProductholds a confidential cost next to a public price.margin(product: Product) -> confidential Int. The result ofprice - costjoins the labels of its operands, so it isconfidential. The header must say so: declaring-> Intwould claim the margin is public, and the checker reports U4001.price_tag. It reads onlyskuandprice, which are public, so its result is public. The checker does not label a whole record by its most sensitive field when you read a public field of it.margins.len.marginsis aList[confidential Int]: the elements are confidential, the list itself is not. How many margins there are is public, somainmay print it.
una run . prints:
LAMP-01: 4990 cents
DESK-02: 18900 cents
2 margins computed17.1.5 What the checker promises
main reads both costs to compute the margins. Would its output change if the costs did? Change them, and run it again. Here the lamp costs the store 40.00 instead of 21.00, and the desk 0.01 instead of 126.00:
--- a/src/pricing.una
+++ b/src/pricing.una
@@ -17,3 +17,3 @@
=
- let catalog = [Product(sku: "LAMP-01", price: 4990, cost: 2100), Product(sku: "DESK-02", price: 18900, cost: 12600)]
+ let catalog = [Product(sku: "LAMP-01", price: 4990, cost: 4000), Product(sku: "DESK-02", price: 18900, cost: 1)]
for product in cataloguna run . prints:
LAMP-01: 4990 cents
DESK-02: 18900 cents
2 margins computedThese are the three lines that the catalog of A catalog with a confidential cost printed, character for character. The margins are very different, and nothing on the console shows it. That is not luck with these numbers. The checker accepts this program, and the program releases nothing, so no other costs could change what it prints, as long as the run finishes.
This promise is called noninterference: values with a high label do not interfere with what can be seen at a lower one. An observer is whoever reads one place where data leaves the program: the person who reads the console sees public data, and a service that accepts internal data sees data up to internal. The promise holds for every observer. Take two runs whose data is the same at the observer's label and below, and differs only above it: the observer sees the same thing in both. What an observer can see is what the program returns, the failures it reports, the arguments it passes to operations, and whether an operation runs at all.
The promise has three limits:
- What a policy releases. A policy lowers a label on purpose (section 17.5), so what it releases may differ between two runs. The build report lists every release, so you can see each one.
- Runs that finish. The promise compares runs that end. A run that stops early, for instance because it runs out of memory, may stop at a point that depends on a labeled value.
- What the model covers. Some ways of learning about data are outside it, such as how long a run takes and how much memory it uses: a run that is slower for some costs shows that to anyone who times it. The build report lists them under
out of model(What the build report shows), and the security model describes each one.
17.1.6 How labels follow data
The checker gives every value a label, and follows it through each step of the program. These are the rules, each with the example that shows it.
17.1.6.1 A literal is public
A value written in the program, such as 4990, "LAMP-01" or true, is public. Anyone who reads the program can see it, so it reveals nothing.
17.1.6.2 Combining values joins their labels
When a computation uses several values, its result takes the highest of their levels. This is called the join of the labels. product.price - product.cost joins public and confidential, so the margin is confidential. cost + freight in landed is confidential for the same reason. The rule holds for arithmetic (+, -, *, /), comparisons (==, <, >=), the logical operators (and, or, not), and interpolation: "margin {margin(product)}" is a confidential text.
17.1.6.3 A field keeps its own label
Reading a field gives the field's label, raised by the label of the record it comes from. product.sku is public and product.cost is confidential, from the same product. That is why price_tag is public: it reads only public fields.
17.1.6.4 Length, and the label of a whole
.len has the label of the whole it measures, not of its elements. cost_list(...).len is public, since the list of costs is public and only its elements are labeled. renegotiating().len is confidential, since the whole list is labeled.
Whole values work the same way. Comparing two products with ==, or interpolating a whole product with "{product}", reads every field, cost included. So both results carry the label of the most sensitive field of the kind. (Interpolating a whole record needs edition 0.2, chapter 19.)
17.1.6.5 A declared type is a checkpoint
A value may flow into a place with a declared type only if its label is at or below the declared one. Every declared type is such a place: a parameter, a result, a field, and an annotated let. Here the annotated let of batch says Int, and the value is confidential:
--- a/src/pricing.una
+++ b/src/pricing.una
@@ -14,3 +14,3 @@
=
- let total: confidential Int = item.cents * quantity
+ let total: Int = item.cents * quantity
totaluna check . reports:
[U4001] Error: `total` is `Int`, and this value is `confidential Int`: a flow from `confidential` to `public`
╭─[ src/pricing.una:15:20 ]
│
15 │ let total: Int = item.cents * quantity
│ ──────────┬──────────
│ ╰──────────── `total` is `Int`, and this value is `confidential Int`: a flow from `confidential` to `public`
│
│ Note: run `una explain U4001` for an explanation
────╯Read it from the top. [U4001] is the code of a flow into a declared type with a lower label. The message names the place, `total` is `Int`, and the value, `confidential Int`. The mark under line 15 points at the value, not at the name. The last clause, a flow from confidential to public, says which way the information would move. The repair is one of two: raise the declared label to confidential Int, or lower the value on purpose through a policy, a declared release (section 17.5).
17.1.7 Printing a confidential value
Now print the margins themselves, as Why a program needs labels did:
--- a/src/pricing.una
+++ b/src/pricing.una
@@ -21,2 +21,2 @@
let margins = catalog.map(each: margin)
- @console.print("{margins.len} margins computed")
+ @console.print("margins: {margins}")[U4003] Error: `@console.print` accepts `public` data, and this argument is `confidential`
╭─[ src/pricing.una:22:18 ]
│
22 │ @console.print("margins: {margins}")
│ ──────────┬─────────
│ ╰─────────── `@console.print` accepts `public` data, and this argument is `confidential`
│
│ Help 1: repair 1: send `@console.print` only data labeled `public` or lower, or send this value to an operation that accepts `confidential`
│
│ Help 2: repair 2 (escape: trusted; the guarantee then rests on trusted code, whose labels are not checked: a policy releases the data, or a module joins the trusted base; it is listed in the build report and needs review): declassify the value through a policy of a trusted moduleThe interpolation "margins: {margins}" carries the labels of what it interpolates, so the text is confidential, and Console.print accepts public. The place where data leaves the program, the sink, is the subject of section 17.2. The repairs una lists, in the Help lines, come in order: first send only public data, or send the value to a place that accepts its label; last, release it through a policy, which it marks as an escape. Section 17.5 shows when that is right.
17.1.8 Choosing a level
Which to use:
| The value is… | Label it |
|---|---|
| Shown to anyone, such as a price | nothing (public) |
| For the store's own systems, such as data read from a file | internal |
| Business data, such as costs and margins | confidential |
| About a person, such as a name or an address | secret[PII], with a category (section 17.4) |
| The most sensitive, such as credentials | restricted |
These are conventions, not rules of the language. The checker knows only the order of the levels. Pick the level that matches who may see the data, and keep it the same across a package. When in doubt between two levels, pick the higher one: a label that is too high costs you a policy later, and a label that is too low lets data out.
17.1.9 Check yourself: labels
Each question changes the catalog of A catalog with a confidential cost. Decide whether una check . passes, and if not, which code it reports and where.
First, a line for the buyer's sheet, printed for each product:
--- a/src/pricing.una
+++ b/src/pricing.una
@@ -14,2 +14,5 @@
+--- A line of the buyer's sheet: what a product costs the store, and what it sells for.
+sheet_line(product: Product) -> Text = "{product.sku}: costs {product.cost}, sells for {product.price}"
+
pub main() -> Unit
@@ -19,3 +22,3 @@
for product in catalog
- @console.print(price_tag(product))
+ @console.print(sheet_line(product))
let margins = catalog.map(each: margin)Show the answer
It does not check:
[U4001] Error: the result of `sheet_line` is `Text`, and this value is `confidential Text`: a flow from `confidential` to `public`The interpolation reads product.cost, so the text is confidential, and the header of sheet_line declares a plain Text. The checker stops at the first checkpoint the value meets, the declared result, before it reaches the console.
Second, print each product whole:
--- a/src/pricing.una
+++ b/src/pricing.una
@@ -19,3 +19,3 @@
for product in catalog
- @console.print(price_tag(product))
+ @console.print("on the shelf: {product}")
let margins = catalog.map(each: margin)Show the answer
It does not check:
[U4003] Error: `@console.print` accepts `public` data, and this argument is `confidential`
╭─[ src/pricing.una:20:20 ]
│
20 │ @console.print("on the shelf: {product}")
│ ────────────┬────────────
│ ╰────────────── `@console.print` accepts `public` data, and this argument is `confidential`
│
│ Help 1: repair 1: field `cost` of `Product` is `confidential`: interpolate only the fields that `@console.print` acceptsInterpolating the whole product writes every field, cost included, so the text is confidential. The first repair names the field that makes it so: interpolate only the fields the console accepts, as price_tag does.