Home / Learn / 17 Information flow
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:
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:
route booked and recordedIt 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:
[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:
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:
phone: secret[PII] Text. A phone number is personal data. The levelsecretand the categoryPIItravel with it.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 thataccepts secretwithoutPIIwould reject the phone with U4003: the category is part of the ceiling.@courier.book(stop.order, phone: stop.phone). The order id is public and the phone issecret[PII]. Each argument is checked against the ceiling.cities. It reads only the publiccityfield, so the dispatch board, printed bymain, shows no personal data.
una run . prints:
route booked: Recife, OlindaThe 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:
--- a/src/courier.una
+++ b/src/courier.una
@@ -12,3 +12,3 @@
op book(order: Text, phone: Text) -> Unit
- accepts secret[PII]
+ accepts secret
[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:
--- 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()[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:
--- a/src/courier.una
+++ b/src/courier.una
@@ -6,3 +6,3 @@
city: Text
- phone: secret[PII] Text
+ phone: secret[PIl] Text
[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:
--- 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:
[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.