Home / Learn / 17 Information flow
17.2 Sinks: where labeled data may go
Page 3 of 11
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), 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, with nothing about labels:
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:
[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). 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) 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) |
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) |
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 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.
--- 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 asaccepts secret[PII](section 17.4). - Without the clause, the operation accepts
public. - One clause per operation. An operation has at most one
acceptsclause, and it applies to every argument of the operation. - Its place. The clauses of an operation come in a fixed order: every
requires, then everyensures, thenfails, thenaccepts. TheMailerof section 17.6 has afailsclause and then itsaccepts.
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:
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:
accepts internal. The supplier's service is one of the store's own systems, so its operation may receiveinternaldata. Without the clause it would accept onlypublicdata, and the call insend_listwould be U4003.send_list(list: internal Text). The parameter declares the label it receives.@supplier.submit(list)checks, becauseinternalis at or belowinternal.@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 grantfiles:src:read,write.let list = @files.read("reorder.csv").listisinternal Text, whatever the file holds, so it is whatsend_listreceives.@console.print("reorder list sent to the supplier"). The message is a literal, so it is public. Printinglisthere would be U4003.
una run . prints:
reorder list sent to the supplier17.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.
17.2.7.3 A handler is checked for its most sensitive caller
A handler of an operation (chapter 12) 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:
--- 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")
[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 revealThe 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.) 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
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) |
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): uses @keys: Keys[hmac]. Then:
- The call is
@keys.hmac(key_name: "optout", data: address).key_namenames a key the host holds, anddatais the text to hash. - The failure.
hmacfails withKeyError, 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). - The type of the result is
Hashed, with a label:internal, joined with the label ofdata.
Here is the check of the do-not-mail list:
--- 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 > 0address: secret Text. An address is about a person, so it issecret.if error pass. If the host has no key namedoptout, the check fails withKeyError, and the caller decides what to do.hashedis asecret Hashed:internal, joined with the label of the address.entry == hashedcompares two hashes. It readshashed, so it is asecret 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 shows. To send a hash where its label may not go, release it through a policy (section 17.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:
[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:
[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:
--- 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 == falsefake_keysis a handler ofKeys, a host capability, written as a fake of a host capability is in chapter 14. It makes hashes withfake_hash(seed), from the standard modulestd.testing, which the file imports withimport std.testing (fake_hash). The seed is a number that picks which fake hash you get: the same seed always gives the same hash, sofake_hash(1)stands for the hash of the listed address.given @keys = fake_keys()installs the handler for one example only. Section 14.3 teachesgivenand 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:
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:
[U3015] Error: this `with` binding installs a handler that uses `std.testing`, which only `given` lines of examples may installuna test . prints:
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 failedUse 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:
--- 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?
Show the answer
No:
[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: 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:
--- 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?
Show the answer
No:
[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.