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