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 theunderscore character, followed byany number of
a-z, A-Z, 0-9, or underscore characters} ;
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'skey
- Authorizer: "RSA:abc123"
Licensees: Alice || Bob
Conditions: (app_domain == "RFC822-EMAIL") &&(address ~= # only applies to onedomain"^.*@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.research.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