diff options
Diffstat (limited to 'crypto/krb5/doc/kadm5/api-server-design.tex')
| -rw-r--r-- | crypto/krb5/doc/kadm5/api-server-design.tex | 1054 |
1 files changed, 0 insertions, 1054 deletions
diff --git a/crypto/krb5/doc/kadm5/api-server-design.tex b/crypto/krb5/doc/kadm5/api-server-design.tex deleted file mode 100644 index 2cf0fe84f363..000000000000 --- a/crypto/krb5/doc/kadm5/api-server-design.tex +++ /dev/null @@ -1,1054 +0,0 @@ -% This document is included for historical purposes only, and does not -% apply to krb5 today. - -\documentstyle[12pt,fullpage]{article} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%% Make _ actually generate an _, and allow line-breaking after it. -\let\underscore=\_ -\catcode`_=13 -\def_{\underscore\penalty75\relax} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\setlength{\parskip}{.7\baselineskip} -\setlength{\parindent}{0pt} - -\def\v#1{\verb+#1+} -\def\k#1{K$_#1$} - -\title{KADM5 Library and Server \\ Implementation Design} -\author{Barry Jaspan} - -\begin{document} - -\sloppy -\maketitle - -{\setlength{\parskip}{0pt}\tableofcontents} - -\section{Overview} - -The KADM5 administration system is designed around the KADM5 API. The -``server-side'' library libkadm5srv.a implements the KADM5 API by -operating directly on the underlying KDC and admin databases. The -``client-side'' library libkadm5clnt.a implements the KADM5 API via an -RPC mechanism. The administration server kadmind accepts RPC requests -from the client-side library and translates them into calls to the -server-side library, performing authentication, authorization, and -logging along the way. - -The two libraries, libkadm5clnt.a and libkadm5srv.a, export the -identical kadm5 interface; for example, both contain definitions for -kadm5_get_principal, and all other kadm5 functions. In most cases, -the client library function just marshalls arguments and results into -and out of an RPC call, whereas the server library function performs -the actual operation on the database file. kadm5_init_*, however, are -substantially different even though they export the same interface: on -the client, they establish the RPC connection and GSS-API context, -whereas on the server side the open the database files, read in the -password dictionary, and the like. Also, the kadm5_free functions -operate on local process memory in both libraries. - -The admin server is implemented as a nearly-stateless transaction -server, where each admin API function represents a single transaction. -No per-client or per-connection information is stored; only local -database handles are maintained between requests. The RPC mechanism -provides access to remote callers' authentication credentials for -authorization purposes. - -The admin API is exported via an RPC interface that hides all details -about network encoding, authentication, and encryption of data on the -wire. The RPC mechanism does, however, allow the server to access the -underlying authentication credentials for authorization purposes. - -The admin system maintains two databases: -% -\begin{itemize} -\item The master Kerberos (KDC) database is used to store all the -information that the Kerberos server understands, thus allowing the -greatest functionality with no modifications to a standard KDC. - -\item The KDC database also stores kadm5-specific per-principal -information in each principal's krb5_tl_data list. In a prior -version, this data was stored in a separate admin principal database; -thus, when this document refers to ``the admin principal database,'' -it now refers to the appropriate krb5_tl_data entries in the KDC -database. - -\item The policy database stores kadm5 policy information. -\end{itemize} - -The per-principal information stored in the admin principal database -consists of the principal's policy name and an array of the -principal's previous keys. The old keys are stored encrypted in the -key of the special principal ``kadmin/history'' that is created by the -server library when it is first needed. Since a change in -kadmin/history's key renders every principal's key history array -useless, it can only be changed using the ovsec_adm_edit utility; that -program will reencrypt every principal's key history in the new -key.\footnote{ovsec_adm_edit has not yet been implemented, and there -are currently no plans to implement it; thus, the history cannot -currently be changed.} The server library refuses all requests to -change kadmin/history's key. - -\section{API Handles} - -Each call to kadm5_init_* on the client or server creates a new API -handle. The handles encapsulate the API and structure versions -specified by kadm5_init_*'s caller and all other internal data needed -by the library. A process can have multiple open API handles -simultaneously by calling kadm5_init_* multiple times, and call can -specify a different version, client or service principal, and so -forth. - -Each kadm5 function verifies the handle it is given with the -CHECK_HANDLE or _KADM5_CHECK_HANDLE macros. The CHECK_HANDLE macro -differs for the client and server library because the handle types -used by those libraries differ, so it is defined in both -$<$client_internal.h$>$ and $<$server_internal.h$>$ in the library -source directory. In each header file, CHECK_HANDLE first calls -GENERIC_CHECK_HANDLE, defined in $<$admin_internal.h$>$, which -verifies the magic number, API version, and structure version that is -contained in both client and server handles. CHECK_HANDLE then calls -either CLIENT_CHECK_HANDLE or SERVER_CHECK_HANDLE respectively to -verify the client- or server-library specific handle fields. - -The CHECK_HANDLE macro is useful because it inlines the handle check -instead of requiring a separate function call. However, using -CHECK_HANDLE means that a source file cannot be compiled once and -included into both the client and server library, because CHECK_HANDLE -is always either specific to either the client or server library, not -both. There are a number of functions that can be implemented with -the same code in both the client and server libraries, however, -including all of the kadm5_free functions and -kadm5_chpass_principal_util. The _KADM5_CHECK_HANDLE macro solves -this problem; instead of inlining the handle check, it calls the -function _kadm5_check_handle which is defined separately in both the -client and server library, in client_init.c and server_init.c. -Since these two files are only compiled once and put in a single -library, they simply verify the handle they are passed with -CHECK_HANDLE and return the result. - -\section{API Versioning} - -The KADM5 system was designed by OpenVision to support multiple -versions of the KADM5 API. MIT has not adopted this level of support, -and considers the KADM5 C API to be unstable from release to release. -This section describes the original design intent; bear in mind that -only the most recent API is supported by current MIT krb5 releases, -and that the API version does not necessarily change with API changes -unless there is a need to do so for wire compatibility. - -Historically, three versions of the KADM5 API have existed: -KADM5_API_VERSION_1 through KADM5_API_VERSION_3. The first version -was equivalent to the initial OpenVision API, -OVSEC_KADM_API_VERSION_1; the second was created during the initial -integration of the OpenVision system into the MIT release; and the -third was created for MIT krb5 1.8 to add lockout fields to policy -entries. MIT dropped wire compatibility support for version 1 in MIT -krb5 1.8 (as version 1 was never used in shipped MIT code), but -retains wire compatibility support for version 2. - -Implementing a versioned API in C via with both local and RPC access -presents a number of design issues, some of them quite subtle. The -contexts in which versioning considerations must be made include: - -\begin{enumerate} -\item Typedefs, function declarations, and defined constants depend on -the API version a client is written to and must be correct at compile -time. - -\item Each function in the server library must behave according to the -API version specified by the caller at runtime to kadm5_init_*. - -\item The XDR functions used by the RPC layer to transmit function -arguments and results must encode data structures correctly depending -on the API version specified by the client at runtime. - -\item Each function in the client library must behave according to the -API version specified by the caller at runtime to kadm5_init_*. - -\item The RPC server (kadmind) must accept calls from a client using -any supported API version, and must then invoke the function in the -server library corresponding to the RPC with the API version indicated -by the client caller. - -\item When a first API function is invoked that needs to call a second -function in the API on its own behalf, and that second API function's -behavior depends on the API version specified, the first API function -must either be prepared to call the second API function at whatever -version its caller specifies or have a means of always calling the -second API function at a pre-determined version. -\end{enumerate} - -The following functions describe how each context is handled. - -\subsection{Designing for future compatibility} - -Any code whose behavior depends on the API version should be written -so as to be compatible with future, currently unknown API versions on -the grounds that any particular piece of API behavior will most -likely not change between versions. For example, in the current -system, the code is not written as ``if this is VERSION_1, do X, else -if this is VERSION_2, do Y''; instead, it is written as ``if this is -VERSION_1, do X; else, do Y.'' The former will require additional -work when VERSION_3 is defined, even if ``do Y'' is still the correct -action, whereas the latter will work without modification in that -case. - -\subsection{Header file declarations} - -Typedefs, defined constants and macros, and function declarations may -change between versions. A client is always written to a single, -specific API version, and thus expects the header files to define -everything according to that API. Failure of a header file to define -values correctly will result in either compiler warnings (e.g. if the -pointer type of a function argument changes) or fatal errors (e.g. if -the number of arguments to a function changes, or the fields of a -structure change). For example, in VERSION_1, kadm5_get_policy took a -pointer to a pointer to a structure, and in VERSION_2 it takes a -pointer to a structure; that would generate a warning if not correct. -In VERSION_1, kadm5_randkey_principal accepted three arguments but in -VERSION_2 accepts four; that would generate a fatal error. - -The header file defines everything correctly based on the value of the -USE_KADM5_API_VERSION constant. The constant can be assigned to an -integer corresponding to any supported API version, and defaults to -the newest version. The header files then simply use an \#ifdef to -include the right definitions: -% -\begin{verbatim} -#if USE_KADM5_API_VERSION == 1 -kadm5_ret_t kadm5_get_principal(void *server_handle, - krb5_principal principal, - kadm5_principal_ent_t *ent); -#else -kadm5_ret_t kadm5_get_principal(void *server_handle, - krb5_principal principal, - kadm5_principal_ent_t ent, - long mask); -#endif -\end{verbatim} - -\subsection{Server library functions} - -Server library functions must know how many and what type of arguments -to expect, and must operate on those arguments correctly, based on the -API version with which they are invoked. The API version is contained -in the handle that is always passed as their first argument, generated -by kadm5_init_* (to which the client specified the API version to use -at run-time). - -In general, it is probably unsafe for a compiled function in a library -to re-interpret the number and type of defined arguments at run-time -since the calling conventions may not allow it; for example, a -function whose first argument was a short in one version and a pointer -in the next might fail if it simply typed-casted the argument. In -that case, the function would have to written to take variable -arguments (i.e. use $<$stdarg.h$>$) and extract them from the stack -based on the API version. Alternatively, a separate function for each -API version could be defined, and $<$kadm5/admin.h$>$ could be written -to \v{\#define} the exported function name based on the value of -USE_KADM5_API_VERSION. - -In the current system, it turns out, that isn't necessary, and future -implementors should take try to ensure that no version has semantics -that will cause such problems in the future. All the functions in -KADM5 that have different arguments or results between VERSION_1 and -VERSION_2 do so simply by type-casting their arguments to the -appropriate version and then have separate code paths to handle each -one correctly. kadm5_get_principal, in svr_principal.c, is a good -example. In VERSION_1, it took the address of a pointer to a -kadm5_principal_ent_t to fill in with a pointer to allocated memory; -in VERSION_2, it takes a pointer to a structure to fill in, and a mask -of which fields in that structure should be filled in. Also, the -contents of the kadm5_principal_ent_t changed slightly between the two -versions. kadm5_get_principal handles versioning as follows -(following along in the source code will be helpful): - -\begin{enumerate} -\item If VERSION_1, it saves away its entry argument (address of a -pointer to a structure) and resets its value to contain the address of -a locally stack-allocated entry structure; this allows most of the -function to written once, in terms of VERSION_2 semantics. If -VERSION_1, it also resets its mask argument to be -KADM5_PRINCIPAL_NORMAL_MASK, because that is the equivalent to -VERSION_1 behavior, which was to return all the fields of the -structure. - -\item The bulk of the function is implemented as expected for -VERSION_2. - -\item The new fields in the VERSION_2 entry structure are assigned -inside a block that is only execute if the caller specified -VERSION_2. This saves a little time for a VERSION_1 caller. - -\item After the entry structure is filled, the function checks again -if it was called as VERSION_1. If so, it allocates a new -kadm5_principal_ent_t_v1 structure (which is conveniently defined in -the header file) with malloc, copies the appropriate values from the -entry structure into the VERSION_1 entry structure, and then writes -the address of the newly allocated memory into address specified by -the original entry argument which it had previously saved away. -\end{enumerate} - -There is another complication involved in a function re-interpreting -the number of arguments it receives at compile time---it cannot assign -any value to an argument for which the client did not pass a value. -For example, a VERSION_1 client only passes three arguments to -kadm5_get_principal. If the implementation of kadm5_get_principal -notices that the caller is VERSION_1 and therefore assigns its fourth -argument, mask, to a value that mimics the VERSION_1 behavior, it may -inadvertently overwrite data on its caller's stack. This problem can -be avoided simply by using a true local variable in such cases, -instead of treating an unpassed argument as a local variable. - -\subsection{XDR functions} - -The XDR functions used to encode function arguments and results must -know how to encode the data for any API version. This is important -both so that all the data gets correctly transmitted and so that -protocol compatibility between clients or servers using the new -library but an old API version is maintained; specific, new kadmind -servers should support old kadm5 clients. - -The signature of all XDR functions is strictly defined: they take the -address of an XDR function and the address of the data object to be -encoded or decoded. It is thus impossible to provide the API version -of the data object as an additional argument to an XDR function. -There are two other means to convey the information, storing the API -version to use as a field in the data object itself and creating -separate XDR functions to handle each different version of the data -object, and both of them are used in KADM5. - -In the client library, each kadm5 function collects its arguments into -a single structure to be passed by the RPC; similarly, it expects all -of the results to come back as a single structure from the RPC that it -will then decode back into its constituent pieces (these are the -standard ONC RPC semantics). In order to pass versioning information -to the XDR functions, each function argument and result datatype has a -filed to store the API version. For example, consider -kadm5_get_principal's structures: -% -\begin{verbatim} -struct gprinc_arg { - krb5_ui_4 api_version; - krb5_principal princ; - long mask; -}; -typedef struct gprinc_arg gprinc_arg; -bool_t xdr_gprinc_arg(); - -struct gprinc_ret { - krb5_ui_4 api_version; - kadm5_ret_t code; - kadm5_principal_ent_rec rec; -}; -typedef struct gprinc_ret gprinc_ret; -bool_t xdr_gprinc_ret(); -\end{verbatim} -% -kadm5_get_principal (in client_principal.c) assigns the api_version -field of the gprinc_arg to the version specified by its caller, -assigns the princ field based on its arguments, and assigns the mask -field from its argument if the caller specified VERSION_2. It then -calls the RPC function clnt_call, specifying the XDR functions -xdr_gprinc_arg and xdr_gprinc_ret to handle the arguments and results. - -xdr_gprinc_arg is invoked with a pointer to the gprinc_arg structure -just described. It first encodes the api_version field; this allows -the server to know what to expect. It then encodes the krb5_principal -structure and, if api_version is VERSION_2, the mask. If api_version -is not VERSION_2, it does not encode {\it anything} in place of the -mask, because an old VERSION_1 server will not expect any other data -to arrive on the wire there. - -The server performs the kadm5_get_principal call and returns its -results in an XDR encoded gprinc_ret structure. clnt_call, which has -been blocking until the results arrived, invokes xdr_gprinc_ret with a -pointer to the encoded data for it to decode. xdr_gprinc_ret first -decodes the api_version field, and then the code field since that is -present in all versions to date. The kadm5_principal_ent_rec presents -a problem, however. The structure does not itself contain an -api_version field, but the structure is different between the two -versions. Thus, a single XDR function cannot decode both versions of -the structure because it will have no way to decide which version to -expect. The solution is to have two functions, -kadm5_principal_ent_rec_v1 and kadm5_principal_ent_rec, which always -decode according to VERSION_1 or VERSION_2, respectively. gprinc_ret -knows which one to invoke because it has the api_version field -returned by the server (which is always the same as that specified by -the client in the gpring_arg). - -In hindsight, it probably would have been better to encode the API -version of all structures directly in a version field in the structure -itself; then multiple XDR functions for a single data type wouldn't be -necessary, and the data objects would stand complete on their own. -This can be added in a future API version if desired. - -\subsection{Client library functions} - -Just as with server library functions, client library functions must -be able to interpret their arguments and provide result according to -the API version specified by the caller. Again, kadm5_get_principal -(in client_principal.c) is a good example. The gprinc_ret structure -that it gets back from clnt_call contains a kadm5_principal_ent_rec or -a kadm5_principal_ent_rec_v1 (the logic is simplified somewhat because -the VERSION_2 structure only has new fields added on the end). If -kadm5_get_principal was invoked with VERSION_2, that structure should -be copied into the pointer provided as the entry argument; if it was -invoked with VERSION_1, however, the structure should be copied into -allocated memory whose address is then written into the pointer -provided by the entry argument. Client library functions make this -determination based on the API version specified in the provided -handle, just like server library functions do. - -\subsection{Admin server stubs} - -When an RPC call arrives at the server, the RPC layer authenticates -the call using the GSS-API, decodes the arguments into their -single-structure form (ie: a gprinc_arg) and dispatches the call to a -stub function in the server (in server_stubs.c). The stub function -first checks the caller's authorization to invoke the function and, if -authorized, calls the kadm5 function corresponding to the RPC function -with the arguments specified in the single-structure argument. - -Once again, kadm5_get_principal is a good example for the issues -involved. The contents of the gprinc_arg given to the stub -(get_principal_1) depends on the API version the caller on the client -side specified; that version is available to the server in the -api_version field of the gprinc_arg. When the server calls -kadm5_get_principal in the server library, it must give that function -an API handle that contains the API version requested by the client; -otherwise the function semantics might not be correct. One -possibility would be for the server to call kadm5_init for each client -request, specifying the client's API version number and thus generating -an API handle with the correct version, but that would be -prohibitively inefficient. Instead, the server dips down in the -server library's internal abstraction barrier, using the function -new_server_handle to cons up a server handle based on the server's own -global_server_handle but using the API version specified by the -client. The server then passes the newly generated handle to -kadm5_get_principal, ensuring the right behavior, and creates the -gprinc_ret structure in a manner similar to that described above. - -Although new_server_handle solves the problem of providing the server -with an API handle containing the right API version number, it does -not solve another problem: that a single source file, server_stubs.c, -needs to be able to invoke functions with arguments appropriate for -multiple API versions. If the client specifies VERSION_1, for -example, the server must invoke kadm5_get_principal with three -arguments, but if the client specifies VERSION_2 the server must -invoke kadm5_get_principal with four arguments. The compiler will not -allow this inconsistency. The server defines wrapper functions in a -separate source file that match the old version, and the separate -source file is compiled with USE_KADM5_API_VERSION set to the old -version; see kadm5_get_principal_v1 in server_glue_v1.c. The server -then calls the correct variant of kadm5_get_principal_* based on the -API version and puts the return values into the gprinc_ret in a manner -similar to that described above. - -Neither of these solutions are necessarily correct. new_server_handle -violates the server library's abstraction barrier and is at best a -kludge; the server library should probably export a function to -provide this behavior without violating the abstraction; -alternatively, the librar should be modified so that having the server -call kadm5_init for each client RPC request would not be too -inefficient. The glue functions in server_glue_v1.c really are not -necessary, because the server stubs could always just pass dummy -arguments for the extra arguments; after all, the glue functions pass -{\it nothing} for the extra arguments, so they just end up as stack -garbage anyway. - -Another alternative to the new_server_handle problem is to have the -server always invoke server library functions at a single API version, -and then have the stubs take care of converting the function arguments -and results back into the form expected by the caller. In general, -however, this might require the stubs to duplicate substantial logic -already present in the server library and further violate the server -library's abstraction barrier. - -\subsection{KADM5 self-reference} - -Some kadm5 functions call other kadm5 functions ``on their own -behalf'' to perform functionality that is necessary but that does not -directly affect what the client sees. For example, -kadm5_chpass_principal has to enforce password policies; thus, it -needs to call kadm5_get_principal and, if the principal has a policy, -kadm5_get_policy and kadm5_modify_principal in the process of changing -a principal's password. This leads to a complication: what API handle -should kadm5_chpass_principal pass to the other kadm5 functions it -calls? - -The ``obvious,'' but wrong, answer is that it should pass the handle -it was given by its caller. The caller may provide an API handle -specifying any valid API version. Although the semantics of -kadm5_chpass_principal did not change between VERSION_1 and VERSION_2, -the declarations of both kadm5_get_principal and kadm5_get_policy -did. Thus, to use the caller's API handle, kadm5_chpass_principal -will have to have a separate code path for each API version, even -though it itself did not change between versions, and duplicate a lot -of logic found elsewhere in the library. - -Instead, each API handle contains a ``local-use handle,'' or lhandle, -that kadm5 functions should use to call other kadm5 functions. For -example, the client-side library's handle structure is: -% -\begin{verbatim} -typedef struct _kadm5_server_handle_t { - krb5_ui_4 magic_number; - krb5_ui_4 struct_version; - krb5_ui_4 api_version; - char * cache_name; - int destroy_cache; - CLIENT * clnt; - krb5_context context; - kadm5_config_params params; - struct _kadm5_server_handle_t *lhandle; -} kadm5_server_handle_rec, *kadm5_server_handle_t; -\end{verbatim} -% -The lhandle field is allocated automatically when the handle is -created. All of the fields of the API handle that are accessed -outside kadm5_init are also duplicated in the lhandle; however, the -api_version field of the lhandle is always set to a {\it constant} -value, regardless of the API version specified by the caller to -kadm5_init. In the current implementation, the lhandle's api_version -is always VERSION_2. - -By passing the caller's handle's lhandle to recursively called kadm5 -functions, a kadm5 function is assured of invoking the second kadm5 -function with a known API version. Additionally, the lhandle's -lhandle field points back to the lhandle, in case kadm5 functions call -themselves more than one level deep; handle$->$lhandle always points -to the same lhandle, no matter how many times the indirection is -performed. - -This scheme might break down if a kadm5 function has to call another -kadm5 function to perform operations that they client will see and for -its own benefit, since the semantics of the recursively-called kadm5 -function may depend on the API version specified and the client may be -depending on a particular version's behavior. Future implementors -should avoid creating a situation in which this is possible. - -\section{Server Main} - -The admin server starts by trapping all fatal signals and directing -them to a cleanup-and-exit function. It then creates and exports the -RPC interface and enters its main loop. - -The main loop dispatches all incoming requests to the RPC mechanism. -In a previous version, after 15 seconds of inactivity, the server -closed all open databases; each database was be automatically reopened -by the API function implementations as necessary. That behavior -existed to protect against loss of written data before the process -exited. The current database libraries write all changes out to disk -immediately, however, so this behavior is no longer required or -performed. - -\section{Remote Procedure Calls} - -The RPC for the Admin system will be based on ONC RPC. ONC RPC is -used because it is a well-known, portable RPC mechanism. The -underlying external data representation (xdr) mechanisms for wire -encapsulation are well-known and extensible. Authentication to the -admin server and encryption of all RPC functional arguments and -results are be handled via the AUTH_GSSAPI authentication flavor of -ONC RPC. - -\section{Database Record Types} -\label{sec:db-types} - -\subsection{Admin Principal, osa_princ_ent_t} - -The admin principal database stores records of the type -osa_princ_ent_t (declared in $<$kadm5/adb.h$>$), which is the -subset of the kadm5_principal_ent_t structure that is not stored -in the Kerberos database plus the necessary bookkeeping information. -The records are keyed by the ASCII representation of the principal's -name, including the trailing NULL. - -\begin{verbatim} -typedef struct _osa_pw_hist_t { - int n_key_data; - krb5_key_data *key_data; -} osa_pw_hist_ent, *osa_pw_hist_t; - -typedef struct _osa_princ_ent_t { - char * policy; - u_int32 aux_attributes; - - unsigned int old_key_len; - unsigned int old_key_next; - krb5_kvno admin_history_kvno; - osa_pw_hist_ent *old_keys; - - - u_int32 num_old_keys; - u_int32 next_old_key; - krb5_kvno admin_history_kvno; - osa_pw_hist_ent *old_keys; -} osa_princ_ent_rec, *osa_princ_ent_t; -\end{verbatim} - -The fields that are different from kadm5_principal_ent_t are: - -\begin{description} -\item[num_old_keys] The number of previous keys in the old_keys array. -This value must be 0 $\le$ num_old_keys $<$ pw_history_num. - -\item[old_key_next] The index into old_keys where the next key should -be inserted. This value must be 0 $\le$ old_key_next $\le$ -num_old_keys. - -\item[admin_history_kvno] The key version number of the kadmin/history -principal's key used to encrypt the values in old_keys. If the server -library finds that kadmin/history's kvno is different from the value -in this field, it returns KADM5_BAD_HIST_KEY. - -\item[old_keys] The array of the principal's previous passwords, each -encrypted in the kadmin/history key. There are num_old_keys -elements. Each ``password'' in the array is itself an array of -n_key_data krb5_key_data structures, one for each keysalt type the -password was encoded in. -\end{description} - -\subsection{Policy, osa_policy_ent_t} - -The policy database stores records of the type osa_policy_ent_t -(declared in $<$kadm5/adb.h$>$) , which is all of -kadm5_policy_ent_t plus necessary bookkeeping information. The -records are keyed by the policy name. - -\begin{verbatim} -typedef struct _osa_policy_ent_t { - char *policy; - - u_int32 pw_min_life; - u_int32 pw_max_life; - u_int32 pw_min_length; - u_int32 pw_min_classes; - u_int32 pw_history_num; - - u_int32 refcnt; -} osa_policy_ent_rec, *osa_policy_ent_t; -\end{verbatim} - -\subsection{Kerberos, krb5_db_entry} - -The Kerberos database stores records of type krb5_db_entry, which is -defined in the $<$k5-int.h$>$ header file. The semantics of each -field are defined in the libkdb functional specification. - -\section{Database Access Methods} - -\subsection{Principal and Policy Databases} - -This section describes the database abstraction used for the admin -policy database; the admin principal database used to be treated in -the same manner but is now handled more directly as krb5_tl_data; -thus, nothing in this section applies to it any more. Since both -databases export equivalent functionality, the API is only described -once. The character T is used to represent both ``princ'' and -``policy''. The location of the principal database is defined by the -configuration parameters given to any of the kadm5_init functions in -the server library. - -Note that this is {\it only} a database abstraction. All functional -intelligence, such as maintaining policy reference counts or sanity -checking, must be implemented above this layer. - -Prototypes for the osa functions are supplied in -$<$kadm5/adb.h$>$. The routines are defined in libkadm5srv.a. They -require linking with the Berkely DB library. - -\subsubsection{Error codes} - -The database routines use com_err for error codes. The error code -table name is ``adb'' and the offsets are the same as the order -presented here. The error table header file is -$<$kadm5/adb_err.h$>$. Callers of the OSA routines should first call -init_adb_err_tbl() to initialize the database table. - -\begin{description} -\item[OSA_ADB_OK] Operation successful. -\item[OSA_ADB_FAILURE] General failure. -\item[OSA_ADB_DUP] Operation would create a duplicate database entry. -\item[OSA_ADB_NOENT] Named entry not in database. -\item[OSA_ADB_BAD_PRINC] The krb5_principal structure is invalid. -\item[OSA_ADB_BAD_POLICY] The specified policy name is invalid. -\item[OSA_ADB_XDR_FAILURE] The principal or policy structure cannot be -encoded for storage. -\item[OSA_ADB_BADLOCKMODE] Bad lock mode specified. -\item[OSA_ADB_CANTLOCK_DB] Cannot lock database, presumably because it -is already locked. -\item[OSA_ADB_NOTLOCKED] Internal error, database not locked when -unlock is called. -\item[OSA_ADB_NOLOCKFILE] KADM5 administration database lock file missing. -\end{description} - -Database functions can also return system errors. Unless otherwise -specified, database functions return OSA_ADB_OK. - -\subsubsection{Locking} - -All of the osa_adb functions except open and close lock and unlock the -database to prevent concurrency collisions. The overall locking -algorithm is as follows: - -\begin{enumerate} -\item osa_adb_open_T calls osa_adb_init_db to allocate the osa_adb_T_t -structure and open the locking file for further use. - -\item Each osa_adb functions locks the locking file and opens the -appropriate database with osa_adb_open_and_lock, performs its action, -and then closes the database and unlocks the locking file with -osa_adb_close_and_unlock. - -\item osa_adb_close_T calls osa_adb_fini_db to close the locking file -and deallocate the db structure. -\end{enumerate} - -Functions which modify the database acquire an exclusive lock, others -acquire a shared lock. osa_adb_iter_T acquires an exclusive lock for -safety but as stated below consequences of modifying the database in -the iteration function are undefined. - -\subsubsection{Function descriptions} - -\begin{verbatim} -osa_adb_ret_t osa_adb_create_T_db(kadm5_config_params *params) -\end{verbatim} -% -Create the database and lockfile specified in params. The database -must not already exist, or EEXIST is returned. The lock file is only -created after the database file has been created successfully. - -\begin{verbatim} -osa_adb_ret_t osa_adb_rename_T_db(kadm5_config_params *fromparams, - kadm5_config_params *toparams) -\end{verbatim} -% -Rename the database named by fromparams to that named by toparams. -The fromparams database must already exist; the toparams database may -exist or not. When the function returns, the database named by -fromparams no longer exists, and toparams has been overwritten with -fromparams. This function acquires a permanent lock on both databases -for the duration of its operation, so a failure is likely to leave the -databases unusable. - -\begin{verbatim} -osa_adb_ret_t osa_adb_destroy_policy_db(kadm5_config_params *params) -\end{verbatim} -% -Destroy the database named by params. The database file and lock file -are deleted. - -\begin{verbatim} -osa_adb_ret_t -osa_adb_open_T(osa_adb_T_t *db, char *filename); -\end{verbatim} -% -Open the database named filename. Returns OSA_ADB_NOLOCKFILE if the -database does not exist or if the lock file is missing. The database -is not actually opened in the operating-system file sense until a lock -is acquire. - -\begin{verbatim} -osa_adb_ret_t -osa_adb_close_T(osa_adb_T_t db); -\end{verbatim} -% -Release all shared or exclusive locks (on BOTH databases, since they -use the same lock file) and close the database. - -It is an error to exit while a permanent lock is held; -OSA_ADB_NOLOCKFILE is returned in this case. - -\begin{verbatim} -osa_adb_ret_t osa_adb_get_lock(osa_adb_T_t db, int mode) -\end{verbatim} - -Acquire a lock on the administration databases; note that both -databases are locked simultaneously by a single call. The mode -argument can be OSA_ADB_SHARED, OSA_ADB_EXCLUSIVE, or -OSA_ADB_PERMANENT. The first two and the third are really disjoint -locking semantics and should not be interleaved. - -Shared and exclusive locks have the usual semantics, and a program can -upgrade a shared lock to an exclusive lock by calling the function -again. A reference count of open locks is maintained by this function -and osa_adb_release_lock so the functions can be called multiple -times; the actual lock is not released until the final -osa_adb_release_lock. Note, however, that once a lock is upgraded -from shared to exclusive, or from exclusive to permanent, it is not -downgraded again until released completely. In other words, -get_lock(SHARED), get_lock(EXCLUSIVE), release_lock() leaves the -process with an exclusive lock with a reference count of one. An -attempt to get a shared or exclusive lock that conflicts with another -process results in the OSA_ADB_CANLOCK_DB error code. - -This function and osa_adb_release_lock are called automatically as -needed by all other osa_adb functions to acquire shared and exclusive -locks and so are not normally needed. They can be used explicitly by -a program that wants to perform multiple osa_adb functions within the -context of a single lock. - -Acquiring an OSA_ADB_PERMANENT lock is different. A permanent lock -consists of first acquiring an exclusive lock and then {\it deleting -the lock file}. Any subsequent attempt to acquire a lock by a -different process will fail with OSA_ADB_NOLOCKFILE instead of -OSA_ADB_CANTLOCK_DB (attempts in the same process will ``succeed'' -because only the reference count gets incremented). The lock file is -recreated by osa_adb_release_lock when the last pending lock is released. - -The purpose of a permanent lock is to absolutely ensure that the -database remain locked during non-atomic operations. If the locking -process dies while holding a permanent lock, all subsequent osa_adb -operations will fail, even through a system reboot. This is useful, -for example, for ovsec_adm_import which creates both new database -files in a temporary location and renames them into place. If both -renames do not fully complete the database will probably be -inconsistent and everything should stop working until an administrator -can clean it up. - -\begin{verbatim} -osa_adb_ret_t osa_adb_release_lock(osa_adb_T_t db) -\end{verbatim} - -Releases a shared, exclusive, or permanent lock acquired with -osa_adb_get_lock, or just decrements the reference count if multiple -locks are held. When a permanent lock is released, the lock file is -re-created. - -All of a process' shared or exclusive database locks are released when -the process terminates. A permanent lock is {\it not} released when -the process exits (although the exclusive lock it begins with -obviously is). - -\begin{verbatim} -osa_adb_ret_t -osa_adb_create_T(osa_adb_T_t db, osa_T_ent_t entry); -\end{verbatim} -% -Adds the entry to the database. All fields are defined. Returns -OSA_ADB_DUP if it already exists. - -\begin{verbatim} -osa_adb_ret_t -osa_adb_destroy_T(osa_adb_T_t db, osa_T_t name); -\end{verbatim} - -Removes the named entry from the database. Returns OSA_ADB_NOENT if -it does not exist. - -\begin{verbatim} -osa_adb_ret_t -osa_adb_get_T(osa_adb_T_t db, osa_T_t name, - osa_princ_ent_t *entry); -\end{verbatim} - -Looks up the named entry in the db, and returns it in *entry in -allocated storage that must be freed with osa_adb_free_T. Returns -OSA_ADB_NOENT if name does not exist, OSA_ADB_MEM if memory cannot be -allocated. - -\begin{verbatim} -osa_adb_ret_t -osadb_adb_put_T(osa_adb_T_t db, osa_T_ent_t entry); -\end{verbatim} - -Modifies the existing entry named in entry. All fields must be filled -in. Returns OSA_DB_NOENT if the named entry does not exist. Note -that this cannot be used to rename an entry; rename is implemented by -deleting the old name and creating the new one (NOT ATOMIC!). - -\begin{verbatim} -void osa_adb_free_T(osa_T_ent_t); -\end{verbatim} - -Frees the memory associated with an osa_T_ent_t allocated by -osa_adb_get_T. - -\begin{verbatim} -typedef osa_adb_ret_t (*osa_adb_iter_T_func)(void *data, - osa_T_ent_t entry); - -osa_adb_ret_t osa_adb_iter_T(osa_adb_T_t db, osa_adb_iter_T_func func, - void *data); -\end{verbatim} - -Iterates over every entry in the database. For each entry ent in the -database db, the function (*func)(data, ent) is called. If func -returns an error code, osa_adb_iter_T returns an error code. If all -invocations of func return OSA_ADB_OK, osa_adb_iter_T returns -OSA_ADB_OK. The function func is permitted to access the database, -but the consequences of modifying the database during the iteration -are undefined. - -\subsection{Kerberos Database} - -Kerberos uses the libkdb interface to store krb5_db_entry records. It -can be accessed and modified in parallel with the Kerberos server, -using functions that are defined inside the KDC and the libkdb.a. The -libkdb interface is defined in the libkdb functional specifications. - -\subsubsection{Initialization and Key Access} - -Keys stored in the Kerberos database are encrypted in the Kerberos -master key. The admin server will therefore have to acquire the key -before it can perform any key-changing operations, and will have to -decrypt and encrypt the keys retrieved from and placed into the -database via krb5_db_get_principal and _put_principal. This section -describes the internal admin server API that will be used to perform -these functions. - -\begin{verbatim} -krb5_principal master_princ; -krb5_encrypt_block master_encblock; -krb5_keyblock master_keyblock; - -void kdc_init_master() -\end{verbatim} - -kdc_init_master opens the database and acquires the master key. It -also sets the global variables master_princ, master_encblock, and -master_keyblock: - -\begin{itemize} -\item master_princ is set to the name of the Kerberos master principal -(\v{K/M@REALM}). - -\item master_encblock is something I have no idea about. - -\item master_keyblock is the Kerberos master key -\end{itemize} - -\begin{verbatim} -krb5_error_code kdb_get_entry_and_key(krb5_principal principal, - krb5_db_entry *entry, - krb5_keyblock *key) -\end{verbatim} - -kdb_get_entry_and_key retrieves the named principal's entry from the -database in entry, and decrypts its key into key. The caller must -free entry with krb5_dbm_db_free_principal and free key-$>$contents with -free.\footnote{The caller should also \v{memset(key-$>$contents, 0, -key-$>$length)}. There should be a function krb5_free_keyblock_contents -for this, but there is not.} - -\begin{verbatim} -krb5_error_code kdb_put_entry_pw(krb5_db_entry *entry, char *pw) -\end{verbatim} - -kdb_put_entry_pw stores entry in the database. All the entry values -must already be set; this function does not change any of them except -the key. pw, the NULL-terminated password string, is converted to a -key using string-to-key with the salt type specified in -entry-$>$salt_type.\footnote{The salt_type should be set based on the -command line arguments to the kadmin server (see the ``Command Line'' -section of the functional specification).} - -\section{Admin Principal and Policy Database Implementation} - -The admin principal and policy databases will each be stored in a -single hash table, implemented by the Berkeley 4.4BSD db library. -Each record will consist of an entire osa_T_ent_t. The key into the -hash table is the entry name (for principals, the ASCII representation -of the name). The value is the T entry structure. Since the key and -data must be self-contained, with no pointers, the Sun xdr mechanisms -will be used to marshal and unmarshal data in the database. - -The server in the first release will be single-threaded in that a -request will run to completion (or error) before the next will run, -but multiple connections will be allowed simultaneously. - -\section{ACLs, acl_check} - -The ACL mechanism described in the ``Authorization ACLs'' section of -the functional specifications will be implemented by the acl_check -function. - -\begin{verbatim} -enum access_t { - ACCESS_DENIED = 0, - ACCESS_OK = 1, -}; - -enum access_t acl_check(krb5_principal princ, char *priv); -\end{verbatim} - -The priv argument must be one of ``get'', ``add'', ``delete'', or -``modify''. acl_check returns 1 if the principal princ has the named -privilege, 0 if it does not. - -\section{Function Details} - -This section discusses specific design issues for Admin API functions -that are not addressed by the functional specifications. - -\subsection{kadm5_create_principal} - -If the named principal exists in either the Kerberos or admin -principal database, but not both, return KADM5_BAD_DB. - -The principal's initial key is not stored in the key history array at -creation time. - -\subsection{kadm5_delete_principal} - -If the named principal exists in either the Kerberos or admin -principal database, but not both, return KADM5_BAD_DB. - -\subsection{kadm5_modify_principal} - -If the named principal exists in either the Kerberos or admin -principal database, but not both, return KADM5_BAD_DB. - -If pw_history_num changes and the new value $n$ is smaller than the -current value of num_old_keys, old_keys should end up with the $n$ -most recent keys; these are found by counting backwards $n$ elements -in old_keys from old_key_next. old_key_nexts should then be reset to -0, the oldest of the saved keys, and num_old_keys set to $n$, the -new actual number of old keys in the array. - -\subsection{kadm5_chpass_principal, randkey_principal} - -The algorithm for determining whether a password is in the principal's -key history is complicated by the use of the kadmin/history \k{h} -encrypting key. - -\begin{enumerate} -\item For kadm5_chpass_principal, convert the password to a key -using string-to-key and the salt method specified by the command line -arguments. - -\item If the POLICY bit is set and pw_history_num is not zero, check -if the new key is in the history. -\begin{enumerate} -\item Retrieve the principal's current key and decrypt it with \k{M}. -If it is the same as the new key, return KADM5_PASS_REUSE. -\item Retrieve the kadmin/history key \k{h} and decrypt it with \k{M}. -\item Encrypt the principal's new key in \k{h}. -\item If the principal's new key encrypted in \k{h} is in old_keys, -return KADM5_PASS_REUSE. -\item Encrypt the principal's current key in \k{h} and store it in -old_keys. -\item Erase the memory containing \k{h}. -\end{enumerate} - -\item Encrypt the principal's new key in \k{M} and store it in the -database. -\item Erase the memory containing \k{M}. -\end{enumerate} - -To store the an encrypted key in old_keys, insert it as the -old_key_next element of old_keys, and increment old_key_next by one -modulo pw_history_num. - -\subsection{kadm5_get_principal} - -If the named principal exists in either the Kerberos or admin -principal database, but not both, return KADM5_BAD_DB. - -\end{document} |