*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> keynote (5)              
Title
Content
Arch
Section
 

KEYNOTE(5)

Contents


NAME    [Toc]    [Back]

     keynote - assertion format

SYNOPSIS    [Toc]    [Back]

     KeyNote-Version: 2
     Local-Constants: <assignments>
     Authorizer: <public key or tag>
     Licensees: <public key or tag expression>
     Comment: <comment text>
     Conditions: <logic predicates>
     Signature: <public key signature>

DESCRIPTION    [Toc]    [Back]

     For more details on keynote, see RFC 2704.

     KeyNote  assertions  are  divided  into   sections,   called
`fields', that serve
     various semantic functions.  Each field starts with an identifying label
     at the beginning of a line, followed by  the  ":"  character
and the field's
     contents.  There can be at most one field per line.

     A  field may be continued over more than one line by indenting subsequent
     lines with at  least  one  ASCII  SPACE  or  TAB  character.
Whitespace (a
     SPACE,  TAB,  or  NEWLINE character) separates tokens but is
otherwise ignored
 outside of quoted strings.  Comments  with  a  leading
octothorp character
 ('#') may begin in any column.

     One mandatory field is required in all assertions: Authorizer.

     Six optional fields may also  appear:  Comment,  Conditions,
KeyNote-Version,
 Licensees, Local-Constants, Signature.

     All field names are case-insensitive.  The "KeyNote-Version"
field, if
     present, appears first. The "Signature" field,  if  present,
appears last.
     Otherwise,  fields  may appear in any order.  Each field may
appear at most
     once in any assertion.

     Blank lines are not permitted in assertions. Multiple assertions stored
     in  a  file  (e.g.,  in  application policy configurations),
therefore, can be
     separated from one another unambiguously by the use of blank
lines between
 them.

COMMENTS    [Toc]    [Back]

     The  octothorp character ("#", ASCII 35 decimal) can be used
to introduce
     comments.  Outside of quoted strings,  all  characters  from
the "#" character
 through the end of the current line are ignored.  However, commented
     text is included in the computation of assertion signatures.

STRINGS    [Toc]    [Back]

     A  `string'  is  a  lexical  object containing a sequence of
characters.
     Strings may contain any non-NUL characters,  including  newlines and nonprintable
  characters.   Strings  may  be given as literals,
computed from
     complex expressions, or dereferenced from attribute names.

STRING LITERALS    [Toc]    [Back]

     A string literal directly represents the value of a  string.
String literals
  must be quoted by preceding and following them with the
double-quote
     character (ASCII 34 decimal).

     A printable character  may  be  `escaped'  inside  a  quoted
string literal by
     preceding it with the backslash character (ASCII 92 decimal)
(e.g., "like

     slash characters inside string literals.

     A similar escape mechanism is also used  to  represent  nonprintable characters.
   "0 represents the newline character (ASCII character 10 deci-" represents  the  carriage-return  character  (ASCII
     mal), "
character 13
     decimal), "" represents the tab character (ASCII character 9
decimal),
     and " represents the form-feed character (ASCII character 12
decimal).
     A  backslash  character followed by a newline suppresses all
subsequent
     whitespace (including the  newline)  up  to  the  next  nonwhitespace character
  (this  allows the continuation of long string constants
across lines).
     Un-escaped newline and return characters are illegal  inside
string literals.


     The  constructs  " o", " oo", and "" (where o represents any
octal
     digit) may be used to represent any non-NUL ASCII characters
with their
     corresponding  octal  values (thus, " 12" is the same as "0,
"101" is
     "A", and "377" is the ASCII character 255 decimal).   However, the NUL
     character  cannot  be encoded in this manner; " ", " 0", and
" 00" are
     converted to the strings "0", "00", and "000"  respectively.
Similarly,
     all  other escaped characters have the leading backslash removed (e.g.,
     "" becomes "a", and "\" becomes "
     equivalent:

             "this  string  contains  a  newlinefollowed  by  one
space."
             "this string contains a newline             followed
by one space."
             "this    str                   ing    contains     a
newlinefollowed by one space."
             "this string contains a newline 12 40followed by one
space."

STRING EXPRESSIONS    [Toc]    [Back]

     In general, anywhere a quoted string literal is  allowed,  a
`string
     expression'  can  be used.  A string expression constructs a
string from
     string constants, dereferenced attributes (described below),
and a string
     concatenation operator.  String expressions may be parenthesized.

            <StrEx>:: <StrEx> "." <StrEx>    /* String concatenation */
                    | <StringLiteral>        /* Quoted string */
                    | "(" <StrEx> ")"
                    | <DerefAttribute>
                    | "$" <StrEx> ;

     The  "$" operator has higher precedence than the "".  operator.

DEREFERENCED ATTRIBUTES    [Toc]    [Back]

     Action attributes provide the primary mechanism for applications to pass
     information to assertions.  Attribute names are strings from
a limited
     character set (see below), and attribute values  are  represented internally
 as strings.  An attribute is dereferenced simply by using
its name.
     In general, KeyNote allows the use of an attribute  anywhere
a string literal
 is permitted.

     Attributes are dereferenced as strings by default.  When required, dereferenced
 attributes can be converted to integers or  floating
point numbers
     with  the  type  conversion operators "@" and "&".  Thus, an
attribute named
     "foo" having the value  "1.2"  may  be  interpreted  as  the
string "1.2"
     (foo),  the  integer  value  1 (@foo), or the floating point
value 1.2
     (&foo).

     Attributes converted to integer and floating  point  numbers
are represented
 according to the ANSI C `long' and `float' types, respectively.  In
     particular, integers range from -2147483648  to  2147483647,
whilst floats
     range from 1.17549435E-38F to 3.40282347E+38F.

     Any  uninitialized attribute has the empty-string value when
dereferenced
     as a string and the value zero when dereferenced as an integer or float.

     Attribute  names  may  be given literally or calculated from
string expressions
 and may be recursively dereferenced.  In the  simplest
case, an attribute
  is dereferenced simply by using its name outside of
quotes; e.g.,
     the string value of the attribute named "foo" is  by  reference to `foo'
     (outside  of quotes).  The "$<StrEx>" construct dereferences
the attribute
     named in the string expression <StrEx>.  For example, if the
attribute
     named  "foo"  contains the string "bar", the attribute named
"bar" contains
     the string "xyz",  and  the  attribute  "xyz"  contains  the
string "qua", the
     following string comparisons are all true:

         foo == "bar"
         $("foo") == "bar"
         $foo == "xyz"
         $(foo) == "xyz"
         $$foo == "qua"

     If  <StrEx>  evaluates  to  an  invalid or uninitialized attribute name, its
     value is considered to be the empty string (or zero if  used
as a numeric).


     The <DerefAttribute> token is defined as:

           <DerefAttribute>:: <AttributeID> ;
            <AttributeID>::  {Any  string starting with a-z, A-Z,
or the
                             underscore  character,  followed  by
any number of
                             a-z, A-Z, 0-9, or underscore characters} ;

PRINCIPAL IDENTIFIERS    [Toc]    [Back]

     Principals are represented as ASCII strings called  `Principal
     Identifiers'.  Principal Identifiers may be arbitrary labels
whose structure
 is not interpreted by the KeyNote system  or  they  may
encode cryptographic
  keys that are used by KeyNote for credential signature verification.


            <PrincipalIdentifier>:: <OpaqueID>
                                  | <KeyID> ;

OPAQUE PRINCIPAL IDENTIFIERS    [Toc]    [Back]

     Principal Identifiers that are used by KeyNote only  as  labels are said to
     be  `opaque'.   Opaque identifiers are encoded in assertions
as strings (as
     defined above):

           <OpaqueID>:: <StrEx> ;

     Opaque identifier strings should not contain the ":" character.

CRYPTOGRAPHIC PRINCIPAL IDENTIFIERS    [Toc]    [Back]

     Principal  Identifiers  that  are  used  by KeyNote as keys,
e.g., to verify
     credential  signatures,  are  said  to  be  `cryptographic'.
Cryptographic
     identifiers are also lexically encoded as strings:

           <KeyID>:: <StrEx> ;

     Unlike Opaque Identifiers, however, Cryptographic Identifier
strings have
     a special form.  To be interpreted by KeyNote (for signature
verification),
 an identifier string should be of the form:

           <IDString>:: <ALGORITHM>":"<ENCODEDBITS> ;

     "ALGORITHM"  is  an ASCII substring that describes the algorithms to be
     used in interpreting the key's bits.  The ALGORITHM  identifies the major
     cryptographic  algorithm  (e.g.,  RSA  [RSA78], DSA [DSA94],
etc.), structured
 format (e.g., PKCS1 [PKCS1]),  and  key  bit  encoding
(e.g., HEX or
     BASE64).  By convention, the ALGORITHM substring starts with
an alphabetic
 character and can contain letters,  digits,  underscores,
or dashes
     (i.e.,  it  should match the regular expression "[a-zA-Z][azA-Z0-9_-]*").
     The IANA (or some other appropriate authority) will  provide
a registry of
     reserved algorithm identifiers.

     "ENCODEDBITS"  is a substring of characters representing the
key's bits,
     the encoding and format of which depends on  the  ALGORITHM.
By convention,
  hexadecimal encoded keys use lower-case ASCII characters.

     Cryptographic Principal Identifiers are converted to a  normalized canonical
  form  for  the purposes of any internal comparisons between them; see
     RFC 2704 for more details.

KEYNOTE-VERSION FIELD    [Toc]    [Back]

     The KeyNote-Version field  identifies  the  version  of  the
KeyNote assertion
     language   under  which  the  assertion  was  written.   The
KeyNote-Version
     field is of the form:

            <VersionField>:: "KeyNote-Version:" <VersionString> ;
            <VersionString>:: <StringLiteral>
                            | <IntegerLiteral> ;

     <VersionString>  is  an ASCII-encoded string.  Assertions in
production
     versions of KeyNote use decimal digits in the version representing the
     version  number of the KeyNote language under which they are
to be interpreted.
  Assertions written to conform  with  this  document
should be identified
  with  the version string "2" (or the integer 2). The
KeyNote-Version
 field, if included, should appear first.

LOCAL-CONSTANTS FIELD    [Toc]    [Back]

     This field adds or overrides action attributes in  the  current assertion
     only.   This  mechanism  allows  the  use of short names for
(frequently
     lengthy) cryptographic principal identifiers, especially  to
make the Licensees
  field  more readable.  The Local-Constants field is
of the form:

            <LocalConstantsField>::  "Local-Constants:"  <Assignments> ;
            <Assignments>:: /* can be empty */
                          |   <AttributeID>  "="  <StringLiteral>
<Assignments> ;

     <AttributeID> is an attribute name from the action attribute
namespace.
     The  name is available for use as an attribute in any subsequent field.
     If the Local-Constants field defines more than one identifier, it can occupy
 more than one line and be indented.  <StringLiteral> is
a string
     literal as described previously.  Attributes defined in  the
Local-Constants
  field  override  any  attributes  with the same name
passed in with
     the action attribute set.

     An attribute may be initialized at most once in  the  LocalConstants
     field.   If an attribute is initialized more than once in an
assertion,
     the entire assertion is considered invalid and is  not  considered by the
     KeyNote compliance checker in evaluating queries.

AUTHORIZER FIELD    [Toc]    [Back]

     The  Authorizer  identifies the Principal issuing the assertion.  This
     field is of the form:

            <AuthField>:: "Authorizer:" <AuthID> ;
            <AuthID>:: <PrincipalIdentifier>
                     | <DerefAttribute> ;

     The Principal Identifier may be given directly or by  reference to the attribute
 namespace.

LICENSEES FIELD    [Toc]    [Back]

     The  Licensees field identifies the principals authorized by
the assertion.
  More than one principal can be authorized, and authorization can
     be  distributed across several principals through the use of
`and' and
     threshold constructs.  This field is of the form:

            <LicenseesField>:: "Licensees:" <LicenseesExpr> ;

            <LicenseesExpr>::      /* can be empty */
                              | <PrincExpr> ;

            <PrincExpr>:: "(" <PrincExpr> ")"
                          | <PrincExpr> "&&" <PrincExpr>
                          | <PrincExpr> "||" <PrincExpr>
                          | <K>"-of(" <PrincList>  ")"         /*
Threshold */
                          | <PrincipalIdentifier>
                          | <DerefAttribute> ;

            <PrincList>:: <PrincipalIdentifier>
                        | <DerefAttribute>
                        | <PrincList> "," <PrincList> ;

            <K>:: {Decimal number starting with a digit from 1 to
9} ;

     The "&&" operator has higher precedence than the "||" operator.  <K> is
     an ASCII-encoded positive decimal integer.  If a <PrincList>
contains
     fewer than <K> principals, the entire assertion  is  omitted
from processing.

CONDITIONS FIELD    [Toc]    [Back]

     This field gives the `conditions' under which the Authorizer
trusts the
     Licensees to perform an action.  `Conditions' are predicates
that operate
     on the action attribute set.  The Conditions field is of the
form:

         <ConditionsField>:: "Conditions:" <ConditionsProgram> ;

         <ConditionsProgram>:: /* Can be empty */
                               | <Clause> ";" <ConditionsProgram>
;

         <Clause>:: <Test> "->" "{" <ConditionsProgram> "}"
                  | <Test> "->" <Value>
                  | <Test> ;

         <Value>:: <StrEx> ;

         <Test>:: <RelExpr> ;

         <RelExpr>:: "(" <RelExpr> ")"        /* Parentheses */
                   | <RelExpr> "&&" <RelExpr> /* Logical AND */
                   | <RelExpr> "||" <RelExpr> /* Logical OR */
                   | "!" <RelExpr>         /* Logical NOT */
                   | <IntRelExpr>
                   | <FloatRelExpr>
                   | <StringRelExpr>
                   | "true"        /* case insensitive */
                   | "false" ;     /* case insensitive */

         <IntRelExpr>:: <IntEx> "==" <IntEx>
                      | <IntEx> "!=" <IntEx>
                      | <IntEx> "<" <IntEx>
                      | <IntEx> ">" <IntEx>
                      | <IntEx> "<=" <IntEx>
                      | <IntEx> ">=" <IntEx> ;

         <FloatRelExpr>:: <FloatEx> "<" <FloatEx>
                        | <FloatEx> ">" <FloatEx>
                        | <FloatEx> "<=" <FloatEx>
                        | <FloatEx> ">=" <FloatEx> ;

         <StringRelExpr>:: <StrEx> "==" <StrEx>  /* String equality */
                         | <StrEx> "!=" <StrEx>   /*  String  inequality */
                         |  <StrEx>  "<"  <StrEx>    /* Alphanum.
comparisons */
                         | <StrEx> ">" <StrEx>
                         | <StrEx> "<=" <StrEx>
                         | <StrEx> ">=" <StrEx>
                         | <StrEx> "~=" <RegExpr> ; /* Reg. expr.
matching */

         <IntEx>:: <IntEx> "+" <IntEx>        /* Integer */
                 | <IntEx> "-" <IntEx>
                 | <IntEx> "*" <IntEx>
                 | <IntEx> "/" <IntEx>
                 | <IntEx> "%" <IntEx>
                 |  <IntEx>  "^" <IntEx>        /* Exponentiation
*/
                 | "-" <IntEx>
                 | "(" <IntEx> ")"
                 | <IntegerLiteral>
                 | "@" <StrEx> ;

         <FloatEx>:: <FloatEx> "+" <FloatEx>  /*  Floating  point
*/
                   | <FloatEx> "-" <FloatEx>
                   | <FloatEx> "*" <FloatEx>
                   | <FloatEx> "/" <FloatEx>
                   | <FloatEx> "^" <FloatEx> /* Exponentiation */
                   | "-" <FloatEx>
                   | "(" <FloatEx> ")"
                   | <FloatLiteral>
                   | "&" <StrEx> ;

         <IntegerLiteral>:: {Decimal number of at least one  digit} ;
         <FloatLiteral>:: <IntegerLiteral>"."<IntegerLiteral> ;

         <StringLiteral>  is a quoted string as defined in previously
         <AttributeID> is defined previously.

     The operation precedence classes are (from highest  to  lowest):

             { (, ) }
             {unary -, @, &, $}
             {^}
             {*, /, %}
             {+, -, .}

     Operators  in  the same precedence class are evaluated leftto-right.

     Note the inability to test for floating point  equality,  as
most floating
     point implementations (hardware or otherwise) do not guarantee accurate
     equality testing.

     Also note that integer and floating  point  expressions  can
only be used
     within  clauses of condition fields, but in no other KeyNote
field.

     The keywords "true" and "false" are not reserved;  they  can
be used as attribute
  or  principal identifier names (although this practice makes assertions
 difficult to understand and is discouraged).

     <RegExpr> is a standard regular  expression,  conforming  to
the IEEE Std
     1003.2 (``POSIX.2'') regular expression syntax and semantics
(see
     regex(3)).

     Any string expression (or attribute)  containing  the  ASCII
representation
     of  a  numeric value can be converted to an integer or float
with the use
     of the "@" and "&" operators, respectively.  Any  fractional
component of
     an  attribute  value  dereferenced  as an integer is rounded
down.  If an attribute
 dereferenced as a number cannot be properly converted (e.g., it
     contains  invalid  characters or is empty) its value is considered to be
     zero.

COMMENT FIELD    [Toc]    [Back]

     The Comment field allows assertions to be annotated with information describing
 their purpose.  It is of the form:

           <CommentField>:: "Comment:" <text> ;

     No interpretation of the contents of this field is performed
by KeyNote.
     Note that this is one of two mechanisms for  including  comments in KeyNote
     assertions; comments can also be inserted anywhere in an assertion's body
     by preceding them with  the  "#"  character  (except  inside
string literals).

SIGNATURE FIELD    [Toc]    [Back]

     The  Signature field identifies a signed assertion and gives
the encoded
     digital signature of the principal identified in the  Authorizer field.
     The Signature field is of the form:

            <SignatureField>:: "Signature:" <Signature> ;
            <Signature>:: <StrEx> ;

     The <Signature> string should be of the form:

           <IDString>:: <ALGORITHM>":"<ENCODEDBITS> ;

     The  formats of the "ALGORITHM" and "ENCODEDBITS" substrings
are as described
 for Cryptographic Principal Identifiers.  The  algorithm name
     should be the same as that of the principal appearing in the
Authorizer
     field.  The IANA (or some  other  suitable  authority)  will
provide a registry
  of  reserved names.  It is not necessary that the encodings of the
     signature and the authorizer key be the same.

     If the signature field is included, the principal  named  in
the Authorizer
     field  must be a Cryptographic Principal Identifier, the algorithm must be
     known to the KeyNote implementation, and the signature  must
be correct
     for the assertion body and authorizer key.

     The signature is computed over the assertion text, beginning
with the
     first field (including the field identifier string),  up  to
(but not including)
  the  Signature field identifier.  The newline preceding the signature
 field identifier is the last  character  included  in
signature calculation.
   The  signature  is  always  the  last field in a
KeyNote assertion.
     Text following this field is not considered part of the  assertion.

EXAMPLES    [Toc]    [Back]

     Note that the keys and signatures in these examples are fictional, and
     generally much shorter than would be required for real security, in the
     interest of readability.

                Authorizer: "POLICY"
                Licensees: "RSA:abc123"

                KeyNote-Version: 2
                Local-Constants:  Alice="DSA:4401ff92"  # Alice's
key
                                 Bob="RSA:d1234f"       #   Bob's
key
                Authorizer: "RSA:abc123"
                Licensees: Alice || Bob
                Conditions: (app_domain == "RFC822-EMAIL") &&
                            (address  ~=    # only applies to one
domain
                              "^.*@keynote.research.att.com$") ->
                             "true";
                Signature: "RSA-SHA1:213354f9"

                KeyNote-Version: 2
                Authorizer: "DSA:4401ff92"  # the Alice CA
                Licensees: "DSA:12340987"   # mab's key
                Conditions: ((app_domain == "RFC822-EMAIL") -> {
                                     (name  == "M. Blaze" || name
== "") &&
                                     (address ==
                                         "mab@keynote.re-
search.att.com"));
                                     (name   ==  "anonymous")  ->
"logandaccept";
                             }

                Signature: "DSA-SHA1:ab23487"

                KeyNote-Version: "2"
                Authorizer: "DSA:4401ff92"   # the Alice CA
                Licensees: "DSA:abc991" ||   # jf's DSA key
                           "RSA:cde773" ||   # jf's RSA key
                           "BFIK:fd091a"     # jf's BFIK key
                Conditions: ((app_domain == "RFC822-EMAIL") &&
                             (name == "J. Feigenbaum" || name  ==
"") &&
                             (address      ==     "jf@keynote.re-
search.att.com"));
                Signature: "DSA-SHA1:8912aa"

SEE ALSO    [Toc]    [Back]

      
      
     keynote(1), keynote(3), keynote(4)

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

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

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

AUTHORS    [Toc]    [Back]

     Angelos D. Keromytis <angelos@dsl.cis.upenn.edu>

WEB PAGE    [Toc]    [Back]

     http://www.cis.upenn.edu/~keynote

BUGS    [Toc]    [Back]

     None that we know of.  If you find any, please  report  them
at
           <keynote@research.att.com>

OpenBSD      3.6                         October     10,     1999
[ Back ]
 Similar pages
Name OS Title
INSIST_ERR FreeBSD assertion system
INVARIANT FreeBSD assertion system
REQUIRE_ERR FreeBSD assertion system
ENSURE_ERR FreeBSD assertion system
assertion_type_to_text FreeBSD assertion system
ENSURE FreeBSD assertion system
set_assertion_failure_callback FreeBSD assertion system
assertions FreeBSD assertion system
REQUIRE FreeBSD assertion system
INSIST FreeBSD assertion system
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service