keynote - assertion format
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>
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.
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.
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.
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."
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.
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.
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.
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.
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).
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.
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 ==
"[email protected]-
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 == "[email protected]-
search.att.com"));
Signature: "DSA-SHA1:8912aa"
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.
Angelos D. Keromytis <[email protected]>
http://www.cis.upenn.edu/~keynote
None that we know of. If you find any, please report them
at
<[email protected]>
OpenBSD 3.6 October 10, 1999
[ Back ] |
