Home / Learn / 17 Information flow

Release v0.4.0Edition 0.2

17.4 Categories

Page 5 of 11

17.4.1 What a category is

A level says how sensitive data is. A category says what kind of data it is: personal data, a location, a payment card number. Think of a colored sticker next to the "confidential" stamp: two folders can be equally sensitive and still belong in different cabinets.

You write categories in square brackets after the level: secret[PII] Text is secret, and it is personal data (PII stands for personally identifiable information). Each package declares its own categories by name.

17.4.2 Why a level is not enough

A courier needs a customer's phone number, so that the driver can call at the door. The analytics service records bookings, and it may receive secret data, such as the store's sales figures. Here is a route booking with a level and no category:

steps/25-no-category/src/courier.unacheckrununa
module courier

--- A stop on a delivery route. The phone number is secret, and nothing says it is personal.
kind Stop
  order: Text
  city: Text
  phone: secret Text

--- The courier's booking service. It may receive secret data.
capability Courier
  op book(order: Text, phone: Text) -> Unit
    accepts secret

--- The store's analytics service. It may receive secret data too: sales figures, for one.
capability Analytics
  op record(event: Text) -> Unit
    accepts secret

--- Books every stop of a route, and records each booking for the analysts.
book_route(stops: List[Stop]) -> Unit
  uses @courier: Courier[book]
  uses @analytics: Analytics[record]
=
  for stop in stops
    @courier.book(stop.order, phone: stop.phone)
    @analytics.record("booked {stop.order} in {stop.city} for {stop.phone}")

--- A courier that accepts every booking, for this run.
handler accepting() for Courier
  op book(order, phone) = unit

--- An analytics service that stores nothing, for this run.
handler discarding() for Analytics
  op record(event) = unit

pub main() -> Unit
  uses @console: Console[print]
=
  let route = [Stop(order: "A-1001", city: "Recife", phone: "+55 81 5550 0101"), Stop(order: "A-1002", city: "Olinda", phone: "+55 81 5550 0102")]
  book_route(route) with @courier = accepting(), @analytics = discarding()
  @console.print("route booked and recorded")

una run . prints:

Output
route booked and recorded

It checks, and every customer's phone number now sits in the analytics records. Both services accept secret, and the phone is secret, so nothing tells them apart. A higher level for the phone would not help either: the courier must still receive it. What the program needs to say is that the courier may receive personal data and the analytics service may not.

17.4.3 How to write categories

17.4.3.1 Declaring them in una.toml

A package declares its categories in una.toml, under the table [labels], as a list of names:

steps/26-categories/una.tomltoml
[package]
name = "courier"
version = "0.1.0"
edition = "0.2"

[labels]
categories = ["PII"]

[run]
entry = "courier"
grants = ["console"]

A category's name is written in UpperCamelCase: it starts with a capital letter, and each word in it does too, such as PII or Location. Any other name, such as pii, is U1005.

17.4.3.2 On a type

The categories go in square brackets right after the level, before the type: secret[PII] Text. Several categories are separated by commas: confidential[Location, PII] Text.

17.4.3.3 In an accepts clause

A ceiling can name categories too: accepts secret[PII] accepts secret data that is personal, and anything below it.

17.4.4 A courier that may receive a phone number

The step books a courier, whose service may receive personal data:

steps/26-categories/src/courier.unacheckrununa
module courier

--- A stop on a delivery route. The phone number is personal data.
kind Stop
  order: Text
  city: Text
  phone: secret[PII] Text

--- The courier's booking service. It may receive personal data, so that a driver can call
--- the customer at the door.
capability Courier
  op book(order: Text, phone: Text) -> Unit
    accepts secret[PII]

--- Books every stop of a route with the courier.
book_route(stops: List[Stop]) -> Unit
  uses @courier: Courier[book]
=
  for stop in stops
    @courier.book(stop.order, phone: stop.phone)

--- The cities of a route, for the dispatch board. They are public.
cities(stops: List[Stop]) -> List[Text] = stops.map(each: fn(stop) -> stop.city)

--- A courier that accepts every booking, for this run.
handler accepting() for Courier
  op book(order, phone) = unit

pub main() -> Unit
  uses @console: Console[print]
=
  let route = [Stop(order: "A-1001", city: "Recife", phone: "+55 81 5550 0101"), Stop(order: "A-1002", city: "Olinda", phone: "+55 81 5550 0102")]
  book_route(route) with @courier = accepting()
  let board = cities(route).join(separator: ", ")
  @console.print("route booked: {board}")

Walkthrough:

  1. phone: secret[PII] Text. A phone number is personal data. The level secret and the category PII travel with it.
  2. accepts secret[PII]. The courier's booking service needs the phone, so a driver can call at the door. Its ceiling names the category. An operation that accepts secret without PII would reject the phone with U4003: the category is part of the ceiling.
  3. @courier.book(stop.order, phone: stop.phone). The order id is public and the phone is secret[PII]. Each argument is checked against the ceiling.
  4. cities. It reads only the public city field, so the dispatch board, printed by main, shows no personal data.

una run . prints:

Output
route booked: Recife, Olinda

The analytics service of Why a level is not enough, with accepts secret, would now refuse the phone. Personal data reaches only the places that say they may receive it.

17.4.5 How categories flow and combine

17.4.5.1 A label flows only into one with the same categories, or more

A label flows into another only if its level is at or below the other's, and its categories are among the other's. So secret[PII] flows into secret[PII] and restricted[PII], but not into secret. Give the courier accepts secret:

src/courier.unadiff
--- a/src/courier.una
+++ b/src/courier.una
@@ -12,3 +12,3 @@
   op book(order: Text, phone: Text) -> Unit
-    accepts secret[PII]
+    accepts secret
 
Diagnostic
[U4003] Error: `@courier.book` accepts `secret` data, and this argument is `secret[PII]`

The levels match, and the category does not. Personal data never loses its category by accident.

17.4.5.2 Combining values joins categories

When values combine, the result takes the higher level and every category of either. Declare a second category, Location, for the door of each stop, and send the courier the phone and the door in one text:

src/courier.unadiff
--- a/src/courier.una
+++ b/src/courier.una
@@ -2,3 +2,3 @@
 
---- A stop on a delivery route. The phone number is personal data.
+--- A stop on a delivery route. The phone number is personal data, and the door is a location.
 kind Stop
@@ -7,2 +7,3 @@
   phone: secret[PII] Text
+  door: confidential[Location] Text
 
@@ -19,3 +20,3 @@
   for stop in stops
-    @courier.book(stop.order, phone: stop.phone)
+    @courier.book(stop.order, phone: "{stop.phone}, {stop.door}")
 
@@ -31,3 +32,3 @@
 =
-  let route = [Stop(order: "A-1001", city: "Recife", phone: "+55 81 5550 0101"), Stop(order: "A-1002", city: "Olinda", phone: "+55 81 5550 0102")]
+  let route = [Stop(order: "A-1001", city: "Recife", phone: "+55 81 5550 0101", door: "Rua do Sol 10"), Stop(order: "A-1002", city: "Olinda", phone: "+55 81 5550 0102", door: "Rua da Aurora 5")]
   book_route(route) with @courier = accepting()
Diagnostic
[U4003] Error: `@courier.book` accepts `secret[PII]` data, and this argument is `secret[Location, PII]`
    ╭─[ src/courier.una:21:38 ]
    │
 21 │     @courier.book(stop.order, phone: "{stop.phone}, {stop.door}")
    │                                      ─────────────┬─────────────
    │                                                   ╰─────────────── `@courier.book` accepts `secret[PII]` data, and this argument is `secret[Location, PII]`

The text joins secret[PII] and confidential[Location] into secret[Location, PII]: the higher level, and both categories. The courier accepts personal data, not locations, so the combined text is refused. To send both, the courier's ceiling would name both: accepts secret[Location, PII].

17.4.5.3 A category must be declared

A category that [labels] categories does not declare is U4007. A misspelled category cannot create a new, unchecked kind of data:

src/courier.unadiff
--- a/src/courier.una
+++ b/src/courier.una
@@ -6,3 +6,3 @@
   city: Text
-  phone: secret[PII] Text
+  phone: secret[PIl] Text
 
Diagnostic
[U4007] Error: label category `PIl` is not declared in `[labels] categories` of `una.toml`
   ╭─[ src/courier.una:7:17 ]
   │
 7 │   phone: secret[PIl] Text
   │                 ─┬─
   │                  ╰─── label category `PIl` is not declared in `[labels] categories` of `una.toml`

The help line offers the declared name that is closest, and una fix . applies it.

17.4.5.4 Dropping a category takes a policy

Dropping a category is a release, like lowering a level: only a policy can do it (section 17.5), and its to type shows the label it gives.

17.4.6 Choosing categories

Which to use:

You want to… Do this
Keep one kind of data, such as personal data, away from services that may receive other secrets declare a category, such as PII, and put it on the data and on the ceilings that may receive it
Tell apart two kinds of data that some services receive separately one category for each, such as Location and PII
Mark data that only differs in how sensitive it is a level, with no new category

Declare few categories, each for a kind of data that a law, a contract or a promise to customers treats apart.

17.4.7 Check yourself: categories

A fraud-screening service accepts the highest level, restricted, and no category. Give it the courier's booking:

src/courier.unadiff
--- a/src/courier.una
+++ b/src/courier.una
@@ -12,3 +12,3 @@
   op book(order: Text, phone: Text) -> Unit
-    accepts secret[PII]
+    accepts restricted
 

Does the phone, secret[PII], reach it?

Show the answer

No:

Diagnostic
[U4003] Error: `@courier.book` accepts `restricted` data, and this argument is `secret[PII]`

secret is below restricted, so the level fits. But PII is not among the ceiling's categories, which are none. A label flows only when both its level and its categories fit.

Next:17.5 Releasing data: policies and trusted modules