1.\" $OpenBSD: keynote.3,v 1.31 2001/09/03 20:14:51 deraadt Exp $ 2.\" 3.\" The author of this code is Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) 4.\" 5.\" This code was written by Angelos D. Keromytis in Philadelphia, PA, USA, 6.\" in April-May 1998 7.\" 8.\" Copyright (C) 1998, 1999 by Angelos D. Keromytis. 9.\" 10.\" Permission to use, copy, and modify this software with or without fee 11.\" is hereby granted, provided that this entire notice is included in 12.\" all copies of any software which is or includes a copy or 13.\" modification of this software. 14.\" You may use this code under the GNU public license if you so wish. Please 15.\" contribute changes back to the author. 16.\" 17.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR 18.\" IMPLIED WARRANTY. IN PARTICULAR, THE AUTHORS MAKES NO 19.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE 20.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR 21.\" PURPOSE. 22.\" 23.Dd April 29, 1999 24.Dt KEYNOTE 3 25.\" .TH KeyNote 3 local 26.Os 27.Sh NAME 28.Nm keynote 29.Nd a trust-management system library 30.Sh SYNOPSIS 31.Fd #include <sys/types.h> 32.Fd #include <regex.h> 33.Fd #include <keynote.h> 34.Pp 35.Bd -literal 36struct environment { 37 char *env_name; 38 char *env_value; 39 int env_flags; 40 regex_t env_regex; 41 struct environment *env_next; 42}; 43 44struct keynote_deckey { 45 int dec_algorithm; 46 void *dec_key; 47}; 48 49struct keynote_binary { 50 int bn_len; 51 char *bn_key; 52}; 53 54struct keynote_keylist { 55 int key_alg; 56 void *key_key; 57 char *key_stringkey; 58 struct keynote_keylist *key_next; 59}; 60.Ed 61.Vt extern int keynote_errno; 62.Ft int 63.Fn kn_init "void" 64.Ft int 65.Fn kn_add_assertion "int sessid" "char *assertion" "int len" "int flags" 66.Ft int 67.Fn kn_remove_assertion "int sessid" "int assertid" 68.Ft int 69.Fn kn_add_action "int sessid" "char *name" "char *value" "int flags" 70.Ft int 71.Fn kn_remove_action "int sessid" "char *name" 72.Ft int 73.Fn kn_add_authorizer "int sessid" "char *principal" 74.Ft int 75.Fn kn_remove_authorizer "int sessid" "char *principal" 76.Ft int 77.Fn kn_do_query "int sessid" "char **returnvalues" "int numvalues" 78.Ft int 79.Fn kn_get_failed "int sessid" "int type" "int seq" 80.Ft int 81.Fn kn_cleanup_action_environment "int sessid" 82.Ft int 83.Fn kn_close "int sessid" 84.Ft int 85.Fn kn_query "struct environment *env" "char **returnvalues, int numvalues" "char **trusted, int *trustedlen, int numtrusted" "char **untrusted, int *untrustedlen, int numuntrusted" "char **authorizers, int numauthauthorizers" 86.Ft char ** 87.Fn kn_read_asserts "char *array" "int arraylen" "int *numassertions" 88.Ft int 89.Fn kn_keycompare "void *key1" "void *key2" "int algorithm" 90.Ft void * 91.Fn kn_get_authorizer "int sessid" "int assertid" "int *algorithm" 92.Ft struct keynote_keylist * 93.Fn kn_get_licensees "int sessid" "int assertid" 94.Ft int 95.Fn kn_encode_base64 "unsigned char const *src" "unsigned int srclen" "char *dst" "unsigned int dstlen" 96.Ft int 97.Fn kn_decode_base64 "char const *src" "unsigned char *dst" "unsigned int dstlen" 98.Ft int 99.Fn kn_encode_hex "unsigned char *src" "char **dst" "int srclen" 100.Ft int 101.Fn kn_decode_hex "char *src" "char **dst" 102.Ft char * 103.Fn kn_encode_key "struct keynote_deckey *dc" "int iencoding" "int encoding" "int keytype" 104.Ft int 105.Fn kn_decode_key "struct keynote_deckey *dc" "char *key" "int keytype" 106.Ft char * 107.Fn kn_sign_assertion "char *assertion" "int len" "char *key" "char *algorithm" "int vflag" 108.Ft int 109.Fn kn_verify_assertion "char *assertion" "int len" 110.Ft void 111.Fn kn_free_key "struct keynote_deckey *" 112.Ft char * 113.Fn kn_get_string "char *" 114.Fd Link options: -lkeynote -lm -lcrypto 115.Sh DESCRIPTION 116For more details on 117.Nm keynote , 118see RFC 2704. 119.Pp 120.Va keynote_errno 121contains an error code if some library call failed. 122Failed calls return \-1 (if their return value is integer), or 123.Dv NULL 124(if their return value is a pointer) and set 125.Va keynote_errno . 126The defined error codes are: 127.Bl -tag -width "ERROR_NOTFOUND" -offset indent 128.It Li ERROR_MEMORY 129Some memory allocation or usage error was encountered. 130.It Li ERROR_SYNTAX 131Some syntactic or logical error was encountered. 132.It Li ERROR_NOTFOUND 133One of the arguments referred to a nonexistent structure or entry. 134.El 135.Pp 136If no errors were encountered, 137.Va keynote_errno 138will be set to 0. 139This variable should be reset to 0 if an error was encountered, 140prior to calling other library routines. 141.Pp 142The main interface to 143.Nm 144is centered around the concept of a session. 145A session describes a collection of policies, assertions, action 146authorizers, return values, and action attributes that the 147.Nm 148system uses to evaluate a query. 149Information is not shared between sessions. 150Policies, credentials, action authorizers, and action 151attributes can be added or deleted at any point during the lifetime of 152a session. 153Furthermore, an application can discover which assertions failed to be 154evaluated, and in what way, during a query. 155.Pp 156For those applications that only need to do a simple query, there 157exists a single call that takes as arguments all the necessary 158information and performs all the necessary steps. 159This is essentially a wrapper that calls the session API functions as 160necessary. 161.Pp 162Finally, there exist functions for doing ASCII to hexadecimal and 163Base64 encoding (and vice versa), for encoding/decoding keys between 164ASCII and binary formats, and for signing and verifying assertions. 165.Pp 166The description of all 167.Nm 168library functions follows. 169.Pp 170.Fn kn_init 171creates a new 172.Nm 173session, and performs any necessary initializations. 174On success, this function returns the new session ID, which is used by 175all subsequent calls with a 176.Fa sessid 177argument. 178On failure, it returns \-1 and sets 179.Va keynote_errno 180to 181.Er ERROR_MEMORY . 182.Pp 183.Fn kn_add_assertion 184adds the assertion pointed to by the array 185.Fa assertion , 186of length 187.Fa len 188in the session identified by 189.Fa sessid . 190The first argument can be discarded after the call to this function. 191The following flags are defined: 192.Bl -tag -width ASSERT_FLAG_LOCAL -offset indent 193.It ASSERT_FLAG_LOCAL 194Mark this assertion as ultimately trusted. 195Trusted assertions need not be signed, and the 196.Fa Authorizer 197and 198.Fa Licensees 199fields can have non-key entries. 200.El 201.Pp 202At least one (trusted) assertion should have 203.Dv POLICY 204as the 205.Fa Authorizer . 206On success, this function will return an assertion ID which can be 207used to remove the assertion from the session, by using 208.Xr kn_remove_assertion 3 . 209On failure, \-1 is returned, and 210.Va keynote_errno 211is set to 212.Er ERROR_NOTFOUND 213if the session was not found, 214.Er ERROR_SYNTAX 215if the assertion was syntactically incorrect, or 216.Er ERROR_MEMORY 217if necessary memory could not be allocated. 218.Pp 219.Fn kn_remove_assertion 220removes the assertion identified by 221.Fa assertid 222from the session identified by 223.Fa sessid . 224On success, this function returns 0. 225On failure, it returns \-1 and sets 226.Va keynote_errno 227to 228.Er ERROR_NOTFOUND . 229.Pp 230.Fn kn_add_action 231inserts the variable 232.Fa name 233in the action environment of session 234.Fa sessid , 235with the value 236.Fa value . 237The same attribute may be added more than once, but only the last 238instance will be used (memory resources are consumed however). 239.Pp 240The 241.Fa flags 242specified are formed by or'ing the following values: 243.Bl -tag -width ENVIRONMENT_FLAG_REGEX -offset indent 244.It ENVIRONMENT_FLAG_FUNC 245In this case, 246.Fa value 247is a pointer to a function that takes as argument a string and returns 248a string. 249This is used to implement callbacks for getting action attribute values. 250The argument passed to such a callback function is a string identifying 251the action attribute whose value is requested, and should return a pointer 252to string containing that value (this pointer will not be freed by the 253library), the empty string if the value was not found, or a 254.Dv NULL 255to indicate an error (and may set 256.Va keynote_errno 257appropriately). 258Prior to first use (currently, at the time the attribute is added to the 259session environment), such functions are called with 260.Dv KEYNOTE_CALLBACK_INITIALIZE 261as the argument (defined in keynote.h) so that they can perform any special 262initializations. 263Furthermore, when the session is deleted, all such functions will be called 264with 265.Dv KEYNOTE_CALLBACK_CLEANUP 266to perform any special cleanup (such as free any allocated memory). 267A function may be called with either of these arguments more than once, 268if it has been defined as the callback function for more than one attribute. 269.It ENVIRONMENT_FLAG_REGEX 270In this case, 271.Fa name 272is a regular expression that may match more than one attribute. 273In case of conflict between a regular expression and a 274.Dq simple 275attribute, the latter will be given priority. 276In case of conflict between two regular expression attributes, the one added 277later will be given priority. 278A callback function should never change the current 279.Nm 280session, start/invoke/operate on another session, or call one of the 281session-API functions. 282.El 283.Pp 284The combination of the two flags may be used to specify callback 285functions that handle large sets of attributes (even to the extent of 286having one callback function handling all attribute references). 287This is particularly useful when the action attribute set is particularly 288large. 289.Pp 290On success, 291.Xr kn_add_action 3 292returns 0. On failure, it returns \-1 and sets 293.Va keynote_errno 294to 295.Er ERROR_NOTFOUND 296if the session was not found, 297.Er ERROR_SYNTAX 298if the 299.Fa name 300was invalid (e.g., started with an underscore character) or was 301.Dv NULL , 302or 303.Er ERROR_MEMORY 304if necessary memory could not be allocated. 305.Pp 306.Fn kn_remove_action 307removes action attribute 308.Fa name 309from the environment of session 310.Fa sessid . 311Notice that if more than one instances of 312.Fa name 313exist, only the one added last will be deleted. 314On success, this function returns 0. 315On failure, it returns \-1 and 316.Va keynote_errno 317is set to 318.Er ERROR_NOTFOUND 319if the session or the attribute were not found, or 320.Er ERROR_SYNTAX 321if the name was invalid. 322If the attribute value was a callback, that function will be called with 323the define 324.Dv KEYNOTE_CALLBACK_CLEANUP 325as the argument. 326.Pp 327.Fn kn_add_authorizer 328adds the principal pointed to by 329.Fa principal 330to the action authorizers list of session 331.Fa sessid . 332The principal is typically an ASCII-encoded key. 333On success, this function will return 0. 334On failure, it returns \-1 and sets 335.Va keynote_errno 336to 337.Er ERROR_NOTFOUND 338if the session was not found, 339.Er ERROR_SYNTAX 340if the encoding was invalid, or 341.Er ERROR_MEMORY 342if necessary memory could not be allocated. 343.Pp 344.Fn kn_remove_authorizer 345removes 346.Fa principal 347from the action authorizer list of session 348.Fa sessid . 349On success, this function returns 0. 350On failure, it returns \-1 and sets 351.Va keynote_errno 352to 353.Er ERROR_NOTFOUND 354if the session was not found. 355.Pp 356.Fn kn_do_query 357evaluates the request based on the assertions, action attributes, and 358action authorizers added to session 359.Fa sessid . 360.Fa returnvalues 361is an ordered array of strings that contain the return values. 362The lowest-ordered return value is contained in 363.Fa returnvalues[0] , 364and the highest-ordered value is 365.Fa returnvalues[numvalues - 1] . 366If 367.Fa returnvalues 368is 369.Dv NULL , 370the 371.Fa returnvalues 372from the previous call to 373.Xr kn_do_query 3 374will be used. 375The programmer SHOULD NOT free 376.Fa returnvalues 377after the call to 378.Xr kn_do_query 3 379if this feature is used, as the array is not replicated internally. 380On success, this function returns an index into the 381.Fa returnvalues 382array. 383On failure, it returns \-1 and sets 384.Va keynote_errno 385to 386.Er ERROR_NOTFOUND 387if the session was not found or the authorizers list was empty, 388.Er ERROR_SYNTAX 389if no 390.Fa returnvalues 391have been specified, or 392.Er ERROR_MEMORY 393if necessary memory could not be allocated. 394.Pp 395.Fn kn_get_failed 396returns the assertion ID of the 397.Fa num'th 398assertion (starting from zero) in session 399.Fa sessid 400that was somehow invalid during evaluation. 401This function is typically called after 402.Xr kn_do_query 3 403is used to evaluate a request. 404.Fa type 405specifies the type of failure the application is interested in. 406It can be set to: 407.Bl -tag -width KEYNOTE_ERROR_SIGNATURE -offset indent 408.It KEYNOTE_ERROR_ANY 409to indicate interest in any error. 410.It KEYNOTE_ERROR_SYNTAX 411for syntactic or semantic errors. 412.It KEYNOTE_ERROR_MEMORY 413for memory-related problems. 414.It KEYNOTE_ERROR_SIGNATURE 415if the assertion could not be cryptographically verified. 416.El 417.Pp 418These values are defined in keynote.h. 419An application can then delete the offending assertion using 420.Xr kn_remove_assertion 3 . 421For example, to remove all assertion whose signature failed, an application 422could do something like: 423.Bd -literal 424 while ((assertid = kn_get_failed(sessid, KEYNOTE_ERROR_SIGNATURE, 0) 425 != -1) 426 kn_remove_assertion(sessid, assertid); 427.Ed 428.Pp 429On success, 430.Xr kn_get_failed 3 431returns an assertion ID. 432On failure, or when no assertion matching the given criteria is found, 433it returns \-1 and set 434.Va keynote_errno 435to 436.Er ERROR_NOTFOUND . 437.Pp 438.Fn kn_cleanup_action_environment 439removes all action attributes from the action environment of session 440.Fa sessid . 441It returns 0 on success. 442.Pp 443.Fn kn_close 444closes session 445.Fa sessid 446and frees all related resources, deleting action attributes, action 447authorizers, and assertions. 448On success, this function returns 0. 449On failure, it returns \-1 and sets 450.Va keynote_errno 451to 452.Er ERROR_NOTFOUND 453if the session was not found. 454.Pp 455.Fn kn_read_asserts 456parses the string 457.Fa array 458of length 459.Fa arraylen 460and returns an array of pointers to strings containing copies of 461the assertions found in 462.Fa array . 463Both the array of pointers and the strings are allocated by 464.Fn kn_read_asserts 465dynamically, and thus should be freed by the programmer when they are 466no longer needed. 467.Fa numassertions 468contains the number of assertions (and thus strings in the returned 469array) found in 470.Fa array . 471On failure, this function returns 472.Dv NULL 473and sets 474.Va keynote_errno 475to 476.Er ERROR_MEMORY 477if necessary memory could not be allocated, or 478.Er ERROR_SYNTAX 479if 480.Fa array 481was 482.Dv NULL . 483Note that if there were no assertions found in 484.Fa array , 485a valid pointer will be returned, but 486.Fa numassertions 487will contain the value zero on return. 488The returned pointer should be freed by the programmer. 489.Pp 490.Fn kn_keycompare 491compares 492.Fa key1 493and 494.Fa key2 495(which must be of the same 496.Fa algorithm ) 497and returns 1 if equal and 0 otherwise. 498.Pp 499.Fn kn_get_authorizer 500returns the authorizer key (in binary format) for assertion 501.Fa assertid 502in session 503.Fa sessid . 504It also sets the 505.Fa algorithm 506argument to the algorithm of the authorizer key. 507On failure, 508.Fn kn_get_authorizer 509returns 510.Dv NULL , 511and sets 512.Va keynote_errno 513to 514.Er ERROR_NOTFOUND . 515.Pp 516.Fn kn_get_licensees 517returns the licensee key(s) for assertion 518.Fa assertid 519in session 520.Fa sessid . 521The keys are returned in a linked list of 522.Fa struct keynote_keylist 523structures. 524On failure, 525.Fn kn_get_licensees 526returns 527.Dv NULL . 528and sets 529.Va keynote_errno 530to 531.Er ERROR_NOTFOUND . 532.Pp 533.Fn kn_query 534takes as arguments a list of action attributes in 535.Fa env , 536a list of return values in 537.Fa returnvalues 538(the number of returnvalues in indicated by 539.Fa numvalues ) , 540a number 541.Pf ( Fa numtrusted ) 542of locally-trusted assertions in 543.Fa trusted 544(the length of each assertion is given by the respective element of 545.Fa trustedlen ) , 546a number 547.Pf ( Fa numuntrusted ) 548of assertions that need to be cryptographically verified in 549.Fa untrusted 550(the length of each assertion is given by the respective element of 551.Fa untrustedlen ) , 552and a number 553.Pf ( Fa numauthorizers ) 554of action authorizers in 555.Fa authorizers . 556.Fa env 557is a linked list of 558.Fa struct environment 559structures. The 560.Fa env_name , 561.Fa env_value , 562and 563.Fa env_flags 564fields correspond to the 565.Fa name , 566.Fa value , 567and 568.Fa flags 569arguments to 570.Xr kn_add_assertion 3 571respectively. 572.Fa env_regex 573is not used. 574On success, this function returns an index in 575.Fa returnvalues 576indicating the returned value to the query. 577On failure, it returns \-1 and sets 578.Va keynote_errno 579to the same values as 580.Xr kn_do_query 3 , 581or to 582.Er ERROR_MEMORY 583if a trusted or untrusted assertion could not be added to the session due 584to lack of memory resources. 585Syntax errors in assertions will not be reported by 586.Fn kn_query . 587.Pp 588.Fn kn_encode_base64 589converts the data of length 590.Fa srclen 591contained in 592.Fa src 593in Base64 encoding and stores them in 594.Fa dst 595which is of length 596.Fa dstlen . 597The actual length of the encoding stored in 598.Fa dst 599is returned. 600.Fa dst 601should be long enough to also contain the trailing 602string terminator. 603If 604.Fa srclen 605is not a multiple of 4, or 606.Fa dst 607is not long enough to contain the encoded data, this function returns 608\-1 and sets 609.Va keynote_errno 610to 611.Er ERROR_SYNTAX . 612.Pp 613.Fn kn_decode_base64 614decodes the Base64-encoded data stored in 615.Fa src 616and stores the result in 617.Fa dst , 618which is of length 619.Fa dstlen . 620The actual length of the decoded data is returned on success. 621On failure, this function returns \-1 and sets 622.Va keynote_errno 623to 624.Er ERROR_SYNTAX , 625denoting either an invalid Base64 encoding or insufficient space in 626.Fa dst . 627.Pp 628.Fn kn_encode_hex 629encodes in ASCII-hexadecimal format the data of length 630.Fa srclen 631contained in 632.Fa src . 633This function allocates a chunk of memory to store the result, which 634is returned in 635.Fa dst . 636Thus, this function should be used as follows: 637.Bd -literal 638 char *dst; 639 640 kn_encode_hex(src, &dst, srclen); 641.Ed 642.Pp 643The length of the allocated buffer will be (2 * srclen + 1). 644On success, this function returns 0. 645On failure, it returns \-1 and sets 646.Va keynote_errno 647to 648.Er ERROR_MEMORY 649if it failed to allocate enough memory, 650.Er ERROR_SYNTAX 651if 652.Fa dst 653was 654.Dv NULL . 655.Pp 656.Fn kn_decode_hex 657decodes the ASCII hex-encoded string in 658.Fa src 659and stores the result in a memory chunk allocated by the function. 660A pointer to that memory is stored in 661.Fa dst . 662The length of the allocated memory will be (strlen(src) / 2). 663On success, this function returns 0. 664On failure, it returns \-1 and sets 665.Va keynote_errno 666to 667.Er ERROR_MEMORY 668if it could not allocate enough memory, or 669.Er ERROR_SYNTAX 670if 671.Fa dst 672was 673.Dv NULL , 674or the length of 675.Fa src 676is not even. 677.Pp 678.Fn kn_encode_key 679ASCII-encodes a cryptographic key. 680The binary representation of the key is contained in 681.Fa dc . 682The field 683.Fa dec_key 684in that structure is a pointer to some cryptographic algorithm 685dependent information describing the key. 686In this implementation, this pointer should be a 687.Fa DSA * 688or 689.Fa RSA * 690for DSA or RSA keys respectively, as used in the SSL library, or a 691.Fa keynote_binary * 692for cryptographic keys whose algorithm 693.Nm 694does not know about but the application wishes to include in the 695action authorizers (and thus need to be canonicalized). 696The field 697.Fa dec_algorithm 698describes the cryptographic algorithm, and may be one of 699.Dv KEYNOTE_ALGORITHM_DSA , 700.Dv KEYNOTE_ALGORITHM_RSA , 701or 702.Dv KEYNOTE_ALGORITHM_BINARY 703in this implementation. 704.Pp 705.Fa iencoding 706describes how the key should be binary-encoded. 707This implementation supports 708.Dv INTERNAL_ENC_PKCS1 709for RSA keys, 710.Dv INTERNAL_ENC_ASN1 711for DSA keys, and 712.Dv INTERNAL_ENC_NONE 713for BINARY keys. 714.Fa encoding 715describes what ASCII encoding should be applied to the key. 716Valid values are 717.Dv ENCODING_HEX 718and 719.Dv ENCODING_BASE64 , 720for hexadecimal and Base64 encoding respectively. 721.Fa keytype 722is one of 723.Dv KEYNOTE_PUBLIC_KEY 724or 725.Dv KEYNOTE_PRIVATE_KEY 726to indicate whether the key is public or private. 727Private keys have the string 728.Dv KEYNOTE_PRIVATE_KEY_PREFIX 729(defined in keynote.h) prefixed to the algorithm name. 730On success, this function returns a string containing the encoded key. 731On failure, it returns 732.Dv NULL 733and sets 734.Va keynote_errno 735to 736.Er ERROR_NOTFOUND 737if the 738.Fa dc 739argument was invalid, 740.Er ERROR_MEMORY 741if it failed to allocate the necessary memory, or 742.Er ERROR_SYNTAX 743if the key to be converted was invalid. 744.Pp 745.Fn kn_decode_key 746decodes the ASCII-encoded string contained in 747.Fa key . 748The result is placed in 749.Fa dc , 750with 751.Fa dec_algorithm 752describing the algorithm (see 753.Xr kn_encode_key 3 ) , 754and 755.Fa dec_key 756pointing to an algorithm-dependent structure. 757In this implementation, this is an SSLeay/OpenSSL-defined 758.Fa DSA * 759for DSA keys, 760.Fa RSA * 761for RSA and X509-based keys, and a 762.Fa keynote_binary * 763for BINARY keys. 764.Fa keytype 765takes the values 766.Dv KEYNOTE_PUBLIC_KEY 767or 768.Dv KEYNOTE_PRIVATE_KEY 769to specify a public or private key, where applicable. 770On success, this function returns 0. 771On failure, it returns \-1 and sets 772.Va keynote_errno 773to 774.Er ERROR_MEMORY 775if necessary memory could not be allocated, or 776.Er ERROR_SYNTAX 777if the key or the ASCII encoding was malformed. 778.Pp 779.Fn kn_sign_assertion 780produces the cryptographic signature for the assertion of length 781.Fa len 782stored in 783.Fa assertion , 784using the ASCII-encoded cryptographic key contained in 785.Fa key . 786The type of signature to be produced is described by the string 787.Fa algorithm . 788Possible values for this string are 789.Dv SIG_RSA_SHA1_HEX , 790.Dv SIG_RSA_SHA1_BASE64 , 791.Dv SIG_RSA_MD5_HEX 792and 793.Dv SIG_RSA_MD5_HEX 794for RSA keys, 795.Dv SIG_DSA_SHA1_HEX 796and 797.Dv SIG_DSA_SHA1_BASE64 798for DSA keys, 799.Dv SIG_X509_SHA1_HEX 800and 801.Dv SIG_X509_SHA1_BASE64 802for X509-based keys. 803No other cryptographic signatures are currently 804supported by this implementation. 805If 806.Fa vflag 807is set to 1, then the generated signature will also be verified. 808On success, this function returns a string containing the ASCII-encoded 809signature, without modifying the 810.Fa assertion . 811On failure, it returns 812.Dv NULL 813and sets 814.Va keynote_errno 815to 816.Er ERROR_NOTFOUND 817if one of the arguments was 818.Dv NULL , 819.Er ERROR_MEMORY 820if necessary memory could not be allocated, or 821.Er ERROR_SYNTAX 822if the 823.Fa algorithm , 824the 825.Fa key , 826or the 827.Fa assertion 828(if signature verification was requested) was invalid. 829.Pp 830.Fn kn_verify_assertion 831verifies the cryptographic signature on the assertion of length 832.Fa len 833contained in string 834.Fa assertion . 835On success, this function returns 836.Dv SIGRESULT_TRUE 837if the signature could be verified, or 838.Dv SIGRESULT_FALSE 839otherwise. On failure, this function returns \-1 and sets 840.Va keynote_errno 841to 842.Er ERROR_MEMORY 843if necessary memory could not be allocated, or 844.Er ERROR_SYNTAX 845if the assertion contained a syntactic error, or the cryptographic 846algorithm was not supported. 847.Pp 848.Fn kn_free_key 849frees a cryptographic key. 850.Pp 851.Fn kn_get_string 852parses the argument, treating it as a 853.Xr keynote 4 854(quoted) string. 855This is useful for parsing key files. 856.Sh FILES 857.Bl -tag -width libkeynote.a -compact 858.It Pa keynote.h 859.It Pa libkeynote.a 860.El 861.Sh SEE ALSO 862.Xr keynote 1 , 863.Xr keynote 4 , 864.Xr keynote 5 865.Rs 866.%A M. Blaze 867.%A J. Feigenbaum 868.%A A. D. Keromytis 869.%T "The KeyNote Trust-Management System, Version 2" 870.%N RFC 2704 871.%D 1999 872.Re 873.Rs 874.%A M. Blaze 875.%A J. Feigenbaum 876.%A J. Lacy 877.%T Decentralized Trust Management 878.%J IEEE Conference on Privacy and Security 879.%D 1996 880.Re 881.Rs 882.%A M. Blaze 883.%A J. Feigenbaum 884.%A M. Strauss 885.%T Compliance-Checking in the PolicyMaker Trust Management System 886.%J Financial Crypto Conference 887.%D 1998 888.Re 889.Sh AUTHORS 890Angelos D. Keromytis 891.Aq angelos@dsl.cis.upenn.edu 892.Sh WEB PAGE 893.Pa http://www.cis.upenn.edu/~keynote 894.Sh DIAGNOSTICS 895The return values of all the functions have been given along with the 896function description above. 897.Sh BUGS 898None that we know of. 899If you find any, please report them to 900.Bd -literal -offset indent -compact 901keynote@research.att.com 902.Ed 903