1.\" $OpenBSD: keynote.5,v 1.7 2001/08/06 10:42:26 mpech Exp $ 2.\" 3.\" The author of this code is Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) 4.\" 5.\" This code was written by Angelos D. Keromytis in Philadelphia, PA, USA, 6.\" in April-May 1998 7.\" 8.\" Copyright (C) 1998, 1999 by Angelos D. Keromytis. 9.\" 10.\" Permission to use, copy, and modify this software without fee 11.\" is hereby granted, provided that this entire notice is included in 12.\" all copies of any software which is or includes a copy or 13.\" modification of this software. 14.\" You may use this code under the GNU public license if you so wish. Please 15.\" contribute changes back to the author. 16.\" 17.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR 18.\" IMPLIED WARRANTY. IN PARTICULAR, THE AUTHORS MAKES NO 19.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE 20.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR 21.\" PURPOSE. 22.\" 23.Dd October 10, 1999 24.Dt KEYNOTE 5 25.\" .TH KeyNote 5 local 26.Os 27.Sh NAME 28.Nm keynote 29.Nd assertion format 30.Sh SYNOPSIS 31.Bd -literal 32KeyNote-Version: 2 33Local-Constants: <assignments> 34Authorizer: <public key or tag> 35Licensees: <public key or tag expression> 36Comment: <comment text> 37Conditions: <logic predicates> 38Signature: <public key signature> 39.Ed 40.Sh DESCRIPTION 41For more details on 42.Nm KeyNote , 43see RFC 2704. 44.Pp 45KeyNote assertions are divided into sections, called `fields', that 46serve various semantic functions. Each field starts with an 47identifying label at the beginning of a line, followed by the ":" 48character and the field's contents. There can be at most one field per 49line. 50.Pp 51A field may be continued over more than one line by indenting 52subsequent lines with at least one ASCII SPACE or TAB character. 53Whitespace (a SPACE, TAB, or NEWLINE character) separates tokens but 54is otherwise ignored outside of quoted strings. Comments with a 55leading octothorp character ('#') may begin in any column. 56.Pp 57One mandatory field is required in all assertions: Authorizer 58.Pp 59Six optional fields may also appear: Comment, Conditions, 60KeyNote-Version, Licensees, Local-Constants, Signature. 61.Pp 62All field names are case-insensitive. The "KeyNote-Version" field, if 63present, appears first. The "Signature" field, if present, appears 64last. Otherwise, fields may appear in any order. Each field may appear 65at most once in any assertion. 66.Pp 67Blank lines are not permitted in assertions. Multiple assertions 68stored in a file (e.g., in application policy configurations), 69therefore, can be separated from one another unambiguously by the use 70of blank lines between them. 71.Sh COMMENTS 72The octothorp character ("#", ASCII 35 decimal) can be used to 73introduce comments. Outside of quoted strings, all characters from the 74"#" character through the end of the current line are ignored. 75However, commented text is included in the computation of assertion 76signatures. 77.Sh STRINGS 78A `string' is a lexical object containing a sequence of characters. 79Strings may contain any non-NUL characters, including newlines and 80nonprintable characters. Strings may be given as literals, computed 81from complex expressions, or dereferenced from attribute names. 82.Sh STRING LITERALS 83A string literal directly represents the value of a string. String 84literals must be quoted by preceding and following them with the 85double-quote character (ASCII 34 decimal). 86.Pp 87A printable character may be `escaped' inside a quoted string literal 88by preceding it with the backslash character (ASCII 92 decimal) (e.g., 89"like \\"this\\"."). This permits the inclusion of the double- quote and 90backslash characters inside string literals. 91.Pp 92A similar escape mechanism is also used to represent non-printable 93characters. "\\n" represents the newline character (ASCII character 10 94decimal), "\\r" represents the carriage-return character (ASCII 95character 13 decimal), "\\t" represents the tab character (ASCII 96character 9 decimal), and "\\f" represents the form-feed character 97(ASCII character 12 decimal). A backslash character followed by a 98newline suppresses all subsequent whitespace (including the newline) 99up to the next non-whitespace character (this allows the continuation 100of long string constants across lines). Un-escaped newline and return 101characters are illegal inside string literals. 102.Pp 103The constructs "\\0o", "\\0oo", and "\\ooo" (where o represents any 104octal digit) may be used to represent any non-NUL ASCII characters 105with their corresponding octal values (thus, "\\012" is the same as 106"\\n", "\\101" is "A", and "\\377" is the ASCII character 255 decimal). 107However, the NUL character cannot be encoded in this manner; "\\0", 108"\\00", and "\\000" are converted to the strings "0", "00", and "000" 109respectively. Similarly, all other escaped characters have the 110leading backslash removed (e.g., "\\a" becomes "a", and "\\\\" becomes 111"\\"). The following four strings are equivalent: 112.Bd -literal 113 "this string contains a newline\\n followed by one space." 114 "this string contains a newline\\n \\ 115 followed by one space." 116 "this str\\ 117 ing contains a \\ 118 newline\\n followed by one space." 119 "this string contains a newline\\012\\040followed by one space." 120.Ed 121.Sh STRING EXPRESSIONS 122In general, anywhere a quoted string literal is allowed, a `string 123expression' can be used. A string expression constructs a string from 124string constants, dereferenced attributes (described below), and a 125string concatenation operator. String expressions may be 126parenthesized. 127 128.Bd -literal 129 <StrEx>:: <StrEx> "." <StrEx> /* String concatenation */ 130 | <StringLiteral> /* Quoted string */ 131 | "(" <StrEx> ")" 132 | <DerefAttribute> 133 | "$" <StrEx> ; 134.Ed 135 136The "$" operator has higher precedence than the "." operator. 137.Sh DEREFERENCED ATTRIBUTES 138Action attributes provide the primary mechanism for applications to 139pass information to assertions. Attribute names are strings from a 140limited character set (see below), and attribute values are 141represented internally as strings. An attribute is dereferenced simply 142by using its name. In general, KeyNote allows the use of an attribute 143anywhere a string literal is permitted. 144.Pp 145Attributes are dereferenced as strings by default. When required, 146dereferenced attributes can be converted to integers or floating point 147numbers with the type conversion operators "@" and "&". Thus, an 148attribute named "foo" having the value "1.2" may be interpreted as the 149string "1.2" (foo), the integer value 1 (@foo), or the floating point 150value 1.2 (&foo). 151.Pp 152Attributes converted to integer and floating point numbers are 153represented according to the ANSI C `long' and `float' types, 154respectively. In particular, integers range from -2147483648 to 1552147483647, whilst floats range from 1.17549435E-38F to 1563.40282347E+38F. 157.Pp 158Any uninitialized attribute has the empty-string value when 159dereferenced as a string and the value zero when dereferenced as an 160integer or float. 161.Pp 162Attribute names may be given literally or calculated from string 163expressions and may be recursively dereferenced. In the simplest case, 164an attribute is dereferenced simply by using its name outside of 165quotes; e.g., the string value of the attribute named "foo" is by 166reference to `foo' (outside of quotes). The "$<StrEx>" construct 167dereferences the attribute named in the string expression <StrEx>. For 168example, if the attribute named "foo" contains the string "bar", the 169attribute named "bar" contains the string "xyz", and the attribute 170"xyz" contains the string "qua", the following string comparisons are 171all true: 172 173.Bd -literal 174 foo == "bar" 175 $("foo") == "bar" 176 $foo == "xyz" 177 $(foo) == "xyz" 178 $$foo == "qua" 179.Ed 180 181If <StrEx> evaluates to an invalid or uninitialized attribute name, 182its value is considered to be the empty string (or zero if used as a 183numeric). 184.Pp 185The <DerefAttribute> token is defined as: 186.Bd -literal 187 <DerefAttribute>:: <AttributeID> ; 188 <AttributeID>:: {Any string starting with a-z, A-Z, or the 189 underscore character, followed by any number of 190 a-z, A-Z, 0-9, or underscore characters} ; 191.Ed 192.Sh PRINCIPAL IDENTIFIERS 193Principals are represented as ASCII strings called `Principal 194Identifiers'. Principal Identifiers may be arbitrary labels whose 195structure is not interpreted by the KeyNote system or they may encode 196cryptographic keys that are used by KeyNote for credential signature 197verification. 198 199.Bd -literal 200 <PrincipalIdentifier>:: <OpaqueID> 201 | <KeyID> ; 202.Ed 203.Sh OPAQUE PRINCIPAL IDENTIFIERS 204Principal Identifiers that are used by KeyNote only as labels are 205said to be `opaque'. Opaque identifiers are encoded in assertions as 206strings (as defined above): 207 208.Bd -literal 209 <OpaqueID>:: <StrEx> ; 210.Ed 211 212Opaque identifier strings should not contain the ":" character. 213.Sh CRYPTOGRAPHIC PRINCIPAL IDENTIFIERS 214Principal Identifiers that are used by KeyNote as keys, e.g., to 215verify credential signatures, are said to be `cryptographic'. 216Cryptographic identifiers are also lexically encoded as strings: 217 218.Bd -literal 219 <KeyID>:: <StrEx> ; 220.Ed 221 222Unlike Opaque Identifiers, however, Cryptographic Identifier strings 223have a special form. To be interpreted by KeyNote (for signature 224verification), an identifier string should be of the form: 225 226.Bd -literal 227 <IDString>:: <ALGORITHM>":"<ENCODEDBITS> ; 228.Ed 229 230"ALGORITHM" is an ASCII substring that describes the algorithms to be 231used in interpreting the key's bits. The ALGORITHM identifies the 232major cryptographic algorithm (e.g., RSA [RSA78], DSA [DSA94], etc.), 233structured format (e.g., PKCS1 [PKCS1]), and key bit encoding (e.g., 234HEX or BASE64). By convention, the ALGORITHM substring starts with an 235alphabetic character and can contain letters, digits, underscores, or 236dashes (i.e., it should match the regular expression "[a-zA-Z][a- 237zA-Z0-9_-]*"). The IANA (or some other appropriate authority) will 238provide a registry of reserved algorithm identifiers. 239.Pp 240"ENCODEDBITS" is a substring of characters representing the key's 241bits, the encoding and format of which depends on the ALGORITHM. By 242convention, hexadecimal encoded keys use lower-case ASCII characters. 243.Pp 244Cryptographic Principal Identifiers are converted to a normalized 245canonical form for the purposes of any internal comparisons between 246them; see RFC 2704 for more details. 247.Sh KEYNOTE-VERSION FIELD 248The KeyNote-Version field identifies the version of the KeyNote 249assertion language under which the assertion was written. The 250KeyNote-Version field is of the form: 251 252.Bd -literal 253 <VersionField>:: "KeyNote-Version:" <VersionString> ; 254 <VersionString>:: <StringLiteral> 255 | <IntegerLiteral> ; 256.Ed 257 258<VersionString> is an ASCII-encoded string. Assertions in production 259versions of KeyNote use decimal digits in the version representing the 260version number of the KeyNote language under which they are to be 261interpreted. Assertions written to conform with this document should 262be identified with the version string "2" (or the integer 2). The 263KeyNote-Version field, if included, should appear first. 264.Sh LOCAL-CONSTANTS FIELD 265This field adds or overrides action attributes in the current 266assertion only. This mechanism allows the use of short names for 267(frequently lengthy) cryptographic principal identifiers, especially 268to make the Licensees field more readable. The Local-Constants field 269is of the form: 270 271.Bd -literal 272 <LocalConstantsField>:: "Local-Constants:" <Assignments> ; 273 <Assignments>:: /* can be empty */ 274 | <AttributeID> "=" <StringLiteral> <Assignments> ; 275.Ed 276 277<AttributeID> is an attribute name from the action attribute 278namespace. The name is available for use as an attribute in any 279subsequent field. If the Local-Constants field defines more than one 280identifier, it can occupy more than one line and be indented. 281<StringLiteral> is a string literal as described previously. 282Attributes defined in the Local-Constants field override any 283attributes with the same name passed in with the action attribute set. 284.Pp 285An attribute may be initialized at most once in the Local-Constants 286field. If an attribute is initialized more than once in an assertion, 287the entire assertion is considered invalid and is not considered by 288the KeyNote compliance checker in evaluating queries. 289.Sh AUTHORIZER FIELD 290The Authorizer identifies the Principal issuing the assertion. This 291field is of the form: 292 293.Bd -literal 294 <AuthField>:: "Authorizer:" <AuthID> ; 295 <AuthID>:: <PrincipalIdentifier> 296 | <DerefAttribute> ; 297.Ed 298 299The Principal Identifier may be given directly or by reference to the 300attribute namespace. 301.Sh LICENSEES FIELD 302The Licensees field identifies the principals authorized by the 303assertion. More than one principal can be authorized, and 304authorization can be distributed across several principals through the 305use of `and' and threshold constructs. This field is of the form: 306 307.Bd -literal 308 <LicenseesField>:: "Licensees:" <LicenseesExpr> ; 309 310 <LicenseesExpr>:: /* can be empty */ 311 | <PrincExpr> ; 312 313 <PrincExpr>:: "(" <PrincExpr> ")" 314 | <PrincExpr> "&&" <PrincExpr> 315 | <PrincExpr> "||" <PrincExpr> 316 | <K>"-of(" <PrincList> ")" /* Threshold */ 317 | <PrincipalIdentifier> 318 | <DerefAttribute> ; 319 320 <PrincList>:: <PrincipalIdentifier> 321 | <DerefAttribute> 322 | <PrincList> "," <PrincList> ; 323 324 <K>:: {Decimal number starting with a digit from 1 to 9} ; 325.Ed 326 327The "&&" operator has higher precedence than the "||" operator. <K> is 328an ASCII-encoded positive decimal integer. If a <PrincList> contains 329fewer than <K> principals, the entire assertion is omitted from 330processing. 331.Sh CONDITIONS FIELD 332This field gives the `conditions' under which the Authorizer trusts 333the Licensees to perform an action. `Conditions' are predicates that 334operate on the action attribute set. The Conditions field is of the 335form: 336 337.Bd -literal 338 <ConditionsField>:: "Conditions:" <ConditionsProgram> ; 339 340 <ConditionsProgram>:: /* Can be empty */ 341 | <Clause> ";" <ConditionsProgram> ; 342 343 <Clause>:: <Test> "->" "{" <ConditionsProgram> "}" 344 | <Test> "->" <Value> 345 | <Test> ; 346 347 <Value>:: <StrEx> ; 348 349 <Test>:: <RelExpr> ; 350 351 <RelExpr>:: "(" <RelExpr> ")" /* Parentheses */ 352 | <RelExpr> "&&" <RelExpr> /* Logical AND */ 353 | <RelExpr> "||" <RelExpr> /* Logical OR */ 354 | "!" <RelExpr> /* Logical NOT */ 355 | <IntRelExpr> 356 | <FloatRelExpr> 357 | <StringRelExpr> 358 | "true" /* case insensitive */ 359 | "false" ; /* case insensitive */ 360 361 <IntRelExpr>:: <IntEx> "==" <IntEx> 362 | <IntEx> "!=" <IntEx> 363 | <IntEx> "<" <IntEx> 364 | <IntEx> ">" <IntEx> 365 | <IntEx> "<=" <IntEx> 366 | <IntEx> ">=" <IntEx> ; 367 368 <FloatRelExpr>:: <FloatEx> "<" <FloatEx> 369 | <FloatEx> ">" <FloatEx> 370 | <FloatEx> "<=" <FloatEx> 371 | <FloatEx> ">=" <FloatEx> ; 372 373 <StringRelExpr>:: <StrEx> "==" <StrEx> /* String equality */ 374 | <StrEx> "!=" <StrEx> /* String inequality */ 375 | <StrEx> "<" <StrEx> /* Alphanum. comparisons */ 376 | <StrEx> ">" <StrEx> 377 | <StrEx> "<=" <StrEx> 378 | <StrEx> ">=" <StrEx> 379 | <StrEx> "~=" <RegExpr> ; /* Reg. expr. matching */ 380 381 <IntEx>:: <IntEx> "+" <IntEx> /* Integer */ 382 | <IntEx> "-" <IntEx> 383 | <IntEx> "*" <IntEx> 384 | <IntEx> "/" <IntEx> 385 | <IntEx> "%" <IntEx> 386 | <IntEx> "^" <IntEx> /* Exponentiation */ 387 | "-" <IntEx> 388 | "(" <IntEx> ")" 389 | <IntegerLiteral> 390 | "@" <StrEx> ; 391 392 <FloatEx>:: <FloatEx> "+" <FloatEx> /* Floating point */ 393 | <FloatEx> "-" <FloatEx> 394 | <FloatEx> "*" <FloatEx> 395 | <FloatEx> "/" <FloatEx> 396 | <FloatEx> "^" <FloatEx> /* Exponentiation */ 397 | "-" <FloatEx> 398 | "(" <FloatEx> ")" 399 | <FloatLiteral> 400 | "&" <StrEx> ; 401 402 <IntegerLiteral>:: {Decimal number of at least one digit} ; 403 <FloatLiteral>:: <IntegerLiteral>"."<IntegerLiteral> ; 404 405 <StringLiteral> is a quoted string as defined in previously 406 <AttributeID> is defined previously. 407.Ed 408 409The operation precedence classes are (from highest to lowest): 410 411.Bd -literal 412 { (, ) } 413 {unary -, @, &, $} 414 {^} 415 {*, /, %} 416 {+, -, .} 417.Ed 418 419Operators in the same precedence class are evaluated left-to-right. 420.Pp 421Note the inability to test for floating point equality, as most 422floating point implementations (hardware or otherwise) do not 423guarantee accurate equality testing. 424.Pp 425Also note that integer and floating point expressions can only be used 426within clauses of condition fields, but in no other KeyNote field. 427.Pp 428The keywords "true" and "false" are not reserved; they can be used as 429attribute or principal identifier names (although this practice makes 430assertions difficult to understand and is discouraged). 431.Pp 432<RegExpr> is a standard regular expression, conforming to the POSIX 4331003.2 regular expression syntax and semantics (see 434.Xr regex 3 ) . 435.Pp 436Any string expression (or attribute) containing the ASCII 437representation of a numeric value can be converted to an integer or 438float with the use of the "@" and "&" operators, respectively. Any 439fractional component of an attribute value dereferenced as an integer 440is rounded down. If an attribute dereferenced as a number cannot be 441properly converted (e.g., it contains invalid characters or is empty) 442its value is considered to be zero. 443.Sh COMMENT FIELD 444The Comment field allows assertions to be annotated with information 445describing their purpose. It is of the form: 446 447.Bd -literal 448 <CommentField>:: "Comment:" <text> ; 449.Ed 450 451No interpretation of the contents of this field is performed by 452KeyNote. Note that this is one of two mechanisms for including 453comments in KeyNote assertions; comments can also be inserted anywhere 454in an assertion's body by preceding them with the "#" character 455(except inside string literals). 456.Sh SIGNATURE FIELD 457The Signature field identifies a signed assertion and gives the 458encoded digital signature of the principal identified in the 459Authorizer field. The Signature field is of the form: 460 461.Bd -literal 462 <SignatureField>:: "Signature:" <Signature> ; 463 <Signature>:: <StrEx> ; 464.Ed 465 466The <Signature> string should be of the form: 467 468.Bd -literal 469 <IDString>:: <ALGORITHM>":"<ENCODEDBITS> ; 470.Ed 471 472The formats of the "ALGORITHM" and "ENCODEDBITS" substrings are as 473described for Cryptographic Principal Identifiers. The algorithm name 474should be the same as that of the principal appearing in the 475Authorizer field. The IANA (or some other suitable authority) will 476provide a registry of reserved names. It is not necessary that the 477encodings of the signature and the authorizer key be the same. 478.Pp 479If the signature field is included, the principal named in the 480Authorizer field must be a Cryptographic Principal Identifier, the 481algorithm must be known to the KeyNote implementation, and the 482signature must be correct for the assertion body and authorizer key. 483.Pp 484The signature is computed over the assertion text, beginning with the 485first field (including the field identifier string), up to (but not 486including) the Signature field identifier. The newline preceding the 487signature field identifier is the last character included in signature 488calculation. The signature is always the last field in a KeyNote 489assertion. Text following this field is not considered part of the 490assertion. 491.Sh EXAMPLES 492Note that the keys and signatures in these examples are fictional, and 493generally much shorter than would be required for real security, in 494the interest of readability. 495.Bd -literal 496 Authorizer: "POLICY" 497 Licensees: "RSA:abc123" 498 499 KeyNote-Version: 2 500 Local-Constants: Alice="DSA:4401ff92" # Alice's key 501 Bob="RSA:d1234f" # Bob's key 502 Authorizer: "RSA:abc123" 503 Licensees: Alice || Bob 504 Conditions: (app_domain == "RFC822-EMAIL") && 505 (address ~= # only applies to one domain 506 "^.*@keynote\\.research\\.att\\.com$") -> 507 "true"; 508 Signature: "RSA-SHA1:213354f9" 509 510 KeyNote-Version: 2 511 Authorizer: "DSA:4401ff92" # the Alice CA 512 Licensees: "DSA:12340987" # mab's key 513 Conditions: ((app_domain == "RFC822-EMAIL") -> { 514 (name == "M. Blaze" || name == "") && 515 (address == 516 "mab@keynote.research.att.com")); 517 (name == "anonymous") -> "logandaccept"; 518 } 519 520 Signature: "DSA-SHA1:ab23487" 521 522 KeyNote-Version: "2" 523 Authorizer: "DSA:4401ff92" # the Alice CA 524 Licensees: "DSA:abc991" || # jf's DSA key 525 "RSA:cde773" || # jf's RSA key 526 "BFIK:fd091a" # jf's BFIK key 527 Conditions: ((app_domain == "RFC822-EMAIL") && 528 (name == "J. Feigenbaum" || name == "") && 529 (address == "jf@keynote.research.att.com")); 530 Signature: "DSA-SHA1:8912aa" 531.Ed 532.Sh SEE ALSO 533.Xr keynote 1 , 534.Xr keynote 3 , 535.Xr keynote 4 536.Bl -tag -width "AAAAAAA" 537.It ``The KeyNote Trust-Management System, Version 2'' 538M. Blaze, J. Feigenbaum, A. D. Keromytis, 539Internet Drafts, RFC 2704. 540.It ``Decentralized Trust Management'' 541M. Blaze, J. Feigenbaum, J. Lacy, 5421996 IEEE Conference on Privacy and Security 543.It ``Compliance-Checking in the PolicyMaker Trust Management System'' 544M. Blaze, J. Feigenbaum, M. Strauss, 5451998 Financial Crypto Conference 546.El 547.Sh AUTHORS 548Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) 549.Sh WEB PAGE 550http://www.cis.upenn.edu/~keynote 551.Sh BUGS 552None that we know of. 553If you find any, please report them at 554.Bd -literal -offset indent -compact 555keynote@research.att.com 556.Ed 557