Next: Generic Security Service, Previous: Examples, Up: Programming Manual [Contents][Index]
Shisa is a separate and standalone library from Shishi (see Introduction to Shisa). If you only wish to manipulate the information stored in the Kerberos user database used by Shishi, you do not need to link or use the Shishi library at all. However, you may find it useful to combine the two libraries.
For two real world examples on using the Shisa library, refer to src/shisa.c (Shisa command line tool) and src/kdc.c (part of Shishid server).
Shisa uses two ‘struct’s to carry information. The first,
Shisa_principal, is used to hold information about principals.
The struct does not contain pointers to strings etc, so the library
assumes the caller is responsible for allocating and deallocating the
struct itself. Each such struct is (uniquely) identified by the
combination of principal name and realm name.
struct Shisa_principal
{
int isdisabled;
uint32_t kvno;
time_t notusedbefore;
time_t lastinitialtgt; /* time of last initial request for a TGT */
time_t lastinitialrequest; /* time of last initial request */
time_t lasttgt; /* time of issue for the newest TGT used */
time_t lastrenewal; /* time of the last renewal */
time_t passwordexpire; /* time when the password will expire */
time_t accountexpire; /* time when the account will expire. */
};
typedef struct Shisa_principal Shisa_principal;
The second structure is called Shisa_key and hold information
about cryptographic keys. Because the struct contain pointers, and
the caller cannot know how many keys a principal have, the Shisa
library manages memory for the struct. The library allocate the
structs, and the pointers within them. The caller may deallocate
them, but it is recommended to use shisa_key_free or
shisa_keys_free instead. Note that each principal may have
multiple keys.
struct Shisa_key
{
uint32_t kvno;
int32_t etype;
int priority;
char *key;
size_t keylen;
char *salt;
size_t saltlen;
char *str2keyparam;
size_t str2keyparamlen;
char *password;
};
typedef struct Shisa_key Shisa_key;
Shisa is typically initialized by calling shisa_init, and
deinitialized (when the application no longer need to use Shisa,
typically when it shuts down) by calling shisa_done, but here
are the complete (de)initialization interface functions.
Description: Initializes the Shisa library. If this function fails, it may print diagnostic errors to standard error.
Return value: Returns a Shisa library handle, or NULL on error.
dbh: Shisa handle as allocated by shisa().
Description: Deallocates the shisa library handle. The handle must not be used in calls to any shisa function after the completion of this call.
dbh: Returned pointer to a created Shisa library handle.
Description: Creates a Shisa library handle, using shisa(), reading the system
configuration file from its default location. The path to the
default system configuration file is decided at compile time
(sysconfdir/shisa.conf).
The handle is allocated regardless of return value, the only
exception being SHISA_INIT_ERROR, which indicates a problem
in allocating the handle. Other error conditions arise while
reading a file.
Return value: Returns SHISA_OK, or an error code. The value
SHISA_INIT_ERROR indicates a failure to create the handle.
dbh: Returned pointer to a created Shisa library handle.
file: Filename of system configuration, or NULL.
Description: Creates a Shisa library handle, using shisa(), but reading
the system configuration file at the location file, or at
the default location, should file be NULL. The path to
the default system configuration file is decided at compile
time (sysconfdir/shisa.conf).
The handle is allocated regardless of return value, the only
exception being SHISA_INIT_ERROR, which indicates a problem
in allocating the handle. Other error conditions arise while
reading a file.
Return value: Returns SHISA_OK, or an error code. The value
SHISA_INIT_ERROR indicates a failure to create the handle.
The default configuration file is typically read automatically by
calling shisa_init, but if you wish to manually access the
Shisa configuration file functions, here is the complete interface.
dbh: Shisa library handle created by shisa().
value: String containing database definition.
Description: Sets up and opens a new database. The syntax of the parameter value is "TYPE[ LOCATION[ PARAMETER]]", where TYPE is one of the supported database types, typically "file".
The above substrings LOCATION and PARAMETER are optional strings passed on verbatim to the database during initialization. Neither TYPE nor LOCATION may contain embedded spaces, but PARAMETER may do so.
Return value: Returns SHISA_OK if a database was parsed and opened
successfully.
dbh: Shisa library handle created by shisa().
option: String with options to prime the Shisa library.
Description: Configures the Shisa library from the specification option.
This call expects a string declaration of the form "db=VALUE",
or "db VALUE". Here VALUE is the same declaration as used by
shisa_cfg_db(), i.e., of the form "TYPE[ LOCATION[ PARAMETER]]".
The prefix "db", mandatory in option, makes shisa_cfg() suited
to a syntax with key-value pairs also in PARAMETER.
Return value: Returns SHISA_OK if option is valid.
dbh: Shisa library handle created by shisa().
cfg: File name where to read configuration.
Description: Configures the Shisa library using a configuration file located at cfg.
Return value: Returns SHISA_OK if successful. Typically
returns SHISA_CFG_NO_FILE in response to a misnamed file.
dbh: Shisa library handle created by shisa().
Description: Fetches information on the installed configuration.
Return value: Returns file name of the active system configuration.
The core part of the Shisa interface follows. The typical procedure
is to use shisa_principal_find to verify that a specific
principal exists, and to extract some information about it, and then
use shisa_keys_find to get the cryptographic keys for the
principal, usually suppliying some hints as to which of all keys you
are interested in (e.g., key version number and encryption algorithm
number).
dbh: Shisa library handle created by shisa().
realms: Returned pointer to a newly allocated array of also
allocated and null-terminated UTF-8 strings with realm names.
nrealms: Pointer to a number which is updated with the number
of just allocated and returned realm strings.
Description: Extracts a list of all realm names in backend, as null-terminated UTF-8 strings. The caller is responsible for deallocating all strings as well as the array *realms.
Return value: Returns SHISA_OK on success, or an error code.
dbh: Shisa library handle created by shisa().
realm: Name of realm, as null-terminated UTF-8 string.
principals: Returned pointer to newly allocated array of just
allocated null-terminated UTF-8 strings with principal names.
nprincipals: Pointer to an integer updated with the number of just
allocated and returned principal names.
Description: Extracts a list of all principal names in backend belonging to the realm realm, as null-terminated UTF-8 strings. The caller is responsible for deallocating all strings and the array *principals.
Return value: Returns SHISA_OK on success, SHISA_NO_REALM if the
specified realm does not exist, or an error code otherwise.
dbh: Shisa library handle created by shisa().
realm: Name of the realm the principal belongs to.
principal: Name of principal to get information about.
ph: Pointer to a previously allocated principal structure
where information about the principal is to be stored.
Description: Extracts information about given the PRINCIPAL@REALM pair selected by principal and realm.
Return value: Returns SHISA_OK if successful, SHISA_NO_REALM if
the indicated realm does not exist, SHISA_NO_PRINCIPAL if the
indicated principal does not exist, or an error code otherwise.
dbh: Shisa library handle created by shisa().
realm: Name of the realm the principal belongs to.
principal: Name of principal to get information about.
ph: Pointer to an existing principal structure containing
information to store in the database.
Description: Modifies information stored about the given principal PRINCIPAL@REALM. Note that it is usually a good idea to set in ph only the fields that are to be updated.
It is generally suggested to first call shisa_principal_find(),
to get the current information, then to modify one field and
call shisa_principal_update().
Modifying several values is not recommended in general, as this will 1) overwrite any modifications made to other fields between the two calls (by other processes) and 2) will cause all values to be written again, which may generate more overhead.
Return value: Returns SHISA_OK if successful, SHISA_NO_REALM if
the indicated realm does not exist, SHISA_NO_PRINCIPAL if the
indicated principal does not exist, or an error code otherwise.
dbh: Shisa library handle created by shisa().
realm: Name of the realm the principal belongs to.
principal: Name of principal to add. When set to NULL,
only the realm realm is created.
ph: Pointer to a principal structure with information to store
in the database.
key: Pointer to a key structure with information to store in
the database.
Description: Inserts the given information into the database for the
principal PRINCIPAL@REALM. In case principal is NULL,
the parameters ph and key are not used, so only the realm
is added to the database.
Return value: Returns SHISA_OK if the information was
successfully added, or an error code otherwise.
dbh: Shisa library handle created by shisa().
realm: Name of the realm the principal belongs to.
principal: Name of the principal to remove. Set to NULL,
only the realm realm is removed.
Description: Removes all information stored in the database for the given
principal PRINCIPAL@REALM. When principal is NULL, then the
realm realm is itself removed, but this can only succeed if
the realm is already empty of principals.
Return value: Returns SHISA_OK if successful, or an error code.
dbh: Shisa library handle created by shisa().
realm: Name of the realm the principal belongs to.
principal: Name of the principal whose keys are examined.
hint: Pointer to a Shisa key structure with hints on matching
criteria for relevant keys. NULL matches all keys.
keys: Returned pointer to a newly allocated array of Shisa
key structures.
nkeys: Pointer to an integer updated with the number of
allocated Shisa key structures in *keys.
Description: Iterates through the set of keys belonging to PRINCIPAL@REALM, as selected by principal and realm. Then extracts any keys that match the criteria in hint.
Not all elements of hint 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 key->etype to 3, and all other fields to zero.
Return value: Returns SHISA_OK if successful, or an error code.
dbh: Shisa library handle created by shisa().
realm: Name of the realm the principal belongs to.
principal: Name of the principal to add a new key for.
key: Pointer to a Shisa key structure with the new key.
Description: Adds a complete key key to the database entry belonging to the principal PRINCIPAL@REALM, as set by principal and realm.
Return value: Returns SHISA_OK if successful, or an error code.
dbh: Shisa library handle created by shisa().
realm: Name of the realm the principal belongs to.
principal: Name of the principal needing an updated key.
oldkey: Pointer to a Shisa key structure giving matching
criteria for locating the key to be updated.
newkey: Pointer to a complete Shisa key structure, in which
all fields are used for the new key. Note that oldkey
normally has far fewer fields filled-in.
Description: Modifies data about a key stored in the database, a key
belonging to the principal selected by principal and realm.
First oldkey is used to locate the key to update, as does
shisa_keys_find(). Then the found key is modified to carry
whatever information is stored in newkey.
Not all elements of oldkey need to be filled out, only sufficiently many so as to uniquely identify the desired key. For example, if you want to modify the information stored about a unique key of etype 3, i.e., DES-CBC-MD5, then set the field key->etype to 3, leaving all other fields as zero.
Return value: Returns SHISA_OK on success, SHISA_NO_KEY if no
key could be located, SHISA_MULTIPLE_KEY_MATCH if more
than a single key matched the given criteria, or an error code
otherwise.
dbh: Shisa library handle created by shisa().
realm: Name of the realm the principal belongs to.
principal: Name of the principal whose key is to be removed.
key: Pointer to a Shisa key structure with hints on matching
criteria for the key to select.
Description: Removes from the Shisa database a key, matching the hints in key, for the user PRINCIPAL@REALM. Not all elements of key need to be filled in, only those relevant to locate the key uniquely.
For example, if you want to remove the only key of etype 3, i.e., DES-CBC-MD5, then set the field key->etype to 3, and all other fields to zero.
Return value: Returns SHISA_OK on success, SHISA_NO_KEY if no key
could be located, SHISA_MULTIPLE_KEY_MATCH if more than one
key matched the given criteria, or an error code otherwise.
dbh: Shisa library handle created by shisa().
key: Pointer to a Shisa key structure to deallocate.
Description: Deallocates the fields of a Shisa key structure, as well as the structure itself.
dbh: Shisa library handle created by shisa().
keys: Pointer to an array of Shisa key structures.
nkeys: Number of key elements in the array keys.
Description: Deallocates each key element in the array keys of Shisa
database keys, using repeated calls to shisa_key_free().
Error handling is similar to that for Shishi in general (see Error Handling), i.e., you invoke shisa_strerror on the integer
return value received by some function, if the return value is
non-zero. Below is the complete interface.
err: Shisa error code.
Description: Explains verbally an error status err. The returned string can be used to compose a diagnostic message of benefit to a user.
Return value: Returns a pointer to a statically allocated string, containing a description of the error given as input argument.
dbh: Shisa library handle created by shisa().
format: printf style format string.
...: printf style arguments.
Description: Prints an informational message to standard error. The text is composed from the arguments, like printf(3).
Next: Generic Security Service, Previous: Examples, Up: Programming Manual [Contents][Index]