[cap-talk] Implementing a crypto brand: What are the security requirements?

[Tyler Close]

On 3/25/07, David Wagner <daw at cs.berkeley.edu> wrote:
> Tyler Close writes:
> >On 3/23/07, Mark Miller <erights at gmail.com> wrote:
> >> To avoid a conflict, Tyler is now looking for another name
> >> for the concept he was calling "Brand".
> >
> >I think I'm going to rename it "Purpose".
>
> For what it's worth, I would find this name confusing.
>
> I'm inclined to expect that this object is not something that you'll
> want to pass around or expose very much.  It seems like only a temporary
> object: we have a method that we want to return both a sealer and an
> unsealer, but a method can only return one object, so we create a
> pair object that contains both things.  Therefore, it doesn't seem
> like it needs a short name.  And giving it a name that looks entirely
> unrelated to Sealer and Unsealer suggests that it is somehow some new,
> fundamental concept -- whereas I think the idea of a record that
> contains a sealer and an unsealer is not very fundamental.  The fundamental
> concept is that of a sealer and an unsealer, and once you understand
> what they are, everything else can be described in terms of those two
> concepts.  In general, minimizing the number of fundamental concepts
> that someone has to understand reduces the mental burden.

The more I think about it, the more I think "Purpose" is a very good
name for this class. I think the name will encourage people to write
code that easier to security review.

In this past Friday's cap-talk meeting, we spent almost the whole two
hours discussing the meaning of a ( sealer, unsealer ) pair and why
they are used. We had very quick agreement on what the seal() and
unseal() operations are supposed to do, but struggled mightily in
finding words to describe what kind of thing these operations provide
you with. I found this pretty disturbing. It's like we had crisp
definitions for the push() and pop() methods, but hadn't yet
crystallized the concept of a stack. If we're to teach other
programmers how to use seal() and unseal(), I think we need a good
name for the abstraction they implement.

So I spent some time looking at my IOU mint implementation, trying to
clarify in my mind why I am using a ( sealer, unsealer ) pair and what
exactly it is  providing me with. I think I've clarified the logic and
found some good names for it.

The IOU mint must ensure that clients cannot inflate the number of
outstanding rights, while still allowing them to move rights between
accounts. The simplest way to provide such a guarantee is to have a
single method that performs a transfer directly from one account to
another. For example,

    void
    transfer(Account src, Account dst) {
        final int delta = src.balance;
        src.balance = 0;
        dst.balance += delta;
    }

The above code works because the straight line code path guarantees us
that the delta we're adding to the destination account came from a
valid withdrawal from the source account.

Though the above design is safe, it lacks some important features. In
particular, the spender needs to know what account funds are to be
withdrawn from, but it should be up to the recipient of the funds to
decide what account should be deposited into. In the above code, the
caller must specify both the source and destination accounts, so
neither the spender nor the recipient can be the caller. Really what
we want to do is have the spender decrement their account and the
recipient increment their account. The trick is guaranteeing that the
recipient's increment matches the spender's decrement, despite the
fact that they are now happening in separate method calls. We need to
somehow reify the temporary "delta" variable, capturing both its value
and the knowledge that it represents an amount withdrawn from a source
account, but not yet deposited into a destination account. A ( sealer,
unsealer ) pair enables this kind of reification of value and purpose.

After applying some name changes to the sealing API, I updated the IOU
mint implementation, such that it now has the line:

        final Purpose<PurseX> deposit = encapsulation.create();

The ( sealer, unsealer ) pair created above is used to reify amounts
that can be deposited into an account. The variable is named "deposit"
to indicate that a sealed PurseX was produced by a valid withdrawal
and is available for deposit. When doing a security review of this
code, the reviewer should check all calls to deposit.sealer.seal() to
verify that the provided argument is a PurseX produced by a valid
withdrawal. If not, a single ( sealer, unsealer ) pair is being reused
for multiple purposes and there is likely a security vulnerability.
The presence of the Purpose announces to the reviewer that this code
reifies one of its transition states and allows a caller to select the
completion logic, located in one or more separate methods. The
completion methods and initiation methods must be checked for
consistency to ensure the caller cannot cause an initiated transition
to be completed in an unanticipated way. The variable name describes
the point of consistency that must be checked.

I think naming the abstraction implemented by the seal() and unseal()
operations "Purpose" encourages this variable naming convention and
usage, leading to more secure code. Already as a result of this
conversation, MarkM has updated some code he is currently working on
to use two ( sealer, unsealer ) pairs instead of reusing one for two
purposes.

I named the Purpose maker "Encapsulation" because it implements the
reified encapsulation boundary need to ensure a sealed reference came
from a particular source. The transfer() example above creates an
implicit encapsulation boundary between the curly braces. An
Encapsulation creates an encapsulation boundary that can be explicitly
manipulated.

Code that uses ( sealer, unsealer ) pairs tends to be fairly
sophisticated, so I think it's worth getting good names that help us
understand that complexity. If you still think these names are
confusing, please say so.

Tyler

-- 
The web-calculus is the union of REST and capability-based security:
http://www.waterken.com/dev/Web/

Name your trusted sites to distinguish them from phishing sites.
https://addons.mozilla.org/firefox/957/