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, fol
lowed 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 indent
ing subsequent lines with at least one ASCII SPACE or TAB charac
ter. Whitespace (a SPACE, TAB, or NEWLINE character) separates
tokens but is otherwise ignored outside of quoted strings. Com
ments with a leading octothorp character ('#') may begin in any
column.
One mandatory field is required in all assertions: Authoriz
er
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 asser
tions stored in a file (e.g., in application policy configura
tions), therefore, can be separated from one another unambiguous
ly 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 "#" character 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, includ
ing newlines and nonprintable 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 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
"
represents the carriage-return character (ASCII character 13 dec
imal), "" represents the tab character (ASCII character 9 deci
mal), and " represents the form-feed character (ASCII character
12 decimal). A backslash character followed by a newline sup
presses all subsequent whitespace (including the newline) up to
the next non-whitespace character (this allows the continuation
of long string constants across lines). Un-escaped newline and
return characters are illegal inside string literals.
A similar escape mechanism is also used to represent non
printable characters. "0 represents the newline character (ASCII
character 10 decimal), "
The constructs " o", " oo", and "" (where o represents any
octal digit) may be used to represent any non-NUL ASCII charac
ters 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 char
acters have the leading backslash removed (e.g., "" becomes "a",
and "

"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

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 concatena
tion */
| <StringLiteral> /* Quoted string */
| "(" <StrEx> ")"
| <DerefAttribute>
| "$" <StrEx> ;
The "$" operator has higher precedence than the "." opera
tor.

DEREFERENCED ATTRIBUTES

Action attributes provide the primary mechanism for applica
tions 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 re
quired, 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" con
tains 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 at
tribute 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 charac
ters} ;

PRINCIPAL IDENTIFIERS

Principals are represented as ASCII strings called `Princi
pal 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 cre
dential signature verification.

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

OPAQUE PRINCIPAL IDENTIFIERS

Principal Identifiers that are used by KeyNote only as la
bels 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 ":" charac
ter.

CRYPTOGRAPHIC PRINCIPAL IDENTIFIERS

Principal Identifiers that are used by KeyNote as keys,
e.g., to verify credential signatures, are said to be `crypto
graphic'. 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 algo
rithms 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 ALGO
RITHM substring starts with an alphabetic character and can con
tain 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 ALGO
RITHM. By convention, hexadecimal encoded keys use lower-case
ASCII characters.
Cryptographic Principal Identifiers are converted to a nor
malized canonical form for the purposes of any internal compar
isons 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 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

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

<LocalConstantsField>:: "Local-Constants:" <Assign
ments> ;
<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. At
tributes defined in the Local-Constants field override any at
tributes 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 asser
tion. This field is of the form:

<AuthField>:: "Authorizer:" <AuthID> ;
<AuthID>:: <PrincipalIdentifier>
| <DerefAttribute> ;
The Principal Identifier may be given directly or by refer
ence to the attribute namespace.

LICENSEES FIELD

The Licensees field identifies the principals authorized by
the assertion. More than one principal can be authorized, and au
thorization 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 "||" opera
tor. <K> is an ASCII-encoded positive decimal integer. If a
<PrincList> contains fewer than <K> principals, the entire asser
tion is omitted from processing.

CONDITIONS FIELD

This field gives the `conditions' under which the Authorizer
trusts the Licensees to perform an action. `Conditions' are pred
icates 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 equal
ity */
| <StrEx> "!=" <StrEx> /* String in
equality */
| <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 dig
it} ;
<FloatLiteral>:: <IntegerLiteral>"."<IntegerLiteral> ;
<StringLiteral> is a quoted string as defined in previ
ously
<AttributeID> is defined previously.
The operation precedence classes are (from highest to low
est):

{ (, ) }
{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 discour
aged).
<RegExpr> is a standard regular expression, conforming to
the POSIX 1003.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 charac
ters or is empty) its value is considered to be zero.

COMMENT FIELD

The Comment field allows assertions to be annotated with in
formation 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 al
gorithm name should be the same as that of the principal appear
ing in the Authorizer field. The IANA (or some other suitable au
thority) 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 Identifi
er, the algorithm must be known to the KeyNote implementation,
and the signature must be correct for the assertion body and au
thorizer 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 new
line preceding the signature field identifier is the last charac
ter 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

Note that the keys and signatures in these examples are fic
tional, and generally much shorter than would be required for re
al 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

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

``The KeyNote Trust-Management System, Version 2''
M. Blaze, J. Feigenbaum, A. D. Keromytis, Internet
Drafts, RFC 2704.
``Decentralized Trust Management''
M. Blaze, J. Feigenbaum, J. Lacy, 1996 IEEE Confer
ence on Privacy and Security
``Compliance-Checking in the PolicyMaker Trust Management
System''
M. Blaze, J. Feigenbaum, M. Strauss, 1998 Financial
Crypto Conference

AUTHOR

Angelos D. Keromytis (angelos@dsl.cis.upenn.edu)

WEB PAGE

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

BUGS

None that we know of. If you find any, please report them
at
keynote@research.att.com
BSD October 10, 1999
Copyright © 2010-2024 Platon Technologies, s.r.o.           Home | Man pages | tLDP | Documents | Utilities | About
Design by styleshout