### Certificate Provisioning

[DIAGRAM: Provisioning token flow]

The single argument passed to `step ca new-token` binds an identity to the authentication token. By default this identity becomes the common name in an x.509 certificate (and is duplicated in the IP or DNS subject alternative name as appropriate).

The CA will only issue a certificate with a common name that matches the identity bound to the authentication token. That means you can lock down your PKI and control who can issue certificates, and for what identities, by controlling access to the private key used for token signing (located in `/path/to/run/secrets/ott-private.pem`).

We're now running with TLS. We've securely provisioned a certificate without passing any sensitive key material over the network. Use of the step language to control the proxy and CA means you're free to customize certificate provisioning and other behaviors if you'd like. If you do decide to change anything step makes it easy to quickly deploy your changes everywhere.

### Step Policy

The `acl` that we define at the start of the script uses the *step policy language*: a declarative language for capturing things like authorization rules. There's some new syntax here, but it's really pretty simple.

Policy consists of *facts* (without `when` clauses) and *rules* (with `when` clauses).
- A **fact** holds unconditionally
- A **rule** only holds when its sub-clauses hold
The `prove` function returns a boolean indicating whether some statement holds in some policy.

The first line of our policy is:

```
contains [?x ...] x
```

This is a fact. It says that a list contains element `x` if the first element of the list is `x`. Pretty obvious stuff. The identifier `x` appears twice, and both occurrences must match. The ellipsis (`...`) matches the remainder of the list (which might be empty) but doesn't bind it to a variable. This fact tells us that `contains [1] 1` and `contains [1,2,3] 1` both hold true.

*Note: the `?` is required here for technical reasons [1]. You can ignore it.*

*Footnote [1]: If you're curious: the first item in a list is normally interpreted as an atomic symbol. The `?` forces it to be interpreted as a variable. An upcoming language revision will further simplify policy syntax and eliminate this requirement.*

The next two lines of our policy are:

```
contains [_ t...] x when
    contains t x
```

This is a rule. It says that a list also contains `x` if the tail of the list contains `x`. The wildcard (`_`) matches and discards the first element of the list, and the ellipsis (`t...`) is used to bind the rest of the list to `t`. The sub-clause then recursively checks that `t` contains `x`. This rule together with the first fact tells us that `contains [1,2,3] 2` and `contains [1,2,3] 3` both hold true.

Step policy may look unfamiliar at first, but if you've followed along with the previous couple paragraphs you now know 90% of the language. It's easy to learn and it's great at capturing concise and readable definitions of complex policy logic. Policy has a number of other benefits:
- It's easy to generate and manipulate policy programmatically
- It's easy to display and manipulate policy visually in UIs
- Policy can be "run in both directions"

To unpack that last part a bit let's look at a series of rules mapping users to resources that they're allowed to access:

```
let acl = policy
    allow "mike" "/resource1"
    allow "mike" "/resource2"
    allow "max"  "/resource2"
```

This one policy definition can be used to determine:
- Whether a user has access to a particular resource: `(prove acl [allow "mike" "/resource1"])` (returns a bool)
- Which resources a user can access: `(query acl [allow "mike" r])` (returns a list of bindings for `r`)
- which users can access a resource: `(query acl [allow u "/resource2"])` (returns a list of bindings for `u`)
This is useful for auditing policies and for providing meta-APIs to determine whether a user has some ability without duplicating logic (e.g., in order to gracefully degrade a user interface depending on whether a user is allowed to perform some action).