---
title: "17.2 Sinks: where labeled data may go"
url: https://una-lang.org/en/learn/information-flow/sinks-where-labeled-data-may-go/
release: v0.4.0
edition: "0.2"
---

# 17.2 Sinks: where labeled data may go

## 17.2.1 What a sink is

A **sink** is a place where data leaves the program: printed to the console, written to a file, sent to a service. In Una every such exit is an argument of a capability operation ([chapter 12](https://una-lang.org/en/learn/capabilities/)), so every argument of an operation is a sink.

Each sink has a **ceiling**: the highest label it accepts. Think of a mail slot marked "internal mail only": anything at or below that label may go through, and anything above it is turned away at the slot. The checker proves, at every call of an operation, that every argument is at or below the operation's ceiling.

## 17.2.2 Why a sink needs a ceiling

The store's supplier needs the reorder list, which the program reads from a file. Here is a program that sends it. The supplier's service is a capability declared as in [chapter 12](https://una-lang.org/en/learn/capabilities/your-own-capabilities-and-handlers/#s12-3), with nothing about labels:

```una include="steps/09-no-accepts/src/reorder.una" title="steps/09-no-accepts/src/reorder.una"
module reorder

--- The supplier's ordering service, declared as in chapter 12.
capability Supplier
  op submit(order: Text) -> Unit

--- Sends the reorder list to the supplier.
send_list(list: internal Text) -> Unit
  uses @supplier: Supplier[submit]
=
  @supplier.submit(list)

--- A supplier that accepts every order, for this run.
handler accepting() for Supplier
  op submit(order) = unit

pub main() -> Unit
  uses @console: Console[print]
  uses @files: Files[read, write]
=
  @files.write("reorder.csv", content: "LAMP-01,20\nDESK-02,5\n")
    if error use unit
  let list = @files.read("reorder.csv")
    if error use ""
  send_list(list) with @supplier = accepting()
  @console.print("reorder list sent to the supplier")
```

`main` writes the list to a file, reads it back into `list`, and hands it to `send_list`, which submits it to the supplier. The parameter of `send_list` says `internal Text`: data read from a file is `internal`, as the next subsections explain. `una check .` refuses the call in `send_list`:

```text include="steps/09-no-accepts/expected/rendered.txt#L1-L8"
[U4003] Error: `@supplier.submit` accepts `public` data, and this argument is `internal`
    ╭─[ src/reorder.una:11:20 ]
    │
 11 │   @supplier.submit(list)
    │                    ──┬─
    │                      ╰─── `@supplier.submit` accepts `public` data, and this argument is `internal`
    │
    │ Help 1: repair 1: send `@supplier.submit` only data labeled `public` or lower, or send this value to an operation that accepts `internal`
```

The list is `internal`, since it came from a file ([Data from outside is `internal`](#data-from-outside-is-internal)). An operation with no ceiling of its own accepts only `public` data. So the checker refuses to send the list, even though the supplier is exactly where it should go. What is missing is a way to say that this service may receive the store's internal data. That is the `accepts` clause. The first repair una lists says the same: send this value to an operation that accepts `internal`.

## 17.2.3 The ceilings of the host's operations

The operations the host provides ([chapter 12](https://una-lang.org/en/learn/capabilities/the-hosts-capabilities-and-grants/#s12-2)) have fixed ceilings:

| Operation | Accepts | Gives back |
| --- | --- | --- |
| `Console.print(line)` | `public` | nothing |
| `Clock.now()` | `public` | a public `Int` |
| `Env.get(name)` | `public` | an `Option[internal Text]` |
| `Files.read(path)` | `public` | an `internal Text` |
| `Files.write(path, content)` | `internal` | nothing |
| `Http.get`, `post`, `put` and `delete` ([chapter 12](https://una-lang.org/en/learn/capabilities/the-hosts-capabilities-and-grants/#s12-2)) | `internal`, for every argument | a `Response`, the web service's answer, labeled `internal` |
| `Keys.hmac(key_name, data)` | `public` for the key name, any label for the data | a `Hashed`, labeled `internal` and the label of the data ([A keyed hash](#a-keyed-hash-keyshmac-and-hashed)) |

So a program may print only public data, and may write to a file, or send to a web service, what it read from one, but no more than `internal`.

## 17.2.4 Data from outside is `internal`

Data read from files, the environment or the network is labeled `internal`. `Files.read` returns `internal Text`, `Env.get` returns `internal` values, and an `Http` request, a message to a web service, returns a `Response`, the web service's answer, labeled `internal`: a file, an environment variable or a web service may hold anything, so the program may pass what it read to the store's own systems, but may not print it. A count of what was read, such as its length, carries the same label, as [Check yourself: sinks and keyed hashes](#check-yourself-sinks-and-keyed-hashes) shows.

## 17.2.5 How to write `accepts`

An operation of your own states its ceiling with an `accepts` clause, the word `accepts` and a label, on its own line under the operation. The clause belongs only to an `op` of a `capability`: a function has no ceiling of its own, since what it may send is bounded by the operations it calls.

```una include="steps/08-sinks/src/reorder.una#Supplier" title="steps/08-sinks/src/reorder.una"
--- The supplier's ordering service. It may receive the store's internal data, and no more.
capability Supplier
  op submit(order: Text) -> Unit
    accepts internal
```

- **The label** is any label: a level, such as `accepts internal`, or a level with categories, such as `accepts secret[PII]` ([section 17.4](https://una-lang.org/en/learn/information-flow/categories/#s17-4)).
- **Without the clause,** the operation accepts `public`.
- **One clause per operation.** An operation has at most one `accepts` clause, and it applies to every argument of the operation.
- **Its place.** The clauses of an operation come in a fixed order: every `requires`, then every `ensures`, then `fails`, then `accepts`. The `Mailer` of [section 17.6](https://una-lang.org/en/learn/information-flow/day-to-day-shipping-notices-with-labels/#s17-6) has a `fails` clause and then its `accepts`.

## 17.2.6 Sending a reorder list to the supplier

This step passes a reorder list from a file to the supplier, whose service accepts `internal` data:

:::steps
```una include="steps/08-sinks/src/reorder.una" title="steps/08-sinks/src/reorder.una" verified="check, run"
module reorder

--- The supplier's ordering service. It may receive the store's internal data, and no more.
capability Supplier
  op submit(order: Text) -> Unit
    accepts internal

--- Sends the reorder list to the supplier.
send_list(list: internal Text) -> Unit
  uses @supplier: Supplier[submit]
=
  @supplier.submit(list)

--- A supplier that accepts every order, for this run.
handler accepting() for Supplier
  op submit(order) = unit

pub main() -> Unit
  uses @console: Console[print]
  uses @files: Files[read, write]
=
  @files.write("reorder.csv", content: "LAMP-01,20\nDESK-02,5\n")
    if error use unit
  let list = @files.read("reorder.csv")
    if error use ""
  send_list(list) with @supplier = accepting()
  @console.print("reorder list sent to the supplier")
```

Walkthrough:

1. **`accepts internal`.** The supplier's service is one of the store's own systems, so its operation may receive `internal` data. Without the clause it would accept only `public` data, and the call in `send_list` would be U4003.
2. **`send_list(list: internal Text)`.** The parameter declares the label it receives. `@supplier.submit(list)` checks, because `internal` is at or below `internal`.
3. **`@files.write(…)` then `@files.read(…)`.** A nightly job would write the list and a morning job read it. Here one program does both, with the grant `files:src:read,write`.
4. **`let list = @files.read("reorder.csv")`.** `list` is `internal Text`, whatever the file holds, so it is what `send_list` receives.
5. **`@console.print("reorder list sent to the supplier")`.** The message is a literal, so it is public. Printing `list` here would be U4003.
:::

`una run .` prints:

```text include="steps/08-sinks/expected/output.txt"
reorder list sent to the supplier
```

## 17.2.7 How a sink is checked

### 17.2.7.1 Every argument, on its own

The checker compares each argument with the ceiling, one at a time. A call with two arguments above the ceiling gets two diagnostics, one for each. An argument at or below the ceiling checks: `public` data may go anywhere.

### 17.2.7.2 Every label inside an argument

An argument's label includes the labels inside it. A `List[confidential Int]` sent to the console is refused, although the list itself is public, since printing it would print its elements. That is the leak of [Printing a confidential value](https://una-lang.org/en/learn/information-flow/labels-and-how-they-follow-data/#printing-a-confidential-value).

### 17.2.7.3 A handler is checked for its most sensitive caller

A handler of an operation ([chapter 12](https://una-lang.org/en/learn/capabilities/your-own-capabilities-and-handlers/#s12-3)) receives what callers send. The checker does not know which caller will run it, so it checks the handler for the most sensitive caller the `accepts` clause allows. Here the fake supplier prints a fixed line each time it is called:

```diff include="steps/08-sinks..steps/10-printing-handler:src/reorder.una" context="1" title="src/reorder.una"
--- a/src/reorder.una
+++ b/src/reorder.una
@@ -13,5 +13,6 @@
 
---- A supplier that accepts every order, for this run.
+--- A supplier that accepts every order, and says so on the console.
 handler accepting() for Supplier
-  op submit(order) = unit
+  uses @console: Console[print]
+  op submit(order) = @console.print("order received")
 
```

```text include="steps/10-printing-handler/expected/rendered.txt#L1-L6"
[U4003] Error: `@console.print` accepts `public` data, and it runs in an operation body whose callers may pass `internal` data, which it would reveal
    ╭─[ src/reorder.una:17:22 ]
    │
 17 │   op submit(order) = @console.print("order received")
    │                      ────────────────┬───────────────
    │                                      ╰───────────────── `@console.print` accepts `public` data, and it runs in an operation body whose callers may pass `internal` data, which it would reveal
```

The printed line is a literal, and it is still refused. The message gives the reason: the operation body may receive `internal` data, which the print *would reveal*. Whether the line appears is itself a signal, and a handler could print it only for some orders. So a handler of an operation that accepts `internal` data may not print at all. A fake that does nothing, fails, or returns fixed values stays valid.

### 17.2.7.4 Examples are not sinks

> [!NOTE]
> `expect` lines of examples are not sinks. An example may compare a `secret` result with a value, and in a package of edition `0.2`, `una test .` prints it in full when the example fails, since a test is the author looking at their own data. (Edition `0.1` hides the labeled fields of a result as `<redacted:level>`, [chapter 19](https://una-lang.org/en/learn/editions/).) The `do` line is checked like any other code: an example can observe a secret, but cannot send it anywhere the program itself could not.

## 17.2.8 Raising a ceiling, or sending less

:::decide
**Which to use:**

| The data… | Do this |
| --- | --- |
| Must reach the service as it is, such as an address for the mail service | give the operation an `accepts` clause with the data's label |
| Is more than the service needs, such as a whole record when it needs an id | send only the fields it needs, which may be public |
| Must reach a public place in part, such as a masked address in a log | release that part through a policy ([section 17.5](https://una-lang.org/en/learn/information-flow/releasing-data-policies-and-trusted-modules/#s17-5)) |
:::

Raise a ceiling only to the label the real service may receive. An `accepts` clause is a statement about the service, which a reviewer reads, not a way to make a diagnostic go away.

## 17.2.9 A keyed hash: `Keys.hmac` and `Hashed`

### 17.2.9.1 What a keyed hash is

A fingerprint card tells you whether two cards come from the same person, and it does not tell you the person's name or address. A **hash** is that card for a piece of data: a short value computed from a text, such that the same text always gives the same hash, and the hash does not give the text back. A **keyed hash** also mixes in a secret key that the host keeps outside the program, so that someone who has a copy of the hashes, and no key, cannot hash a guess and compare. The standard way to compute one is called HMAC, short for *hash-based message authentication code*.

In Una the host's `Keys` capability computes keyed hashes, with its operation `hmac`, and the result has the built-in type `Hashed`. A `Hashed` is opaque: the program can compare two of them, and can do nothing else with them.

### 17.2.9.2 Why a program hashes data

The store keeps a do-not-mail list: the customers who asked for no marketing. A list of their addresses would itself be personal data, and anyone who saw a copy would learn who is on it. A list of keyed hashes holds no address. To check a customer, the program hashes the customer's address with the same key and looks for that hash in the list. A match says the address is on the list, and the list never says whose addresses it holds.

### 17.2.9.3 How to write a keyed hash

A function that hashes declares the capability, as any function that uses the host does ([chapter 12](https://una-lang.org/en/learn/capabilities/the-hosts-capabilities-and-grants/#s12-2)): `uses @keys: Keys[hmac]`. Then:

- **The call** is `@keys.hmac(key_name: "optout", data: address)`. `key_name` names a key the host holds, and `data` is the text to hash.
- **The failure.** `hmac` fails with `KeyError`, whose one variant, `UnknownKey`, means the host has no key of that name. The call needs a handling clause, as every call that may fail does ([chapter 7](https://una-lang.org/en/learn/failure/handling-a-failure-the-clauses/#s7-3)).
- **The type** of the result is `Hashed`, with a label: `internal`, joined with the label of `data`.

Here is the check of the do-not-mail list:

```una include="steps/11-hashed/src/optout.una#opted_out" title="steps/11-hashed/src/optout.una"
--- Whether an address is on the do-not-mail list. The list keeps no addresses, only their
--- keyed hashes, made with the key `optout`, so a copy of the list reveals no one.
opted_out(address: secret Text, list: List[internal Hashed]) -> secret Bool
  uses @keys: Keys[hmac]
  fails KeyError
=
  let hashed = @keys.hmac(key_name: "optout", data: address)
    if error pass
  list.filter(keep: fn(entry) -> entry == hashed).len > 0
```

1. **`address: secret Text`.** An address is about a person, so it is `secret`.
2. **`if error pass`.** If the host has no key named `optout`, the check fails with `KeyError`, and the caller decides what to do.
3. **`hashed`** is a `secret Hashed`: `internal`, joined with the label of the address.
4. **`entry == hashed`** compares two hashes. It reads `hashed`, so it is a `secret Bool`, and so is the answer: whether a customer is on the list is something about the customer.

### 17.2.9.4 How a hash behaves

**It keeps the label of what it hashed.** Hashing does not lower a label. The hash of a `secret` address is `secret`, and a public answer computed from it is U4001, as [Check yourself: sinks and keyed hashes](#check-yourself-sinks-and-keyed-hashes) shows. To send a hash where its label may not go, release it through a policy ([section 17.5](https://una-lang.org/en/learn/information-flow/releasing-data-policies-and-trusted-modules/#s17-5)).

**Only `==` and `!=`.** A `Hashed` cannot be interpolated, so its bytes never reach a text. Add `let shown: secret Text = "hash {hashed}"` to `opted_out`:

```text include="steps/12-hash-text/expected/rendered.txt#L1"
[U2001] Error: interpolation writes values that hold no function and no `Hashed`, and this value is a `Hashed`
```

**The key name is public.** `hmac` accepts `public` data for `key_name` and any label for `data`, since whether the call fails with `UnknownKey` depends on the key name alone. Hash with `key_name: address`:

```text include="steps/13-hash-key-name/expected/rendered.txt#L1"
[U4003] Error: `@keys.hmac` accepts `public` data, and this argument is `secret`
```

### 17.2.9.5 Testing it with a stand-in

To run `hmac`, `una run` needs the grant `keys:<file>`, which names the file of keys the host reads. The steps of this book run with no keys, so `main` here prints only a line, and examples check `opted_out` with a stand-in for the host:

```una include="steps/11-hashed/src/optout.una#L15-L28" title="steps/11-hashed/src/optout.una" caption="the stand-in and the examples"
--- A stand-in for the key service, for the examples: one address hashes to the seed 1, and
--- every other address to the seed 2.
handler fake_keys() for Keys
  op hmac(key_name, data) = if data == "rita@example.invalid" then fake_hash(1) else fake_hash(2)

example "an address on the list is found"
  given @keys = fake_keys()
  do opted_out("rita@example.invalid", list: [fake_hash(1)])
  expect result == true

example "an address that is not on the list is not found"
  given @keys = fake_keys()
  do opted_out("tom@example.invalid", list: [fake_hash(1)])
  expect result == false
```

- **`fake_keys`** is a handler of `Keys`, a host capability, written as a fake of a host capability is in [chapter 14](https://una-lang.org/en/learn/testing/fakes-given-expect-performed-and-expect-not-performed/#a-fake-of-a-host-capability). It makes hashes with `fake_hash(seed)`, from the standard module `std.testing`, which the file imports with `import std.testing (fake_hash)`. The **seed** is a number that picks which fake hash you get: the same seed always gives the same hash, so `fake_hash(1)` stands for the hash of the listed address.
- **`given @keys = fake_keys()`** installs the handler for one example only. [Section 14.3](https://una-lang.org/en/learn/testing/fakes-given-expect-performed-and-expect-not-performed/#s14-3) teaches `given` and fakes in full.

**Only in examples.** A function of `std.testing` may be called only in example lines and in handlers that only `given` installs, so fake hashes never reach a real run. Install `fake_keys` in `main`, with `with` and the clause that handles a `KeyError`:

```una include="steps/14-hash-fake-in-main/src/optout.una#main" title="steps/14-hash-fake-in-main/src/optout.una"
pub main() -> Unit
  uses @console: Console[print]
=
  let found = opted_out("rita@example.invalid", list: []) with @keys = fake_keys()
    if error use false
  @console.print("checked")
```

`una check .` refuses the binding:

```text include="steps/14-hash-fake-in-main/expected/rendered.txt#L1"
[U3015] Error: this `with` binding installs a handler that uses `std.testing`, which only `given` lines of examples may install
```

`una test .` prints:

```text include="steps/11-hashed/expected/commands/test.txt#L2-L5"
example optout "an address on the list is found" ... ok
example optout "an address that is not on the list is not found" ... ok

2 examples: 2 passed, 0 failed
```

Use a keyed hash to recognize or match a value without keeping it, such as a do-not-mail list or a list of addresses already seen. Do not hash a value you need back: nothing turns a `Hashed` into the text it came from.

## 17.2.10 Check yourself: sinks and keyed hashes

The reorder program prints how many characters it sent, instead of a fixed message:

```diff include="steps/08-sinks..steps/15-length:src/reorder.una" context="1" title="src/reorder.una"
--- a/src/reorder.una
+++ b/src/reorder.una
@@ -26,2 +26,2 @@
   send_list(list) with @supplier = accepting()
-  @console.print("reorder list sent to the supplier")
+  @console.print("{list.len} characters sent to the supplier")
```

Does `una check .` pass?

:::answer Show the answer
No:

```text include="steps/15-length/expected/rendered.txt#L1"
[U4003] Error: `@console.print` accepts `public` data, and this argument is `internal`
```

`list` is `internal Text`, a whole that is labeled. `.len` has the label of the whole it measures, so the length is `internal` too, and the console accepts only `public`. Compare `margins.len` in [A catalog with a confidential cost](https://una-lang.org/en/learn/information-flow/labels-and-how-they-follow-data/#a-catalog-with-a-confidential-cost): there the list was public and only its elements were labeled.
:::

Second, someone declares the answer of `opted_out` public, reasoning that a hash reveals nothing:

```diff include="steps/11-hashed..steps/16-hashed-public:src/optout.una" context="1" title="src/optout.una"
--- a/src/optout.una
+++ b/src/optout.una
@@ -6,3 +6,3 @@
 --- keyed hashes, made with the key `optout`, so a copy of the list reveals no one.
-opted_out(address: secret Text, list: List[internal Hashed]) -> secret Bool
+opted_out(address: secret Text, list: List[internal Hashed]) -> Bool
   uses @keys: Keys[hmac]
```

Does `una check .` pass?

:::answer Show the answer
No:

```text include="steps/16-hashed-public/expected/rendered.txt#L1"
[U4001] Error: the result of `opted_out` is `Bool`, and this value is `secret Bool`: a flow from `secret` to `public`
```

The hash carries the label of the address it was made from, so `entry == hashed` is a `secret Bool`, and the declared result is a public `Bool`. A hash hides the text, but whether a customer is on the list is still a fact about that customer. Keep the answer `secret`, or release it through a policy if a public place must have it.
:::
