---
title: "17.1 Labels and how they follow data"
url: https://una-lang.org/en/learn/information-flow/labels-and-how-they-follow-data/
release: v0.4.0
edition: "0.2"
---

# 17.1 Labels and how they follow data

## 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](https://una-lang.org/en/learn/numbers/values-types-and-names-let/#s2-1)): `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](https://una-lang.org/en/learn/information-flow/categories/#s17-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](https://una-lang.org/en/learn/numbers/values-types-and-names-let/#each-step-is-a-package) 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:

```una include="steps/01-no-labels/src/pricing.una" title="steps/01-no-labels/src/pricing.una" verified="check, run"
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:

```text include="steps/01-no-labels/expected/output.txt"
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](#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](https://una-lang.org/en/learn/kinds/records/#s4-1)) can carry a label. Every value of the kind then holds a labeled value in that field, next to its unlabeled ones:

```una include="steps/02-label-forms/src/pricing.una#UnitCost" title="steps/02-label-forms/src/pricing.una"
--- 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 Int
```

`sku` 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:

```una include="steps/02-label-forms/src/pricing.una#landed" title="steps/02-label-forms/src/pricing.una"
--- 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 + freight
```

`freight` 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:

```una include="steps/02-label-forms/src/pricing.una#batch" title="steps/02-label-forms/src/pricing.una"
--- 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
  total
```

`let 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:

```una include="steps/02-label-forms/src/pricing.una#cost_list" title="steps/02-label-forms/src/pricing.una"
--- 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:

```una include="steps/02-label-forms/src/pricing.una#renegotiating" title="steps/02-label-forms/src/pricing.una"
--- 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:

```una include="steps/02-label-forms/src/pricing.una#shelf_name" title="steps/02-label-forms/src/pricing.una"
--- `public` written out, which means the same as no label.
shelf_name(item: UnitCost) -> public Text = item.sku
```

Write 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](https://una-lang.org/en/learn/information-flow/releasing-data-policies-and-trusted-modules/#s17-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](https://una-lang.org/en/learn/information-flow/sinks-where-labeled-data-may-go/#examples-are-not-sinks) says more):

```una include="steps/02-label-forms/src/pricing.una#L34-L48" title="steps/02-label-forms/src/pricing.una" caption="the examples"
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 == 1
```

`una run .` prints:

```text include="steps/02-label-forms/expected/output.txt"
LAMP-01 and DESK-02: 2 costs on file
```

and `una test .` prints:

```text include="steps/02-label-forms/expected/commands/test.txt#L2-L7"
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 failed
```

## 17.1.4 A catalog with a confidential cost

Now the catalog of [Why a program needs labels](#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:

:::steps
```una include="steps/03-labels/src/pricing.una" title="steps/03-labels/src/pricing.una" verified="check, run"
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:

1. **`cost: confidential Int`.** A field can carry a label. Every `Product` holds a confidential cost next to a public price.
2. **`margin(product: Product) -> confidential Int`.** The result of `price - cost` joins the labels of its operands, so it is `confidential`. The header must say so: declaring `-> Int` would claim the margin is public, and the checker reports U4001.
3. **`price_tag`.** It reads only `sku` and `price`, 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.
4. **`margins.len`.** `margins` is a `List[confidential Int]`: the elements are confidential, the list itself is not. How many margins there are is public, so `main` may print it.
:::

`una run .` prints:

```text include="steps/03-labels/expected/output.txt"
LAMP-01: 4990 cents
DESK-02: 18900 cents
2 margins computed
```

## 17.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:

```diff include="steps/03-labels..steps/37-other-costs:src/pricing.una" context="1" title="src/pricing.una"
--- 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 catalog
```

`una run .` prints:

```text include="steps/37-other-costs/expected/output.txt"
LAMP-01: 4990 cents
DESK-02: 18900 cents
2 margins computed
```

These are the three lines that the catalog of [A catalog with a confidential cost](#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](https://una-lang.org/en/learn/information-flow/releasing-data-policies-and-trusted-modules/#s17-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](https://una-lang.org/en/learn/information-flow/releasing-data-policies-and-trusted-modules/#what-the-build-report-shows)), and [the security model](https://una-lang.org/en/docs/security/) 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](https://una-lang.org/en/learn/editions/).)

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

```diff include="steps/02-label-forms..steps/04-let-flow:src/pricing.una" context="1" title="src/pricing.una"
--- 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
   total
```

`una check .` reports:

```text include="steps/04-let-flow/expected/rendered.txt"
[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](https://una-lang.org/en/learn/information-flow/releasing-data-policies-and-trusted-modules/#s17-5)).

## 17.1.7 Printing a confidential value

Now print the margins themselves, as [Why a program needs labels](#why-a-program-needs-labels) did:

```diff include="steps/03-labels..steps/05-leak:src/pricing.una" context="1" title="src/pricing.una"
--- 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}")
```

```text include="steps/05-leak/expected/rendered.txt#L1-L10"
[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 module
```

The 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](https://una-lang.org/en/learn/information-flow/sinks-where-labeled-data-may-go/#s17-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](https://una-lang.org/en/learn/information-flow/releasing-data-policies-and-trusted-modules/#s17-5) shows when that is right.

## 17.1.8 Choosing a level

:::decide
**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](https://una-lang.org/en/learn/information-flow/categories/#s17-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](#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:

```diff include="steps/03-labels..steps/06-sheet-line:src/pricing.una" context="1" title="src/pricing.una"
--- 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)
```

:::answer Show the answer
It does not check:

```text include="steps/06-sheet-line/expected/rendered.txt#L1"
[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:

```diff include="steps/03-labels..steps/07-whole-record:src/pricing.una" context="1" title="src/pricing.una"
--- 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)
```

:::answer Show the answer
It does not check:

```text include="steps/07-whole-record/expected/rendered.txt#L1-L8"
[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` accepts
```

Interpolating 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.
:::
