Home / Learn / 17 Information flow
17.3 Branches and failures: implicit flows
Page 4 of 11
17.3.1 What an implicit flow is
Ask a colleague whether a customer spent more than 500.00 this year, and agree that they will answer by raising a hand for yes. They never say the amount, yet you learn something about it. The answer is in which way they acted.
A program can leak the same way. A value flows explicitly when it is copied or computed into another, as the cost flows into the margin. It flows implicitly when it decides which way the program goes: a branch on the cost that returns 0 or 790 reveals something about the cost, although 0 and 790 are constants.
The checker tracks implicit flows with the label of the program counter: the label of what decided that the program is where it is now. (The name comes from the processor, whose program counter holds the place in the program that runs next. Here it names the label of that place.) At the start of a function it is public. Inside a branch on labeled data, it rises to the condition's label, and everything the branch decides carries that label. After the branch, it is back to what it was.
17.3.2 Why constants can leak
Give a loyalty card a badge, decided by what the customer spent, and declare the badge public:
--- `if … then … else` on a labeled condition: the badge printed on a loyalty card.
badge(spent: confidential Int) -> Text = if spent >= 50000 then "gold" else "standard"una check . reports:
[U4001] Error: the result of `badge` is `public`, and which value it returns depends on this `confidential` condition: a flow from `confidential` to `public`
╭─[ src/loyalty.una:7:45 ]
│
7 │ badge(spent: confidential Int) -> Text = if spent >= 50000 then "gold" else "standard"
│ ───────┬──────
│ ╰──────── the result of `badge` is `public`, and which value it returns depends on this `confidential` condition: a flow from `confidential` to `public`"gold" and "standard" are literals, so each is public. But a reader who sees the badge learns whether spent is at least 50000. The diagnostic says so, and points at the condition, spent >= 50000, since that is where the information enters. Without this rule, a program could copy a secret one bit at a time through branches, and no single value in it would carry a label.
17.3.3 How the program counter rises
Every construct that chooses a way by a value raises the program counter by that value's label: the branches, and loops, which choose how many times their body runs. The next step shows each one, with a confidential amount, and declares each result confidential:
17.3.3.1 if … then … else
--- `if … then … else` on a labeled condition: the badge printed on a loyalty card.
badge(spent: confidential Int) -> confidential Text = if spent >= 50000 then "gold" else "standard"17.3.3.2 An if block
--- An `if` block on a labeled condition: the points a purchase of `cents` earns.
points(spent: confidential Int, cents: Int) -> confidential Int
=
if spent >= 50000
let doubled = cents / 50
doubled
else
cents / 100Both branches of the block run under the condition's label: doubled, computed from the public cents, is confidential inside the branch, and so is cents / 100.
17.3.3.3 when on a labeled value
A when (chapter 8) chooses an arm by the variant of a value. On a labeled value, which arm runs reveals the variant:
--- A `when` on a labeled value: the discount of a tier, in percent.
discount(tier: confidential Tier) -> confidential Int
=
when tier
is Gold -> 10
is Silver -> 5
is Standard -> 017.3.3.4 if none use on a labeled Option
Whether an Option (chapter 7) is None is information too, so the value chosen by if none use carries the option's label:
--- `if none use` on a labeled `Option`: what a customer spent, or 0 for a new customer.
spending(found: confidential Option[Int]) -> confidential Int
=
let spent = found
if none use 0
spent17.3.3.5 A for loop over a labeled list or range
A for loop (chapter 9) decides something too: how many times its body runs. A loop over a list runs once per element, so the number of turns reveals the list's length, which has the label of the whole list (Length, and the label of a whole). A loop over a range reveals its bounds. So the body runs under the label of the whole list, or of the bounds:
--- A `for` loop over a labeled list: what a customer spent over several purchases.
total_spent(purchases: confidential List[Int]) -> confidential Int
=
let edit total: confidential Int = 0
for cents in purchases
total = total + cents
total
--- A `for` loop over a labeled range: the stamps on a card, 10 for each visit.
stamps(visits: confidential Int) -> confidential Int
=
let edit earned: confidential Int = 0
for visit in 1..visits
earned = earned + 10
earnedtotal and earned are editable names, accumulators that each turn updates (chapter 9). An editable name keeps the label it was declared with, so each one is declared with the label the loop gives it: let edit total: confidential Int = 0. Without that label, total would be a public Int, and the update inside the loop would be U4001.
A loop over a list whose elements alone are labeled, such as the catalog of step 03, a List[Product] with a confidential field, runs at the program counter it had: how many products there are is public. Each element still carries its own labels. The prelude's map, filter and fold follow the same rule as a loop: the function they call once per element runs under the label of the whole list.
An operation in the body is under the loop's label too. Print a line for each purchase:
--- a/src/loyalty.una
+++ b/src/loyalty.una
@@ -48,2 +48,9 @@
+--- Prints a line for each purchase on the receipt.
+print_purchases(purchases: confidential List[Int]) -> Unit
+ uses @console: Console[print]
+=
+ for cents in purchases
+ @console.print("one more purchase")
+
pub main() -> Unit[U4003] Error: `@console.print` accepts `public` data, and it runs under a `confidential` condition, which it would reveal
╭─[ src/loyalty.una:54:5 ]
│
53 │ for cents in purchases
│ ────┬────
│ ╰────── the labeled condition
54 │ @console.print("one more purchase")
│ ─────────────────┬─────────────────
│ ╰─────────────────── `@console.print` accepts `public` data, and it runs under a `confidential` condition, which it would revealThe mark "the labeled condition" points at purchases, after in: the list decides how many times the body runs, so it plays the part of an if's condition. The printed text is a literal, and the number of lines printed would still reveal how many purchases there are. To show the count, release it through a policy (section 17.5) and print it after the loop, or send each line to a place that accepts confidential data.
17.3.3.6 Running the branch forms
The examples look at each labeled result:
example "a customer who spent 720.00 gets the gold badge"
do badge(72000)
expect result == "gold"
example "a gold customer earns double points"
do points(72000, cents: 5000)
expect result == 100
example "a silver customer gets 5 percent off"
do discount(Silver)
expect result == 5
example "a new customer has spent nothing"
do spending(None)
expect result == 0
example "three purchases add up"
do total_spent([2100, 4990, 12600])
expect result == 19690
example "a customer with 3 visits has 30 stamps"
do stamps(3)
expect result == 30example loyalty "a customer who spent 720.00 gets the gold badge" ... ok
example loyalty "a gold customer earns double points" ... ok
example loyalty "a silver customer gets 5 percent off" ... ok
example loyalty "a new customer has spent nothing" ... ok
example loyalty "three purchases add up" ... ok
example loyalty "a customer with 3 visits has 30 stamps" ... ok
6 examples: 6 passed, 0 failed17.3.4 A fee decided by a branch
This step charges a shipping fee. Loyal customers, those who spent at least 50000 cents, ship for free, and what a customer spent is confidential:
module shipping
--- The payment provider. It may receive confidential amounts.
capability Payments
op charge(order: Text, cents: Int) -> Unit
accepts confidential
--- The shipping fee, in cents. Loyal customers ship for free. Which branch runs depends on
--- what the customer spent, so the fee is confidential, even though 0 and 790 are not.
shipping_fee(spent: confidential Int) -> confidential Int = if spent >= 50000 then 0 else 790
--- Charges an order's shipping fee.
charge_shipping(order: Text, spent: confidential Int) -> Unit
uses @payments: Payments[charge]
=
@payments.charge(order, cents: shipping_fee(spent))
--- A payment provider that accepts every charge, for this run.
handler accepting() for Payments
op charge(order, cents) = unit
pub main() -> Unit
uses @console: Console[print]
=
charge_shipping("A-1001", spent: 72000) with @payments = accepting()
charge_shipping("A-1002", spent: 1500) with @payments = accepting()
@console.print("shipping charged for 2 orders")Walkthrough:
accepts confidentialoncharge. The payment provider must receive the shipping fee, which is confidential, so its operation acceptsconfidentialdata.shipping_fee(spent: confidential Int) -> confidential Int. The branch is onspent, so the fee isconfidential. Declaring-> Intis U4001, at the condition (a branch that decides a public result shows it).@console.print("shipping charged for 2 orders").mainprints a constant. It knows how many orders it charged, which depends on nothing confidential.
una run . prints:
shipping charged for 2 orders17.3.5 What may happen under a labeled branch
A branch on labeled data may compute values, and those values carry the label. It may not do anything a public observer would notice: fail, or act on the world below the label.
17.3.5.1 A failure is a flow too
Whether a function fails is something its caller observes (chapter 7). A fail inside a branch on labeled data would reveal the condition to every caller, through the failure. So fail, and handling clauses that fail or pass a failure on, are allowed only where the program counter is public. Add a free-shipping code that fails for customers who did not spend enough:
--- a/src/shipping.una
+++ b/src/shipping.una
@@ -10,2 +10,13 @@
shipping_fee(spent: confidential Int) -> confidential Int = if spent >= 50000 then 0 else 790
+
+kind FeeError = | NotEligible
+
+--- The free-shipping code of a loyal customer.
+free_shipping_code(spent: confidential Int) -> confidential Text
+ fails FeeError
+=
+ if spent < 50000
+ fail NotEligible
+ else
+ "FREESHIP"
[U4002] Error: this `fail` depends on `confidential` data, so its failure would reveal it; return a labeled value instead of failing
╭─[ src/shipping.una:19:5 ]
│
18 │ if spent < 50000
│ ──────┬──────
│ ╰──────── the labeled condition
19 │ fail NotEligible
│ ────────┬───────
│ ╰───────── this `fail` depends on `confidential` data, so its failure would reveal it; return a labeled value instead of failing
│The diagnostic has two marks. The first, "the labeled condition", is the branch that raised the program counter. The second is the fail it decides. The repair is in the message: return a labeled value instead of failing.
17.3.5.2 Return a labeled answer instead
Here is the repair. The code is an Option: Some with the code for a loyal customer, None for anyone else, and the whole answer is confidential:
--- The free-shipping code of a loyal customer, or `None`. The answer carries the label of
--- what decided it, so the caller learns it only where `confidential` data may go.
free_shipping_code(spent: confidential Int) -> confidential Option[Text] = if spent < 50000 then None else Some("FREESHIP")example shipping "a loyal customer has a code" ... ok
example shipping "another customer has none" ... ok
2 examples: 2 passed, 0 failedThe caller receives the answer with its label, and decides what to do with it under the same rules. It may send it to a place that accepts confidential data, such as the payment provider, and may not branch on it to fail.
17.3.5.3 An effect under a labeled branch
An operation performed inside the branch is seen by its sink, so the sink must accept the condition's label. Thank loyal customers on the console:
--- a/src/shipping.una
+++ b/src/shipping.una
@@ -17,2 +17,9 @@
+--- Greets a loyal customer at the checkout.
+greet(spent: confidential Int) -> Unit
+ uses @console: Console[print]
+=
+ if spent >= 50000
+ @console.print("thank you for shopping with us again")
+
--- A payment provider that accepts every charge, for this run.[U4003] Error: `@console.print` accepts `public` data, and it runs under a `confidential` condition, which it would reveal
╭─[ src/shipping.una:23:5 ]
│
22 │ if spent >= 50000
│ ───────┬──────
│ ╰──────── the labeled condition
23 │ @console.print("thank you for shopping with us again")
│ ───────────────────────────┬──────────────────────────
│ ╰──────────────────────────── `@console.print` accepts `public` data, and it runs under a `confidential` condition, which it would revealThe printed text is a literal, but whether it is printed reveals the branch. The message names both: the console accepts public, and it runs under a confidential condition. The payment provider of this step accepts confidential, so @payments.charge would be allowed in the same branch.
17.3.5.4 A call under a labeled branch
The same rule covers calls of your own functions. Under a labeled program counter, a function may call another only if the callee cannot fail, and every operation it may perform accepts that label. A pure function, one with no uses that does nothing but compute its result, such as shipping_fee, may be called anywhere if it cannot fail. Move the print of the last step into a function of its own, thank, and call it from the branch:
--- a/src/shipping.una
+++ b/src/shipping.una
@@ -21,2 +21,15 @@
+--- Thanks a customer on the console.
+thank() -> Unit
+ uses @console: Console[print]
+=
+ @console.print("thank you for shopping with us again")
+
+--- Greets a loyal customer at the checkout, through `thank`.
+greet(spent: confidential Int) -> Unit
+ uses @console: Console[print]
+=
+ if spent >= 50000
+ thank()
+
pub main() -> Unit[U4002] Error: `thank` has effects that accept at most `public` data, and it is called under a `confidential` condition, which would be revealed
╭─[ src/shipping.una:33:5 ]
│
32 │ if spent >= 50000
│ ───────┬──────
│ ╰──────── the labeled condition
33 │ thank()
│ ───┬───
│ ╰───── `thank` has effects that accept at most `public` data, and it is called under a `confidential` condition, which would be revealedThe print is now one call away, and the checker still finds it: thank holds the console, which accepts only public data, so calling it under a confidential condition is U4002. The code is U4002 rather than U4003 because the diagnostic is about the call of your function, not about an operation in this branch. A function with a fails clause is refused in the same place, for the reason of A failure is a flow too.
17.3.5.5 After the branch
The program counter rises only inside the branch. The lines after the if, the when or the for run at the label they had before it, so a function may branch on a secret, produce a labeled value, and then fail or print on public data in its next lines.
17.3.6 Where to put a decision
Which to use:
| You need to… | Do this |
|---|---|
| Compute a value that depends on labeled data | branch, and label the result |
| Repeat work over a labeled list or up to a labeled bound | loop, label the accumulators, and act only on services that accept the label |
| Report "no answer" for some labeled inputs | return a labeled Option or a labeled variant, not a failure |
| Fail, or print, or call a service, depending on labeled data | release the one fact the decision needs through a policy (section 17.5), then branch on the public result |
| Act on a service that accepts the label | do it in the branch: its accepts covers the condition |
17.3.7 Check yourself: branches
A bulky item costs 15.00 to ship for every customer. Someone writes it with the same shape as shipping_fee, and declares it public:
--- a/src/shipping.una
+++ b/src/shipping.una
@@ -10,2 +10,5 @@
shipping_fee(spent: confidential Int) -> confidential Int = if spent >= 50000 then 0 else 790
+
+--- The fee for a bulky item, which every customer pays.
+bulky_fee(spent: confidential Int) -> Int = if spent >= 50000 then 1500 else 1500
Both branches give 1500. Does una check . pass?
Show the answer
No:
[U4001] Error: the result of `bulky_fee` is `public`, and which value it returns depends on this `confidential` condition: a flow from `confidential` to `public`The checker does not compare the branches' values: it sees a result chosen by a confidential condition, and labels it so. Here the branch is useless, and the repair is to remove it: bulky_fee() -> Int = 1500. A rule that never looks at the values is one you can predict from the code's shape alone.
Next:17.4 Categories