Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Apropos / Subsearch:
optional field

KEYNOTE(4)               BSD Kernel Interfaces Manual               KEYNOTE(4)

     keynote -- a trust-management system

     #include <&lt;sys/types.h>&gt;
     #include <&lt;regex.h>&gt;
     #include <&lt;keynote.h>&gt;
     Link options: -lkeynote -lm -lcrypto

     For more details on keynote, see RFC 2704.

     Details on the API, assertion syntax, and command-line tool are given in
     the man pages listed at the end of this manual.

     Trust management, introduced in the PolicyMaker system, is a unified
     approach to specifying and interpreting security policies, credentials,
     and relationships; it allows direct authorization of security-critical
     actions.  A trust-management system provides standard, general-purpose
     mechanisms for specifying application security policies and credentials.
     Trust-management credentials describe a specific delegation of trust and
     subsume the role of public key certificates; unlike traditional certifi-
     cates, which bind keys to names, credentials can bind keys directly to
     the authorization to perform specific tasks.

     A trust-management system has five basic components:

        o   A language for describing 'actions', which are operations with
            security consequences that are to be controlled by the system.

        o   A mechanism for identifying 'principals', which are entities that
            can be authorized to perform actions.

        o   A language for specifying application 'policies', which govern the
            actions that principals are authorized to perform.

        o   A language for specifying 'credentials', which allow principals to
            delegate authorization to other principals.

        o   A 'compliance checker', which provides a service to applications
            for determining how an action requested by principals should be
            handled, given a policy and a set of credentials.

     The trust-management approach has a number of advantages over other mech-
     anisms for specifying and controlling authorization, especially when
     security policy is distributed over a network or is otherwise decentral-

     Trust management unifies the notions of security policy, credentials,
     access control, and authorization.  An application that uses a trust-man-
     agement system can simply ask the compliance checker whether a requested
     action should be allowed.  Furthermore, policies and credentials are
     written in standard languages that are shared by all trust-managed appli-
     cations; 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 differ-

     Trust-management policies are easy to distribute across networks, helping
     to avoid the need for application-specific distributed policy configura-
     tion mechanisms, access control lists, and certificate parsers and inter-

     For a general discussion of the use of trust management in distributed
     system security, see the papers listed at the end of this manual.

     KeyNote is a simple and flexible trust-management system designed to work
     well for a variety of large- and small- scale Internet-based applica-
     tions.  It provides a single, unified language for both local policies
     and credentials.  KeyNote policies and credentials, called 'assertions',
     contain predicates that describe the trusted actions permitted by the
     holders of specific public keys.  KeyNote assertions are essentially
     small, highly-structured programs.  A signed assertion, which can be sent
     over an untrusted network, is also called a 'credential assertion'.  Cre-
     dential 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.

     In KeyNote:

        o   Actions are specified as a collection of name-value pairs.

        o   Principal names can be any convenient string and can directly rep-
            resent cryptographic public keys.

        o   The same language is used for both policies and credentials.

        o   The policy and credential language is concise, highly expressive,
            human readable and writable, and compatible with a variety of
            storage and transmission media, including electronic mail.

        o   The compliance checker returns an application-configured 'policy
            compliance value' that describes how a request should be handled
            by the application.  Policy compliance values are always posi-
            tively derived from policy and credentials, facilitating analysis
            of KeyNote-based systems.

        o   Compliance checking is efficient enough for high-performance and
            real-time applications.

     In KeyNote, the authority to perform trusted actions is associated with
     one or more 'principals'.  A principal may be a physical entity, a
     process in an operating system, a public key, or any other convenient
     abstraction.  KeyNote principals are identified by a string called a
     'Principal Identifier'.  In some cases, a Principal Identifier will con-
     tain a cryptographic key interpreted by the KeyNote system (e.g., for
     credential signature verification).  In other cases, Principal Identi-
     fiers may have a structure that is opaque to KeyNote.

     Principals perform two functions of concern to KeyNote: They request
     'actions' and they issue 'assertions'.  Actions are any trusted opera-
     tions that an application places under KeyNote control.  Assertions dele-
     gate the authorization to perform actions to other principals.

     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 struc-
     ture and format are described in detail elsewhere of this document.

     KeyNote provides advice to applications on the interpretation of policy
     with regard to specific requested actions.  Applications invoke the Key-
     Note compliance checker by issuing a 'query' containing a proposed action
     attribute set and identifying the principal(s) requesting it.  The Key-
     Note system determines and returns an appropriate 'policy compliance
     value' from an ordered set of possible responses.

     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").  Asser-
     tions can also be written to select from a range of possible compliance
     values, when appropriate for the application (e.g., "no access",
     "restricted access", "full access").  Applications can configure the rel-
     ative ordering (from 'weakest' to 'strongest') of compliance values at
     query time.

     Assertions are the basic programming unit for specifying policy and dele-
     gating authority.  Assertions describe the conditions under which a prin-
     cipal 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 keynote(5).

     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.

     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.

     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 called
     'credentials', and serve a role similar to that of traditional 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 sign-
     ing them.

     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 format of
     RFC822-style message headers.  A KeyNote assertion contains a sequence of
     sections, called 'fields', each of which specifying one aspect of the
     assertion's semantics.  Fields start with an identifier at the beginning
     of a line and continue until the next field is encountered.  For example:

       KeyNote-Version: 2
       Comment: A simple, if contrived, email certificate for user mab
       Local-Constants:  ATT_CA_key = "RSA:acdfa1df1011bbac"
                         mab_key = "DSA:deadbeefcafe001a"
       Authorizer: ATT_CA_key
       Licensees: mab_key
       Conditions: ((app_domain == "email")  # valid for email only
                 && (address == "mabATresearch.com"));
       Signature: "RSA-SHA1:f00f2244"

     For the exact meanings of all the fields, see the RFC reference at the
     end of this manual, and/or keynote(5).

     KeyNote semantics resolve the relationship between an application's pol-
     icy and actions requested by other principals, as supported by creden-
     tials.  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 later in this document.

     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.  Removing an assertion never
     results in increasing the compliance value returned by KeyNote for a
     given query.  The monotonicity property can simplify the design and anal-
     ysis of complex network-based security protocols; network failures that
     prevent the transmission of credentials can never result in spurious
     authorization of dangerous actions.

     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.

     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.

     Action attribute names and values are represented by arbitrary-length
     strings.  KeyNote guarantees support of attribute names and values up to
     2048 characters long.  Applications and assertions should therefore avoid
     depending on the use of attributes with names or values longer than 2048

     Attribute values are inherently untyped and are represented as character
     strings by default.  Attribute values may contain any non-NUL ASCII char-
     acter.  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".

     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.

     If an action attribute is not defined its value is considered to be the
     empty string.

     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:

             Lowest-order (minimum) compliance value in query.

             Highest-order (maximum) compliance value in query.

             Linearly ordered set of compliance value in query.

             Names of principals directly authorizing action in query.  Comma

     In addition, attributes with names of the form "_<N>", where <N> is an
     ASCII-encoded integer, are used by the regular expression matching mecha-
     nism described in keynote(5).

     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.

     The app_domain convention helps to ensure that credentials are inter-
     preted as they were intended.  An attribute with any given name may be
     used in many different application domains but might have different mean-
     ings in each of them.  However, the use of a global registry is not
     always required for small-scale, closed applications; the only require-
     ment 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.

     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

     The discussion in the following sections assume some familiarity with
     assertion syntax.  Please refer to keynote(5) for more details on the

     A KeyNote query has four parameters:

        o   The identifier of the principal(s) requesting the action.

        o   The action attribute set describing the action.

        o   The set of compliance values of interest to the application,
            ordered from _MIN_TRUST to _MAX_TRUST.

        o   The policy and credential assertions that should be included in
            the evaluation.

     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 dis-
     tribution system), while still others might be requested from the appli-
     cation as needed by the evaluator, through a 'callback' mechanism (e.g.,
     for attribute values that represent values from among a very large names-

     At least one Principal must be identified in each query as the
     'requester' of the action.  Actions may be requested by several princi-
     pals, 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 autho-
     rizers, their identifiers are separated with commas.

     The set of compliance values of interest to an application (and their
     relative ranking to one another) is determined by the invoking applica-
     tion 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.

     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 them-
     selves contain commas.

     Principal identifier comparisons among Cryptographic Principal Identi-
     fiers (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.

     Every cryptographic algorithm used in KeyNote defines a method for con-
     verting keys to their canonical form and that specifies how the compari-
     son for equality of two keys is performed.  If the algorithm named in the
     identifier is unknown to KeyNote, the identifier is treated as opaque.

     Opaque identifiers are compared as case sensitive strings.

     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).

     The Policy Compliance Value of a query is the Principal Compliance Value
     of the principal named "POLICY".

     The Compliance Value of a principal <X> is the highest order (maximum)

        o   the Direct Authorization Value of principal <X>; and

        o   the Assertion Compliance Values of all assertions identifying <X>
            in the Authorizer field.

     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.

     The Assertion Compliance Value of an assertion is the lowest order (mini-
     mum) of the assertion's Conditions Compliance Value and its Licensee Com-
     pliance Value.

     The Conditions Compliance Value of an assertion is the highest-order
     (maximum) value among all successful clauses listed in the conditions

     If no clause's test succeeds or the Conditions field is empty, an asser-
     tion's Conditions Compliance Value is considered to be the _MIN_TRUST
     value, as described previously.

     If an assertion's Conditions field is missing entirely, its Conditions
     Compliance Value is considered to be the _MAX_TRUST value, as defined

     The set of successful test clause values is calculated as follows:

     Recall from the grammar of the Conditions field (see 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 evalu-
     ates 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


     is equivalent to

           foo=="bar" -> _MAX_TRUST;

     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:

               @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)

     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).

     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.

     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,

            a=="b" ->  { b=="c" -> "value1";
                         d=="e"  -> "value2";
                         true -> "value3"; } ;

     is equivalent to

            (a=="b") && (b=="c") -> "value1";
            (a=="b") && (d=="e") -> "value2";
            (a=="b") -> "value3";

     Notice that string comparisons are case sensitive.

     A regular expression comparison ("~=") is considered true if the left-
     hand-side string expression matches the right-hand-side regular expres-
     sion.  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 tempo-
     rary 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.

     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 consid-
     ered false.  For example:

           foo == "bar" -> {
                             @a == 1/0 -> "oneval";    # subclause 1
                             @a == 2 -> "anotherval";  # subclause 2

     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.

     An invalid <RegExpr> is considered a runtime error and causes the test in
     which it occurs to be considered false.

     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.

     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

     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.

     The licensees expression (see keynote(5)) is evaluated as follows:

        o   A "(...)" expression has the value of the enclosed subexpression.

        o   A "" expression has the lower-order (minimum) of its two subex-
            pression values.

        o   A "" expression has the higher-order (maximum) of its two subex-
            pression values.

        o   A "<K>-of(<List>)" expression has the K-th highest order compli-
            ance 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.

     For example, consider the following Licensees field:

           Licensees: ("alice" && "bob") || "eve"

     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".

     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.

     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).

     Implementations that permit signed credentials to be verified by the Key-
     Note 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 creden-
     tials 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 Key-
     Note via the trusted interface.

     Note that applications that use KeyNote exclusively as a local policy
     specification mechanism need use only trusted assertions.  Other applica-
     tions 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.


     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.

             Authorizer: "POLICY"
             Licensees: "RSA:dab212"  # the CFO's key
             Conditions: (app_domain=="SPEND") && (@dollars < 10000);

     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.

             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"

     According to this policy, any two signers from the list of managers will
     do if @(dollars) < 1000:

             KeyNote-Version: 2
             Authorizer: "POLICY"
             Licensees: 2-of("DSA:feed1234", # The VP
                             "RSA:abc123",   # Middle management clones
             Conditions: (app_domain=="SPEND") &&
                         (@(dollars) < 1000);

     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.

             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" ||
             Conditions: (app_domain="SPEND")  # nested clauses
                           -> { (@(dollars) < 100) -> _MAX_TRUST;
                                (@(dollars) < 500) -> "ApproveAndLog";
             Signature: "RSA-SHA1:186123"

     Assume a query in which the ordered set of Compliance Values is
     {"Reject", "ApproveAndLog", "Approve"}.  Under policies E and G, and cre-
     dentials F and H, the Policy Compliance Value is "Approve" (_MAX_TRUST)

             _ACTION_AUTHORIZERS = "DSA:978add"
             app_domain = "SPEND"
             dollars = "45"
             unmentioned_attribute = "whatever"
             _ACTION_AUTHORIZERS = "RSA:abc123,DSA:cde333"
             app_domain = "SPEND"
             dollars = "550"

     The following return "ApproveAndLog":

             _ACTION_AUTHORIZERS = "DSA:feed1234,DSA:cde333"
             app_domain = "SPEND"
             dollars = "5500"
             _ACTION_AUTHORIZERS = "DSA:cde333"
             app_domain = "SPEND"
             dollars = "150"

     However, the following return "Reject" (_MIN_TRUST):

             _ACTION_AUTHORIZERS = "DSA:def975"
             app_domain = "SPEND"
             dollars = "550"
             _ACTION_AUTHORIZERS = "DSA:cde333,DSA:978add"
             app_domain = "SPEND"
             dollars = "5500"

     keynote(1), keynote(3), keynote(5)

     M. Blaze, J. Feigenbaum, and J. Lacy, "Decentralized Trust Management",
     IEEE Symposium on Security and Privacy, 1996.

     M. Blaze, J. Feigenbaum, and M. Strauss, "Compliance-Checking in the
     PolicyMaker Trust Management System", Financial Crypto Conference, 1998.

     M. Blaze, J. Feigenbaum, J. Ioannidis, and A. Keromytis, The KeyNote
     Trust-Management System Version 2, RFC 2704, September 1999.

     Angelos D. Keromytis <angelos@cs.columbia.edu>


     None that we know of.  If you find any, please report them at

BSD                              July 16, 2013                             BSD