Using the KeyNote Trust Management System

Matt Blaze

November 1999
Updated 1 March 2001

What's a Trust-Management System? Do I Really Need One?

A trust-management system helps applications answer questions of the form, "does this potentially dangerous operation conform to my security policy?" Typically, the correct answer to such a question depends on what the operation is, who's asking for it to be performed, the local security policy, the requester's credentials, and other factors. Trust-management systems provide applications with a standard interface for getting answers to such questions, and provide users with a standard language for writing the policies and credentials that control what is allowed and what isn't.

Using a trust-management system for controlling security-critical services frees the application developer from a number of often difficult (and subtle) design and implementation issues and allows users to take advantage of a flexible, standard, application-independent language for specifying policy. Before trust management, every application had to provide its own mechanisms for specifying policy, interpreting credentials, and binding user authentication with the authorization to perform "dangerous" operations. Trust-management systems, on the other hand, provide a simple interface that takes care of all of these things. All the application designer has to do is identify the trust management questions in the application and formulate appropriate queries to the trust-management system.

In spite of its name, the field of "trust management" is concerned neither with finance nor with having faith in one's boss. The term "trust management" was coined, and the concept first introduced, in the PolicyMaker system in 1995 by Blaze, Feigenbaum and Lacy. For an introduction to the theory and concepts behind trust management, see the various papers referenced in Slides from a recent invited talk (at the Policy 2001 conference in Bristol UK) with an overview of Trust Management can be found here, in PDF format.

What's KeyNote?

KeyNote is our latest, "state-of-the-art" trust-management system, designed by Matt Blaze, Joan Feigenbaum and John Ioannidis of AT&T Labs - Research and Angelos Keromytis of the University of Pennsylvania. Work on KeyNote began in 1997 and has evolved to the point of supporting a wide variety of applications, ranging from IPSEC policy control to electronic payment systems. The current version of the KeyNote language (called "version 2") is the stable public release described in RFC-2704. KeyNote is not patented and we have placed no restrictions on its use (which means, of course, that anyone is free to invent, and therefore could conceivably patent, their own new and novel applications based on KeyNote).

The KeyNote Toolkit is a simple and flexible C language open-source reference implementation of the KeyNote system written and distributed by Angelos Keromytis. This web page provides an introduction to the use of that toolkit.

KeyNote provides a simple language for describing and implementing security policies, trust relationships, and digitally-signed credentials. Users of applications built with the KeyNote system have access to a powerful, standardized language for writing security policies and credentials that can control potentially dangerous actions requested across untrusted networks.

KeyNote allows the creation of sophisticated security policies and credentials in which entities (which can be identified by cryptographic public keys) can be granted limited authorization to perform specific kinds of trusted actions. When a "dangerous" action is requested of a KeyNote-based application, the application submits a description of the action along with a copy of its local security policy to the KeyNote interpreter. KeyNote then "approves" or "rejects" the action according to the rules given in the application's security policy.

In traditional applications, policies are often "hard-coded" into applications and are difficult to change. In KeyNote, policies are written in a standard language that stays the same across different applications, that is defined outside of the application's code and that can be altered by the responsible user whenever needed. An especially powerful concept in KeyNote is the unification of the notion of security policy with that of security credentials. Distributed applications can easily create polices that defer to a remotely-managed authority, which can change the policy simply by issuing new credentials (certificates). In KeyNote, a policy can become a remotely-usable credential simply by being signed.

KeyNote Trust Management Architecture

This web page is intended as an introductory overview and starting point for learning the basics of how KeyNote works and what it might do in various applications. Before actually integrating KeyNote into an application, you'll definitely want to familiarize yourself in depth with the capabilities and limitations of the KeyNote language, which is defined in detail in RFC-2704. The details of KeyNote RSA and DSA public key formats are given in RFC-2792. You'll also want a copy of the latest version of the KeyNote toolkit, which you can get from here. Angelos Keromytis maintains a web page with the latest toolkit news. There's a low-volume mailing list for KeyNote users that you are strongly encouraged to join if you are using or considering using KeyNote or other trust-management tools. To subscribe, send the string

subscribe keynote-users
in the body of an email message to

KeyNote can be used to control policy in many different kinds of applications and can be integrated in many different ways. Several popular open-source software packages use KeyNote for some aspect of policy control:

(If you're distributing an open-source KeyNote-based application, let us know so we can link to it here).

KeyNote Concepts and Jargon

KeyNote has developed some specific terminology that makes it easier to discuss what it does and how it works. For the most part, the names of KeyNote concepts follow from their standard technical meanings. Specifically, for the purposes of KeyNote:

It's the application's job to notice when a principal requests an action and to call the KeyNote system with a correct description of the action, the governing policy, and the relevant credentials. The PCV returned by KeyNote then advises the application how to handle the request.

Thus, the basic pseudocode for using KeyNote in an application typically looks something like this:

/* At each point the application decides that someone's
   requesting an action, do the following: */

requester            = requesting principal's identifier;
action_description   = data structure describing action;
policy               = data structure describing local policy,
                           typically read from a local file;
credentials          = data structure with any relevant
                           credentials, typically sent along with
                           the request by the requesting principal;

PCV                  = Call_KeyNote(requester,
if (PCV == "allowed")
     do the requested action
     tell principal that action isn't allowed

Applications describe actions to KeyNote with a set of attribute/value pairs (called an "action attribute set" in KeyNote jargon) that describe the context and consequences of security-critical operations. The KeyNote system itself doesn't understand or interpret the action attributes; that's the job of the application's policy.

KeyNote application policies and credentials are written in the same language. The basic unit of KeyNote programming is the assertion. Assertions contain programmable predicates that operate on the requested attribute set and describe to limit the actions that principals are allowed to perform.

The first task of the application designer who wants to use KeyNote is to identify the places in the application where trust management decisions occur. Then, at each trust management decision point, the designer identifies and defines a set of attributes that captures the information that the security policy will need to decide whether or not to proceed. Finally, the designer decides how to identify and name principals, and creates a scheme for managing policy files and marshaling appropriate credentials.

Where To Go From Here

A future version of this document will provide a tutorial introduction to integrating KeyNote into applications and will include complete example application code.

RFC-2704 contains details on the KeyNote language, action attributes, and KeyNote semantics. The reference implementation and toolkit contains extensive example code and API documentation. RFC-2792 has details on the representation of RSA and DSA public keys used as KeyNote principals; you probably don't need to worry about this unless you're using your own code to sign or verify things. The keynote-users mailing list (see above for subscription details) is probably the best place for questions, support, and discussion.

For a discussion of a trust management architecture for IPSEC that can use KeyNote for its policies and credentials, see our Internet Draft on the subject, and also our NDSS 2001 paper (PDF format).

If you're using KeyNote, implementing a KeyNote interpreter, or have discovered problems or bugs, please let us know. The KeyNote team can be reached at