.\" DO NOT MODIFY THIS FILE!  It was generated by gdoc.
.TH "shisa_keys_find" 3 "1.0.3" "shishi" "shishi"
.SH NAME
shisa_keys_find \- API function
.SH SYNOPSIS
.B #include <shisa.h>
.sp
.BI "int shisa_keys_find(Shisa * " dbh ", const char * " realm ", const char * " principal ", const Shisa_key * " hint ", Shisa_key *** " keys ", size_t * " nkeys ");"
.SH ARGUMENTS
.IP "Shisa * dbh" 12
Shisa library handle created by \fBshisa()\fP.
.IP "const char * realm" 12
Name of the realm the principal belongs to.
.IP "const char * principal" 12
Name of the principal whose keys are examined.
.IP "const Shisa_key * hint" 12
Pointer to a Shisa key structure with hints on matching
criteria for relevant keys.  \fBNULL\fP matches all keys.
.IP "Shisa_key *** keys" 12
Returned pointer to a newly allocated array of Shisa
key structures.
.IP "size_t * nkeys" 12
Pointer to an integer updated with the number of
allocated Shisa key structures in *\fIkeys\fP.
.SH "DESCRIPTION"
Iterates through the set of keys belonging to PRINCIPAL@REALM,
as selected by \fIprincipal\fP and \fIrealm\fP.  Then extracts any keys
that match the criteria in \fIhint\fP.

Not all elements of \fIhint\fP need to be filled in.  Set only
the fields you are interested in.  For example, if you want
to extract all keys of etype 3, i.e., DES\-CBC\-MD5, then set
the field \fIkey\fP\->etype to 3, and all other fields to zero.
.SH "RETURN VALUE"
Returns \fBSHISA_OK\fP if successful, or an error code.
.SH "REPORTING BUGS"
Report bugs to <bug-shishi@gnu.org>.
GNU Shishi home page: http://www.gnu.org/software/shishi/
General help using GNU software: http://www.gnu.org/gethelp/
.SH COPYRIGHT
Copyright \(co 2002-2022 Simon Josefsson.
.br
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.
.SH "SEE ALSO"
The full documentation for
.B shishi
is maintained as a Texinfo manual.  If the
.B info
and
.B shishi
programs are properly installed at your site, the command
.IP
.B info shishi
.PP
should give you access to the complete manual.