unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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

KEYNOTE(5)                  BSD File Formats Manual                 KEYNOTE(5)

NAME
     keynote -- assertion format

SYNOPSIS
     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
     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-Ver-
     sion, 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
     The octothorp character ("#", ASCII 35 decimal) can be used to introduce
     comments.  Outside of quoted strings, all characters from the "#" charac-
     ter through the end of the current line are ignored.  However, commented
     text is included in the computation of assertion signatures.

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

STRING LITERALS
     A string literal directly represents the value of a string.  String lit-
     erals 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
     \"this\".".  This permits the inclusion of the double-quote and backslash
     characters inside string literals.

     A similar escape mechanism is also used to represent non-printable char-
     acters.  "\n" represents the newline character (ASCII character 10 deci-
     mal), "\r" represents the carriage-return character (ASCII character 13
     decimal), "\t" represents the tab character (ASCII character 9 decimal),
     and "\f" 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 non-whitespace charac-
     ter (this allows the continuation of long string constants across lines).
     Un-escaped newline and return characters are illegal inside string liter-
     als.

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

             "this string contains a newline\n followed by one space."
             "this string contains a newline\n \
             followed by one space."
             "this str\
                ing contains a \
                  newline\n followed by one space."
             "this string contains a newline\012\040followed by one space."

STRING EXPRESSIONS
     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
     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 inter-
     nally as strings.  An attribute is dereferenced simply by using its name.
     In general, KeyNote allows the use of an attribute anywhere a string lit-
     eral is permitted.

     Attributes are dereferenced as strings by default.  When required, deref-
     erenced 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 repre-
     sented 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 expres-
     sions 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
     Principals are represented as ASCII strings called 'Principal
     Identifiers'.  Principal Identifiers may be arbitrary labels whose struc-
     ture is not interpreted by the KeyNote system or they may encode crypto-
     graphic keys that are used by KeyNote for credential signature verifica-
     tion.

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

OPAQUE PRINCIPAL IDENTIFIERS
     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
     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 verifica-
     tion), 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.), struc-
     tured format (e.g., PKCS1 [PKCS1]), and key bit encoding (e.g., HEX or
     BASE64).  By convention, the ALGORITHM substring starts with an alpha-
     betic character and can contain letters, digits, underscores, or dashes
     i.e., it should match the regular expression "[a-zA-Z][a-zA-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 conven-
     tion, hexadecimal encoded keys use lower-case ASCII characters.

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

KEYNOTE-VERSION FIELD
     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 inter-
     preted.  Assertions written to conform with this document should be iden-
     tified with the version string "2" (or the integer 2).  The KeyNote-Ver-
     sion field, if included, should appear first.

LOCAL-CONSTANTS FIELD
     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-Con-
     stants 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 Local-Constants
     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
     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
     The Licensees field identifies the principals authorized by the asser-
     tion.  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 process-
     ing.

CONDITIONS FIELD
     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 left-to-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
     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
     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 reg-
     istry 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 asser-
     tion.  Text following this field is not considered part of the assertion.

EXAMPLES
     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 ==
                                         "mabATkeynote.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 == "jfATkeynote.com"));
                Signature: "DSA-SHA1:8912aa"

SEE ALSO
     keynote(1), keynote(3), keynote(4)

     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.

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

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

WEB PAGE
           http://www1.cs.columbia.edu/~angelos/keynote.html

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

BSD                              July 16, 2013                             BSD