next up previous contents
Next: Encryption system interface Up: Kerberos V5 Implementer's Guide Previous: Operating-system specific functions   Contents

Principal database functions

The 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 name.

Must be called before krb5_db_init or after 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 *oldmode.

If 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 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 krb5_db_get_principal, krb5_db_put_principal, krb5_db_iterate, and krb5_db_set_nonblocking.

Does any required initialization.


\begin{funcdecl}{krb5_db_fini}{krb5_error_code}{\funcvoid}
\end{funcdecl}

Called after all database operations are complete, to perform any required clean-up.


\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 db_name (or the current default database if db_name is NULL).

*age is filled in in local system time units, and represents the last modification time of the database.


\begin{funcdecl}{krb5_db_create}{krb5_error_code}{\funcin}
\funcarg{char *}{db_name}
\end{funcdecl}

Creates a new database named db_name. Will not create a database by that name if it already exists. The database must be populated by the caller by using krb5_db_put_principal.


\begin{funcdecl}{krb5_db_rename}{krb5_error_code}{\funcin}
\funcarg{char *}{source}
\funcarg{char *}{dest}
\end{funcdecl}
Renames the database source to dest

Any database named dest is destroyed.


\begin{funcdecl}{krb5_db_get_principal}{krb5_error_code}{\funcin}
\funcarg{krb5_...
...\funcarg{int *}{nentries}
\funcout
\funcarg{krb5_boolean *}{more}
\end{funcdecl}

Retrieves the principal records named by searchfor.

entries must point to an array of *nentries krb5_db_entry structures. At most *nentries structures are filled in, and *nentries is modified to reflect the number actually returned.

*nentries must be at least one (1) when this function is called.

*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; krb5_db_free_principal should be called with entries and *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 entries as filled in by 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 *nentries principal structures pointed to by entries in the database.

*nentries is updated upon return to reflect the number of records acutally stored; the first *nentries records will have been stored in the database.


\begin{funcdecl}{krb5_db_iterate}{krb5_error_code}{\funcin}
\funcfuncarg{krb5_er...
...db_entry *}{}
\funcendfuncarg
\funcarg{krb5_pointer}{iterate_arg}
\end{funcdecl}

Iterates over the database, fetching every entry in an unspecified order and calling (*func)(iterate_arg, principal) where principal points to a record from the database.

If (*func)() ever returns an error code, the iteration should be aborted and that error code is returned by this function.


\begin{funcdecl}{krb5_db_store_mkey}{krb5_error_code}{\funcin}
\funcarg{char *}{...
...e}
\funcarg{krb5_principal}{mname}
\funcarg{krb5_keyblock *}{key}
\end{funcdecl}

Put the KDC database master key into the file keyfile. If keyfile is NULL, then a default file name derived from the principal name mname is used.


\begin{funcdecl}{krb5_db_fetch_mkey}{krb5_error_code}{\funcin}
\funcarg{krb5_pri...
...ncarg{krb5_data }{salt}
\funcinout
\funcarg{krb5_keyblock *}{key}
\end{funcdecl}

Get the KDC database master key from somewhere, filling it into *key. keykeytype should be set to the desired key type.

If fromkeyboard is TRUE, then the master key is read as a password from the user's terminal. In this case: eblock should point to a block with an appropriate string_to_key function; if twice is TRUE, the password is read twice for verification; and if salt is non-NULL, it is used as the salt when converting the typed password to the master key.

If fromkeyboard is false, then the key is read from a file whose name is derived from the principal name mname. Therefore, eblock, twice and salt are ignored.

mname is the name of the key sought; this is often used by 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_e...
...yblock *}{in}
\funcinout
\funcarg{krb5_encrypted_keyblock *}{out}
\end{funcdecl}

Encrypt a key for storage in the database. eblock is used to encrypt the key in in into out; the storage pointed to by *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_e...
...crypted_keyblock *}{in}
\funcinout
\funcarg{krb5_keyblock *}{out}
\end{funcdecl}

Decrypt a key from storage in the database. eblock is used to decrypt the key in in into out; the storage pointed to by *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{con...
...\funcarg{char **}{fullname}
\funcarg{krb5_principal *}{principal}
\end{funcdecl}

Given a key name keyname and a realm name realm, construct a principal which can be used to fetch the master key from the database. This principal is filled into *principal; *principal should be freed by krb5_free_principal when the caller is finished.

If keyname is NULL, the default key name will be used.

If 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 free on *fullname.


next up previous contents
Next: Encryption system interface Up: Kerberos V5 Implementer's Guide Previous: Operating-system specific functions   Contents
Autobuild 2009-09-05