xref: /openbsd/lib/libkeynote/keynote.3 (revision 78b63d65)
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