-\documentstyle[12pt,fullpage,changebar]{article}
+\documentstyle[12pt,fullpage,changebar,rcsid]{article}
-% $Id$
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Make _ actually generate an _, and allow line-breaking after it.
+\let\underscore=\_
+\catcode`_=13
+\def_{\underscore\penalty75\relax}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\rcs$Id$
\setlength{\parskip}{.7\baselineskip}
\setlength{\parindent}{0pt}
\def\secure{OV*Secure}
\def\v#1{\verb+#1+}
-\title{OV*Secure Admin \\ Functional Specifications}
+\title{OV*Secure Admin \\ Functional Specifications\thanks{\rcsId}}
\author{Barry Jaspan}
-\date{DRAFT --- \today}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% Make _ actually generate an _, and allow line-breaking after it.
-\let\underscore=\_
-\catcode`_=13
-\def_{\underscore\penalty75\relax}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}
+\sloppy
\maketitle
{\setlength{\parskip}{0pt}\tableofcontents}
\item A single ``forbidden password'' dictionary can be specified for all
users; a password that is not significantly different from every word
in the dictionary will not be accepted.
-
-\item A password that is not significantly different from each
-component and the realm of the principal's name will not be accepted.
\end{itemize}
-\section{Interrealm Operation}
+\section{Multi-realm Operation}
-For version 1.0, the behavior of any function when called with a
-principal name that is not in the host's local realm is undefined.
+The behavior of any function when called with a principal name that is
+not in the host's local realm is currently undefined.
\section{Admin API}
setting of the bit on the client is irrelevant for a TGS_REQ).
\begin{description}
-\item[KRB5_KDB_DISALLOW_POSTDATED] Disables the ALLOW_POSTDATE
+\item[KRB5_KDB_DISALLOW_POSTDATED] Disables the ALLOW_POSTDATED
and POSTDATED KDC options on AS_REQ and TGS_REQ.
\item[KRB5_KDB_DISALLOW_FORWARDABLE] Disables the FORWARDABLE KDC
\subsection{Constants, Header Files, Libraries}
-For release 1.0 both all of the files decribed in this section are
+For release 1.0 and release 1.0.1, all of the files decribed in this
+section are
rooted off of the ``stage'' directory in the build tree. If we export
this interface in future releases they will move to the ``install''
tree. Include files are found under ``stage/include'', libraries under
``stage/lib''.
-$<$ovsec_admin/admin.h$>$ contains ovsec_kadm routine prototypes, data
-structures, mask bitfields defines, and the following name and
-location definitions:
-
+$<$ovsec_admin/admin.h$>$ includes a number of required header files,
+including RPC, Kerberos 5, com_err, and \secure{} admin com_err
+defines. It contains prototypes for all ovsec_kadm routines mentioned
+below, as well as all Admin API data structures, type definitions and
+defines mentioned in this document. The defines and their values
+contained in the file include the following (whose OVSEC_KADM_
+prefixes have been removed):
\begin{description}
-\item[admin service principal] ADM_PRINCIPAL (``ovsec_kadm/admin'')
-\item[admin history key] HIST_PRINCIPAL (``ovsec_kadm/history'')
-\item[change password principal] CHANGEPW_PRINCIPAL (``ovsec_kadm/changepw'')
-\item[server acl file path] ACLFILE (``/krb5/ovsec_admin.acl'')
-\item[dictionary] WORDFILE (``/krb5/ovsec_adm_dict'')
+\item[admin service principal] ADMIN_SERVICE (``ovsec_adm/admin'')
+\item[admin history key] HIST_PRINCIPAL (``ovsec_adm/history'')
+\item[change password principal] CHANGEPW_SERVICE (``ovsec_adm/changepw'')
+\item[server acl file path] ACLFILE (``/krb5/ovsec_adm.acl'')
+\item[dictionary] WORDFILE (``/krb5/ovsec_adm.dict'')
\end{description}
-OVSEC_KADM errors are described in $<$ovsec_admin/kadm_err.h$>$.
-
-The location of the admin policy and principal databases are defined
-in $<$ovsec_admin/adb.h$>$:
+OVSEC_KADM errors are described in $<$ovsec_admin/kadm_err.h$>$, which
+is included by $<$ovsec_admin/admin.h$>$.
+The locations of the admin policy and principal databases, as well as
+defines and type definitions for the databases, are defined in
+$<$ovsec_admin/adb.h$>$. Some of the defines in that file are:
\begin{description}
\item[admin policy database] POLICY_DB (``/krb5/ovsec_policy.db'')
\item[admin principal database] PRINCIPAL_DB (``/krb5/ovsec_principal.db'')
\end{description}
-Client applications will link against libclient.a and server programs
-against libsrv.a. Right now both clients and servers also need to link
-against libcommon.a but we should put that in both libclient.a and
-libsrv.a to simplify the linking process.
+Client applications will link against libadmclnt.a and server programs
+against libadmsrv.a.\footnote{In Secure 1.0, client applications
+linked against libclient.a and libcommon.a, and server applications
+linked against libsrv.a and libcommon.a.} Client applications must
+also link against: libgssapi_krb5.a, libkrb5.a, libisode.a,
+libcrypto.a, librpclib.a, libcom_err.a, libdyn.a, and libdb.a. Server
+applications must also link against: libkdb5.a, libkrb5.a,
+libcrypto.a, libdb.a, librpclib.a, libcom_err.a, and libdyn.a.
\subsection{Error Codes}
has no other side effect.
The Admin system will use \v{com_err} for error codes. Note that this
-means \v{com_err} codes may returned from functions that the admin
+means \v{com_err} codes may be returned from functions that the admin
routines call (e.g. the kerberos library). Callers should not expect
that only OVSEC errors will be returned. The Admin system error code
table name will be ``ovk'', and the offsets will be the same as the
-order presented here. The error table include file will be
-$<$ovsec_admin/kadm_err.h$>$.
+order presented here. As mentioned above, the error table include file
+will be $<$ovsec_admin/kadm_err.h$>$.
\begin{description}
\item[* OVSEC_KADM_FAILURE] Operation failed for unspecified reason.
\item[OVSEC_KADM_INIT] Connection to server already initialized.
\item[OVSEC_KADM_BAD_PASSWORD] Incorrect password.
\item[OVSEC_KADM_PROTECT_PRINCIPAL] Cannot change protected principal."
+\item[* OVSEC_KADM_BAD_SERVER_HANDLE] Programmer error! Bad Admin server handle.
+\item[* OVSEC_KADM_BAD_STRUCT_VERSION] Programmer error! Bad API structure version.
+\item[* OVSEC_KADM_OLD_STRUCT_VERSION] API structure version specified by application is no longer supported; recompile application against current OpenV*Secure Admin API header files and libraries.
+\item[* OVSEC_KADM_NEW_STRUCT_VERSION] API structure version specified by application is unknown to libraries; obtain current OpenV*Secure Admin API header files and libraries and recompile application.
+\item[* OVSEC_KADM_BAD_API_VERSION] Programmer error! Bad API version.
+\item[* OVSEC_KADM_OLD_LIB_API_VERSION] API version specified by application is no longer supported by libraries; update application to adhere to current API version and recompile.
+\item[* OVSEC_KADM_OLD_SERVER_API_VERSION] API version specified by application is no longer supported by server; update application to adhere to current API version and recompile.
+\item[* OVSEC_KADM_NEW_LIB_API_VERSION] API version specified by application is unknown to libraries; obrain current OpenV*Secure Admin API header files and libraries and recompile application.
+\item[* OVSEC_KADM_NEW_SERVER_API_VERSION] API version specified by application is unknown to server; obtain and install newest OpenV*Secure Admin Server.
\end{description}
\subsection{Authentication and Authorization}
\label{sec:auth}
Two Kerberos principals exist for use in communicating with the Admin
-system: ovsec_kadm/admin and ovsec_kadm/changepw. Both principals
+system: ovsec_adm/admin and ovsec_adm/changepw. Both principals
have the KRB5_KDB_DISALLOW_TGT_BASED bit set in their attributes so
that service tickets for them can only be acquired via a
-password-based (AS_REQ) request. Additionally, ovsec_kadm/changepw
+password-based (AS_REQ) request. Additionally, ovsec_adm/changepw
has the KRB5_KDB_PWCHANGE_SERVICE bit set so that a principal with an
expired password can still obtain a service ticket for it.
The Admin system accepts requests that are authenticated to either
-service principal, but the set of operations that can be performed by
+service principal, but the sets of operations that can be performed by
a request authenticated to each service are different. In particular,
only the functions chpass_principal, randkey_principal, get_principal,
and get_policy can be performed by a request authenticated to the
-ovsec_kadm/changepw service. The function semantics describe the precise
-details.
+ovsec_adm/changepw service. The function semantics descriptions below
+give the precise details.
-Each Admin API operation authenticated to the ovsec_kadm/admin service
+Each Admin API operation authenticated to the ovsec_adm/admin service
requires a specific authorization to run. This version uses a simple
named privilege system with the following names and meanings:
The Authorization checks only happen if you are using the RPC mechanism.
-If you are using the server side API functions locally on the admin server,
+If you are using the server-side API functions locally on the admin server,
the only authorization check is if you can access the approporiate local
files.
\begin{verbatim}
ovsec_kadm_ret_t ovsec_kadm_init(char *client_name, char *pass,
- char *service_name, char *realm)
+ char *service_name, char *realm,
+ unsigned long struct_version,
+ unsigned long api_version,
+ void **server_handle)
\end{verbatim}
AUTHORIZATION REQUIRED: none
\item Initializes all the com_err error tables used by the Admin
system.
-\item Acquire a Kerberos ticket for the specified service.
+\item Acquires a Kerberos ticket for the specified service.
\begin{enumerate}
\item The ticket's client is client_name, which can be any valid
the user is prompted (via the tty) for a password.
\end{enumerate}
-\item Create a GSS-API authenticated connection to the Admin server,
+\item Creates a GSS-API authenticated connection to the Admin server,
using the just-acquired Kerberos ticket.
+
+\item Verifies that the struct_version and api_version specified by
+the caller are valid and known to the library.
+
+\item Sends the specified api_version to the server.
+
+\item Upon successful completion, fills in server_handle with a handle
+for this connection, to be used in all subsequent API calls.
\end{enumerate}
+The caller should always specify OVSEC_KADM_STRUCT_VERSION for the
+struct_version argument, a valid and supported API version constant
+for the api_version argument (currently, theonly valid API version
+constant is OVSEC_KADM_API_VERSION_1), and a valid pointer in which
+the server handle will be stored.
+
Local clients, running on the KDC, may be useful. For now this is will
most likely be used for testing, but could in the future be the basis
for a command-line system that works both remotely and on the KDC
\item Initializes the dictionary (if present) for dictionary checks.
-\item Parses client_name as a Kerberos principal and initializes the
-global current_caller principal to it. client_name should usually be
-specified as the name of the program.
+\item Parses client_name as a Kerberos principal. client_name should
+usually be specified as the name of the program.
-\item The service_name argument is not used.
+\item Verifies that the struct_version and api_version specified by
+the caller are valid.
+
+\item Fills in server_handle with a handle containing all state
+information (version numbers and client name) for this ``connection.''
\end{enumerate}
+The service_name argument is not used.
RETURN CODES:
\subsection{ovsec_kadm_destroy}
\begin{verbatim}
-ovsec_kadm_ret_t ovsec_kadm_destroy()
+ovsec_kadm_ret_t ovsec_kadm_destroy(void *server_handle)
\end{verbatim}
AUTHORIZATION REQUIRED: none
\item Tear down the GSS-API context negotiated with the server.
\item Close the RPC connection.
+
+\item Free storage space associated with server_handle, after erasing
+its magic number so it won't be mistaken for a valid handle by the
+library later.
\end{enumerate}
-For local clients, this function does nothing.
+For local clients, this function just frees the storage space
+associated with server_handle after erasing its magic number.
RETURN CODES:
\begin{verbatim}
ovsec_kadm_ret_t
-ovsec_kadm_create_principal(ovsec_kadm_principal_ent_t princ, u_int32 mask,
- char *pw);
+ovsec_kadm_create_principal(void *server_handle,
+ ovsec_kadm_principal_ent_t princ, u_int32 mask,
+ char *pw);
\end{verbatim}
AUTHORIZATION REQUIRED: add
\begin{verbatim}
ovsec_kadm_ret_t
-ovsec_kadm_delete_principal(krb5_principal princ);
+ovsec_kadm_delete_principal(void *server_handle, krb5_principal princ);
\end{verbatim}
AUTHORIZATION REQUIRED: delete
\begin{verbatim}
ovsec_kadm_ret_t
-ovsec_kadm_modify_principal(ovsec_kadm_principal_ent_t princ, u_int32 mask);
+ovsec_kadm_modify_principal(void *server_handle,
+ ovsec_kadm_principal_ent_t princ, u_int32 mask);
\end{verbatim}
Modify the attributes of the principal named in
\begin{verbatim}
ovsec_kadm_ret_t
-ovsec_kadm_rename_principal(krb5_principal source, krb5_principal target);
+ovsec_kadm_rename_principal(void *server_handle, krb5_principal source,
+ krb5_principal target);
\end{verbatim}
AUTHORIZATION REQUIRED: add and delete
\begin{verbatim}
ovsec_kadm_ret_t
-ovsec_kadm_chpass_principal(krb5_principal princ, char *pw);
+ovsec_kadm_chpass_principal(void *server_handle, krb5_principal princ,
+ char *pw);
\end{verbatim}
AUTHORIZATION REQUIRED: modify, or the calling principal being the
same as the princ argument. If the request is authenticated to the
-ovsec_kadm/changepw service, the modify privilege is disregarded.
+ovsec_adm/changepw service, the modify privilege is disregarded.
Change a principal's password.
\begin{verbatim}
ovsec_kadm_ret_t
-ovsec_kadm_chpass_principal_util(krb5_principal princ, char *new_pw,
- char **pw_ret, char *msg_ret);
+ovsec_kadm_chpass_principal_util(void *server_handle, krb5_principal princ,
+ char *new_pw, char **pw_ret,
+ char *msg_ret);
\end{verbatim}
AUTHORIZATION REQUIRED: modify, or the calling principal being the
same as the princ argument. If the request is authenticated to the
-ovsec_kadm/changepw service, the modify privilege is disregarded.
+ovsec_adm/changepw service, the modify privilege is disregarded.
This function is a wrapper around ovsec_kadm_chpass_principal. It can
read a new password from a user, change a principal's password, and
administrator.
\end{description}
-\item For other errors copy the string ``$<$com_err message$>$ occurred while trying to change password.'' following by a blank line and ``Password not changed.'' into msg_ret. Return the error code returned by ovsec_kadm_chpass_principal.
+\item For other errors copy the string ``$<$com_err message$>$
+occurred while trying to change password.'' following by a blank line
+and ``Password not changed.'' into msg_ret. Return the error code
+returned by ovsec_kadm_chpass_principal.
\end{enumerate}
\begin{verbatim}
ovsec_kadm_ret_t
-ovsec_kadm_randkey_principal(krb5_principal princ, krb5_keyblock **new_key)
+ovsec_kadm_randkey_principal(void *server_handle, krb5_principal princ,
+ krb5_keyblock **new_key)
\end{verbatim}
AUTHORIZATION REQUIRED: modify, or the calling principal being the
same as the princ argument. If the request is authenticated to the
-ovsec_kadm/changepw service, the modify privilege is disregarded.
+ovsec_adm/changepw service, the modify privilege is disregarded.
Generate and assign a new random key to the named principal, and
return the generated key in allocated storage. The caller must free
\begin{verbatim}
ovsec_kadm_ret_t
-ovsec_kadm_get_principal(krb5_principal princ,
+ovsec_kadm_get_principal(void *server_handle, krb5_principal princ,
ovsec_kadm_principal_ent_t *ent);
\end{verbatim}
AUTHORIZATION REQUIRED: get, or the calling principal being the same
as the princ argument. If the request is authenticated to the
-ovsec_kadm/changepw service, the get privilege is disregarded.
+ovsec_adm/changepw service, the get privilege is disregarded.
RETURN CODES:
\begin{verbatim}
ovsec_kadm_ret_t
-ovsec_kadm_create_policy(ovsec_kadm_policy_ent_t policy, u_int32 mask);
+ovsec_kadm_create_policy(void *server_handle,
+ ovsec_kadm_policy_ent_t policy, u_int32 mask);
\end{verbatim}
Create a new policy.
\begin{verbatim}
ovsec_kadm_ret_t
-ovsec_kadm_delete_policy(char *policy);
+ovsec_kadm_delete_policy(void *server_handle, char *policy);
\end{verbatim}
Deletes a policy.
\begin{verbatim}
ovsec_kadm_ret_t
-ovsec_kadm_modify_policy(ovsec_kadm_policy_ent_t policy, u_int32 mask);
+ovsec_kadm_modify_policy(void *server_handle,
+ ovsec_kadm_policy_ent_t policy, u_int32 mask);
\end{verbatim}
Modify an existing policy. Note that modifying a policy has no affect
\begin{verbatim}
ovsec_kadm_ret_t
-ovsec_kadm_get_policy(char *policy, ovsec_kadm_policy_ent_t *ent);
+ovsec_kadm_get_policy(void *server_handle, char *policy,
+ ovsec_kadm_policy_ent_t *ent);
\end{verbatim}
AUTHORIZATION REQUIRED: get, or the calling principal's policy being
the same as the policy argument. If the request is authenticated to
-the ovsec_kadm/changepw service, the get privilege is disregarded.
+the ovsec_adm/changepw service, the get privilege is disregarded.
If an error is returned entry is set to NULL.
Return the policy's attributes in allocated memory. The caller must
\subsection{ovsec_kadm_free_principal_ent, _policy_ent}
\begin{verbatim}
-void ovsec_kadm_free_principal_ent(ovsec_kadm_principal_ent_t princ);
+void ovsec_kadm_free_principal_ent(void *server_handle,
+ ovsec_kadm_principal_ent_t princ);
\end{verbatim}
Free the memory that was allocated by a call to
\begin{verbatim}
ovsec_kadm_ret_t
-ovsec_kadm_get_privs(u_int32 *privs);
+ovsec_kadm_get_privs(void *server_handle, u_int32 *privs);
\end{verbatim}
Return the caller's admin server privileges in the integer pointed to
\begin{verbatim}
ovsec_adm_server [-m] [-r realm] [-createsalt normal|none]
- [-modifysalt normal|none|keep]
+ [-modifysalt normal|none|keep]
\end{verbatim}
The -m argument specifies that the Kerberos master key should be read
\subsection{Key Table, Authorization ACLs}
\label{sec:acls}
-The admin server's keytable is stored in /krb5/ovsec_admin.srvtab. It
-contains entries for the principals ovsec_kadm/admin and
-ovsec_kadm/changepw.
+The admin server's keytable is stored in /krb5/ovsec_adm.srvtab. It
+contains entries for the principals OVSEC_KADM_ADMIN_SERVICE and
+OVSEC_KADM_CHANGEPW_SERVICE.
The admin server will use a simple ACL mechanism to grant privileges
-to principals. The file {\tt /krb5/ovsec_admin_acl} will contain a
+to principals. The file OVSEC_KADM_ACLFILE will contain a
list of principals and their privileges. It is read at start-up, and
can only be reread by restarting the admin server.
as the existing but invalid service name ``mailserver@REALM.COM'':
\begin{verbatim}
-Authentication attempt failed: 192.231.148.11, Miscellaneous error, Wrong
-principal in request
+Authentication attempt failed: 192.231.148.11, Miscellaneous error,
+Wrong principal in request
\end{verbatim}
\item Authentication failure. This error can occur both within the
attack, or a header/argument splicing attack.
\begin{verbatim}
-WARNING! Forged/garbled request: <procedure name>, claimed client = <client
-name>, service = <service name>, addr = <IP address>
+WARNING! Forged/garbled request: <procedure name>, claimed client =
+<client name>, service = <service name>, addr = <IP address>
\end{verbatim}
Example: An attacker attempts to replay a previously valid ``create
principal'' message from jon/admin@REALM.COM:
\begin{verbatim}
-WARNING! Forged/garbled request: ovsec_kadm_create_principal, claimed client =
-jon/admin@REALM.COM, service = admin@REALM.COM, addr = 192.231.148.12
+WARNING! Forged/garbled request: ovsec_kadm_create_principal, claimed
+client = jon/admin@REALM.COM, service = admin@REALM.COM, addr =
+192.231.148.12
\end{verbatim}
\item Unauthorized request. This error occurs when a properly
\begin{verbatim}
Request: ovsec_kadm_chpass_principal, joe/user@REALM.COM, success,
-client = joe/user@REALM.COM, server = ovsec_kadm/changepw@REALM.COM,
+client = joe/user@REALM.COM, server = ovsec_adm/changepw@REALM.COM,
addr = 192.231.148.12
\end{verbatim}
\subsection{Password Dictionary}
The Admin server's password dictionary is stored in
-/krb5/ovsec_adm_dict. It is read once when the server starts. It
+OVSEC_KADM_WORDFILE. It is read once when the server starts. It
contains a list of entries, separated by newlines. An entry may
include any character except a newline and NULL, including spaces.
The dictionary does not need to be sorted.
\item[ovsec_adm_db_export/import] dump or load the admin policy and
principal databases
\item[ovsec_adm_check] check the KDC and admin databases for
-inconsistencies and repair them.
+inconsistencies and repair them.\footnote{Not yet implemented.}
\end{description}
The details of these tools are described in their own documents.
projects / krb5.git / commitdiff