From 6605bb6a0a915927a1fc20c09d8cee003a851c3c Mon Sep 17 00:00:00 2001 From: John Kohl Date: Mon, 4 Jun 1990 13:59:53 +0000 Subject: [PATCH] add function stuff from libkdb.spec git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@991 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/implement/kdb-i.tex | 229 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) diff --git a/doc/implement/kdb-i.tex b/doc/implement/kdb-i.tex index 1dd7f3ea5..9583f5a12 100644 --- a/doc/implement/kdb-i.tex +++ b/doc/implement/kdb-i.tex @@ -1,3 +1,232 @@ The \libname{libkdb.a} library provides a principal database interface to be used by the Key Distribution center and other database manipulation tools. + + +\begin{funcdecl}{krb5_db_set_name}{krb5_error_code}{\funcin} +\funcarg{char *}{name} +\end{funcdecl} + +Set the name of the database to \funcparam{name}. If it doesn't exist, +an error code is returned. + +Must be called before \funcname{krb5_db_init} or after +\funcname{krb5_db_fini}; must not be called while db functions are active. + +\begin{funcdecl}{krb5_db_set_nonblocking}{krb5_error_code}{\funcin} +\funcarg{krb5_boolean}{newmode} +\funcout +\funcarg{krb5_boolean *}{oldmode} +\end{funcdecl} + +Changes the locking mode of the database functions, returning the previous +mode in \funcparam{*oldmode}. + +If \funcparam{newmode} is TRUE, then the database is put into +non-blocking mode, which may result in "database busy" error codes from +the get, put, and iterate routines. + +If \funcparam{newmode} is FALSE, then the database is put into blocking mode, +which may result in delays from the get, put and iterate routines. + +The default database mode is blocking mode. + +\begin{funcdecl}{krb5_db_init}{krb5_error_code}{\funcvoid} +\end{funcdecl} + +Called before using \funcname{krb5_db_get_principal}, +\funcname{krb5_db_put_principal}, \funcname{krb5_db_iterate}, and +\funcname{krb5_db_set_nonblocking}. + +Does any required initialization. + +Errors: init errors, system errors. + +\begin{funcdecl}{krb5_db_fini}{krb5_error_code}{\funcvoid} +\end{funcdecl} + +Called after all database operations are complete, to perform any required +clean-up. + +Errors: sysytem errors. + + +\begin{funcdecl}{krb5_db_get_age}{krb5_error_code}{\funcin} +\funcarg{char *}{db_name} +\funcout +\funcarg{time_t *}{age} +\end{funcdecl} + +Retrieves the age of the database \funcname{db_name} (or the current +default database if \funcname{db_name} is NULL). + +\funcparam{*age} is filled in in local system time units, and represents +the last modification time of the database. + +Errors: system errors. + + +\begin{funcdecl}{krb5_db_create}{krb5_error_code}{\funcin} +\funcarg{char *}{db_name} +\end{funcdecl} + +Creates a new database named \funcname{db_name}. Will not create a +database by that name if it already exists. The database must be +populated by the caller by using \funcname{krb5_db_put_principal}. + +Errors: db exists, system errors. + +\begin{funcdecl}{krb5_db_rename}{krb5_error_code}{\funcin} +\funcarg{char *}{source} +\funcarg{char *}{dest} +\end{funcdecl} +Renames the database \funcarg{source} to \funcarg{dest} + +Any database named \funcarg{dest} is destroyed. + +Errors: system errors. + +\begin{funcdecl}{krb5_db_get_principal}{krb5_error_code}{\funcin} +\funcarg{krb5_principal}{searchfor} +\funcout +\funcarg{krb5_db_entry *}{entries} +\funcinout +\funcarg{int *}{nentries} +\funcout +\funcarg{krb5_boolean *}{more} +\end{funcdecl} + +Retrieves the principal records named by \funcparam{searchfor}. + +\funcparam{entries} must point to an array of \funcparam{*nentries} +krb5_db_entry structures. +At most \funcparam{*nentries} structures are filled in, and +\funcparam{*nentries} is modified to reflect the number actually returned. + +\funcparam{*nentries} must be at least one (1) when this function is called. + +\funcparam{*more} is set to TRUE if there are more records that wouldn't fit +in the available space, and FALSE otherwise. + +The principal structures filled in have pointers to allocated storage; +\funcname{krb5_db_free_principal} should be called with +\funcparam{entries} and \funcparam{*nentries} +in order to free this storage when no longer needed. + + +\begin{funcdecl}{krb5_db_free_principal}{void}{\funcin} +\funcarg{krb5_db_entry *}{entries} +\funcarg{int}{nentries} +\end{funcdecl} + +Frees allocated storage held by \funcparam{entries} as filled in by +\funcname{krb5_db_get_principal}. + + +\begin{funcdecl}{krb5_db_put_principal}{krb5_error_code}{\funcin} +\funcarg{krb5_db_entry *}{entries} +\funcarg{int *}{nentries} +\end{funcdecl} + +Stores the \funcparam{*nentries} principal structures pointed to by +\funcparam{entries} in the database. + +\funcparam{*nentries} is updated upon return to reflect the number of records +acutally stored; the first \funcparam{*nentries} records will have been +stored in the database. + +Returns error code if not all entries were stored. + +\begin{funcdecl}{krb5_db_iterate}{krb5_error_code}{\funcin} +\funcfuncarg{krb5_error_code}{(*func)} +\funcarg{krb5_pointer}{} +\funcarg{krb5_db_entry *}{} +\funcendfuncarg +\funcarg{krb5_pointer}{iterate_arg} +\end{funcdecl} + +Iterates over the database, fetching every entry in an unspecified order +and calling \funcparam{(*func)}(\funcparam{iterate_arg}, +{\sl principal}) where {\sl principal} points to a record from the database. + +If \funcparam{(*func)}() ever returns an error code, the iteration is +aborted and that error code is returned by this function. + +\begin{funcdecl}{krb5_db_store_mkey}{krb5_error_code}{\funcin} +\funcarg{char *}{keyfile} +\funcarg{krb5_principal}{mname} +\funcarg{krb5_keyblock *}{key} +\end{funcdecl} + +Put the KDC database master key into the file \funcparam{keyfile}. If +\funcparam{keyfile} is NULL, then a default file name derived from the +principal name \funcparam{mname} is used. + +\begin{funcdecl}{krb5_db_fetch_mkey}{krb5_error_code}{\funcin} +\funcarg{krb5_principal}{mname} +\funcarg{krb5_encrypt_block *}{eblock} +\funcarg{krb5_boolean}{fromkeyboard} +\funcarg{krb5_boolean}{twice} +\funcinout +\funcarg{krb5_keyblock *}{key} +\end{funcdecl} + +Get the KDC database master key from somewhere, filling it into +\funcparam{*key}. +\funcparam{key{\ptsto}keytype} should be set to the desired key type. +If \funcparam{fromkeyboard} is TRUE, then the master key is read as a password +from the user's terminal. In this case, +\funcparam{eblock} should point to a block with an appropriate +\funcname{string_to_key} function. +If \funcparam{twice} is TRUE, the password is read twice for verification. + +If \funcparam{fromkeyboard} is false, then the key is read from +a file whose name is derived from the principal name \funcparam{mname}. + +\funcparam{mname} is the name of the key sought; this is often used by +\funcname{string_to_key} to aid in conversion of the password to a key. + +\begin{funcdecl}{krb5_kdb_encrypt_key}{krb5_error_code}{\funcin} +\funcarg{krb5_encrypt_block *}{eblock} +\funcarg{krb5_keyblock *}{in} +\funcinout +\funcarg{krb5_keyblock *}{out} +\end{funcdecl} + +Encrypt a key for storage in the database. \funcparam{eblock} is used +to encrypt the key in \funcparam{in} into \funcparam{out}; the storage +pointed to by \funcparam{*out} is allocated before use and should be +freed when the caller is finished with it. + +\begin{funcdecl}{krb5_kdb_decrypt_key}{krb5_error_code}{\funcin} +\funcarg{krb5_encrypt_block *}{eblock} +\funcarg{krb5_keyblock *}{in} +\funcinout +\funcarg{krb5_keyblock *}{out} +\end{funcdecl} + +Decrypt a key from storage in the database. \funcparam{eblock} is used +to decrypt the key in \funcparam{in} into \funcparam{out}; the storage +pointed to by \funcparam{*out} is allocated before use and should be +freed when the caller is finished with it. + +\begin{funcdecl}{krb5_db_setup_mkey_name}{krb5_error_code}{\funcin} +\funcarg{const}{char *keyname} +\funcarg{const}{char *realm} +\funcout +\funcarg{char **}{fullname} +\funcarg{krb5_principal *}{principal} +\end{funcdecl} + +Given a key name \funcparam{keyname} and a realm name \funcparam{realm}, +construct a principal which can be used to fetch the master key from the +database. This principal is filled into \funcparam{*principal}; +\funcparam{*principal} should be freed by \funcname{krb5_free_principal} +when the caller is finished. + +If \funcparam{keyname} is NULL, the default key name will be used. + +If \funcparam{fullname} is not NULL, it is set to point to a string +representation of the complete principal name; its storage may be freed +by calling \funcname{free} on \funcparam{*fullname}. + -- 2.26.2