diff options
| -rw-r--r-- | lib/libkeynote/keynote.1 | 136 | ||||
| -rw-r--r-- | lib/libkeynote/keynote.3 | 300 | ||||
| -rw-r--r-- | lib/libkeynote/keynote.4 | 903 | ||||
| -rw-r--r-- | lib/libkeynote/keynote.5 | 511 |
4 files changed, 1119 insertions, 731 deletions
diff --git a/lib/libkeynote/keynote.1 b/lib/libkeynote/keynote.1 index c77bf3e612b..539ce9e9d5f 100644 --- a/lib/libkeynote/keynote.1 +++ b/lib/libkeynote/keynote.1 @@ -1,4 +1,4 @@ -.\" $OpenBSD: keynote.1,v 1.18 2001/08/06 10:42:26 mpech Exp $ +.\" $OpenBSD: keynote.1,v 1.19 2001/08/16 17:58:06 mpech Exp $ .\" .\" The author of this code is Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) .\" @@ -37,7 +37,6 @@ operations .Ar PrivateKeyFile .Op print-offset .Op print-length - .Nm keynote sign .Op Fl v .Ar AlgorithmName @@ -45,10 +44,8 @@ operations .Ar PrivateKeyFile .Op print-offset .Op print-length - .Nm keynote sigver .Op AssertionFile - .Nm keynote verify .Op Fl h .Op Fl e Ar file @@ -66,26 +63,29 @@ see RFC 2704. .Fa KeySize , (in bits) for the algorithm specified by .Fa AlgorithmName . -Typical keysizes are 512, 1024, or 2048 (bits). The minimum key size -for DSA keys is 512 (bits). Supported +Typical keysizes are 512, 1024, or 2048 (bits). +The minimum key size for DSA keys is 512 (bits). +Supported .Fa AlgorithmName identifiers are: -.Bl -tag -width indent -.It ``dsa-hex:'' -.It ``dsa-base64:'' -.It ``rsa-hex:'' -.It ``rsa-base64:'' -.It ``x509-hex:'' -.It ``x509-base64:'' +.Pp +.Bl -tag -width -offset indent -compact +.It Dq dsa-hex: +.It Dq dsa-base64: +.It Dq rsa-hex: +.It Dq rsa-base64: +.It Dq x509-hex: +.It Dq x509-base64: .El .Pp -Notice that the trailing colon is required. The resulting public key is -stored in file +Notice that the trailing colon is required. +The resulting public key is stored in file .Fa PublicKeyFile . Similarly, the resulting private key is stored in file .Fa PrivateKeyFile . -Either of the filenames can be specified to be ``-'', in which -case the corresponding key(s) will be printed in standard output. +Either of the filenames can be specified to be +.Dq \- , +in which case the corresponding key(s) will be printed in standard output. .Pp The optional parameters .Fa print-offset @@ -102,7 +102,8 @@ for the first line and has to be longer (by at least 2) than .Fa print-length also accounts for the line-continuation character (backslash) at the end of each line, and the doublequotes at the beginning and end -of the key encoding. Default values are 12 and 50 respectively. +of the key encoding. +Default values are 12 and 50 respectively. .Sh ASSERTION SIGNING "keynote sign" reads the assertion contained in .Fa AssertionFile @@ -111,26 +112,29 @@ and generates a signature specified by using the private key stored in .Fa PrivateKeyFile . The private key is expected to be of the form output by -"keynote keygen". The private key algorithm and the +.Qq keynote keygen . +The private key algorithm and the .Fa AlgorithmName -specified as an argument are expected to match. There is no requirement -for the internal or ASCII encodings to match. Valid +specified as an argument are expected to match. +There is no requirement for the internal or ASCII encodings to match. +Valid .Fa AlgorithmName identifiers are: -.Bl -tag -width indent -.It ``sig-dsa-sha1-hex:'' -.It ``sig-dsa-sha1-base64:'' -.It ``sig-rsa-sha1-hex:'' -.It ``sig-rsa-sha1-base64:'' -.It ``sig-rsa-md5-hex:'' -.It ``sig-rsa-md5-base64:'' -.It ``sig-x509-sha1-hex:'' -.It ``sig-x509-sha1-base64:'' +.Pp +.Bl -tag -width indent -compact +.It Dq sig-dsa-sha1-hex: +.It Dq sig-dsa-sha1-base64: +.It Dq sig-rsa-sha1-hex: +.It Dq sig-rsa-sha1-base64: +.It Dq sig-rsa-md5-hex: +.It Dq sig-rsa-md5-base64: +.It Dq sig-x509-sha1-hex: +.It Dq sig-x509-sha1-base64: .El .Pp Notice that the trailing colon is required. -The resulting signature is printed in standard output. This can then -be added (via cut-and-paste or some script) at the end of the +The resulting signature is printed in standard output. +This can then be added (via cut-and-paste or some script) at the end of the assertion, in the .Fa Signature field. @@ -155,8 +159,9 @@ string. .Pp If the .Fl v -flag is provided, "keynote sign" will also verify the newly-created -signature using the +flag is provided, +.Qq keynote sign +will also verify the newly-created signature using the .Fa Authorizer field key. .Pp @@ -175,22 +180,24 @@ for the first line and has to be longer (by at least 2) than .Fa print-length also accounts for the line-continuation character (backslash) at the end of each line, and the doublequotes at the beginning and end -of the signature encoding. Default values are 12 and 50 respectively. +of the signature encoding. +Default values are 12 and 50 respectively. .Sh SIGNATURE VERIFICATION -"keynote sigver" reads the assertions contained in +.Qq keynote sigver +reads the assertions contained in .Fa AssertionFile and verifies the public-key signatures on all of them. -.Pp .Sh QUERY TOOL For each operand that names a .A file , -"keynote verify" reads the file and parses the assertions contained -therein (one assertion per file). +.Qq keynote verify +reads the file and parses the assertions contained therein (one assertion +per file). .Pp Files given with the .Fl l flag are assumed to contain trusted assertions (no signature -verification is performed, and the +verification is performed), and the .Fa Authorizer field can contain non-key principals. There should be at least one assertion with the @@ -237,29 +244,46 @@ and least one of each .Fl l , and .Fl k -flags should be given per invocation. If no flags are given, -"keynote verify" prints the usage message and exits with error code \-1. +flags should be given per invocation. +If no flags are given, +.Qq keynote verify +prints the usage message and exits with error code \-1. .Pp -"keynote verify" exits with code \-1 if there was an error, and 0 on success. +.Qq keynote verify +exits with code \-1 if there was an error, and 0 on success. .Sh SEE ALSO .Xr keynote 3 , .Xr keynote 4 , .Xr keynote 5 -.Bl -tag -width "AAAAAAA" -.It ``The KeyNote Trust-Management System, Version 2'' -M. Blaze, J. Feigenbaum, A. D. Keromytis, -Internet Drafts, RFC 2704. -.It ``Decentralized Trust Management'' -M. Blaze, J. Feigenbaum, J. Lacy, -1996 IEEE Conference on Privacy and Security -.It ``Compliance-Checking in the PolicyMaker Trust Management System'' -M. Blaze, J. Feigenbaum, M. Strauss, -1998 Financial Crypto Conference -.El +.Rs +.%A M. Blaze +.%A J. Feigenbaum +.%A A. D. Keromytis +.%T "The KeyNote Trust-Management System, Version 2" +.%N RFC 2704 +.%D 1999 +.Re +.Rs +.%A M. Blaze +.%A J. Feigenbaum +.%A J. Lacy +.%T Decentralized Trust Management +.%J IEEE Conference on Privacy and Security +.%D 1996 +.Re +.Rs +.%A M. Blaze +.%A J. Feigenbaum +.%A M. Strauss +.%T Compliance-Checking in the PolicyMaker Trust Management System +.%J Financial Crypto Conference +.%D 1998 +.Re .Sh AUTHORS -Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) +Angelos D. Keromytis +.Aq angelos@dsl.cis.upenn.edu .Sh WEB PAGE -http://www.cis.upenn.edu/~keynote +.Pa http://www.cis.upenn.edu/~keynote .Sh BUGS None that we know of. If you find any, please report them at diff --git a/lib/libkeynote/keynote.3 b/lib/libkeynote/keynote.3 index 575f51b6bb4..d6af0442117 100644 --- a/lib/libkeynote/keynote.3 +++ b/lib/libkeynote/keynote.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: keynote.3,v 1.28 2001/08/06 10:42:26 mpech Exp $ +.\" $OpenBSD: keynote.3,v 1.29 2001/08/16 17:58:06 mpech Exp $ .\" .\" The author of this code is Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) .\" @@ -31,8 +31,8 @@ .Fd #include <sys/types.h> .Fd #include <regex.h> .Fd #include <keynote.h> +.Pp .Bd -literal - struct environment { char *env_name; @@ -62,8 +62,7 @@ struct keynote_keylist struct keynote_keylist *key_next; }; .Ed -.Ft int -.Fd keynote_errno ; +.Vt extern int keynote_errno; .Ft int .Fn kn_init "void" .Ft int @@ -119,12 +118,12 @@ struct keynote_keylist .Fd Link options: -lkeynote -lm -lcrypto .Sh DESCRIPTION For more details on -.Nm KeyNote , +.Nm keynote , see RFC 2704. .Pp .Va keynote_errno -contains an error code if some library call failed. Failed calls -return \-1 (if their return value is integer), or +contains an error code if some library call failed. +Failed calls return \-1 (if their return value is integer), or .Dv NULL (if their return value is a pointer) and set .Va keynote_errno . @@ -140,40 +139,44 @@ One of the arguments referred to a nonexistent structure or entry. .Pp If no errors were encountered, .Va keynote_errno -will be set to 0. This variable should be reset to 0 if an error was -encountered, prior to calling other library routines. +will be set to 0. +This variable should be reset to 0 if an error was encountered, +prior to calling other library routines. .Pp The main interface to -.Nm KeyNote -is centered around the concept of a session. A session describes a -collection of policies, assertions, action authorizers, return values, -and action attributes that the -.Nm KeyNote -system uses to evaluate a query. Information is not shared between -sessions. Policies, credentials, action authorizers, and action +.Nm +is centered around the concept of a session. +A session describes a collection of policies, assertions, action +authorizers, return values, and action attributes that the +.Nm +system uses to evaluate a query. +Information is not shared between sessions. +Policies, credentials, action authorizers, and action attributes can be added or deleted at any point during the lifetime of -a session. Furthermore, an application can discover which assertions -failed to be evaluated, and in what way, during a query. +a session. +Furthermore, an application can discover which assertions failed to be +evaluated, and in what way, during a query. .Pp For those applications that only need to do a simple query, there exists a single call that takes as arguments all the necessary -information and performs all the necessary steps. This is essentially -a wrapper that calls the session API functions as necessary. +information and performs all the necessary steps. +This is essentially a wrapper that calls the session API functions as +necessary. .Pp Finally, there exist functions for doing ASCII to hexadecimal and Base64 encoding (and vice versa), for encoding/decoding keys between ASCII and binary formats, and for signing and verifying assertions. .Pp The description of all -.Nm KeyNote +.Nm library functions follows. .Pp .Fn kn_init creates a new -.Nm KeyNote -session, and performs any necessary initializations. On success, this -function returns the new session ID, which is used by all subsequent -calls with a +.Nm +session, and performs any necessary initializations. +On success, this function returns the new session ID, which is used by +all subsequent calls with a .Fa sessid argument. On failure, it returns \-1 and sets @@ -222,8 +225,8 @@ removes the assertion identified by .Fa assertid from the session identified by .Fa sessid . -On success, this function returns 0. On failure, it returns \-1 and -sets +On success, this function returns 0. +On failure, it returns \-1 and sets .Va keynote_errno to .Er ERROR_NOTFOUND . @@ -246,50 +249,53 @@ specified are formed by or'ing the following values: In this case, .Fa value is a pointer to a function that takes as argument a string and returns -a string. This is used to implement callbacks for getting action -attribute values. The argument passed to such a callback function is a -string identifying the action attribute whose value is requested, and -should return a pointer to string containing that value (this pointer -will not be freed by the library), the empty string if the value was -not found, or a +a string. +This is used to implement callbacks for getting action attribute values. +The argument passed to such a callback function is a string identifying +the action attribute whose value is requested, and should return a pointer +to string containing that value (this pointer will not be freed by the +library), the empty string if the value was not found, or a .Dv NULL to indicate an error (and may set .Va keynote_errno -appropriately). Prior to first use (currently, at the time the -attribute is added to the session environment), such functions are -called with +appropriately). +Prior to first use (currently, at the time the attribute is added to the +session environment), such functions are called with .Dv KEYNOTE_CALLBACK_INITIALIZE -as the argument (defined in keynote.h) so that they can -perform any special initializations. Furthermore, when the -session is deleted, all such functions will be called with +as the argument (defined in keynote.h) so that they can perform any special +initializations. +Furthermore, when the session is deleted, all such functions will be called +with .Dv KEYNOTE_CALLBACK_CLEANUP -to perform any special cleanup (such as free any allocated memory). A -function may be called with either of these arguments more than once, -if it has been defined as the callback function for more than one -attribute. +to perform any special cleanup (such as free any allocated memory). +A function may be called with either of these arguments more than once, +if it has been defined as the callback function for more than one attribute. .It ENVIRONMENT_FLAG_REGEX In this case, .Fa name is a regular expression that may match more than one attribute. -In case of conflict between a regular expression and a ``simple'' -attribute, the latter will be given priority. In case of conflict -between two regular expression attributes, the one added later will be -given priority. A callback function should never change the current -.Nm KeyNote +In case of conflict between a regular expression and a +.Dq simple +attribute, the latter will be given priority. +In case of conflict between two regular expression attributes, the one added +later will be given priority. +A callback function should never change the current +.Nm session, start/invoke/operate on another session, or call one of the session-API functions. .El .Pp The combination of the two flags may be used to specify callback functions that handle large sets of attributes (even to the extent of -having one callback function handling all attribute references). This -is particularly useful when the action attribute set is particularly +having one callback function handling all attribute references). +This is particularly useful when the action attribute set is particularly large. .Pp On success, .Xr kn_add_action 3 returns 0. On failure, it returns \-1 and sets -.Va keynote_errno to +.Va keynote_errno +to .Er ERROR_NOTFOUND if the session was not found, .Er ERROR_SYNTAX @@ -309,14 +315,16 @@ from the environment of session Notice that if more than one instances of .Fa name exist, only the one added last will be deleted. -On success, this function returns 0. On failure, it returns \-1 and +On success, this function returns 0. +On failure, it returns \-1 and .Va keynote_errno is set to .Er ERROR_NOTFOUND if the session or the attribute were not found, or .Er ERROR_SYNTAX -if the name was invalid. If the attribute value was a callback, that -function will be called with the define +if the name was invalid. +If the attribute value was a callback, that function will be called with +the define .Dv KEYNOTE_CALLBACK_CLEANUP as the argument. .Pp @@ -325,8 +333,9 @@ adds the principal pointed to by .Fa principal to the action authorizers list of session .Fa sessid . -The principal is typically an ASCII-encoded key. On success, this -function will return 0. On failure, it returns \-1 and sets +The principal is typically an ASCII-encoded key. +On success, this function will return 0. +On failure, it returns \-1 and sets .Va keynote_errno to .Er ERROR_NOTFOUND @@ -341,7 +350,8 @@ removes .Fa principal from the action authorizer list of session .Fa sessid . -On success, this function returns 0. On failure, it returns \-1 and sets +On success, this function returns 0. +On failure, it returns \-1 and sets .Va keynote_errno to .Er ERROR_NOTFOUND @@ -352,8 +362,8 @@ evaluates the request based on the assertions, action attributes, and action authorizers added to session .Fa sessid . .Fa returnvalues -is an ordered array of strings that contain the return values. The -lowest-ordered return value is contained in +is an ordered array of strings that contain the return values. +The lowest-ordered return value is contained in .Fa returnvalues[0] , and the highest-ordered value is .Fa returnvalues[numvalues - 1] . @@ -365,14 +375,16 @@ the .Fa returnvalues from the previous call to .Xr kn_do_query 3 -will be used. The programmer SHOULD NOT free +will be used. +The programmer SHOULD NOT free .Fa returnvalues after the call to .Xr kn_do_query 3 if this feature is used, as the array is not replicated internally. On success, this function returns an index into the .Fa returnvalues -array. On failure, it returns \-1 and sets +array. +On failure, it returns \-1 and sets .Va keynote_errno to .Er ERROR_NOTFOUND @@ -389,13 +401,13 @@ returns the assertion ID of the .Fa num'th assertion (starting from zero) in session .Fa sessid -that was somehow invalid during evaluation. This function is typically -called after +that was somehow invalid during evaluation. +This function is typically called after .Xr kn_do_query 3 is used to evaluate a request. .Fa type -specifies the type of failure the application is interested in. It can -be set to: +specifies the type of failure the application is interested in. +It can be set to: .Bl -tag -width KEYNOTE_ERROR_SIGNATURE -offset indent .It KEYNOTE_ERROR_ANY to indicate interest in any error. @@ -407,11 +419,11 @@ for memory-related problems. if the assertion could not be cryptographically verified. .El .Pp -These values are defined in keynote.h. An application can then delete -the offending assertion using +These values are defined in keynote.h. +An application can then delete the offending assertion using .Xr kn_remove_assertion 3 . -For example, to remove all assertion whose signature failed, an -application could do something like: +For example, to remove all assertion whose signature failed, an application +could do something like: .Bd -literal while ((assertid = kn_get_failed(sessid, KEYNOTE_ERROR_SIGNATURE, 0) != -1) @@ -420,8 +432,9 @@ application could do something like: .Pp On success, .Xr kn_get_failed 3 -returns an assertion ID. On failure, or when no assertion matching the -given criteria is found, it returns \-1 and set +returns an assertion ID. +On failure, or when no assertion matching the given criteria is found, +it returns \-1 and set .Va keynote_errno to .Er ERROR_NOTFOUND . @@ -435,8 +448,9 @@ It returns 0 on success. closes session .Fa sessid and frees all related resources, deleting action attributes, action -authorizers, and assertions. On success, this function returns 0. On -failure, it returns \-1 and sets +authorizers, and assertions. +On success, this function returns 0. +On failure, it returns \-1 and sets .Va keynote_errno to .Er ERROR_NOTFOUND @@ -474,8 +488,8 @@ Note that if there were no assertions found in .Fa array , a valid pointer will be returned, but .Fa numassertions -will contain the value zero on return. The returned pointer should be -freed by the programmer. +will contain the value zero on return. +The returned pointer should be freed by the programmer. .Pp .Fn kn_keycompare compares @@ -560,18 +574,19 @@ arguments to .Xr kn_add_assertion 3 respectively. .Fa env_regex -is not used. On success, this function returns an index in +is not used. +On success, this function returns an index in .Fa returnvalues -indicating the returned value to the query. On failure, it returns \-1 -and sets +indicating the returned value to the query. +On failure, it returns \-1 and sets .Va keynote_errno to the same values as .Xr kn_do_query 3 , or to .Er ERROR_MEMORY if a trusted or untrusted assertion could not be added to the session due -to lack of memory resources. Syntax errors in assertions will not be reported -by +to lack of memory resources. +Syntax errors in assertions will not be reported by .Fn kn_query . .Pp .Fn kn_encode_base64 @@ -586,8 +601,10 @@ which is of length The actual length of the encoding stored in .Fa dst is returned. -.Fa dst should be long enough to also contain the trailing -string terminator. If +.Fa dst +should be long enough to also contain the trailing +string terminator. +If .Fa srclen is not a multiple of 4, or .Fa dst @@ -604,8 +621,8 @@ and stores the result in .Fa dst , which is of length .Fa dstlen . -The actual length of the decoded data is returned on success. On -failure, this function returns \-1 and sets +The actual length of the decoded data is returned on success. +On failure, this function returns \-1 and sets .Va keynote_errno to .Er ERROR_SYNTAX , @@ -627,8 +644,9 @@ Thus, this function should be used as follows: kn_encode_hex(src, &dst, srclen); .Ed .Pp -The length of the allocated buffer will be (2 * srclen + 1). On -success, this function returns 0. On failure, it returns \-1 and sets +The length of the allocated buffer will be (2 * srclen + 1). +On success, this function returns 0. +On failure, it returns \-1 and sets .Va keynote_errno to .Er ERROR_MEMORY @@ -642,11 +660,12 @@ was .Fn kn_decode_hex decodes the ASCII hex-encoded string in .Fa src -and stores the result in a memory chunk allocated by the function. A -pointer to that memory is stored in +and stores the result in a memory chunk allocated by the function. +A pointer to that memory is stored in .Fa dst . -The length of the allocated memory will be (strlen(src) / 2). On -success, this function returns 0. On failure, it returns \-1 and sets +The length of the allocated memory will be (strlen(src) / 2). +On success, this function returns 0. +On failure, it returns \-1 and sets .Va keynote_errno to .Er ERROR_MEMORY @@ -661,23 +680,24 @@ or the length of is not even. .Pp .Fn kn_encode_key -ASCII-encodes a cryptographic key. The binary representation of the -key is contained in +ASCII-encodes a cryptographic key. +The binary representation of the key is contained in .Fa dc . The field .Fa dec_key in that structure is a pointer to some cryptographic algorithm -dependent information describing the key. In this implementation, this -pointer should be a +dependent information describing the key. +In this implementation, this pointer should be a .Fa DSA * or .Fa RSA * for DSA or RSA keys respectively, as used in the SSL library, or a .Fa keynote_binary * for cryptographic keys whose algorithm -.Nm KeyNote +.Nm does not know about but the application wishes to include in the -action authorizers (and thus need to be canonicalized). The field +action authorizers (and thus need to be canonicalized). +The field .Fa dec_algorithm describes the cryptographic algorithm, and may be one of .Dv KEYNOTE_ALGORITHM_DSA , @@ -687,8 +707,8 @@ or in this implementation. .Pp .Fa iencoding -describes how the key should be binary-encoded. This implementation -supports +describes how the key should be binary-encoded. +This implementation supports .Dv INTERNAL_ENC_PKCS1 for RSA keys, .Dv INTERNAL_ENC_ASN1 @@ -696,8 +716,8 @@ for DSA keys, and .Dv INTERNAL_ENC_NONE for BINARY keys. .Fa encoding -describes what ASCII encoding should be applied to the key. Valid -values are +describes what ASCII encoding should be applied to the key. +Valid values are .Dv ENCODING_HEX and .Dv ENCODING_BASE64 , @@ -707,12 +727,12 @@ is one of .Dv KEYNOTE_PUBLIC_KEY or .Dv KEYNOTE_PRIVATE_KEY -to indicate whether the key is public or private. Private keys have -the string +to indicate whether the key is public or private. +Private keys have the string .Dv KEYNOTE_PRIVATE_KEY_PREFIX -(defined in keynote.h) prefixed to the algorithm name. On success, -this function returns a string containing the encoded key. On failure, -it returns +(defined in keynote.h) prefixed to the algorithm name. +On success, this function returns a string containing the encoded key. +On failure, it returns .Dv NULL and sets .Va keynote_errno @@ -737,8 +757,8 @@ describing the algorithm (see .Xr kn_encode_key 3 ) , and .Fa dec_key -pointing to an algorithm-dependent structure. In this implementation, -this is an SSLeay/OpenSSL-defined +pointing to an algorithm-dependent structure. +In this implementation, this is an SSLeay/OpenSSL-defined .Fa DSA * for DSA keys, .Fa RSA * @@ -750,8 +770,9 @@ takes the values .Dv KEYNOTE_PUBLIC_KEY or .Dv KEYNOTE_PRIVATE_KEY -to specify a public or private key, where applicable. On success, this -function returns 0. On failure, it returns \-1 and sets +to specify a public or private key, where applicable. +On success, this function returns 0. +On failure, it returns \-1 and sets .Va keynote_errno to .Er ERROR_MEMORY @@ -769,9 +790,9 @@ using the ASCII-encoded cryptographic key contained in The type of signature to be produced is described by the string .Fa algorithm . Possible values for this string are -.Dv SIG_RSA_SHA1_HEX +.Dv SIG_RSA_SHA1_HEX , .Dv SIG_RSA_SHA1_BASE64 , -.Dv SIG_RSA_MD5_HEX , +.Dv SIG_RSA_MD5_HEX and .Dv SIG_RSA_MD5_HEX for RSA keys, @@ -779,14 +800,16 @@ for RSA keys, and .Dv SIG_DSA_SHA1_BASE64 for DSA keys, -.Dv SIG_X509_SHA1_HEX , +.Dv SIG_X509_SHA1_HEX and .Dv SIG_X509_SHA1_BASE64 -for X509-based keys. No other cryptographic signatures are currently -supported by this implementation. If +for X509-based keys. +No other cryptographic signatures are currently +supported by this implementation. +If .Fa vflag -is set to 1, then the generated signature will also be verified. On -success, this function returns a string containing the ASCII-encoded +is set to 1, then the generated signature will also be verified. +On success, this function returns a string containing the ASCII-encoded signature, without modifying the .Fa assertion . On failure, it returns @@ -832,7 +855,8 @@ frees a cryptographic key. .Fn kn_get_string parses the argument, treating it as a .Xr keynote 4 -(quoted) string. This is useful for parsing key files. +(quoted) string. +This is useful for parsing key files. .Sh FILES .Bl -tag -width libkeynote.a -compact .It Pa keynote.h @@ -842,21 +866,35 @@ parses the argument, treating it as a .Xr keynote 1 , .Xr keynote 4 , .Xr keynote 5 -.Bl -tag -width "AAAAAAA" -.It ``The KeyNote Trust-Management System, Version 2'' -M. Blaze, J. Feigenbaum, A. D. Keromytis, -Internet Drafts, RFC 2704. -.It ``Decentralized Trust Management'' -M. Blaze, J. Feigenbaum, J. Lacy, -1996 IEEE Conference on Privacy and Security -.It ``Compliance-Checking in the PolicyMaker Trust Management System'' -M. Blaze, J. Feigenbaum, M. Strauss, -1998 Financial Crypto Conference -.It Web Page -http://www.cis.upenn.edu/~keynote -.El +.Rs +.%A M. Blaze +.%A J. Feigenbaum +.%A A. D. Keromytis +.%T "The KeyNote Trust-Management System, Version 2" +.%N RFC 2704 +.%D 1999 +.Re +.Rs +.%A M. Blaze +.%A J. Feigenbaum +.%A J. Lacy +.%T Decentralized Trust Management +.%J IEEE Conference on Privacy and Security +.%D 1996 +.Re +.Rs +.%A M. Blaze +.%A J. Feigenbaum +.%A M. Strauss +.%T Compliance-Checking in the PolicyMaker Trust Management System +.%J Financial Crypto Conference +.%D 1998 +.Re .Sh AUTHORS -Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) +Angelos D. Keromytis +.Aq angelos@dsl.cis.upenn.edu +.Sh WEB PAGE +.Pa http://www.cis.upenn.edu/~keynote .Sh DIAGNOSTICS The return values of all the functions have been given along with the function description above. diff --git a/lib/libkeynote/keynote.4 b/lib/libkeynote/keynote.4 index d2fa247fe96..161fc4d9760 100644 --- a/lib/libkeynote/keynote.4 +++ b/lib/libkeynote/keynote.4 @@ -1,4 +1,4 @@ -.\" $OpenBSD: keynote.4,v 1.18 2001/08/06 10:42:26 mpech Exp $ +.\" $OpenBSD: keynote.4,v 1.19 2001/08/16 17:58:06 mpech Exp $ .\" .\" The author of this code is Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) .\" @@ -34,7 +34,7 @@ .Fd Link options: -lkeynote -lm -lcrypto .Sh DESCRIPTION For more details on -.Nm KeyNote , +.Nm keynote , see RFC 2704. .Pp Details on the API, assertion syntax, and command-line tool are given in @@ -43,167 +43,204 @@ the man pages listed at the end of this manual. Trust management, introduced in the PolicyMaker system, is a unified approach to specifying and interpreting security policies, credentials, and relationships; it allows direct authorization of -security-critical actions. A trust-management system provides -standard, general-purpose mechanisms for specifying application -security policies and credentials. Trust-management credentials -describe a specific delegation of trust and subsume the role of public -key certificates; unlike traditional certificates, which bind keys to -names, credentials can bind keys directly to the authorization to -perform specific tasks. +security-critical actions. +A trust-management system provides standard, general-purpose mechanisms +for specifying application security policies and credentials. +Trust-management credentials describe a specific delegation of trust +and subsume the role of public key certificates; unlike traditional +certificates, which bind keys to names, credentials can bind keys directly +to the authorization to perform specific tasks. .Pp A trust-management system has five basic components: - -.nf -* A language for describing `actions,' which are operations with - security consequences that are to be controlled by the system. - -* A mechanism for identifying `principals,' which are entities that - can be authorized to perform actions. - -* A language for specifying application `policies,' which govern the - actions that principals are authorized to perform. - -* A language for specifying `credentials,' which allow principals - to delegate authorization to other principals. - -* A `compliance checker,' which provides a service to applications - for determining how an action requested by principals should be - handled, given a policy and a set of credentials. -.fi - +.Bl -bullet -offset "xxx" +.It +A language for describing +.Sq actions , +which are operations with security consequences that are +to be controlled by the system. +.It +A mechanism for identifying +.Sq principals , +which are entities that can be authorized to perform actions. +.It +A language for specifying application +.Sq policies , +which govern the actions that principals are authorized to perform. +.It +A language for specifying +.Sq credentials , +which allow principals to delegate authorization to other principals. +.It +A +.Sq compliance checker , +which provides a service to applications for determining how an action +requested by principals should be handled, given a policy and a set +of credentials. +.El +.Pp The trust-management approach has a number of advantages over other mechanisms for specifying and controlling authorization, especially when security policy is distributed over a network or is otherwise decentralized. .Pp Trust management unifies the notions of security policy, credentials, -access control, and authorization. An application that uses a -trust-management system can simply ask the compliance checker whether -a requested action should be allowed. Furthermore, policies and -credentials are written in standard languages that are shared by all -trust-managed applications; the security configuration mechanism for -one application carries exactly the same syntactic and semantic -structure as that of another, even when the semantics of the -applications themselves are quite different. -.Pp -Trust-management policies are easy to distribute across networks, -helping to avoid the need for application-specific distributed policy -configuration mechanisms, access control lists, and certificate -parsers and interpreters. +access control, and authorization. +An application that uses a trust-management system can simply ask the +compliance checker whether a requested action should be allowed. +Furthermore, policies and credentials are written in standard languages +that are shared by all trust-managed applications; the security configuration +mechanism for one application carries exactly the same syntactic and semantic +structure as that of another, even when the semantics of the applications +themselves are quite different. +.Pp +Trust-management policies are easy to distribute across networks, helping +to avoid the need for application-specific distributed policy configuration +mechanisms, access control lists, and certificate parsers and interpreters. .Pp For a general discussion of the use of trust management in distributed system security, see the papers listed at the end of this manual. .Pp KeyNote is a simple and flexible trust-management system designed to work well for a variety of large- and small- scale Internet-based -applications. It provides a single, unified language for both local -policies and credentials. KeyNote policies and credentials, called -`assertions,' contain predicates that describe the trusted actions -permitted by the holders of specific public keys. KeyNote assertions -are essentially small, highly-structured programs. A signed assertion, -which can be sent over an untrusted network, is also called a -`credential assertion.' Credential assertions, which also serve the -role of certificates, have the same syntax as policy assertions but -are also signed by the principal delegating the trust. +applications. +It provides a single, unified language for both local policies and +credentials. +KeyNote policies and credentials, called +.Sq assertions , +contain predicates that describe the trusted actions permitted by +the holders of specific public keys. +KeyNote assertions are essentially small, highly-structured programs. +A signed assertion, which can be sent over an untrusted network, is also +called a +.Sq credential assertion . +Credential assertions, which also serve the role of certificates, have +the same syntax as policy assertions but are also signed by the principal +delegating the trust. .Pp In KeyNote: - -.nf -* Actions are specified as a collection of name-value pairs. - -* Principal names can be any convenient string and can directly - represent cryptographic public keys. - -* The same language is used for both policies and credentials. - -* The policy and credential language is concise, highly expressive, - human readable and writable, and compatible with a variety of - storage and transmission media, including electronic mail. - -* The compliance checker returns an application-configured `policy - compliance value' that describes how a request should be handled - by the application. Policy compliance values are always - positively derived from policy and credentials, facilitating - analysis of KeyNote-based systems. - -* Compliance checking is efficient enough for high-performance and - real-time applications. -.fi - +.Bl -bullet -offset "xxx" +.It +Actions are specified as a collection of name-value pairs. +.It +Principal names can be any convenient string and can directly represent +cryptographic public keys. +.It +The same language is used for both policies and credentials. +.It +The policy and credential language is concise, highly expressive, human +readable and writable, and compatible with a variety of storage and +transmission media, including electronic mail. +.It +The compliance checker returns an application-configured +.Sq policy compliance value +that describes how a request should be handled by the application. +Policy compliance values are always positively derived from policy and +credentials, facilitating analysis of KeyNote-based systems. +.It +Compliance checking is efficient enough for high-performance and real-time +applications. +.El +.Pp In KeyNote, the authority to perform trusted actions is associated -with one or more `principals.' A principal may be a physical entity, a -process in an operating system, a public key, or any other convenient -abstraction. KeyNote principals are identified by a string called a -`Principal Identifier.' In some cases, a Principal Identifier will -contain a cryptographic key interpreted by the KeyNote system (e.g., -for credential signature verification). In other cases, Principal -Identifiers may have a structure that is opaque to KeyNote. +with one or more +.Sq principals . +A principal may be a physical entity, a process in an operating system, +a public key, or any other convenient abstraction. +KeyNote principals are identified by a string called a +.Sq Principal Identifier . +In some cases, a Principal Identifier will contain a cryptographic key +interpreted by the KeyNote system (e.g., for credential signature +verification). +In other cases, Principal Identifiers may have a structure that is opaque +to KeyNote. .Pp Principals perform two functions of concern to KeyNote: They request -`actions' and they issue `assertions.' Actions are any trusted -operations that an application places under KeyNote control. -Assertions delegate the authorization to perform actions to other -principals. +.Sq actions +and they issue +.Sq assertions . +Actions are any trusted operations that an application places under +KeyNote control. +Assertions delegate the authorization to perform actions to other principals. .Pp Actions are described to the KeyNote compliance checker in terms of a -collection of name-value pairs called an `action attribute set.' The -action attribute set is created by the invoking application. Its -structure and format are described in detail elsewhere of this -document. +collection of name-value pairs called an +.Sq action attribute set . +The action attribute set is created by the invoking application. +Its structure and format are described in detail elsewhere of this document. .Pp KeyNote provides advice to applications on the interpretation of -policy with regard to specific requested actions. Applications invoke -the KeyNote compliance checker by issuing a `query' containing a -proposed action attribute set and identifying the principal(s) -requesting it. The KeyNote system determines and returns an -appropriate `policy compliance value' from an ordered set of possible -responses. +policy with regard to specific requested actions. +Applications invoke the KeyNote compliance checker by issuing a +.Sq query +containing a proposed action attribute set and identifying the principal(s) +requesting it. +The KeyNote system determines and returns an appropriate +.Sq policy compliance value +from an ordered set of possible responses. .Pp The policy compliance value returned from a KeyNote query advises the -application how to process the requested action. In the simplest case, -the compliance value is Boolean (e.g., "reject" or "approve"). +application how to process the requested action. +In the simplest case, the compliance value is Boolean (e.g., +.Qq reject +or +.Qq approve ) . Assertions can also be written to select from a range of possible -compliance values, when appropriate for the application (e.g., "no -access", "restricted access", "full access"). Applications can -configure the relative ordering (from `weakest' to `strongest') of -compliance values at query time. +compliance values, when appropriate for the application (e.g., +.Qq no access , +.Qq restricted access , +.Qq full access ) . +Applications can configure the relative ordering (from +.Sq weakest +to +.Sq strongest ) +of compliance values at query time. .Pp Assertions are the basic programming unit for specifying policy and -delegating authority. Assertions describe the conditions under which a -principal authorizes actions requested by other principals. An -assertion identifies the principal that made it, which other -principals are being authorized, and the conditions under which the -authorization applies. The syntax of assertions is given +delegating authority. +Assertions describe the conditions under which a principal authorizes actions +requested by other principals. +An assertion identifies the principal that made it, which other principals +are being authorized, and the conditions under which the authorization +applies. +The syntax of assertions is given .Xr keynote 5 . .Pp -A special principal, whose identifier is "POLICY", provides the root -of trust in KeyNote. "POLICY" is therefore considered to be authorized -to perform any action. +A special principal, whose identifier is +.Qq POLICY , +provides the root of trust in KeyNote. +.Qq POLICY +is therefore considered to be authorized to perform any action. .Pp -Assertions issued by the "POLICY" principal are called `policy -assertions' and are used to delegate authority to otherwise untrusted -principals. The KeyNote security policy of an application consists of -a collection of policy assertions. +Assertions issued by the +.Qq POLICY +principal are called +.Sq policy assertions +and are used to delegate authority to otherwise untrusted principals. +The KeyNote security policy of an application consists of a collection +of policy assertions. .Pp When a principal is identified by a public key, it can digitally sign assertions and distribute them over untrusted networks for use by -other KeyNote compliance checkers. These signed assertions are also -called `credentials,' and serve a role similar to that of traditional -public key certificates. Policies and credentials share the same -syntax and are evaluated according to the same semantics. A principal -can therefore convert its policy assertions into credentials simply by -digitally signing them. +other KeyNote compliance checkers. +These signed assertions are also called +.Sq credentials , +and serve a role similar to that of traditional public key certificates. +Policies and credentials share the same syntax and are evaluated according +to the same semantics. +A principal can therefore convert its policy assertions into credentials +simply by digitally signing them. .Pp KeyNote is designed to encourage the creation of human-readable policies and credentials that are amenable to transmission and storage -over a variety of media. Its assertion syntax is inspired by the -format of RFC822-style message headers. A KeyNote assertion contains a -sequence of sections, called `fields,' each of which specifying one -aspect of the assertion's semantics. Fields start with an identifier -at the beginning of a line and continue until the next field is -encountered. For example: - -.nf +over a variety of media. +Its assertion syntax is inspired by the format of RFC822-style message +headers. +A KeyNote assertion contains a sequence of sections, called +.Sq fields , +each of which specifying one aspect of the assertion's semantics. +Fields start with an identifier at the beginning of a line and continue +until the next field is encountered. For example: +.Bd -literal KeyNote-Version: 2 Comment: A simple, if contrived, email certificate for user mab Local-Constants: ATT_CA_key = "RSA:acdfa1df1011bbac" @@ -213,66 +250,74 @@ encountered. For example: Conditions: ((app_domain == "email") # valid for email only && (address == "mab@research.att.com")); Signature: "RSA-SHA1:f00f2244" -.fi - +.Ed +.Pp For the exact meanings of all the fields, see the RFC reference at the end of this manual, and/or .Xr keynote 5 . .Pp KeyNote semantics resolve the relationship between an application's policy and actions requested by other principals, as supported by -credentials. The KeyNote compliance checker processes the assertions -against the action attribute set to determine the policy compliance -value of a requested action. These semantics are defined later in this -document. -.Pp -An important principle in KeyNote's design is `assertion -monotonicity'; the policy compliance value of an action is always -positively derived from assertions made by trusted principals. +credentials. +The KeyNote compliance checker processes the assertions against the action +attribute set to determine the policy compliance value of a requested action. +These semantics are defined later in this document. +.Pp +An important principle in KeyNote's design is +.Sq assertion monotonicity ; +the policy compliance value of an action is always positively derived from +assertions made by trusted principals. Removing an assertion never results in increasing the compliance value -returned by KeyNote for a given query. The monotonicity property can -simplify the design and analysis of complex network-based security -protocols; network failures that prevent the transmission of -credentials can never result in spurious authorization of dangerous -actions. -.Pp -Trusted actions to be evaluated by KeyNote are described by a -collection of name-value pairs called the `action attribute set'. +returned by KeyNote for a given query. +The monotonicity property can simplify the design and analysis of complex +network-based security protocols; network failures that prevent the +transmission of credentials can never result in spurious authorization of +dangerous actions. +.Pp +Trusted actions to be evaluated by KeyNote are described by a collection of +name-value pairs called the +.Sq action attribute set . Action attributes are the mechanism by which applications communicate requests to KeyNote and are the primary objects on which KeyNote -assertions operate. An action attribute set is passed to the KeyNote -compliance checker with each query. -.Pp -Each action attribute consists of a name and a value. The semantics of -the names and values are not interpreted by KeyNote itself; they vary -from application to application and must be agreed upon by the writers -of applications and the writers of the policies and credentials that +assertions operate. +An action attribute set is passed to the KeyNote compliance checker with +each query. +.Pp +Each action attribute consists of a name and a value. +The semantics of the names and values are not interpreted by KeyNote itself; +they vary from application to application and must be agreed upon by the +writers of applications and the writers of the policies and credentials that will be used by them. .Pp Action attribute names and values are represented by arbitrary-length -strings. KeyNote guarantees support of attribute names and values up -to 2048 characters long. Applications and assertions should therefore -avoid depending on the use of attributes with names or values -longer than 2048 characters. +strings. +KeyNote guarantees support of attribute names and values up +to 2048 characters long. +Applications and assertions should therefore avoid depending on the use of +attributes with names or values longer than 2048 characters. .Pp Attribute values are inherently untyped and are represented as -character strings by default. Attribute values may contain any non- -NUL ASCII character. Numeric attribute values should first be -converted to an ASCII text representation by the invoking application, -e.g., the value 1234.5 would be represented by the string "1234.5". -.Pp -An <AttributeID> begins with an alphabetic or underscore character and -can be followed by any number of alphanumerics and underscores. -Attribute names are case-sensitive. +character strings by default. +Attribute values may contain any non-NUL ASCII character. Numeric attribute +values should first be converted to an ASCII text representation by the +invoking application, e.g., the value 1234.5 would be represented by +the string +.Qq 1234.5 . +.Pp +An +.Aq AttributeID +begins with an alphabetic or underscore character and can be followed +by any number of alphanumerics and underscores. +Attribute names are case sensitive. .Pp If an action attribute is not defined its value is considered to be the empty string. .Pp -Attribute names beginning with the "_" character are reserved for use -by the KeyNote runtime environment and cannot be passed from -applications as part of queries. The following special attribute names -are used: - +Attribute names beginning with the +.Dq \_ +character are reserved for use by the KeyNote runtime environment and +cannot be passed from applications as part of queries. +The following special attribute names are used: .Bl -tag -width indent .It _MIN_TRUST Lowest-order (minimum) compliance value in query. @@ -285,34 +330,46 @@ Names of principals directly authorizing action in query. Comma separated. .El .Pp -In addition, attributes with names of the form "_<N>", where <N> is an -ASCII-encoded integer, are used by the regular expression matching +In addition, attributes with names of the form +.Qq \_ Ns Aq N , +where +.Aq N +is an ASCII-encoded integer, are used by the regular expression matching mechanism described in .Xr keynote 5 . .Pp By convention, the name of the application domain over which action attributes should be interpreted is given in the attribute named -"app_domain". The IANA (or some other suitable authority) will provide -a registry of reserved app_domain names. The registry will list the -names and meanings of each application's attributes. +.Qq app_domain . +The IANA (or some other suitable authority) will provide a registry +of reserved app_domain names. +The registry will list the names and meanings of each application's +attributes. .Pp The app_domain convention helps to ensure that credentials are -interpreted as they were intended. An attribute with any given name -may be used in many different application domains but might have -different meanings in each of them. However, the use of a global -registry is not always required for small-scale, closed applications; -the only requirement is that the policies and credentials made -available to the KeyNote compliance checker interpret attributes -according to the same semantics assumed by the application that -created them. +interpreted as they were intended. +An attribute with any given name may be used in many different application +domains but might have different meanings in each of them. +However, the use of a global registry is not always required for +small-scale, closed applications; the only requirement is that the +policies and credentials made available to the KeyNote compliance checker +interpret attributes according to the same semantics assumed by the +application that created them. .Pp For example, an email application might reserve the app_domain -"RFC822-EMAIL" and might use the attributes named "address" (the mail -address of a message's sender), "name" (the human name of the message -sender), and any "organization" headers present (the organization -name). The values of these attributes would be derived in the obvious -way from the email message headers. The public key of the message's -signer would be given in the "_ACTION_AUTHORIZERS" attribute. +.Qq RFC822-EMAIL +and might use the attributes named +.Qq address +(the mail address of a message's sender), +.Qq name +(the human name of the message sender), and any +.Qq organization +headers present (the organization name). +The values of these attributes would be derived in the obvious way from +the email message headers. +The public key of the message's signer would be given in the +.Qq _ACTION_AUTHORIZERS +attribute .Sh QUERY SEMANTICS The discussion in the following sections assume some familiarity with assertion syntax. Please refer to @@ -320,53 +377,65 @@ assertion syntax. Please refer to for more details on the syntax. .Sh QUERY PARAMETERS A KeyNote query has four parameters: - -.nf -* The identifier of the principal(s) requesting the action. - -* The action attribute set describing the action. - -* The set of compliance values of interest to the application, - ordered from _MIN_TRUST to _MAX_TRUST - -* The policy and credential assertions that should be included in - the evaluation. -.fi - +.Bl -bullet -offset "xxx" +.It +The identifier of the principal(s) requesting the action. +.It +The action attribute set describing the action. +.It +The set of compliance values of interest to the application, +ordered from _MIN_TRUST to _MAX_TRUST +.It +The policy and credential assertions that should be included in +the evaluation. +.El +.Pp The mechanism for passing these parameters to the KeyNote evaluator is -application dependent. In particular, an evaluator might provide for -some parameters to be passed explicitly, while others are looked up -externally (e.g., credentials might be looked up in a network- based -distribution system), while still others might be requested from the -application as needed by the evaluator, through a `callback' mechanism -(e.g., for attribute values that represent values from among a very -large namespace). +application dependent. +In particular, an evaluator might provide for some parameters to be passed +explicitly, while others are looked up externally (e.g., credentials might +be looked up in a network- based distribution system), while still others +might be requested from the application as needed by the evaluator, +through a +.Sq callback +mechanism (e.g., for attribute values that represent values from among +a very large namespace). .Sh ACTION REQUESTER -At least one Principal must be identified in each query as the -`requester' of the action. Actions may be requested by several -principals, each considered to have individually requested it. This -allows policies that require multiple authorizations, e.g., `two -person control'. The set of authorizing principals is made available -in the special attribute "_ACTION_AUTHORIZERS"; if several principals -are authorizers, their identifiers are separated with commas. +At least one Principal must be identified in each query as the +.Sq requester +of the action. Actions may be requested by several principals, each +considered to have individually requested it. +This allows policies that require multiple authorizations, e.g., +.Sq two person control . +The set of authorizing principals is made available in the special +attribute +.Qq _ACTION_AUTHORIZERS ; +if several principals are authorizers, their identifiers are separated +with commas. .Sh ORDERED COMPLIANCE VALUE SET The set of compliance values of interest to an application (and their relative ranking to one another) is determined by the invoking application and passed to the KeyNote evaluator as a parameter of the -query. In many applications, this will be Boolean, e.g., the ordered -sets {FALSE, TRUE} or {REJECT, APPROVE}. Other applications may -require a range of possible values, e.g., {No_Access, Limited_Access, -Full_Access}. Note that applications should include in this set only -compliance value names that are actually returned by the assertions. +query. +In many applications, this will be Boolean, e.g., the ordered +sets {FALSE, TRUE} or {REJECT, APPROVE}. +Other applications may require a range of possible values, e.g., +{No_Access, Limited_Access, Full_Access}. Note that applications should +include in this set only compliance value names that are actually returned +by the assertions. .Pp The lowest-order and highest-order compliance value strings given in -the query are available in the special attributes named "_MIN_TRUST" -and "_MAX_TRUST", respectively. The complete set of query compliance -values is made available in ascending order (from _MIN_TRUST to -_MAX_TRUST) in the special attribute named "_VALUES". Values are -separated with commas; applications that use assertions that make use -of the _VALUES attribute should therefore avoid the use of compliance -value strings that themselves contain commas. +the query are available in the special attributes named +.Qq _MIN_TRUST +and +.Qq _MAX_TRUST , +respectively. The complete set of query compliance values is made +available in ascending order (from _MIN_TRUST to _MAX_TRUST) in +the special attribute named +.Qq _VALUES . +Values are separated with commas; applications that use assertions +that make use of the _VALUES attribute should therefore avoid the +use of compliance value strings that themselves contain commas. .Sh PRINCIPAL IDENTIFIER NORMALIZATION Principal identifier comparisons among Cryptographic Principal Identifiers (that represent keys) in the Authorizer and Licensees @@ -375,32 +444,42 @@ normalizing them by conversion to a canonical form. .Pp Every cryptographic algorithm used in KeyNote defines a method for converting keys to their canonical form and that specifies how the -comparison for equality of two keys is performed. If the algorithm -named in the identifier is unknown to KeyNote, the identifier is -treated as opaque. +comparison for equality of two keys is performed. +If the algorithm named in the identifier is unknown to KeyNote, +the identifier is treated as opaque. .Pp -Opaque identifiers are compared as case-sensitive strings. +Opaque identifiers are compared as case sensitive strings. .Pp Notice that use of opaque identifiers in the Authorizer field requires that the assertion's integrity be locally trusted (since it cannot be cryptographically verified by the compliance checker). .Sh POLICY COMPLIANCE VALUE CALCULATION The Policy Compliance Value of a query is the Principal Compliance -Value of the principal named "POLICY". +Value of the principal named +.Qq POLICY . .Sh PRINCIPAL COMPLIANCE VALUE -The Compliance Value of a principal <X> is the highest order (maximum) -of: - -.nf -- the Direct Authorization Value of principal <X>; and - -- the Assertion Compliance Values of all assertions identifying - <X> in the Authorizer field. +The Compliance Value of a principal +.Aq X +is the highest order (maximum) of: +.Bl -bullet -offset "xxx" +.It +the Direct Authorization Value of principal +.Aq X ; +and +.It +the Assertion Compliance Values of all assertions identifying +.Aq X +in the Authorizer field. .fi .Sh DIRECT AUTHORIZATION VALUE -The Direct Authorization Value of a principal <X> is _MAX_TRUST if <X> -is listed in the query as an authorizer of the action. Otherwise, the -Direct Authorization Value of <X> is _MIN_TRUST. +The Direct Authorization Value of a principal +.Aq X +is _MAX_TRUST if +.Aq X +is listed in the query as an authorizer of the action. +Otherwise, the Direct Authorization Value of +.Aq X +is _MIN_TRUST. .Sh ASSERTION COMPLIANC VALUE The Assertion Compliance Value of an assertion is the lowest order (minimum) of the assertion's Conditions Compliance Value and its @@ -423,22 +502,30 @@ The set of successful test clause values is calculated as follows: Recall from the grammar of the Conditions field (see .Xr keynote 5 for more details) that each clause in the conditions section has two -logical parts: a `test' and an optional `value', which, if present, is -separated from the test with the "->" token. The test subclause is a -predicate that either succeeds (evaluates to logical `true') or fails -(evaluates to logical `false'). The value subclause is a string +logical parts: a `test' and an optional +.Sq value , +which, if present, is separated from the test with the +.Qq \-\> +token. +The test subclause is a +predicate that either succeeds (evaluates to logical +.Sq true ) +or fails (evaluates to logical +.Sq false ) . +The value subclause is a string expression that evaluates to one value from the ordered set of -compliance values given with the query. If the value subclause is -missing, it is considered to be _MAX_TRUST. That is, the clause +compliance values given with the query. +If the value subclause is missing, it is considered to be _MAX_TRUST. +That is, the clause .Bd -literal foo=="bar"; .Ed - +.Pp is equivalent to -.Bd literal +.Bd -literal foo=="bar" -> _MAX_TRUST; .Ed - +.Pp If the value component of a clause is present, in the simplest case it contains a string expression representing a possible compliance value. For example, consider an assertion with the following Conditions @@ -450,51 +537,84 @@ field: @user_id < 10000 -> "guest_access"; # clause (3) user_name == "root" -> "full_access"; # clause (4) .Ed - -Here, if the value of the "user_id" attribute is "1073" and the -"user_name" attribute is "root", the possible compliance value set -would contain the values "guest_access" (by clause (3)) and -"full_access" (by clause (4)). If the ordered set of compliance values -given in the query (in ascending order) is {"no_access", -"guest_access", "user_access", "full_access"}, the Conditions -Compliance Value of the assertion would be "full_access" (because -"full_access" has a higher-order value than "guest_access"). If the -"user_id" attribute had the value "19283" and the "user_name" -attribute had the value "nobody", no clause would succeed and the -Conditions Compliance Value would be "no_access", which is the -lowest-order possible value (_MIN_TRUST). +.Pp +Here, if the value of the +.Qq user_id +attribute is +.Qq 1073 +and the +.Qq user_name +attribute is +.Qq root , +the possible compliance value set would contain the values +.Qq guest_access +(by clause (3)) and +.Qq full_access +(by clause (4)). If the ordered set of compliance values +given in the query (in ascending order) is +.Pf { Ns Qo no_access +.Qc , +.Qq guest_access , +.Qq user_access , +.Qo full_access +.No Qc Ns }, +the Conditions Compliance Value of the assertion would be +.Qq full_access +(because +.Qq full_access +has a higher-order value than +.Qq guest_access ) . +If the +.Qq user_id +attribute had the value +.Qq 19283 +and the +.Qq user_name +attribute had the value +.Qq nobody , +no clause would succeed and the Conditions Compliance Value would be +.Qq no_access , +which is the lowest-order possible value (_MIN_TRUST). .Pp If a clause lists an explicit value, its value string must be named in -the query ordered compliance value set. Values not named in the query +the query ordered compliance value set. +Values not named in the query compliance value set are considered equivalent to _MIN_TRUST. .Pp The value component of a clause can also contain recursively-nested -clauses. Recursively-nested clauses are evaluated only if their parent -test is true. That is, +clauses. +Recursively-nested clauses are evaluated only if their parent test is true. +That is, .Bd -literal a=="b" -> { b=="c" -> "value1"; d=="e" -> "value2"; true -> "value3"; } ; .Ed - +.Pp is equivalent to .Bd -literal (a=="b") && (b=="c") -> "value1"; (a=="b") && (d=="e") -> "value2"; (a=="b") -> "value3"; .Ed - -Notice that string comparisons are case-sensitive. .Pp -A regular expression comparison ("~=") is considered true if the -left-hand-side string expression matches the right-hand-side regular -expression. If the POSIX regular expression group matching scheme is +Notice that string comparisons are case sensitive. +.Pp +A regular expression comparison +.Po +.Qq ~= +.Pc +is considered true if the left-hand-side string expression matches +the right-hand-side regular expression. +If the POSIX regular expression group matching scheme is used, the number of groups matched is placed in the temporary meta- -attribute "_0" (dereferenced as _0), and each match is placed in -sequence in the temporary attributes (_1, _2, ..., _N). These -match-attributes' values are valid only within subsequent references -made within the same clause. Regular expression evaluation is case- -sensitive. +attribute +.Qq _0 +(dereferenced as _0), and each match is placed in +sequence in the temporary attributes (_1, _2, ..., _N). +These match-attributes' values are valid only within subsequent references +made within the same clause. +Regular expression evaluation is case sensitive. .Pp A runtime error occurring in the evaluation of a test, such as division by zero or an invalid regular expression, causes the test to @@ -505,12 +625,14 @@ be considered false. For example: @a == 2 -> "anotherval"; # subclause 2 }; .Ed - -Here, subclause 1 triggers a runtime error. Subclause 1 is therefore -false (and has the value _MIN_TRUST). Subclause 2, however, would be -evaluated normally. .Pp -An invalid <RegExpr> is considered a runtime error and causes the test +Here, subclause 1 triggers a runtime error. +Subclause 1 is therefore false (and has the value _MIN_TRUST). +Subclause 2, however, would be evaluated normally. +.Pp +An invalid +.Aq RegExpr +is considered a runtime error and causes the test in which it occurs to be considered false. .Sh LICENSEE COMPLIANCE VALUE The Licensee Compliance Value of an assertion is calculated by @@ -518,87 +640,126 @@ evaluating the expression in the Licensees field, based on the Principal Compliance Value of the principals named there. .Pp If an assertion's Licensees field is empty, its Licensee Compliance -Value is considered to be _MIN_TRUST. If an assertion's Licensees -field is missing altogether, its Licensee Compliance Value is -considered to be _MAX_TRUST. +Value is considered to be _MIN_TRUST. +If an assertion's Licensees field is missing altogether, its Licensee +Compliance Value is considered to be _MAX_TRUST. .Pp For each principal named in the Licensees field, its Principal -Compliance Value is substituted for its name. If no Principal -Compliance Value can be found for some named principal, its name is -substituted with the _MIN_TRUST value. +Compliance Value is substituted for its name. +If no Principal Compliance Value can be found for some named principal, +its name is substituted with the _MIN_TRUST value. .Pp The licensees expression (see .Xr keynote 5 ) is evaluated as follows: - -.nf -* A "(...)" expression has the value of the enclosed subexpression. - -* A "&&" expression has the lower-order (minimum) of its two - subexpression values. - -* A "||" expression has the higher-order (maximum) of its two - subexpression values. - -* A "<K>-of(<List>)" expression has the K-th highest order - compliance value listed in <list>. Values that appear multiple - times are counted with multiplicity. For example, if K = 3 and - the orders of the listed compliance values are (0, 1, 2, 2, 3), - the value of the expression is the compliance value of order 2. -.fi - +.Bl -bullet -offset "xxx" +.It +A +.Qq (...) +expression has the value of the enclosed subexpression. +.It +A +.Qq \&\& +expression has the lower-order (minimum) of its two subexpression values. +.It +A +.Qq \|\| +expression has the higher-order (maximum) of its two subexpression values. +.It +A +.Qo +.Ao K +.No Ac Ns -of Ns Po Aq List +.Pc +.Qc +expression has the K-th highest order compliance value listed in +.Aq list . +Values that appear multiple times are counted with multiplicity. + For example, if K = 3 and the orders of the listed compliance values are +(0, 1, 2, 2, 3), the value of the expression is the compliance value of +order 2. +.El +.Pp For example, consider the following Licensees field: .Bd -literal Licensees: ("alice" && "bob") || "eve" .Ed - -If the Principal Compliance Value is "yes" for principal "alice", "no" -for principal "bob", and "no" for principal "eve", and "yes" is higher -order than "no" in the query's Compliance Value Set, then the -resulting Licensee Compliance Value is "no". +.Pp +If the Principal Compliance Value is +.Qq yes +for principal +.Qq alice , +.Qq no +for principal +.Qq bob , +and +.Qq no +for principal +.Qq eve , +and +.Qq yes +is higher order than +.Qq no +in the query's Compliance Value Set, then the resulting Licensee Compliance +Value is +.Qq no . .Pp Observe that if there are exactly two possible compliance values -(e.g., "false" and "true"), the rules of Licensee Compliance Value -resolution reduce exactly to standard Boolean logic. +(e.g., +.Qq false +and +.Qq true ) , +the rules of Licensee Compliance Value resolution reduce exactly to standard +Boolean logic. .Sh ASSERTION MANAGEMENT -Assertions may be either signed or unsigned. Only signed assertions -should be used as credentials or transmitted or stored on untrusted -media. Unsigned assertions should be used only to specify policy and -for assertions whose integrity has already been verified as conforming +Assertions may be either signed or unsigned. +Only signed assertions should be used as credentials or transmitted or +stored on untrusted media. +Unsigned assertions should be used only to specify policy and for assertions +whose integrity has already been verified as conforming to local policy by some mechanism external to the KeyNote system itself (e.g., X.509 certificates converted to KeyNote assertions by a trusted conversion program). .Pp Implementations that permit signed credentials to be verified by the -KeyNote compliance checker generally provide two `channels' through -which applications can make assertions available. Unsigned, -locally-trusted assertions are provided over a `trusted' interface, -while signed credentials are provided over an `untrusted' interface. +KeyNote compliance checker generally provide two +.Sq channels +through which applications can make assertions available. +Unsigned, locally-trusted assertions are provided over a +.Sq trusted +interface, while signed credentials are provided over an +.Sq untrusted +interface. The KeyNote compliance checker verifies correct signatures for all -assertions submitted over the untrusted interface. The integrity of -KeyNote evaluation requires that only assertions trusted as reflecting -local policy are submitted to KeyNote via the trusted interface. +assertions submitted over the untrusted interface. +The integrity of KeyNote evaluation requires that only assertions trusted +as reflecting local policy are submitted to KeyNote via the trusted interface. .Pp Note that applications that use KeyNote exclusively as a local policy -specification mechanism need use only trusted assertions. Other -applications might need only a small number of infrequently changed -trusted assertions to `bootstrap' a policy whose details are specified -in signed credentials issued by others and submitted over the -untrusted interface. +specification mechanism need use only trusted assertions. +Other applications might need only a small number of infrequently changed +trusted assertions to +.Sq bootstrap +a policy whose details are specified in signed credentials issued +by others and submitted over the untrusted interface. .Sh EXAMPLES -A policy that delegates authority for the "SPEND" application domain -to RSA key dab212 when the amount given in the "dollars" attribute is -less than 10000. +A policy that delegates authority for the +.Qq SPEND +application domain to RSA key dab212 when the amount given in the +.Qq dollars +attribute is less than 10000. .Bd -literal Authorizer: "POLICY" Licensees: "RSA:dab212" # the CFO's key Conditions: (app_domain=="SPEND") && (@dollars < 10000); .Ed - +.Pp RSA key dab212 delegates authorization to any two signers, from a -list, one of which must be DSA key feed1234 in the "SPEND" application -when @dollars < 7500. If the amount in @dollars is 2500 or greater, -the request is approved but logged. +list, one of which must be DSA key feed1234 in the +.Qq SPEND +application when @dollars < 7500. +If the amount in @dollars is 2500 or greater, the request is approved +but logged. .Bd -literal KeyNote-Version: 2 Comment: This credential specifies a spending policy @@ -617,7 +778,7 @@ the request is approved but logged. }; Signature: "RSA-SHA1:9867a1" .Ed - +.Pp According to this policy, any two signers from the list of managers will do if @(dollars) < 1000: .Bd -literal @@ -632,10 +793,10 @@ will do if @(dollars) < 1000: Conditions: (app_domain=="SPEND") && (@(dollars) < 1000); .Ed - +.Pp A credential from dab212 with a similar policy, but only one signer is -required if @(dollars) < 500. A log entry is made if the amount is at -least 100. +required if @(dollars) < 500. +A log entry is made if the amount is at least 100. .Bd -literal KeyNote-Version: 2 Comment: This one credential is equivalent to six separate @@ -655,10 +816,16 @@ least 100. }; Signature: "RSA-SHA1:186123" .Ed - +.Pp Assume a query in which the ordered set of Compliance Values is -{"Reject", "ApproveAndLog", "Approve"}. Under policies E and G, and -credentials F and H, the Policy Compliance Value is "Approve" +.Pf { Ns Qo Reject +.Qc , +.Qq ApproveAndLog , +.Qo Approve +.No Qc Ns }. +Under policies E and G, and +credentials F and H, the Policy Compliance Value is +.Qq Approve (_MAX_TRUST) when: .Bd -literal _ACTION_AUTHORIZERS = "DSA:978add" @@ -670,7 +837,7 @@ credentials F and H, the Policy Compliance Value is "Approve" app_domain = "SPEND" dollars = "550" .Ed - +.Pp The following return "ApproveAndLog": .Bd -literal _ACTION_AUTHORIZERS = "DSA:feed1234,DSA:cde333" @@ -681,7 +848,7 @@ The following return "ApproveAndLog": app_domain = "SPEND" dollars = "150" .Ed - +.Pp However, the following return "Reject" (_MIN_TRUST): .Bd -literal _ACTION_AUTHORIZERS = "DSA:def975" @@ -693,27 +860,43 @@ However, the following return "Reject" (_MIN_TRUST): dollars = "5500" .Ed .Sh FILES -.Fd keynote.h -.Fd libkeynote.a +.Bl -tag -width libkeynote.a -compact +.It Pa keynote.h +.It Pa libkeynote.a +.El .Sh SEE ALSO .Xr keynote 1 , .Xr keynote 3 , .Xr keynote 5 -.Bl -tag -width "AAAAAAA" -.It ``The KeyNote Trust-Management System, Version 2'' -M. Blaze, J. Feigenbaum, A. D. Keromytis, -Internet Drafts, RFC 2704. -.It ``Decentralized Trust Management'' -M. Blaze, J. Feigenbaum, J. Lacy, -1996 IEEE Conference on Privacy and Security -.It ``Compliance-Checking in the PolicyMaker Trust Management System'' -M. Blaze, J. Feigenbaum, M. Strauss, -1998 Financial Crypto Conference -.El +.Rs +.%A M. Blaze +.%A J. Feigenbaum +.%A A. D. Keromytis +.%T "The KeyNote Trust-Management System, Version 2" +.%N RFC 2704 +.%D 1999 +.Re +.Rs +.%A M. Blaze +.%A J. Feigenbaum +.%A J. Lacy +.%T Decentralized Trust Management +.%J IEEE Conference on Privacy and Security +.%D 1996 +.Re +.Rs +.%A M. Blaze +.%A J. Feigenbaum +.%A M. Strauss +.%T Compliance-Checking in the PolicyMaker Trust Management System +.%J Financial Crypto Conference +.%D 1998 +.Re .Sh AUTHORS -Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) +Angelos D. Keromytis +.Aq angelos@dsl.cis.upenn.edu .Sh WEB PAGE -http://www.cis.upenn.edu/~keynote +.Pa http://www.cis.upenn.edu/~keynote .Sh BUGS None that we know of. If you find any, please report them at diff --git a/lib/libkeynote/keynote.5 b/lib/libkeynote/keynote.5 index baa800b6cd7..22a382a4c6c 100644 --- a/lib/libkeynote/keynote.5 +++ b/lib/libkeynote/keynote.5 @@ -1,4 +1,4 @@ -.\" $OpenBSD: keynote.5,v 1.7 2001/08/06 10:42:26 mpech Exp $ +.\" $OpenBSD: keynote.5,v 1.8 2001/08/16 17:58:06 mpech Exp $ .\" .\" The author of this code is Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) .\" @@ -39,12 +39,14 @@ Signature: <public key signature> .Ed .Sh DESCRIPTION For more details on -.Nm KeyNote , +.Nm keynote , see RFC 2704. .Pp -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 ":" +KeyNote assertions are divided into sections, called +.Sq fields , +that serve various semantic functions. Each field starts with an +identifying label at the beginning of a line, followed by the +.Qq \: character and the field's contents. There can be at most one field per line. .Pp @@ -59,56 +61,107 @@ One mandatory field is required in all assertions: Authorizer Six optional fields may also appear: Comment, Conditions, KeyNote-Version, Licensees, Local-Constants, Signature. .Pp -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. +All field names are case-insensitive. The +.Qq KeyNote-Version +field, if present, appears first. The +.Qq Signature +field, if present, appears last. +Otherwise, fields may appear in any order. +Each field may appear at most once in any assertion. .Pp 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. .Sh 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. +The octothorp character +.Pf ( Ns Qo # Qc , +ASCII 35 decimal) can be used to +introduce comments. +Outside of quoted strings, all characters from the +.Qq # +character through the end of the current line are ignored. However, commented text is included in the computation of assertion signatures. .Sh STRINGS -A `string' is a lexical object containing a sequence of characters. +A +.Sq 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. +nonprintable characters. +Strings may be given as literals, computed from complex expressions, +or dereferenced from attribute names. .Sh 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). .Pp -A printable character may be `escaped' inside a quoted string literal -by preceding it with the backslash character (ASCII 92 decimal) (e.g., -"like \\"this\\"."). This permits the inclusion of the double- quote and -backslash characters inside string literals. +A printable character may be +.Sq escaped +inside a quoted string literal by preceding it with the backslash +character (ASCII 92 decimal) (e.g., +.Qo like \& +.No \e Ns Qo this Ns \e +.Qc . +.\".Pf { Qo mike Ns Qc 12 +.Qc Ns ). +This permits the inclusion of the double- quote and backslash characters +inside string literals. .Pp A similar escape mechanism is also used to represent non-printable -characters. "\\n" represents the newline character (ASCII character 10 -decimal), "\\r" represents the carriage-return character (ASCII -character 13 decimal), "\\t" represents the tab character (ASCII -character 9 decimal), and "\\f" 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 non-whitespace character (this allows the continuation -of long string constants across lines). Un-escaped newline and return -characters are illegal inside string literals. -.Pp -The constructs "\\0o", "\\0oo", and "\\ooo" (where o represents any -octal digit) may be used to represent any non-NUL ASCII characters -with their corresponding octal values (thus, "\\012" is the same as -"\\n", "\\101" is "A", and "\\377" is the ASCII character 255 decimal). -However, the NUL character cannot be encoded in this manner; "\\0", -"\\00", and "\\000" are converted to the strings "0", "00", and "000" -respectively. Similarly, all other escaped characters have the -leading backslash removed (e.g., "\\a" becomes "a", and "\\\\" becomes -"\\"). The following four strings are equivalent: +characters. +.Qq \e Ns n +represents the newline character (ASCII character 10 +decimal), +.Qq \e Ns r +represents the carriage-return character (ASCII +character 13 decimal), +.Qq \e Ns t +represents the tab character (ASCII character 9 decimal), and +.Qq \e Ns f +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 non-whitespace character +(this allows the continuation of long string constants across lines). +Un-escaped newline and return characters are illegal inside string literals. +.Pp +The constructs +.Qq \e Ns 0o , +.Qq \e Ns 0oo , +and +.Qq \e Ns ooo +(where o represents any octal digit) may be used to represent any non-NUL +ASCII characters with their corresponding octal values (thus, +.Qq \e Ns 012 +is the same as +.Qq \e Ns n , +.Qq \e Ns 101 +is +.Qq A , +and +.Qq \e Ns 377 +is the ASCII character 255 decimal). +However, the NUL character cannot be encoded in this manner; +.Qq \e Ns 0 , +.Qq \e Ns 00 , +and +.Qq \e Ns 000 +are converted to the strings +.Qq 0 , +.Qq 00 , +and +.Qq 000 +respectively. +Similarly, all other escaped characters have the +leading backslash removed (e.g., +.Qq \e Ns a +becomes +.Qq a , +and +.Qq \e\e +becomes +.Qq \e ) . +The following four strings are equivalent: .Bd -literal "this string contains a newline\\n followed by one space." "this string contains a newline\\n \\ @@ -119,12 +172,13 @@ leading backslash removed (e.g., "\\a" becomes "a", and "\\\\" becomes "this string contains a newline\\012\\040followed by one space." .Ed .Sh 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. - +In general, anywhere a quoted string literal is allowed, a +.Sq 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. .Bd -literal <StrEx>:: <StrEx> "." <StrEx> /* String concatenation */ | <StringLiteral> /* Quoted string */ @@ -132,8 +186,12 @@ parenthesized. | <DerefAttribute> | "$" <StrEx> ; .Ed - -The "$" operator has higher precedence than the "." operator. +.Pp +The +.Qq $ +operator has higher precedence than the +.Qq . +operator. .Sh DEREFERENCED ATTRIBUTES Action attributes provide the primary mechanism for applications to pass information to assertions. Attribute names are strings from a @@ -144,16 +202,27 @@ anywhere a string literal is permitted. .Pp 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 +numbers with the type conversion operators +.Qq \@ +and +.Qq \& . +Thus, an attribute named +.Qq foo +having the value +.Qq 1.2 +may be interpreted as the string +.Qq 1.2 +(foo), the integer value 1 (@foo), or the floating point value 1.2 (&foo). .Pp 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. +represented according to the ANSI C +.Sq long +and +.Sq float +types, respectively. +In particular, integers range from -2147483648 to 2147483647, whilst floats +range from 1.17549435E-38F to 3.40282347E+38F. .Pp Any uninitialized attribute has the empty-string value when dereferenced as a string and the value zero when dereferenced as an @@ -162,14 +231,30 @@ 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: - +quotes; e.g., the string value of the attribute named +.Qq foo +is by reference to +.Sq foo +(outside of quotes). +The +.Qo $ Ns Ao StrEx +.Ac +.Qc +construct dereferences the attribute named in the string expression +.Aq StrEx . +For example, if the attribute named +.Qq foo +contains the string +.Qq bar , +the attribute named +.Qq bar +contains the string +.Qq xyz , +and the attribute +.Qq xyz +contains the string +.Qq qua , +the following string comparisons are all true: .Bd -literal foo == "bar" $("foo") == "bar" @@ -177,12 +262,15 @@ all true: $(foo) == "xyz" $$foo == "qua" .Ed - -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). .Pp -The <DerefAttribute> token is defined as: +If +.Aq 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). +.Pp +The +.Aq DerefAttribute +token is defined as: .Bd -literal <DerefAttribute>:: <AttributeID> ; <AttributeID>:: {Any string starting with a-z, A-Z, or the @@ -190,56 +278,67 @@ The <DerefAttribute> token is defined as: a-z, A-Z, 0-9, or underscore characters} ; .Ed .Sh PRINCIPAL IDENTIFIERS -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. - +Principals are represented as ASCII strings called +.Sq 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. .Bd -literal <PrincipalIdentifier>:: <OpaqueID> | <KeyID> ; .Ed .Sh OPAQUE PRINCIPAL IDENTIFIERS 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): - +said to be +.Sq opaque . +Opaque identifiers are encoded in assertions as strings (as defined above): .Bd -literal <OpaqueID>:: <StrEx> ; .Ed - -Opaque identifier strings should not contain the ":" character. +.Pp +Opaque identifier strings should not contain the +.Qq \: +character. .Sh CRYPTOGRAPHIC PRINCIPAL IDENTIFIERS Principal Identifiers that are used by KeyNote as keys, e.g., to -verify credential signatures, are said to be `cryptographic'. +verify credential signatures, are said to be +.Sq cryptographic . Cryptographic identifiers are also lexically encoded as strings: - .Bd -literal <KeyID>:: <StrEx> ; .Ed - +.Pp 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: - .Bd -literal <IDString>:: <ALGORITHM>":"<ENCODEDBITS> ; .Ed - -"ALGORITHM" is an ASCII substring that describes the algorithms to be +.Pp +.Qq 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][a- -zA-Z0-9_-]*"). The IANA (or some other appropriate authority) will -provide a registry of reserved algorithm identifiers. -.Pp -"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. +major cryptographic algorithm (e.g., RSA +.Bq RSA78 , +DSA +.Bq DSA94 , +etc.), +structured format (e.g., PKCS1 +.Bq 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 +.Qo Ns Bo a-zA-Z +.Bc Ns Bo a-zA-Z0-9_- +.Bc Ns * +.Qc Ns ) . +The IANA (or some other appropriate authority) will provide a registry of +reserved algorithm identifiers. +.Pp +.Qq 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. .Pp Cryptographic Principal Identifiers are converted to a normalized canonical form for the purposes of any internal comparisons between @@ -248,62 +347,68 @@ them; see RFC 2704 for more details. 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: - .Bd -literal <VersionField>:: "KeyNote-Version:" <VersionString> ; <VersionString>:: <StringLiteral> | <IntegerLiteral> ; .Ed - -<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 +.Pp +.Aq 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 +.Qq 2 +(or the integer 2). The KeyNote-Version field, if included, should appear first. .Sh LOCAL-CONSTANTS FIELD 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: - +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: .Bd -literal <LocalConstantsField>:: "Local-Constants:" <Assignments> ; <Assignments>:: /* can be empty */ | <AttributeID> "=" <StringLiteral> <Assignments> ; .Ed - -<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. -.Pp -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. +.Pp +.Aq 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. +.Aq 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. +.Pp +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. .Sh AUTHORIZER FIELD -The Authorizer identifies the Principal issuing the assertion. This -field is of the form: - +The Authorizer identifies the Principal issuing the assertion. +This field is of the form: .Bd -literal <AuthField>:: "Authorizer:" <AuthID> ; <AuthID>:: <PrincipalIdentifier> | <DerefAttribute> ; .Ed - +.Pp The Principal Identifier may be given directly or by reference to the attribute namespace. .Sh LICENSEES FIELD 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: - +assertion. +More than one principal can be authorized, and authorization can be +distributed across several principals through the use of +.Sq and +and threshold constructs. +This field is of the form: .Bd -literal <LicenseesField>:: "Licensees:" <LicenseesExpr> ; @@ -323,17 +428,26 @@ use of `and' and threshold constructs. This field is of the form: <K>:: {Decimal number starting with a digit from 1 to 9} ; .Ed - -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. +.Pp +The +.Qq && +operator has higher precedence than the +.Qq || +operator. +.Aq K +is an ASCII-encoded positive decimal integer. +If a +.Aq PrincList +contains fewer than +.Aq K +principals, the entire assertion is omitted from processing. .Sh CONDITIONS FIELD -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: - +This field gives the +.Sq conditions +under which the Authorizer trusts the Licensees to perform an action. +.Sq Conditions +are predicates that operate on the action attribute set. +The Conditions field is of the form: .Bd -literal <ConditionsField>:: "Conditions:" <ConditionsProgram> ; @@ -405,9 +519,8 @@ form: <StringLiteral> is a quoted string as defined in previously <AttributeID> is defined previously. .Ed - +.Pp The operation precedence classes are (from highest to lowest): - .Bd -literal { (, ) } {unary -, @, &, $} @@ -415,7 +528,7 @@ The operation precedence classes are (from highest to lowest): {*, /, %} {+, -, .} .Ed - +.Pp Operators in the same precedence class are evaluated left-to-right. .Pp Note the inability to test for floating point equality, as most @@ -425,56 +538,72 @@ 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. .Pp -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). +The keywords +.Qq true +and +.Qq 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). .Pp -<RegExpr> is a standard regular expression, conforming to the POSIX -1003.2 regular expression syntax and semantics (see +.Aq RegExpr +is a standard regular expression, conforming to the +.St -p1003.2 +regular expression syntax and semantics (see .Xr regex 3 ) . .Pp 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. +float with the use of the +.Qq \@ +and +.Qq \& +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. .Sh COMMENT FIELD The Comment field allows assertions to be annotated with information describing their purpose. It is of the form: - .Bd -literal <CommentField>:: "Comment:" <text> ; .Ed - +.Pp No interpretation of the contents of this field is performed by -KeyNote. Note that this is one of two mechanisms for including +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). +in an assertion's body by preceding them with the +.Qq \# +character (except inside string literals). .Sh 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: - +Authorizer field. +The Signature field is of the form: .Bd -literal <SignatureField>:: "Signature:" <Signature> ; <Signature>:: <StrEx> ; .Ed - +.Pp The <Signature> string should be of the form: - .Bd -literal <IDString>:: <ALGORITHM>":"<ENCODEDBITS> ; .Ed - -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. +.Pp +The formats of the +.Qq ALGORITHM +and +.Qq 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. .Pp If the signature field is included, the principal named in the Authorizer field must be a Cryptographic Principal Identifier, the @@ -483,11 +612,11 @@ signature must be correct for the assertion body and authorizer key. .Pp 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. +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. .Sh EXAMPLES Note that the keys and signatures in these examples are fictional, and generally much shorter than would be required for real security, in @@ -533,21 +662,35 @@ the interest of readability. .Xr keynote 1 , .Xr keynote 3 , .Xr keynote 4 -.Bl -tag -width "AAAAAAA" -.It ``The KeyNote Trust-Management System, Version 2'' -M. Blaze, J. Feigenbaum, A. D. Keromytis, -Internet Drafts, RFC 2704. -.It ``Decentralized Trust Management'' -M. Blaze, J. Feigenbaum, J. Lacy, -1996 IEEE Conference on Privacy and Security -.It ``Compliance-Checking in the PolicyMaker Trust Management System'' -M. Blaze, J. Feigenbaum, M. Strauss, -1998 Financial Crypto Conference -.El +.Rs +.%A M. Blaze +.%A J. Feigenbaum +.%A A. D. Keromytis +.%T "The KeyNote Trust-Management System, Version 2" +.%N RFC 2704 +.%D 1999 +.Re +.Rs +.%A M. Blaze +.%A J. Feigenbaum +.%A J. Lacy +.%T Decentralized Trust Management +.%J IEEE Conference on Privacy and Security +.%D 1996 +.Re +.Rs +.%A M. Blaze +.%A J. Feigenbaum +.%A M. Strauss +.%T Compliance-Checking in the PolicyMaker Trust Management System +.%J Financial Crypto Conference +.%D 1998 +.Re .Sh AUTHORS -Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) +Angelos D. Keromytis +.Aq angelos@dsl.cis.upenn.edu .Sh WEB PAGE -http://www.cis.upenn.edu/~keynote +.Pa http://www.cis.upenn.edu/~keynote .Sh BUGS None that we know of. If you find any, please report them at |