Greatly expand keynote.4 to include query semantics, cross references.

4 files changed, 522 insertions, 32 deletions

diff --git a/lib/libkeynote/Makefile b/lib/libkeynote/Makefile
index 81a4333ef64..468fca602d9 100644
--- a/lib/libkeynote/Makefile
+++ b/lib/libkeynote/Makefile
@@ -1,7 +1,7 @@
-#	$OpenBSD: Makefile,v 1.8 1999/10/01 01:55:42 angelos Exp $
+#	$OpenBSD: Makefile,v 1.9 1999/10/11 00:08:28 angelos Exp $
 
 LIB=	keynote
-MAN=	keynote.3 keynote.4
+MAN=	keynote.3 keynote.4 keynote.5
 NOPIC=	
 CFLAGS+= -Wall -DCRYPTO -DHAVE_CONFIG_H -I. -I${.CURDIR}
 LEXFLAGS = -Cr -Pkn -s -i
diff --git a/lib/libkeynote/keynote.1 b/lib/libkeynote/keynote.1
index 6efa366bc81..6b5ea0f51ca 100644
--- a/lib/libkeynote/keynote.1
+++ b/lib/libkeynote/keynote.1
@@ -1,4 +1,4 @@
-.\" $OpenBSD: keynote.1,v 1.10 1999/10/01 01:08:30 angelos Exp $
+.\" $OpenBSD: keynote.1,v 1.11 1999/10/11 00:08:28 angelos Exp $
 .\"
 .\" The author of this code is Angelos D. Keromytis (angelos@dsl.cis.upenn.edu)
 .\"
@@ -228,7 +228,8 @@ flags should be given per invocation. If no flags are given,
 .Pp
 .Sh SEE ALSO
 .Xr keynote 3 ,
-.Xr keynote 4
+.Xr keynote 4 ,
+.Xr keynote 5
 .Bl -tag -width "AAAAAAA"
 .It ``The KeyNote Trust-Management System, Version 2'' 
 M. Blaze, J. Feigenbaum, A. D. Keromytis,
diff --git a/lib/libkeynote/keynote.3 b/lib/libkeynote/keynote.3
index b4f7d208543..9ba9c8b3414 100644
--- a/lib/libkeynote/keynote.3
+++ b/lib/libkeynote/keynote.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: keynote.3,v 1.14 1999/10/09 19:47:32 angelos Exp $
+.\" $OpenBSD: keynote.3,v 1.15 1999/10/11 00:08:28 angelos Exp $
 .\"
 .\" The author of this code is Angelos D. Keromytis (angelos@dsl.cis.upenn.edu)
 .\"
@@ -28,6 +28,8 @@
 .Nm KeyNote
 .Nd a trust-management system library
 .Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <regex.h>
 .Fd #include <keynote.h>
 .Bd -literal
 
@@ -547,7 +549,13 @@ indicating the returned value to the query. On failure, it returns \-1
 and sets
 .Va keynote_errno
 to the same values as
-.Xr kn_do_query 3 .
+.Xr kn_do_query 3 ,
+or to
+.Er ERROR_MEMORY
+if a trusted or untrusted assertion could not be added to the session due
+to lack of memory resources. Syntax errors in assertions will not be reported
+by
+.Fn kn_query .
 .Pp
 .Fn kn_encode_base64
 converts the data of length
@@ -806,7 +814,8 @@ algorithm was not supported.
 .Fd libkeynote.a
 .Sh SEE ALSO
 .Xr keynote 1 ,
-.Xr keynote 4
+.Xr keynote 4 ,
+.Xr keynote 5
 .Bl -tag -width "AAAAAAA"
 .It ``The KeyNote Trust-Management System, Version 2'' 
 M. Blaze, J. Feigenbaum, A. D. Keromytis,
diff --git a/lib/libkeynote/keynote.4 b/lib/libkeynote/keynote.4
index dca070f350a..88bf3638b45 100644
--- a/lib/libkeynote/keynote.4
+++ b/lib/libkeynote/keynote.4
@@ -1,4 +1,4 @@
-.\" $OpenBSD: keynote.4,v 1.10 1999/10/01 01:08:30 angelos Exp $
+.\" $OpenBSD: keynote.4,v 1.11 1999/10/11 00:08:28 angelos Exp $
 .\"
 .\" The author of this code is Angelos D. Keromytis (angelos@dsl.cis.upenn.edu)
 .\"
@@ -28,6 +28,8 @@
 .Nm KeyNote
 .Nd a trust-management system
 .Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <regex.h>
 .Fd #include <keynote.h>
 .Fd Link options: -lkeynote -lm -lcrypto
 .Sh DESCRIPTION
@@ -35,8 +37,8 @@ For more details on
 .Nm KeyNote ,
 see RFC 2704.
 .Pp
-Details on the API and command-line tool are given in the
-man pages listed at the end of this manual.
+Details on the API, assertion syntax, and command-line tool are given in
+the man pages listed at the end of this manual.
 .Pp
 Trust management, introduced in the PolicyMaker system, is a unified
 approach to specifying and interpreting security policies,
@@ -48,7 +50,7 @@ describe a specific delegation of trust and subsume the role of public
 key certificates; unlike traditional certificates, which bind keys to
 names, credentials can bind keys directly to the authorization to
 perform specific tasks.
-
+.Pp
 A trust-management system has five basic components:
 
 .nf
@@ -73,7 +75,7 @@ The trust-management approach has a number of advantages over other
 mechanisms for specifying and controlling authorization, especially
 when security policy is distributed over a network or is otherwise
 decentralized.
-
+.Pp
 Trust management unifies the notions of security policy, credentials,
 access control, and authorization. An application that uses a
 trust-management system can simply ask the compliance checker whether
@@ -83,15 +85,15 @@ trust-managed applications; the security configuration mechanism for
 one application carries exactly the same syntactic and semantic
 structure as that of another, even when the semantics of the
 applications themselves are quite different.
-
+.Pp
 Trust-management policies are easy to distribute across networks,
 helping to avoid the need for application-specific distributed policy
 configuration mechanisms, access control lists, and certificate
 parsers and interpreters.
-
+.Pp
 For a general discussion of the use of trust management in distributed
 system security, see the papers listed at the end of this manual.
-
+.Pp
 KeyNote is a simple and flexible trust-management system designed to
 work well for a variety of large- and small- scale Internet-based
 applications. It provides a single, unified language for both local
@@ -103,7 +105,7 @@ which can be sent over an untrusted network, is also called a
 `credential assertion.' Credential assertions, which also serve the
 role of certificates, have the same syntax as policy assertions but
 are also signed by the principal delegating the trust.
-
+.Pp
 In KeyNote:
 
 .nf
@@ -136,19 +138,19 @@ abstraction. KeyNote principals are identified by a string called a
 contain a cryptographic key interpreted by the KeyNote system (e.g.,
 for credential signature verification). In other cases, Principal
 Identifiers may have a structure that is opaque to KeyNote.
-
+.Pp
 Principals perform two functions of concern to KeyNote: They request
 `actions' and they issue `assertions.' Actions are any trusted
 operations that an application places under KeyNote control.
 Assertions delegate the authorization to perform actions to other
 principals.
-
+.Pp
 Actions are described to the KeyNote compliance checker in terms of a
 collection of name-value pairs called an `action attribute set.' The
 action attribute set is created by the invoking application. Its
-structure and format are described in detail in Section 3 of this
+structure and format are described in detail elsewhere of this
 document.
-
+.Pp
 KeyNote provides advice to applications on the interpretation of
 policy with regard to specific requested actions. Applications invoke
 the KeyNote compliance checker by issuing a `query' containing a
@@ -156,7 +158,7 @@ proposed action attribute set and identifying the principal(s)
 requesting it. The KeyNote system determines and returns an
 appropriate `policy compliance value' from an ordered set of possible
 responses.
-
+.Pp
 The policy compliance value returned from a KeyNote query advises the
 application how to process the requested action. In the simplest case,
 the compliance value is Boolean (e.g., "reject" or "approve").
@@ -165,23 +167,24 @@ compliance values, when appropriate for the application (e.g., "no
 access", "restricted access", "full access"). Applications can
 configure the relative ordering (from `weakest' to `strongest') of
 compliance values at query time.
-
+.Pp
 Assertions are the basic programming unit for specifying policy and
 delegating authority. Assertions describe the conditions under which a
 principal authorizes actions requested by other principals. An
 assertion identifies the principal that made it, which other
 principals are being authorized, and the conditions under which the
-authorization applies. The syntax of assertions is given in Section 4.
-
+authorization applies. The syntax of assertions is given
+.Xr keynote 5 .
+.Pp
 A special principal, whose identifier is "POLICY", provides the root
 of trust in KeyNote. "POLICY" is therefore considered to be authorized
 to perform any action.
-
+.Pp
 Assertions issued by the "POLICY" principal are called `policy
 assertions' and are used to delegate authority to otherwise untrusted
 principals. The KeyNote security policy of an application consists of
 a collection of policy assertions.
-
+.Pp
 When a principal is identified by a public key, it can digitally sign
 assertions and distribute them over untrusted networks for use by
 other KeyNote compliance checkers. These signed assertions are also
@@ -190,7 +193,7 @@ public key certificates. Policies and credentials share the same
 syntax and are evaluated according to the same semantics. A principal
 can therefore convert its policy assertions into credentials simply by
 digitally signing them.
-
+.Pp
 KeyNote is designed to encourage the creation of human-readable
 policies and credentials that are amenable to transmission and storage
 over a variety of media. Its assertion syntax is inspired by the
@@ -213,14 +216,16 @@ encountered. For example:
 .fi
 
 For the exact meanings of all the fields, see the RFC reference at the
-end of this manual.
-
+end of this manual, and/or
+.Xr keynote 5 .
+.Pp
 KeyNote semantics resolve the relationship between an application's
 policy and actions requested by other principals, as supported by
 credentials. The KeyNote compliance checker processes the assertions
 against the action attribute set to determine the policy compliance
-value of a requested action. These semantics are defined in Section 5.
-
+value of a requested action. These semantics are defined later in this
+document.
+.Pp
 An important principle in KeyNote's design is `assertion
 monotonicity'; the policy compliance value of an action is always
 positively derived from assertions made by trusted principals.
@@ -231,12 +236,487 @@ protocols; network failures that prevent the transmission of
 credentials can never result in spurious authorization of dangerous
 actions.
 .Pp
+Trusted actions to be evaluated by KeyNote are described by a
+collection of name-value pairs called the `action attribute set'.
+Action attributes are the mechanism by which applications communicate
+requests to KeyNote and are the primary objects on which KeyNote
+assertions operate. An action attribute set is passed to the KeyNote
+compliance checker with each query.
+.Pp
+Each action attribute consists of a name and a value. The semantics of
+the names and values are not interpreted by KeyNote itself; they vary
+from application to application and must be agreed upon by the writers
+of applications and the writers of the policies and credentials that
+will be used by them.
+.Pp
+Action attribute names and values are represented by arbitrary-length
+strings. KeyNote guarantees support of attribute names and values up
+to 2048 characters long. The handling of longer attribute names or
+values is not specified and is KeyNote-implementation-dependent.
+Applications and assertions should therefore avoid depending on the
+the use of attributes with names or values longer than 2048
+characters. The length of an attribute value is represented by an
+implementation-specific mechanism (e.g., NUL-terminated strings, an
+explicit length field, etc.).
+.Pp
+Attribute values are inherently untyped and are represented as
+character strings by default. Attribute values may contain any non-
+NUL ASCII character. Numeric attribute values should first be
+converted to an ASCII text representation by the invoking application,
+e.g., the value 1234.5 would be represented by the string "1234.5".
+.Pp
+An <AttributeID> begins with an alphabetic or underscore character and
+can be followed by any number of alphanumerics and underscores.
+Attribute names are case-sensitive.
+.Pp
+If an action attribute is not defined its value is considered to be
+the empty string.
+.Pp
+Attribute names beginning with the "_" character are reserved for use
+by the KeyNote runtime environment and cannot be passed from
+applications as part of queries. The following special attribute names
+are used:
+
+.Bl -tag -width indent
+.It _MIN_TRUST
+Lowest-order (minimum) compliance value in query.
+.It _MAX_TRUST
+Highest-order (maximum) compliance value in query.
+.It _VALUES
+Linearly ordered set of compliance value in query.
+.It _ACTION_AUTHORIZERS
+Names of principals directly authorizing action in query. Comma
+separated.
+.El
+.Pp
+In addition, attributes with names of the form "_<N>", where <N> is an
+ASCII-encoded integer, are used by the regular expression matching
+mechanism described in
+.Xr keynote 5 .
+.Pp
+By convention, the name of the application domain over which action
+attributes should be interpreted is given in the attribute named
+"app_domain". The IANA (or some other suitable authority) will provide
+a registry of reserved app_domain names. The registry will list the
+names and meanings of each application's attributes.
+.Pp
+The app_domain convention helps to ensure that credentials are
+interpreted as they were intended. An attribute with any given name
+may be used in many different application domains but might have
+different meanings in each of them. However, the use of a global
+registry is not always required for small-scale, closed applications;
+the only requirement is that the policies and credentials made
+available to the KeyNote compliance checker interpret attributes
+according to the same semantics assumed by the application that
+created them.
+.Pp
+For example, an email application might reserve the app_domain
+"RFC822-EMAIL" and might use the attributes named "address" (the mail
+address of a message's sender), "name" (the human name of the message
+sender), and any "organization" headers present (the organization
+name). The values of these attributes would be derived in the obvious
+way from the email message headers. The public key of the message's
+signer would be given in the "_ACTION_AUTHORIZERS" attribute.
+.Pp
+.Sh QUERY SEMANTICS
+The discussion in the following sections assume some familiarity with
+assertion syntax. Please refer to
+.Xr keynote 5
+for more details on the syntax.
+.Pp
+.Sh QUERY PARAMETERS
+A KeyNote query has four parameters:
+
+.nf
+* The identifier of the principal(s) requesting the action.
+
+* The action attribute set describing the action.
+
+* The set of compliance values of interest to the application,
+  ordered from _MIN_TRUST to _MAX_TRUST
+
+* The policy and credential assertions that should be included in
+  the evaluation.
+.fi
+
+The mechanism for passing these parameters to the KeyNote evaluator is
+application dependent. In particular, an evaluator might provide for
+some parameters to be passed explicitly, while others are looked up
+externally (e.g., credentials might be looked up in a network- based
+distribution system), while still others might be requested from the
+application as needed by the evaluator, through a `callback' mechanism
+(e.g., for attribute values that represent values from among a very
+large namespace).
+.Pp
+.Sh ACTION REQUESTER
+At least one Principal must be identified in each query as the
+`requester' of the action. Actions may be requested by several
+principals, each considered to have individually requested it. This
+allows policies that require multiple authorizations, e.g., `two
+person control'. The set of authorizing principals is made available
+in the special attribute "_ACTION_AUTHORIZERS"; if several principals
+are authorizers, their identifiers are separated with commas.
+.Pp
+.Sh ORDERED COMPLIANCE VALUE SET
+The set of compliance values of interest to an application (and their
+relative ranking to one another) is determined by the invoking
+application and passed to the KeyNote evaluator as a parameter of the
+query. In many applications, this will be Boolean, e.g., the ordered
+sets {FALSE, TRUE} or {REJECT, APPROVE}. Other applications may
+require a range of possible values, e.g., {No_Access, Limited_Access,
+Full_Access}. Note that applications should include in this set only
+compliance value names that are actually returned by the assertions.
+.Pp
+The lowest-order and highest-order compliance value strings given in
+the query are available in the special attributes named "_MIN_TRUST"
+and "_MAX_TRUST", respectively. The complete set of query compliance
+values is made available in ascending order (from _MIN_TRUST to
+_MAX_TRUST) in the special attribute named "_VALUES". Values are
+separated with commas; applications that use assertions that make use
+of the _VALUES attribute should therefore avoid the use of compliance
+value strings that themselves contain commas.
+.Pp
+.Sh PRINCIPAL IDENTIFIER NORMALIZATION
+Principal identifier comparisons among Cryptographic Principal
+Identifiers (that represent keys) in the Authorizer and Licensees
+fields or in an action's direct authorizers are performed after
+normalizing them by conversion to a canonical form.
+.Pp
+Every cryptographic algorithm used in KeyNote defines a method for
+converting keys to their canonical form and that specifies how the
+comparison for equality of two keys is performed. If the algorithm
+named in the identifier is unknown to KeyNote, the identifier is
+treated as opaque.
+.Pp
+Opaque identifiers are compared as case-sensitive strings.
+.Pp
+Notice that use of opaque identifiers in the Authorizer field requires
+that the assertion's integrity be locally trusted (since it cannot be
+cryptographically verified by the compliance checker).
+.Pp
+
+.Sh POLICY COMPLIANCE VALUE CALCULATION
+The Policy Compliance Value of a query is the Principal Compliance
+Value of the principal named "POLICY".
+.Pp
+.Sh PRINCIPAL COMPLIANCE VALUE
+The Compliance Value of a principal <X> is the highest order (maximum)
+of:
+
+.nf
+- the Direct Authorization Value of principal <X>; and
+
+- the Assertion Compliance Values of all assertions identifying
+  <X> in the Authorizer field.
+.fi
+.Sh DIRECT AUTHORIZATION VALUE
+The Direct Authorization Value of a principal <X> is _MAX_TRUST if <X>
+is listed in the query as an authorizer of the action. Otherwise, the
+Direct Authorization Value of <X> is _MIN_TRUST.
+.Pp
+.Sh ASSERTION COMPLIANC VALUE
+The Assertion Compliance Value of an assertion is the lowest order
+(minimum) of the assertion's Conditions Compliance Value and its
+Licensee Compliance Value.
+.Pp
+.Sh CONDITIONS COMPLIANCE VALUE
+The Conditions Compliance Value of an assertion is the highest-order
+(maximum) value among all successful clauses listed in the conditions
+section.
+.Pp
+If no clause's test succeeds or the Conditions field is empty, an
+assertion's Conditions Compliance Value is considered to be the
+_MIN_TRUST value, as described previously.
+.Pp
+If an assertion's Conditions field is missing entirely, its Conditions
+Compliance Value is considered to be the _MAX_TRUST value, as defined
+previously.
+.Pp
+The set of successful test clause values is calculated as follows:
+.Pp
+Recall from the grammar of the Conditions field (see
+.Xr keynote 5
+for more details) that each clause in the conditions section has two
+logical parts: a `test' and an optional `value', which, if present, is
+separated from the test with the "->" token. The test subclause is a
+predicate that either succeeds (evaluates to logical `true') or fails
+(evaluates to logical `false'). The value subclause is a string
+expression that evaluates to one value from the ordered set of
+compliance values given with the query. If the value subclause is
+missing, it is considered to be _MAX_TRUST. That is, the clause
+.Bd -literal
+       foo=="bar";
+.Ed
+
+is equivalent to
+.Bd literal
+       foo=="bar" -> _MAX_TRUST;
+.Ed
+
+If the value component of a clause is present, in the simplest case it
+contains a string expression representing a possible compliance value.
+For example, consider an assertion with the following Conditions
+field:
+.Bd -literal
+       Conditions:
+          @user_id == 0 -> "full_access";             # clause (1)
+          @user_id < 1000 -> "user_access";           # clause (2)
+          @user_id < 10000 -> "guest_access";         # clause (3)
+          user_name == "root" -> "full_access";       # clause (4)
+.Ed
+
+Here, if the value of the "user_id" attribute is "1073" and the
+"user_name" attribute is "root", the possible compliance value set
+would contain the values "guest_access" (by clause (3)) and
+"full_access" (by clause (4)). If the ordered set of compliance values
+given in the query (in ascending order) is {"no_access",
+"guest_access", "user_access", "full_access"}, the Conditions
+Compliance Value of the assertion would be "full_access" (because
+"full_access" has a higher-order value than "guest_access"). If the
+"user_id" attribute had the value "19283" and the "user_name"
+attribute had the value "nobody", no clause would succeed and the
+Conditions Compliance Value would be "no_access", which is the
+lowest-order possible value (_MIN_TRUST).
+.Pp
+If a clause lists an explicit value, its value string must be named in
+the query ordered compliance value set. Values not named in the query
+compliance value set are considered equivalent to _MIN_TRUST.
+.Pp
+The value component of a clause can also contain recursively-nested
+clauses. Recursively-nested clauses are evaluated only if their parent
+test is true. That is,
+.Bd -literal
+       a=="b" ->  { b=="c" -> "value1";
+                    d=="e"  -> "value2";
+                    true -> "value3"; } ;
+.Ed
+
+is equivalent to
+.Bd -literal
+       (a=="b") && (b=="c") -> "value1";
+       (a=="b") && (d=="e") -> "value2";
+       (a=="b") -> "value3";
+.Ed
+
+Notice that string comparisons are case-sensitive.
+.Pp
+A regular expression comparison ("~=") is considered true if the
+left-hand-side string expression matches the right-hand-side regular
+expression. If the POSIX regular expression group matching scheme is
+used, the number of groups matched is placed in the temporary meta-
+attribute "_0" (dereferenced as _0), and each match is placed in
+sequence in the temporary attributes (_1, _2, ..., _N). These
+match-attributes' values are valid only within subsequent references
+made within the same clause. Regular expression evaluation is case-
+sensitive.
+.Pp
+A runtime error occurring in the evaluation of a test, such as
+division by zero or an invalid regular expression, causes the test to
+be considered false. For example:
+.Bd -literal
+      foo == "bar" -> {
+                        @a == 1/0 -> "oneval";    # subclause 1
+                        @a == 2 -> "anotherval";  # subclause 2
+                      };
+.Ed
+
+Here, subclause 1 triggers a runtime error. Subclause 1 is therefore
+false (and has the value _MIN_TRUST). Subclause 2, however, would be
+evaluated normally.
+.Pp
+An invalid <RegExpr> is considered a runtime error and causes the test
+in which it occurs to be considered false.
+.Pp
+.Sh LICENSEE COMPLIANCE VALUE
+The Licensee Compliance Value of an assertion is calculated by
+evaluating the expression in the Licensees field, based on the
+Principal Compliance Value of the principals named there.
+.Pp
+If an assertion's Licensees field is empty, its Licensee Compliance
+Value is considered to be _MIN_TRUST. If an assertion's Licensees
+field is missing altogether, its Licensee Compliance Value is
+considered to be _MAX_TRUST.
+.Pp
+For each principal named in the Licensees field, its Principal
+Compliance Value is substituted for its name. If no Principal
+Compliance Value can be found for some named principal, its name is
+substituted with the _MIN_TRUST value.
+.Pp
+The licensees expression (see
+.Xr keynote 5 )
+is evaluated as follows:
+
+.nf
+* A "(...)" expression has the value of the enclosed subexpression.
+
+* A "&&" expression has the lower-order (minimum) of its two
+  subexpression values.
+
+* A "||" expression has the higher-order (maximum) of its two
+  subexpression values.
+
+* A "<K>-of(<List>)" expression has the K-th highest order
+  compliance value listed in <list>.  Values that appear multiple
+  times are counted with multiplicity.  For example, if K = 3 and
+  the orders of the listed compliance values are (0, 1, 2, 2, 3),
+  the value of the expression is the compliance value of order 2.
+.fi
+
+For example, consider the following Licensees field:
+.Bd -literal
+        Licensees: ("alice" && "bob") || "eve"
+.Ed
+
+If the Principal Compliance Value is "yes" for principal "alice", "no"
+for principal "bob", and "no" for principal "eve", and "yes" is higher
+order than "no" in the query's Compliance Value Set, then the
+resulting Licensee Compliance Value is "no".
+.Pp
+Observe that if there are exactly two possible compliance values
+(e.g., "false" and "true"), the rules of Licensee Compliance Value
+resolution reduce exactly to standard Boolean logic.
+.Pp
+.Sh ASSERTION MANAGEMENT
+Assertions may be either signed or unsigned. Only signed assertions
+should be used as credentials or transmitted or stored on untrusted
+media. Unsigned assertions should be used only to specify policy and
+for assertions whose integrity has already been verified as conforming
+to local policy by some mechanism external to the KeyNote system
+itself (e.g., X.509 certificates converted to KeyNote assertions by a
+trusted conversion program).
+.Pp
+Implementations that permit signed credentials to be verified by the
+KeyNote compliance checker generally provide two `channels' through
+which applications can make assertions available. Unsigned,
+locally-trusted assertions are provided over a `trusted' interface,
+while signed credentials are provided over an `untrusted' interface.
+The KeyNote compliance checker verifies correct signatures for all
+assertions submitted over the untrusted interface. The integrity of
+KeyNote evaluation requires that only assertions trusted as reflecting
+local policy are submitted to KeyNote via the trusted interface.
+.Pp
+Note that applications that use KeyNote exclusively as a local policy
+specification mechanism need use only trusted assertions. Other
+applications might need only a small number of infrequently changed
+trusted assertions to `bootstrap' a policy whose details are specified
+in signed credentials issued by others and submitted over the
+untrusted interface.
+.Pp
+.Sh EXAMPLES
+A policy that delegates authority for the "SPEND" application domain
+to RSA key dab212 when the amount given in the "dollars" attribute is
+less than 10000.
+.Bd -literal
+        Authorizer: "POLICY"
+        Licensees: "RSA:dab212"  # the CFO's key
+        Conditions: (app_domain=="SPEND") && (@dollars < 10000);
+.Ed
+
+RSA key dab212 delegates authorization to any two signers, from a
+list, one of which must be DSA key feed1234 in the "SPEND" application
+when @dollars < 7500. If the amount in @dollars is 2500 or greater,
+the request is approved but logged.
+.Bd -literal
+        KeyNote-Version: 2
+        Comment: This credential specifies a spending policy
+        Authorizer: "RSA:dab212"        # the CFO
+        Licensees: "DSA:feed1234" &&    # The vice president
+                       ("RSA:abc123" || # middle manager #1
+                        "DSA:bcd987" || # middle manager #2
+                        "DSA:cde333" || # middle manager #3
+                        "DSA:def975" || # middle manager #4
+                        "DSA:978add")   # middle manager #5
+        Conditions: (app_domain=="SPEND")  # note nested clauses
+                      -> { (@(dollars) < 2500)
+                             -> _MAX_TRUST;
+                           (@(dollars) < 7500)
+                             -> "ApproveAndLog";
+                         };
+        Signature: "RSA-SHA1:9867a1"
+.Ed
+
+According to this policy, any two signers from the list of managers
+will do if @(dollars) < 1000:
+.Bd -literal
+        KeyNote-Version: 2
+        Authorizer: "POLICY"
+        Licensees: 2-of("DSA:feed1234", # The VP
+                        "RSA:abc123",   # Middle management clones
+                        "DSA:bcd987",
+                        "DSA:cde333",
+                        "DSA:def975",
+                        "DSA:978add")
+        Conditions: (app_domain=="SPEND") &&
+                    (@(dollars) < 1000);
+.Ed
+
+A credential from dab212 with a similar policy, but only one signer is
+required if @(dollars) < 500. A log entry is made if the amount is at
+least 100.
+.Bd -literal
+        KeyNote-Version: 2
+        Comment: This one credential is equivalent to six separate
+                 credentials, one for each VP and middle manager.
+                 Individually, they can spend up to $500, but if
+                 it's $100 or more, we log it.
+        Authorizer: "RSA:dab212"      # From the CFO
+        Licensees: "DSA:feed1234" ||  # The VP
+                   "RSA:abc123" ||    # The middle management clones
+                   "DSA:bcd987" ||
+                   "DSA:cde333" ||
+                   "DSA:def975" ||
+                   "DSA:978add"
+        Conditions: (app_domain="SPEND")  # nested clauses
+                      -> { (@(dollars) < 100) -> _MAX_TRUST;
+                           (@(dollars) < 500) -> "ApproveAndLog";
+                         };
+        Signature: "RSA-SHA1:186123"
+.Ed
+
+Assume a query in which the ordered set of Compliance Values is
+{"Reject", "ApproveAndLog", "Approve"}. Under policies E and G, and
+credentials F and H, the Policy Compliance Value is "Approve"
+(_MAX_TRUST) when:
+.Bd -literal
+        _ACTION_AUTHORIZERS = "DSA:978add"
+        app_domain = "SPEND"
+        dollars = "45"
+        unmentioned_attribute = "whatever"
+    and
+        _ACTION_AUTHORIZERS = "RSA:abc123,DSA:cde333"
+        app_domain = "SPEND"
+        dollars = "550"
+.Ed
+
+The following return "ApproveAndLog":
+.Bd -literal
+        _ACTION_AUTHORIZERS = "DSA:feed1234,DSA:cde333"
+        app_domain = "SPEND"
+        dollars = "5500"
+    and
+        _ACTION_AUTHORIZERS = "DSA:cde333"
+        app_domain = "SPEND"
+        dollars = "150"
+.Ed
+
+However, the following return "Reject" (_MIN_TRUST):
+.Bd -literal
+        _ACTION_AUTHORIZERS = "DSA:def975"
+        app_domain = "SPEND"
+        dollars = "550"
+    and
+        _ACTION_AUTHORIZERS = "DSA:cde333,DSA:978add"
+        app_domain = "SPEND"
+        dollars = "5500"
+.Ed
+.Pp
 .Sh FILES
 .Fd keynote.h
 .Fd libkeynote.a
 .Sh SEE ALSO
 .Xr keynote 1 ,
-.Xr keynote 3
+.Xr keynote 3 ,
+.Xr keynote 5
 .Bl -tag -width "AAAAAAA"
 .It ``The KeyNote Trust-Management System, Version 2'' 
 M. Blaze, J. Feigenbaum, A. D. Keromytis,